# Scan Health Configuration REST API

## Overview

The Scan Health Configuration API allows administrators to configure automatic build failure when a scan detects zero components. This helps identify scan misconfigurations early in the CI/CD pipeline instead of producing empty scan results. Configuration supports hierarchical inheritance. Settings can be configured at the organization level and inherited by applications, or overridden at the application level.

## Base URL

```
/api/v2/config/scanHealth/{ownerType}/{ownerId}
```

| Path Parameter | Type | Value | Description |
| --- | --- | --- | --- |
| ownerType | string | `application` or `organization` | Level where the configuration is applied |
| ownerId | string | Internal ID | Internal ID of the application or organization |

## Authentication and Permissions

All endpoints require authentication.

| Operation | Required Permission |
| --- | --- |
| GET | View IQ Elements (READ) |
| PUT | Edit IQ Elements (WRITE) |
| DELETE | Edit IQ Elements (WRITE) |

## Configuration Model

```
{
  "failOnZeroComponents": true | false | null
}
```

| Field | Type | Description |
| --- | --- | --- |
| failOnZeroComponents | Boolean | `true` fails scans with zero components. `false` explicitly disables the behavior. `null` or absent inherits configuration from the parent organization. |

## Inheritance Rules

Configuration is resolved using the following priority order:

- Application-level configuration
- Organization hierarchy
- Default behavior

By default, scans with zero components are allowed.

## Endpoints

### GET - Retrieve Configuration

Returns the directly stored configuration for the specified owner. This operation does not resolve inherited configuration values.

- **Request**

```
GET /api/v2/config/scanHealth/organization/{orgId}

GET /api/v2/config/scanHealth/application/{appId}
```

- **Response - 200**

```
{
    "failOnZeroComponents": true
}
```

An empty response indicates that no direct configuration exists for the specified owner.

- **Response - 404**

```
Owner not found
```

### PUT - Create or Update Configuration

Creates or updates the scan health configuration for the specified owner.

- **Request**

```
PUT /api/v2/config/scanHealth/organization/{orgId}
Content-Type: application/json
```

- **Response - 200**

```
{
    "failOnZeroComponents": true
}
```

- **Response - 400**

```
Request body is null
```

- **Response - 404**

```
Owner not found
```

### DELETE - Remove Configuration

Removes the direct configuration for the specified owner. After deletion, configuration inheritance applies again from the parent organization or default behavior.

- **Request**

```
DELETE /api/v2/config/scanHealth/organization/{orgId}

DELETE /api/v2/config/scanHealth/application/{appId}
```

- **Response - 204**

```
Configuration deleted successfully
```

- **Response - 404**

```
No configuration found for the specified owner
```

## Scan Behavior

When `failOnZeroComponents` is enabled for an application, either directly or through inheritance:

| Scenario | Behavior |
| --- | --- |
| Scan finds components | Normal evaluation behavior |
| Scan finds zero components | Report is persisted, SBOM is activated, and the build returns HTTP 400 |
| Scan finds only unknown components | Normal evaluation behavior. Unknown components count as detected components. |

## Failure Response

When a scan detects zero components:

```
HTTP 400 Bad Request

Scan failed: zero components detected. This may indicate a scan misconfiguration.
```

## Key Details

- The scan report is still generated and visible in the UI.
- The SBOM remains available for export and download.
- Policy evaluation results are persisted.
- Only the HTTP response returned to the CI/CD client indicates failure.
- Applies to CLI, CI/CD integrations, and continuous monitoring scans.

## Examples

Enable at organization level

```
curl -u admin:admin123 -X PUT 
"https://iq-server/api/v2/config/scanHealth/organization/{orgId}" 
-H "Content-Type: application/json" 
-d '{"failOnZeroComponents": true}'
```

## Enable at application level

```
curl -u admin:admin123 -X PUT 
"https://iq-server/api/v2/config/scanHealth/application/{appId}" 
-H "Content-Type: application/json" 
-d '{"failOnZeroComponents": true}'
```

## Disable at application level

```
curl -u admin:admin123 -X PUT 
"https://iq-server/api/v2/config/scanHealth/application/{appId}" 
-H "Content-Type: application/json" 
-d '{"failOnZeroComponents": false}'
```

## Revert application to inherited behavior

```
curl -u admin:admin123 -X DELETE 
"https://iq-server/api/v2/config/scanHealth/application/{appId}"
```

## Check direct configuration

```
curl -u admin:admin123 
"https://iq-server/api/v2/config/scanHealth/application/{appId}"
```

## Cascade Deletion

When an application or organization is deleted, its scan health configuration is automatically removed.

## Audit Events

GET operations are not audited.

| Operation | Audit Domain | Audit Type |
| --- | --- | --- |
| PUT | `governance.scan-health` | `configure` |
| DELETE | `governance.scan-health` | `delete` |