# Vulnerability Scanner

ODG supports two vulnerability scanner extensions: **BDBA** (Black Duck Binary Analysis) and **Trivy**.
Only one vulnerability scanner may be enabled at a time.

## Scanner Comparison

The following table shows which OCM access and artefact types ODG will forward to each scanner. How the scanner processes a resource depends on the scanner itself.

| OCM Access Type | OCM Artefact Kind | BDBA | Trivy |
|-----------------|-------------------|:----:|:-----:|
| `OCIImage/v1` | `resource` | ✓ | ✓ |
| `LocalBlob/v1` | `resource` | ✓ | ✓ |
| `OCIImageLayer/v1` | `resource` | ✓ | ✓ |
| `S3/v1` | `resource` | ✓ | ✓ |
| `S3/v2` | `resource` | ✓ | ✓ |

Additionally, Trivy only supports the artefact types: `blob`, `directoryTree`, `executable`, `ociArtifact`, `ociImage` or `sbom`.
BDBA does not restrict by artefact type.

---

## BDBA

The BDBA extension consists of workers which interact with Black Duck Binary Analysis (BDBA) to create vulnerability and license findings for scanned components.

### Configuration Example

```yaml
bdba:
  interval: 86400                    # 24 hours
  on_unsupported: warning
  mappings:
    - prefix: 'acme.org/product-a'
      group_id: 1234
      processing_mode: rescan
      aws_secret_name: aws-account-prod
    - prefix: ''                     # catch-all for all other components
      group_id: 5678
      processing_mode: force_upload
      aws_secret_name: aws-account-default
```

### Top-Level Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `interval` | int (seconds) | `86400` | Maximum time before a component is re-scanned. |
| `mappings` | list | `[]` | Per-prefix component mappings. See mapping fields below. |
| `on_unsupported` | string | `warning` | Behaviour when artefact kind/type/access is unsupported. Options: `fail`, `ignore`, `warning`. |

(mappings)=
### Mapping Fields

Each entry in the `mappings` list supports the following fields:

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `prefix` | string | yes | Component name prefix. Use `''` (empty string) to match all components. |
| `group_id` | int | yes | The BDBA group ID used for scanning. |
| `processing_mode` | string | `rescan` | Behaviour for existing scans. Options: `rescan` (reuse binary), `force_upload` (always re-upload). |
| `aws_secret_name` | string | no | Name of the AWS secret to use for S3 artefacts. Required when multiple AWS secrets are configured. |

### Configuration Details

#### `interval`

The maximum time (in seconds) before a component's artefacts are rescanned.
Default is 86400 seconds (24 hours). Components are only rescanned after this
interval has elapsed since the last scan.

#### `on_unsupported`

Defines the behaviour when an artefact kind, type, or access method is not supported
by the BDBA scanner:

- **`fail`**: Raise an exception and stop processing
- **`ignore`**: Silently skip the unsupported artefact
- **`warning`** (default): Skip the artefact and log a warning message

#### `mappings`

Allows per-component-prefix configuration for BDBA scanning. This is useful when:
- Different components belong to different BDBA groups
- Different components require different processing modes
- Components are stored in different AWS S3 accounts

##### Prefix Matching

The `prefix` field uses simple string prefix matching (not regex):
- `prefix: 'acme.org'` matches `acme.org/product` and `acme.org/another-product`
- `prefix: ''` (empty string) matches all components (use as a catch-all)

Multiple mappings are evaluated in order, and the first matching prefix is used.

##### BDBA Group ID

The `group_id` specifies which BDBA group to use for scanning. Contact your
BDBA administrator to obtain the appropriate group ID for your components.

##### Processing Mode

Determines how existing BDBA scans are handled:

- **`rescan`** (default): Reuse the previously uploaded binary and retrieve
  updated scan results. This is faster and recommended for most use cases.

- **`force_upload`**: Always re-upload the binary and retrieve updated scan
  results. Use this when you need to ensure the binary itself is re-analysed,
  not just the findings re-evaluated.

##### AWS Secret Configuration

When scanning artefacts stored in AWS S3, the BDBA extension needs AWS credentials.
The `aws_secret_name` field specifies which AWS secret to use from your ODG
secrets configuration.

**Example with regional AWS accounts:**

```yaml
bdba:
  interval: 86400
  mappings:
    - prefix: 'us-prod.acme.org'
      group_id: 1000
      processing_mode: rescan
      aws_secret_name: aws-us-production
    - prefix: 'eu-prod.acme.org'
      group_id: 2000
      processing_mode: rescan
      aws_secret_name: aws-eu-production
    - prefix: ''
      group_id: 9999
      processing_mode: rescan
      aws_secret_name: aws-default
```

---

## Trivy

The Trivy extension uses [Trivy](https://trivy.dev) to scan artefacts for vulnerabilities.

### Configuration Example

```yaml
trivy:
  interval: 86400
  on_unsupported: warning
  scan_target: sbom_with_binary_fallback
  mappings:
    - prefix: 'acme.org/product-a'
      aws_secret_name: aws-account-prod
    - prefix: ''                     # catch-all for all other components
      aws_secret_name: aws-account-default
```

### Top-Level Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `interval` | int (seconds) | `86400` | Maximum time before a component is re-scanned. |
| `mappings` | list | `[]` | Per-prefix component mappings. See mapping fields below. |
| `on_unsupported` | string | `warning` | Behaviour when artefact kind/type/access is unsupported. Options: `fail`, `ignore`, `warning`. |
| `scan_target` | string | `sbom_with_binary_fallback` | How to scan artefacts. Options: `binary`, `sbom`, `sbom_with_binary_fallback`. |

### Mapping Fields

Each entry in the `mappings` list supports the following fields:

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `prefix` | string | yes | Component name prefix. Use `''` (empty string) to match all components. |
| `aws_secret_name` | string | no | Name of the AWS secret to use for S3 artefacts. Required when multiple AWS secrets are configured. |

Mapping configuration follows the same rules as [BDBA mappings](#mappings).

### Scanning Mode (`scan_target`)

Determines how Trivy scans each artefact:

- **`sbom_with_binary_fallback`** (default): Use an existing SBOM if available;
  fall back to a direct binary scan if no SBOM is found. Recommended for most use cases.

:::{note}
When using `sbom_with_binary_fallback` or `sbom`, Trivy will rely on SBOMs produced by other tools (e.g. Syft). Because Syft and Trivy use different SBOM formats and component representations, scan results may be inconsistent compared to a pure binary scan. When using `sbom_with_binary_fallback` consistence between scans depends on whether ODG already created a SBOM for the component at scan time.
:::

- **`sbom`**: Use an existing SBOM only. If an artefact does not have any SBOM, an exception is raised.

- **`binary`**: Always scan the binary directly, ignoring any available SBOM.
  Use this when you want to ensure Trivy re-analyses the binary itself.