Analysis Configuration File

The analysis configuration file allows you to pass data and configuration options to the scanner while scanning an application. At the moment it supports adjusting component versions, triaging vulnerabilities and adding new components.

The analysis configuration file is in .yaml format.

Changelog

Deprecations:

  • specVersion 2 will be supported one year after the 2023.3.0 release, until 2024.3.0
  • specVersion 1 will be supported one year after the 2022.12.0 release, until 2023.12.0

New in specVersion 3:

  • supports adding new components to the BoM results
  • supports using a singleton codetype: key besides the previous codetypes: list
  • stricter parsing: keys and values disallowed by the spec in a certain place will lead to a parsing error instead of being silently ignored
  • stricter parsing: mistyped keys and values will lead to a parsing error instead of being silently ignored

New in specVersion 2:

  • Supports multiple analysis configuration files in a scanned application
  • When using purl, the original detected version is used in the component selector
  • The BDSA vulnerability type is added for triage
    • CVE or BDSA is required, but cannot be both
  • Added support for distro and distro version override
    • newVersion is now optional
    • newDistroVersion is added as optional
    • newDistro is optional
    • One of three above (newVersion, newDistroVersion, newDistro) is required

File upload

The analysis configuration file should be named .bdba.yaml or .bdba.yml and placed in an archive with the binary to be scanned.

SpecVersion 1:

archive.zip:
    firmware.bin
    .bdba.yaml

SpecVersion 2:

archive.zip:
archive.zip:
    ├── firmware0.bin
    ├── firmware1.bin
    ├── .bdba.yaml                # 1st -level - yaml_1
    └── sub-directory
        ├── firmware2.bin
        ├── .bdba.yaml            # 2nd -level - yaml_2
        ├── sub-directory2
        │   ├── firmware2_2.bin
        │   └── .bdba.yaml        # 3rd -level - yaml_3
        └── sub-directory3
            ├── firmware3.bin
            └── .bdba.yaml        # 3rd -level - yaml_4
Note:

If specVersion is set to 2, multiple configuration files are allowed. If specVersion is set to 1 and there are multiple specVersion 1 files in archive.zip, it will cause an error. Configuration files allow rules to apply on the same level or levels below in the directory structure. The path structure is important to make sure the correct file is affected, for example 1st level .bdba.yaml can affect the sub-directory3/firmware3.bin content but 3rd level .bdba.yaml will not have affect on 1st or 2nd level binaries! With purl matching components, the original detected version is used for detecting which component override will apply.

The uploaded file is visible in Details > Analysis Configuration File. You can copy the file by clicking on the copy icon in the right-hand corner. Black Duck Binary Analysis verifies the uploaded .yaml file and parses it for errors. You can also upload the file without a binary to verify its contents. The results of the verification are displayed on the Details tab. Possible errors are displayed on the Errors tab.

After an application has been scanned with the analysis configuration file, the config-file tag is displayed next to the vulnerability which has been overridden in Vulnerability Analysis > Components > Historical vulnerabilities.

File syntax

The top level of the file can contain these entries:

  • specVersion
  • overrides
  • vulnerabilityTriages
  • componentAdditions

Example of top level entries:

---
specVersion: "3"

overrides:
    ...
vulnerabilityTriages:
    ...
componentAdditions:
    ...

specVersion (REQUIRED)

Current version is 3 - which supports multiple configuration files. The older specVersion 1 is deprecated as it allowed only one configuration file in a scanned app. Note that different specVersion2 and specVersion3 files are allowed to be mixed together in one scan.

specVersion: "3"

overrides (OPTIONAL)

This key gives instructions for overriding some data for components found in the scan. Possible keys and values are: component, files, newVersion, forceVersion, newDistro, newDistroVersion, forceDistro.

---
specVersion: "3"

overrides:
  - component:
      <component>
    newVersion: "1.2.3"
    files:
      - <files>
    forceVersion true|false (default: false)
  - component:
      <component>
    newVersion: "x.y.z"
    newDistro: "distro-name"

The keys component and newVersion are required. files and forceVersion are optional.

