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¶

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:

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 to scan artefacts for vulnerabilities.

Configuration Example¶

trivy:
  interval: 86400
  on_unsupported: warning
  scan_target: sbom_with_binary_fallback

Top-Level Options¶

Option

Type

Default

Description

interval

int (seconds)

86400

Maximum time before a component is re-scanned.

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.

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.