# Vulnerability Scanner

The Vulnerability Scanner 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`. |

## 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
```