component (REQUIRED)

component defines the component which the override or triage applies to. The available keys are name, version, codetype, vendor and purl. The minimum information needed for the component is component name as defined in the Black Duck Binary Analysis component database. You can either define the name in the name key, or as part of the package url in the purl key.

If both name and package url are defined and they conflict, the configuration entry is invalid and will be ignored.

name (OPTIONAL)

Component name as defined in Black Duck Binary Analysis component database. Value is a string with the maximum length of 255 characters.

codetype or codetypes (OPTIONAL)

A codetype or list of codetype strings. The allowed codetype options are:

  • native
  • java
  • dotnet
  • go
  • python
  • ruby
  • distro-package
  • javascript
  • cocoapod

If codetypes are defined, the overrides/triages only apply to components that are in one of the defined codetypes. If no codetype is given, overrides and triages will match to components of all codetypes.

Example:

- component:
      name: curl
      codetype: native
  - component:
      name: openssl
      codetypes:
        - native
        - distro-package

vendor (OPTIONAL)

vendor value is a string with the maximum length of 255 characters that defines the vendor of the component as is defined in the Black Duck Binary Analysis component database. If a vendor is defined, any component that does not have that specific vendor will be ignored for the override/triage.

Example:

 - component:
      name: openssl
      vendor: openssl

purl (OPTIONAL)

Alternatively to above notation, you can specify a component using the package url (purl) format: https://github.com/package-url/purl-spec Note that previously mentioned component keys cannot be combined with a purl.

Example:

- component:
      purl: pkg:deb/debian/dpkg@1.19.0.4?arch=amd64&distro=stretch
  - component:
      purl: pkg:generic/openssl@1.0.1

version (OPTIONAL)

Component version as a string with the maximum length of 255 characters. Only applies the override/triage to component with this specific version. If this entry is missing, default behavior is to apply to all versions.

newVersion (REQUIRED in V1 - OPTIONAL in V2)

newVersion will override the component version. The version is a string with a maximum length of 255 characters.

newDistro (OPTIONAL in V2)

newDistro will override the found distro. The distro name is a string with a maximum length of 255 characters.

newDistroVersion (OPTIONAL in V2)

newDistroVersion will override the distro version. The version is a string with a maximum length of 255 characters.

Note: This override will only be applied if distro is set by the scanner or by another override.

forceVersion (OPTIONAL)

Set forceVersion to true to apply the version even if the scanner finds a version for the component. Default value is false.

forceDistro (OPTIONAL in V2)

Set forceDistro to true to apply a distro or distro version override even if the scanner finds a distro or distro version for the component. Default value is false.

Example:

---
specVersion: "3"

overrides:
  - component:
      name: "zlib"
      
    newDistro: "ubuntu"
    newDistroVersion: "22.4"
    forceDistro: true

files (OPTIONAL)

Select files for which to apply overrides, if the given component is found from those files. If no files are defined, the override will apply to every component that fits the component definition.

The available file selectors are sha1 and path. One of them needs to be defined, and you can define multiple hashes and multiple paths. If the finding matches any of the sha1 or path entries, the override applies, that is, they are alternatives.

sha1 is the sha1 hash of a file. The value is a string with the length of 40 characters. path is a file path of a file or multiple files. It supports glob patterns, and to point to a specific archive you can use // as archive level separator.

Note:

With specVersion 2 path and sha1 are seen as relative to the analysis configuration file path within the scanned application file structure.

Examples:

overrides:
  - component:
      name: "zlib"
      
    files:
      - sha1: e4e2a7d143f9d976ced74f224cdbedb9be414d9c
      - path: usr/bin/bash
      - path: usr/lib/libssl*.so
      - path: archive.zip//sub-archive.zip//usr/lib/*

vulnerabilityTriages (OPTIONAL)

Instructions for triaging vulnerabilities in components found in the scan. The keys available for vulnerabilityTriages are component and triages, both are required. For the format of component key see the dedicated section.

Example:

---
specVersion: "3"

