bdsca-analysis-config-file 0.1.6
Tools and CLI for handling BDSCA analysis configuration file(s).
Requires Python: >=3.9
Keywords: bdsca, analysis, config, yaml, cli


# bdsca-analysis-config-file

Utilities and CLI to validate and work with BDSCA analysis configuration files (YAML).

This tool supports:
- Validating config files with friendly error output
- Adding missing components to a project BOM
- Overwriting component versions in the BOM
- Triaging vulnerabilities (by CVE or BDSA), including filters by vendor and SHA

It also supports dry-run mode to preview changes, and paginated search when resolving components by name/version.

## CLI usage

All commands are available via the `bdsca-config` CLI.

### Show version

```
bdsca-config --version
```

### Validate a YAML configuration file

```
bdsca-config validate <config.yaml> [--output yaml|json|summary] [--target]
```

- Validates the file and prints errors in a table if invalid.
- `--output` pretty-prints the file in YAML, JSON, or a concise summary.
- `--target` prints the effective change target (project info).

### Add missing components to BOM

```
bdsca-config add-components <config.yaml> --base-url <BLACKDUCK_URL> --api-token <TOKEN> [--insecure] [--verbosity info|debug] [--dryrun]
```

- Adds missing components from `componentAdditions` to each target project.
- Each `componentAdditions` entry can identify a component by:
  - purl
  - name (with optional version and vendor)

Examples:

```
componentAdditions:
  - component:
      purl: pkg:maven/org.apache.commons/commons-lang3@3.12.0
  - component:
      name: commons-io
      version: "2.13.0"
      vendor: maven
```

### Remediate vulnerabilities

```
bdsca-config remediate <config.yaml> --base-url <BLACKDUCK_URL> --api-token <TOKEN> [--insecure] [--verbosity info|debug] [--dryrun]
```

- Validates the file and performs remediation using Black Duck.
- `vulnerabilityTriages` can identify a component by any of:
  - purl
  - name + version
  - sha (file/component SHA)
- Each triage uses either `cve` or `bdsa`, plus a `resolution` and optional `comment`.
- `--dryrun` previews changes without making updates.

Example excerpt:

```
vulnerabilityTriages:
  - component:
      name: lodash
      version: "4.17.21"
      vendor: npmjs
    triages:
      - cve: CVE-2020-8203
        resolution: NOT_AFFECTED
        comment: Affected code not used
  - component:
      sha: 5e884898da28047151d0e56f8dc6292773603d0d
    triages:
      - bdsa: BDSA-2024-1234
        resolution: PATCHED
        comment: Fixed by upstream
```

### Overwrite component version

```
bdsca-config overwrite <config.yaml> --base-url <BLACKDUCK_URL> --api-token <TOKEN> [--insecure] [--verbosity info|debug] [--dryrun]
```

- Reads the `overrides` section and updates matching BOM components.
- A component can be identified by `purl` OR by `name` (with optional `version` and `vendor`).
- Set `newVersion` to the desired component version.
- `--dryrun` previews without making changes.

Example excerpt:

```
overrides:
  - component:
      name: Apache Commons IO
      version: "2.2"
      vendor: maven
    newVersion: "2.3"
  - component:
      purl: pkg:npm/semver@5.7.2
    newVersion: "5.7.1"
```

Notes:
- The `vendor` should match the origin name in Black Duck (e.g., `maven`, `npmjs`).
- The tool resolves component versions and origins; for name-based lookups it paginates results when necessary.

### Module usage

You can also run commands via Python module execution:

```
python -m bdsca_analysis_config_file --version
python -m bdsca_analysis_config_file validate examples/example.yaml
```

## Configuration reference

High-level structure:

```
specVersion: "1"
changeTarget:
  - project: { name: <string>, version: <string> }
componentAdditions: []
overrides: []
vulnerabilityTriages: []
```

Targets (one or more projects):

```
changeTarget:
  - project:
      name: example-project
      version: "1.0"
  - project:
      name: another-project
      version: "main"
```

Component additions:

```
componentAdditions:
  - component:
      purl: pkg:pypi/sample@1.0.0
  - component:
      name: sample-lib
      version: "2.0.0"
      vendor: maven
```

Overrides:

```
overrides:
  - component:
      name: example-component
      vendor: ExampleVendor
      version: "1.0.0"
    newVersion: "1.0.1"
```

Vulnerability triages:

```
vulnerabilityTriages:
  - component:
      purl: pkg:maven/org.example/foo@1.2.3
    triages:
      - cve: CVE-2024-0001
        resolution: PATCHED
        comment: fixed upstream
  - component:
      name: lib-a
      version: "1.2.3"
      vendor: vendor-a
    triages:
      - bdsa: BDSA-2024-1111
        resolution: IGNORED
        comment: Not in our threat model
  - component:
      sha: 0123456789abcdef0123456789abcdef01234567
    triages:
      - cve: CVE-2023-9999
        resolution: MITIGATED
        comment: Mitigated by sandboxing
```

See `examples/example_all.yaml` for a comprehensive sample covering all flows.

## Output examples

Single project summary:

```
bdsca-config validate examples/example.yaml --output summary --target
...
target: project name='example-project' version='1.0'
```

Multiple projects summary:

```
bdsca-config validate examples/example2.yaml --output summary --target
...
target:
  - project name='HippotechOrg/sampleapp' version='main'
  - project name='HippotechOrg/anotherapp' version='1.2.3'
```

## Features

- Modern `src/` layout with `pyproject.toml`
- CLI with validate, add-components, remediate, overwrite
- Tests via pytest; lint via ruff/black; typing via mypy
- Dry-run support for safe previews
- Pagination when searching components by name/version

## Quickstart

Install in editable mode and run tests:

```
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -U pip
pip install -e .[dev]
pytest
```

## Installation

Local build and install:

```
python -m build
pip install dist/bdsca_analysis_config_file-<version>-py3-none-any.whl
```

Replace `<version>` with the actual version (e.g., `0.1.2`).

From PyPI or TestPyPI:

```
pip install bdsca-analysis-config-file
```

or

```
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple bdsca-analysis-config-file
```

## Release documentation

See the dedicated guide in `docs/release.md` for release workflow and options.

## Dry-run mode

- Use the `--dryrun` flag with `remediate` or `overwrite` to preview changes.
- The CLI prints current values alongside the new values that would be applied.
- No PUT requests are sent in dry-run mode.

## License

MIT © Jouni Lehto