Metadata-Version: 2.4
Name: bdsca-analysis-config-file
Version: 0.1.4
Summary: Tools and CLI for handling BDSCA analysis configuration file(s).
Author: Jouni Lehto
License-Expression: MIT
Project-URL: Homepage, https://github.com/lejouni/bdsca-analysis-config-file
Project-URL: Repository, https://github.com/lejouni/bdsca-analysis-config-file
Keywords: bdsca,analysis,config,yaml,cli
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: jsonschema>=4.17.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: black>=24.3.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: types-setuptools>=68.0.0.3; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Dynamic: license-file


# bdsca-analysis-config-file

Utilities and CLI to validate and work with BDSCA analysis configuration files (YAML).

Features implemented: validation, vulnerability triage, adding components by PURL, and overwriting component versions in the BOM.

## 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.
- Use `--output` to pretty-print the file in YAML, JSON, or summary format.
- Use `--target` to print 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]
```

- Adds missing components from `componentAdditions` to the BOM for each project in the config.
- Only the `purl` field is allowed in `componentAdditions.component`. Extra fields are rejected by schema validation.

Example config:

```
componentAdditions:
  - component:
      purl: pkg:pypi/sample@1.0.0
```

### 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.
- Use `--dryrun` to preview changes without making updates.

### 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 component versions.
- If `newVersion` is provided, the component's version in the project BOM is updated by resolving component versions and origins.
- Supports `--dryrun` to preview without making changes.

#### Examples

Minimal overrides using component name/vendor and newVersion:

```
specVersion: "1"
overrides:
  - component:
      name: Apache Commons IO
      version: "2.2"
      vendor: "maven"
    newVersion: "2.3"
  - component:
      name: node-semver
      version: "5.7.2"
      vendor: "npmjs"
    newVersion: "5.7.1"
  - component:
      name: AsciidoctorJ
      version: ""
      vendor: "maven"
    newVersion: "0.1.3"

changeTarget:
  - project:
      name: HippotechOrg/sampleapp
      version: "main"
```

Run in dry-run mode to preview:

```
bdsca-config overwrite examples/example4.yaml --base-url <BLACKDUCK_URL> --api-token <TOKEN> --dryrun
```

Notes:
- The `vendor` should match the origin name in Black Duck (e.g., `maven`, `npmjs`).
- If the component exists in the BOM and `newVersion` resolves to a valid component version/origin, the tool will construct and apply the version change; `--dryrun` previews without changing.
- PURL is not supported for the `overwrite` command; use component `name` (and optionally `version`) with `vendor` to target the correct origin.

### 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 Shape & Examples

- `specVersion`: "1"
- `changeTarget`: array of targets; each target is an object with a required project:

```
changeTarget:
  - project:
      name: example-project
      version: "1.0"
  - project:
      name: another-project
      version: "main"
```

- `vulnerabilityTriages` are specified at the top level and apply to all target projects:

```
vulnerabilityTriages:
  - component:
      name: lib-a
      vendor: vendor-a
      version: "1.2.3"
    triages:
      - cve: CVE-2024-0001
        resolution: PATCHED
        comment: fixed upstream
```

- `componentAdditions` for adding components by purl:

```
componentAdditions:
	- component:
			purl: pkg:pypi/sample@1.0.0
```

Overrides example:

```
overrides:
	- component:
			name: example-component
			vendor: ExampleVendor
			version: "1.0.0"
		newVersion: "1.0.1"
```

## 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 validation, remediation, and BOM addition
- Tests via pytest, lint via ruff and black, typing via mypy
- Pre-commit hooks and GitHub Actions CI

## Quickstart

Install in editable mode with dev tools and run tests:

```
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -U pip
pip install -e .[dev]
pytest
```

## Installation

To install the package locally after building:

```
python -m build
pip install dist/bdsca_analysis_config_file-<version>-py3-none-any.whl
```

Replace `<version>` with the actual version number (e.g. 0.1.2).

To install from PyPI or TestPyPI:

```
pip install bdsca-analysis-config-file
```

Or from TestPyPI:

```
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 the `remediate` or `overwrite` commands to preview changes without updating Black Duck.
- The CLI prints current values and the new values that would be applied.
- No PUT requests are sent in dry-run mode, and the command returns success if the preview steps complete.

## Target display

- Single project summary:

```
bdsca-config validate examples/example.yaml --output summary --target
...
target: project name='example-project' version='1.0'
```

- Multiple projects summary lists each project on its own line:

```
bdsca-config validate examples/example2.yaml --output summary --target
...
target:
  - project name='HippotechOrg/sampleapp' version='main'
  - project name='HippotechOrg/anotherapp' version='1.2.3'
```

## License

MIT © Jouni Lehto

## Release documentation

See the dedicated guide in `docs/release.md` for release workflow and options.
## Dry-run mode

- Use the `--dryrun` flag with the `remediate` command to see what would change without making any updates to Black Duck.
- For each matched vulnerable component, the CLI prints the current remediation status and comment alongside the new values that would be applied.
- No PUT requests are sent in dry-run mode, and the command returns success if the preview steps complete.