vulnerabilityTriages:
  - component:
      name: libtiff
      version: "4.0.6"

    triages:
      - cve: CVE-2021-2334  # mandatory

triages (REQUIRED)

A list of entries, which define what will be triaged and the resolution for the triage. The possible entries are listed below. The dictionary requires a cve or bdsa entry. It has two optional keys: resolution and comment.

cve (REQUIRED)

The value for cve is a CVE identifier for a specific vulnerability. For now only public cve's are supported, vendor vulnerabilities may be added in the future.

- cve: CVE-2014-0160

bdsa (OPTIONAL in V2)

The value is a Black Duck Security Advisory (BDSA) identifier for a specific vulnerability.

- bdsa: BDSA-2021-2489

resolution (OPTIONAL, default value: PATCHED)

Reason for why a vulnerability was resolved. Supports the following string values:

  • FalsePositive
  • Patched
  • NotAffected
  • WontFix
  • Ignored
  • Mitigated

If no resolution is defined, the default value is Patched. The values are case-insensitive.

comment (OPTIONAL)

Any optional comments for the triage. A string with the maximum length of 500 characters.

specVersion 2

If a vulnerability triage is created for the same component in multiple files for the same version they are all merged under one component since currently mapping vulnerabilities to separate files is not supported.

componentAdditions (OPTIONAL)

A list of components to add to the Bill of Material (BoM) of the scan results. This is done by specifying the component information and optionally the file paths or file content fingerprints that the components are located in. If no file paths are specified for a component or those files do not exist in the scanned application, the location of the component will be mapped to the path of the .bdba.yaml file itself.

For the format of the component and files entries see the dedicated sections. Additionally, it is possible to add a comment that describes in free form text the rationale of the component addition.

---
specVersion: "3"

componentAdditions:
  - component:
      name: "libtiff"
      version: "3.0.6"
      codetype: native
    files:
      - path: "*/usr/lib/libtiff*"
  - component:
      purl: "pkg:deb/debian/curl@7.50.3-1?arch=i386&distro=jessie"
    files:
      - sha1: d6e908f589e30a3aeb95964705700d0d4821fd8e
  - component:
      name: "testlib"
      codetype: java
    comment: "In-house library used for testing"

Full configuration file and schema examples

Example of a full configuration file:

---
specVersion: "3"

overrides:
  - component:
      name: "zlib"
      vendor: "zlib"
      codetype: native
    files:
      - path: "archive.zip"
    newVersion: "1.1.0"
    forceVersion: true
  - component:
      purl: "pkg:pypi/django"
    files:
      - sha1: d6e908f589e30a3aeb95964705700d0d4821fd8e
    newVersion: "1.11.1"

vulnerabilityTriages:
  - component:
      name: "zlib"
      vendor: "zlib"
      codetype: native
      version: "1.1.0"
    triages:
      - cve: CVE-2020-1223
        resolution: Patched
        comment: "Fixed with custom patch."
  - component:
      purl: "pkg:pypi/django"
    triages:
      - cve: CVE-2020-1000

componentAdditions:
  - component:
      name: testlib
      codetype: java
    comment: "In-house library used for testing"
  - component:
      name: MyMiddleWare
      version: "1.0.5"
      vendor: MyCorp
    comment: "Very important middleware"
  - component:
      name: libtiff
      version: "4.0.6"
    files:
      - sha1: d6e908f589e30a3aeb95964705700d0d4821fd8e
  - component:
      name: libtiff
      version: "3.0.6"
      codetype: native
    files:
      - path: "*/usr/lib/libtiff*"
  - component:
      purl: "pkg:generic/openssl@1.1.10g?download_url=https://openssl.org/source/openssl-1.1.0g.tar.gz&checksum=sha256:de4d501267da"
  - component:
      purl: "pkg:deb/debian/curl@7.50.3-1?arch=i386&distro=jessie"
  - component:
      purl: "pkg:gem/jruby-launcher@1.1.2?platform=java"
    files:
      - path: "ruby/jruby.dll"
  - component:
      purl: "pkg:maven/org.apache.xmlgraphics/batik-anim@1.9.1?packaging=sources"
  - component:
      purl: "pkg:pypi/django@1.11.1"
  - component:
      purl: "pkg:cocoapods/ShareKit@2.0#Twitter"

Schema of the analysis configuration file (specVersion 3):

---
specVersion: "3"

overrides:                          # OPTIONAL
  - component:
      name: <string:255>            # component name from BDBA KB
      codetype: native | java | dotnet | go | python | ruby | distro-package | javascript | cocoapod  # OPTIONAL
      codetypes:                    # OPTIONAL - DEFAULT: all of below
        - native | java | dotnet | go | python | ruby | distro-package | javascript | cocoapod
      vendor: <string:255>          # OPTIONAL - component vendor from BDBA KB
      version: <string:255>         # OPTIONAL - version found by scanner
    files:                          # OPTIONAL - DEFAULT: all files/paths
      - path: <string:5000>         # Unix style path supporting shell globbing
      - sha1: <string:40>
    # one of following fields newVersion, newDistro or newDistroVersion is REQUIRED
    newVersion: <string:255>        # OPTIONAL - new version to override with
    forceVersion: true | false      # OPTIONAL - DEFAULT: false
    newDistroVersion: <string:255>  # OPTIONAL - new distro version to override with
    newDistro: <string:255>         # OPTIONAL - new distro name to override with
    forceDistro: true | false       # OPTIONAL - DEFAULT: false
  - component:
      purl: <string:255>            # component identifier as Package URL
    files:                          # OPTIONAL - DEFAULT: all files/paths
      - path: <string:5000>         # Unix style path supporting shell globbing
      - sha1: <string:40>
    # one of following fields newVersion, newDistro or newDistroVersion is REQUIRED
    newVersion: <string:255>        # OPTIONAL - new version to override with
    forceVersion: true | false      # OPTIONAL - DEFAULT: false
    newDistroVersion: <string:255>  # OPTIONAL - new distro version to override with
    newDistro: <string:255>         # OPTIONAL - new distro name to override with
    forceDistro: true | false       # OPTIONAL - DEFAULT: false

vulnerabilityTriages:               # OPTIONAL
  - component:
      purl: <string:255>            # component identifier as Package URL
      triages:
      # either bdsa or cve is required, but not both
      - bdsa: <string>              # BDSA-xxxx-xxxx ( OPTIONAL )
      - cve: <string>               # CVE-xxxx-xxxx  ( OPTIONAL )
        resolution: FalsePositive | Patched | NotAffected | WontFix | Ignored | Mitigated  # OPTIONAL - DEFAULT: Patched
        comment: <string:500>       # OPTIONAL - free form comment

  - component:
      name: <string:255>
      codetype: native | java | dotnet | go | python | ruby | distro-package | javascript | cocoapod
      version: <string:255>
      vendor: <string:255>
    triages:
      # either bdsa or cve is required, but not both
      - bdsa: <string>              # BDSA-xxxx-xxxx ( OPTIONAL )
      - cve: <string>               # CVE-xxxx-xxxx  ( OPTIONAL )
        resolution: FalsePositive | Patched | NotAffected | WontFix | Ignored | Mitigated  # OPTIONAL - DEFAULT: Patched
        comment: <string:500>       # OPTIONAL - free form comment

componentAdditions:                 # OPTIONAL
  - component:
      purl: <string:255>            # component identifier as Package URL
    files:                          # OPTIONAL - DEFAULT: all files/paths
      - path: <string:5000>         # Unix style path supporting shell globbing
      - sha1: <string:40>
  - component:
      name: <string:255>
      codetype: native | java | dotnet | go | python | ruby | distro-package | javascript | cocoapod
      version: <string:255>
      vendor: <string:255>
    files:                          # OPTIONAL - DEFAULT: all files/paths
      - path: <string:5000>         # Unix style path supporting shell globbing
      - sha1: <string:40>

Schema of the analysis configuration file (specVersion 2):

---
specVersion: "2"

overrides:                  # OPTIONAL
  - component:
      name: <string:255>        # component name from BDBA KB
      codetypes:                # OPTIONAL - DEFAULT: all of below
        - native | java | dotnet | go | python | ruby | distro-package | javascript | cocoapod
      vendor: <string:255>      # OPTIONAL - component vendor from BDBA KB
      version: <string:255>     # OPTIONAL - version found by scanner
    files:                    # OPTIONAL - DEFAULT: all files/paths
      - path: <string:5000>     # Unix style path supporting shell globbing
      - sha1: <string:40>
    # one of following fields newVersion, newDistro or newDistroVersion is REQUIRED
    newVersion: <string:255>  # OPTIONAL - new version to override with
    forceVersion: true | false  # OPTIONAL - DEFAULT: false
    forceDistro: true | false  # OPTIONAL - DEFAULT: false
    newDistroVersion: <string:255>  # OPTIONAL - new distro version to override with
    newDistro: <string:255>  # OPTIONAL - new distro name to override with
  - component:
      purl: <string:255>        # component identifier as Package URL
    newVersion: <string:255>
    forceVersion: true | false

vulnerabilityTriages:       # OPTIONAL
  - component:
      purl: <string:255>        # component identifier as Package URL
    triages:
      # either bdsa or cve is required, but not both
      - bdsa: <string>              # BDSA-xxxx-xxxx ( OPTIONAL )
      - cve: <string>               # CVE-xxxx-xxxx  ( OPTIONAL )
        resolution: FalsePositive | Patched | NotAffected | WontFix | Ignored | Mitigated  # OPTIONAL - DEFAULT: Patched
        comment: <string:500>       # OPTIONAL - free form comment

  - component:
      name: <string:255>
      codetypes:
        - native | java | dotnet | go | python | ruby | distro-package | javascript | cocoapod
      version: <string:255>
      vendor: <string:255>
    triages:
      # either bdsa or cve is required, but not both
      - bdsa: <string>          # BDSA-xxxx-xxxx ( OPTIONAL )
      - cve: <string>           # CVE-xxxx-xxxx  ( OPTIONAL )
        resolution: FalsePositive | Patched | NotAffected | WontFix | Ignored | Mitigated  # OPTIONAL - DEFAULT: Patched
        comment: <string:500>     # OPTIONAL - free form comment

Schema of the analysis configuration file (specVersion 1):

---
specVersion: "1"

overrides:                  # OPTIONAL
  - component:
      name: <string:255>        # component name from BDBA KB
      codetypes:                # OPTIONAL - DEFAULT: all of below
        - native | java | dotnet | go | python | ruby | distro-package | javascript | cocoapod
      vendor: <string:255>      # OPTIONAL - component vendor from BDBA KB
      version: <string:255>     # OPTIONAL - version found by scanner
    files:                    # OPTIONAL - DEFAULT: all files/paths
      - path: <string:5000>     # Unix style path supporting shell globbing
      - sha1: <string:40>
    newVersion: <string:255>  # new version to override with
    forceVersion: true | false  # OPTIONAL - DEFAULT: false
  - component:
      purl: <string:255>        # component identifier as Package URL
    newVersion: <string:255>
    forceVersion: true | false

vulnerabilityTriages:       # OPTIONAL
  - component:
      purl: <string:255>        # component identifier as Package URL
    triages:
    - cve: <string>           # CVE-xxxx-xxxx
        resolution: FalsePositive | Patched | NotAffected | WontFix | Ignored | Mitigated  # OPTIONAL - DEFAULT: Patched
        comment: <string:500>     # OPTIONAL - free form comment

  - component:
      name: <string:255>
      codetypes:
        - native | java | dotnet | go | python | ruby | distro-package | javascript | cocoapod
      version: <string:255>
      vendor: <string:255>
    triages:
      - cve: <string>           # CVE-xxxx-xxxx
        resolution: FalsePositive | Patched | NotAffected | WontFix | Ignored | Mitigated  # OPTIONAL - DEFAULT: Patched
        comment: <string:500>     # OPTIONAL - free form comment