You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tooling.apache.org by ar...@apache.org on 2026/09/15 17:12:48 UTC
(tooling-trusted-releases) branch arm updated: #1386 - update SBOM docs
This is an automated email from the ASF dual-hosted git repository.
alitheg pushed a commit to branch arm
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git
The following commit(s) were added to refs/heads/arm by this push:
new 269621f1 #1386 - update SBOM docs
269621f1 is described below
commit 269621f133d79e3b163ba6dbf7d96f2728a2945f
Author: Alastair McFarlane <ar...@apache.org>
AuthorDate: Tue Sep 15 18:12:21 2026 +0100
#1386 - update SBOM docs
---
atr/docs/developer-guide.md | 15 ++--
atr/docs/index.md | 1 +
atr/docs/resource-management.md | 2 +-
atr/docs/sbom-architecture.md | 106 +++++++++++++++++++++++++
atr/docs/sbom-workflows.md | 167 +++++-----------------------------------
5 files changed, 138 insertions(+), 153 deletions(-)
diff --git a/atr/docs/developer-guide.md b/atr/docs/developer-guide.md
index 2b82d33a..aedd7779 100644
--- a/atr/docs/developer-guide.md
+++ b/atr/docs/developer-guide.md
@@ -20,12 +20,15 @@
* `3.10.` [User interface](user-interface)
* `3.11.` [Tasks](tasks)
* `3.12.` [Authentication security](authentication-security)
-* `3.13.` [Authorization security](authorization-security)
-* `3.14.` [Input validation](input-validation)
-* `3.15.` [TLS security configuration](tls-security-configuration)
-* `3.16.` [API documentation policy](api-documentation-policy)
-* `3.17.` [ASFQuart usage](asfquart-usage)
-* `3.18.` [Resource management](resource-management)
+* `3.13.` [Sessions](sessions)
+* `3.14.` [Authorization security](authorization-security)
+* `3.15.` [Input validation](input-validation)
+* `3.16.` [Dependency updates](dependency-updates)
+* `3.17.` [TLS security configuration](tls-security-configuration)
+* `3.18.` [API documentation policy](api-documentation-policy)
+* `3.19.` [ASFQuart usage](asfquart-usage)
+* `3.20.` [Resource management](resource-management)
+* `3.21.` [SBOM architecture](sbom-architecture)
**Sections**:
diff --git a/atr/docs/index.md b/atr/docs/index.md
index c64027be..cf187feb 100644
--- a/atr/docs/index.md
+++ b/atr/docs/index.md
@@ -42,3 +42,4 @@ NOTE: This documentation is a work in progress.
* `3.18.` [API documentation policy](api-documentation-policy)
* `3.19.` [ASFQuart usage](asfquart-usage)
* `3.20.` [Resource management](resource-management)
+ * `3.21.` [SBOM architecture](sbom-architecture)
diff --git a/atr/docs/resource-management.md b/atr/docs/resource-management.md
index 53f21522..a7d7d9c6 100644
--- a/atr/docs/resource-management.md
+++ b/atr/docs/resource-management.md
@@ -4,7 +4,7 @@
**Prev**: `3.19.` [ASFQuart usage](asfquart-usage)
-**Next**: (none)
+**Next**: `3.21.` [SBOM architecture](sbom-architecture)
**Sections**:
diff --git a/atr/docs/sbom-architecture.md b/atr/docs/sbom-architecture.md
new file mode 100644
index 00000000..3e50d5ac
--- /dev/null
+++ b/atr/docs/sbom-architecture.md
@@ -0,0 +1,106 @@
+# 3.21. SBOM architecture
+
+**Up**: `3.` [Developer guide](developer-guide)
+
+**Prev**: `3.20.` [Resource management](resource-management)
+
+**Next**: (none)
+
+**Sections**:
+
+* [Overview](#overview)
+* [Current status](#current-status)
+* [The SBOM package](#the-sbom-package)
+* [The SBOM CLI](#the-sbom-cli)
+* [Package modules](#package-modules)
+* [External tools](#external-tools)
+* [How the server uses the package](#how-the-server-uses-the-package)
+* [The SBOM report](#the-sbom-report)
+* [Related documentation](#related-documentation)
+
+## Overview
+
+This page describes how ATR's SBOM support is put together, for developers working on ATR itself. For a release manager's view of what the SBOM features do and how to use them, see [SBOM workflows](sbom-workflows).
+
+ATR works with SBOMs in the CycloneDX format, stored as `.cdx.json` files (and other suffixes) that sit beside the artifact they describe. A project-supplied SBOM is always preferred. Most of the SBOM logic lives in its own package, `atr/sbom/`, which the ATR server drives through a set of background tasks. Only the read-only report is currently exposed in the UI; see [Current status](#current-status).
+
+## Current status
+
+Only the read-only SBOM report is currently reachable from the UI. A file that is a CycloneDX JSON SBOM gets a *View SBOM* button in a release's checks (`atr/get/checks.py`), which opens the report described below.
+
+The other workflows, generation, conversion, OSV scanning, and augmentation, are present in the code, as task handlers in `atr/tasks/sbom.py` and as routes in `atr/post/draft.py` and `atr/post/sbom.py`, but nothing in the UI triggers them, so they are dormant. The intention is to build these into external tooling rather than the server, which is what the package's own command line (below) is a step toward. The rest of this page describes the whole toolkit, dormant paths included, since t [...]
+
+## The SBOM package
+
+`atr/sbom/` is its own package with its own command line, so the SBOM operations can be driven directly, not only through the server. The standalone entry point is `python -m atr.sbom` (`__main__.py` just calls `cli.main()`), and `cli.py`'s `setup_cli_logging` wires the shared logging up to stderr, so a bare CLI run produces the same diagnostics as the in-server code.
+
+That standalone use is why the package's imports read differently from the rest of the codebase. Its modules refer to each other with relative, direct-name imports, for example `from .cyclonedx import validate_cli`, rather than the absolute, module-only style, `import atr.x as x`, that ATR uses everywhere else.
+
+The package is not fully decoupled from ATR, though. Its core imports `atr.util` (in `utilities.py` and `osv.py`) alongside `atr.log` and `atr.loggers`, and its `heatmap` and `observations` modules also pull in `atr.metadata` and `atr.models.results`. It is standalone in the sense of having a working command line, not in the sense of having no ATR dependencies.
+
+## The SBOM CLI
+
+`cli.py` is the standalone command line. It takes a command and an SBOM path:
+
+```shell
+python -m atr.sbom <command> <sbom-path>
+```
+
+The commands map onto the package's operations:
+
+* `license` - list the license warnings (Category B) and errors (Category X).
+* `missing` and `where` - list, and locate within the document, the NTIA 2021 fields an SBOM is missing.
+* `osv` - scan the components against OSV.
+* `outdated` - report an SBOM written by a known-outdated tool.
+* `patch-ntia` and `patch-vuln` - emit the JSON patch that would add the missing NTIA metadata, or the OSV findings.
+* `merge` - apply the NTIA patch and print the resulting document.
+* `scores` - print the sbomqs score, before and after an NTIA merge.
+* `validate-cli` and `validate-py` - validate the document, through the CycloneDX CLI and through the CycloneDX Python library respectively.
+
+## Package modules
+
+Each command is a thin wrapper over a module that does the work, and the ATR server calls those same modules directly:
+
+* `cyclonedx.py` validates a document two ways: `validate_cli` shells out to the external `cyclonedx` binary, and `validate_py` uses the CycloneDX Python library.
+* `conformance.py` checks a document against the NTIA 2021 minimum data fields.
+* `licenses.py` places each declared license into an ASF policy category.
+* `sbomqs.py` runs the sbomqs scorer.
+* `osv.py` looks components up in OSV.
+* `tool.py` detects an SBOM written by an outdated tool version.
+* `utilities.py` loads a file into a `Bundle`, builds the NTIA and vulnerability patches, applies them, and writes documents back out.
+* `components.py` reads a document into the component breakdown the report renders.
+* `models/` holds the typed models the rest of the package passes around, including `bundle`, `conformance`, `licenses`, and `components`.
+
+The package also carries `maven.py`, which maps a date to the Maven plugin version current at that time, `spdx.py`, an SPDX license-expression parser, and a `constants` subpackage.
+
+## External tools
+
+The package, and the tasks around it, drive several external tools:
+
+* **syft** generates a CycloneDX SBOM from an artifact. This runs in the task layer (`atr/tasks/sbom.py`) under the sandbox, not in the package. Generation is currently dormant (see [Current status](#current-status)).
+* the **CycloneDX CLI** (`cyclonedx`) validates documents, through `cyclonedx.py`'s `validate_cli`.
+* **sbomqs** scores documents, through `sbomqs.py`.
+* **OSV** supplies vulnerability data, through `osv.py`.
+
+The CycloneDX Python library is a direct dependency too, used for validation and for writing documents out.
+
+## How the server uses the package
+
+The ATR server wraps the package's operations as background [tasks](tasks):
+
+* `atr/tasks/sbom.py` holds the task handlers. It runs syft for generation, and calls into `atr/sbom/` for conversion, scoring, scanning, and augmentation. The task types include `SBOM_GENERATE_CYCLONEDX`, `SBOM_CONVERT`, `SBOM_TOOL_SCORE`, `SBOM_QS_SCORE`, `SBOM_OSV_SCAN`, and `SBOM_AUGMENT`.
+* `atr/storage/writers/sbom.py` queues those tasks as the acting committee member.
+* `atr/post/draft.py` holds the generation and conversion routes (each would land its output as a new revision), and `atr/post/sbom.py` holds the report's scan and augment routes. None of these is currently triggered from the UI (see [Current status](#current-status)).
+* `atr/analysis.py` classifies files, with `is_cyclonedx_json` and `is_cyclonedx_xml` gating which operations apply to a given file.
+
+## The SBOM report
+
+`atr/get/sbom.py` builds the report programmatically with `atr/htm.py` rather than a template. The `quality` handler serves `/sbom/quality/<project>/<version>/<file>` and is reached from a file's check row (see `atr/get/checks.py` and `check-selected-path-table.html`).
+
+The page reads the most recent `SBOM_TOOL_SCORE` task for the file at the release's latest revision, and reads the component breakdown straight from the SBOM through `atr/sbom/components.py`. It deliberately does not render a single headline score: it surfaces the component list, license categories, declared vulnerabilities, and the conformance, outdated-tool, and CycloneDX CLI findings, so a reader sees the underlying issues rather than a number.
+
+## Related documentation
+
+* [SBOM workflows](sbom-workflows) is the user-facing counterpart to this page.
+* [Tasks](tasks) explains the background task system these operations run on.
+* [Checks](checks) covers the wider check pipeline the SBOM report is reached from.
diff --git a/atr/docs/sbom-workflows.md b/atr/docs/sbom-workflows.md
index 7545c028..0948bfdc 100644
--- a/atr/docs/sbom-workflows.md
+++ b/atr/docs/sbom-workflows.md
@@ -9,170 +9,45 @@
**Sections**:
* [Overview](#overview)
-* [Supported SBOM operations](#supported-sbom-operations)
-* [Convert XML SBOM to JSON](#convert-xml-sbom-to-json)
-* [CycloneDX validation](#cyclonedx-validation)
-* [SBOM scoring and validation](#sbom-scoring-and-validation)
-* [Vulnerability scanning](#vulnerability-scanning)
-* [SBOM augmentation](#sbom-augmentation)
-* [Related interfaces](#related-interfaces)
+* [Reading the SBOM report](#reading-the-sbom-report)
* [Related documentation](#related-documentation)
## Overview
-ATR provides multiple Software Bill of Materials (SBOM) workflows based on the CycloneDX specification. These workflows help projects generate, validate, augment, convert, and analyze SBOM files for release artifacts.
+A Software Bill of Materials (SBOM) lists the components that make up a release artifact, so that consumers can see what they are pulling in and check it against known vulnerabilities and license policy. ATR works with SBOMs in the [CycloneDX](https://cyclonedx.org/) format, stored as JSON files with a `.cdx.json` extension.
-ATR integrates several external tools including:
+The best SBOM is one your own build produces, because it knows what actually went into the artifact. When your build produces a CycloneDX JSON SBOM, include it in your release alongside the artifact it describes, and ATR will check it and give you an SBOM report for that file, described below.
-* syft
-* CycloneDX CLI
-* sbomqs
-* OSV
+ATR reads the SBOMs you supply. Producing them, and converting them from other formats, is a job for your own build.
-These workflows are primarily implemented in the `atr/tasks/sbom.py` module and exposed through draft and report interfaces.
+## Reading the SBOM report
-## Supported SBOM operations
+While a release is being prepared, its checks list each file with its results. Any file that is a CycloneDX JSON SBOM carries a **View SBOM** button that opens its SBOM report. The report has two halves: what the SBOM says about the release (Content), and how well-formed the SBOM itself is (Quality). Some of it, the Licenses and Vulnerabilities below and the whole Quality section, appears only once ATR's SBOM checks have run for the file, so parts may be blank on a first look.
-ATR supports several SBOM workflows for generation, conversion, analysis, and augmentation.
+### Content
-### Generate CycloneDX SBOM
+**Components** lists what the SBOM declares is in the artifact, grouped by type, with each component's name, version, licenses, and package URL (PURL) where the SBOM records one. If the SBOM names an overall subject, the report says which component that is. An SBOM that declares no components is worth a second look, as it usually means the tool that wrote it could not see inside the artifact.
-ATR can generate a CycloneDX JSON SBOM from supported release artifacts including:
+**Licenses** places each declared license in a category of the [ASF third party license policy](https://www.apache.org/legal/resolved.html): Category A (permitted), Category B (permitted with conditions), or Category X (not permitted). The categories are read from the license strings the SBOM tool wrote into the file, and those strings can be wrong. A project can declare its license inaccurately in its build file, and an SBOM tool can map a license name to the wrong identifier. A license [...]
-* `.tar.gz`
-* `.tgz`
-* `.zip`
-* `.jar`
+So treat anything unexpected as something to check rather than a verdict. Look it up against the upstream project, then report a wrong declaration to that project, a wrong mapping to the SBOM tool, and a correctly spelled license that ATR fails to place, or places wrongly, to [ATR](https://github.com/apache/tooling-trusted-release/issues).
-SBOM generation uses the `syft` tool and produces `.cdx.json` files.
+Where a component offers a choice of licenses (an `OR` expression), ATR picks the friendliest category and shows the half it chose in colour, with the alternatives it set aside greyed out, so you can see what was on offer without the alternatives reading as a problem.
-Generation tasks are queued through:
+**Vulnerabilities** shows the known vulnerabilities recorded in the SBOM. An SBOM does not carry these unless whatever produced it added them, so this section is empty when the SBOM records none.
-* `atr/post/draft.py`
-* `atr/storage/writers/sbom.py`
+### Quality
-Core implementation:
+The Quality section reports on the SBOM document rather than the release:
-* `generate_cyclonedx`
-* `_generate_cyclonedx_core`
+* **Conformance** checks the SBOM against the NTIA 2021 minimum data fields and lists anything missing as warnings or errors.
+* **Outdated tool** flags an SBOM written by a tool version known to have problems.
+* **CycloneDX CLI validation** lists any structural or schema errors found in the file.
-## Convert XML SBOM to JSON
-
-ATR can convert CycloneDX XML SBOM files into JSON format.
-
-Supported input:
-
-* `.cdx.xml`
-
-Generated output:
-
-* `.cdx.json`
-
-Core implementation:
-
-* `convert_cyclonedx`
-* `_convert_cyclonedx_core`
-
-## CycloneDX validation
-
-ATR validates CycloneDX SBOM files using the CycloneDX CLI.
-
-Validation workflows detect:
-
-* schema violations
-* malformed SBOM structures
-* invalid metadata
-* specification compatibility issues
-
-Related modules include:
-
-* `atr/sbom/cyclonedx.py`
-
-## SBOM scoring and validation
-
-ATR performs several validation and scoring operations for CycloneDX SBOM files.
-
-These include:
-
-* CycloneDX CLI validation
-* NTIA 2021 conformance checks
-* license analysis
-* vulnerability analysis
-* tool version analysis
-
-License analysis places each declared license in a category of the [ASF third party license policy](https://www.apache.org/legal/resolved.html), reading the license strings that the SBOM tool wrote into the file. Those strings can be wrong. A project can declare its license inaccurately in its build file, and an SBOM tool can map a license name to the wrong identifier. A license that ATR does not recognise is treated as Category X. Check anything unexpected against the upstream project. [...]
-
-The scoring workflow is implemented through:
-
-* `score_tool`
-
-Related modules include:
-
-* `atr/sbom/conformance.py`
-* `atr/sbom/licenses.py`
-* `atr/sbom/cyclonedx.py`
-* `atr/sbom/sbomqs.py`
-
-## Vulnerability scanning
-
-ATR supports vulnerability analysis through OSV integration.
-
-The OSV workflow:
-
-* scans CycloneDX SBOM files
-* identifies known vulnerabilities
-* augments SBOM files with vulnerability information
-
-Core implementation:
-
-* `osv_scan`
-* `bundle_to_vuln_patch`
-
-Related modules:
-
-* `atr/sbom/osv.py`
-
-## SBOM augmentation
-
-ATR can augment existing SBOM files with additional metadata and NTIA-related properties.
-
-Augmentation workflows may generate updated revisions containing modified SBOM files.
-
-Core implementation:
-
-* `augment`
-* `bundle_to_ntia_patch`
-
-## Related interfaces
-
-SBOM functionality is exposed through several application layers.
-
-Task handlers:
-
-* `atr/tasks/sbom.py`
-
-POST endpoints:
-
-* `atr/post/sbom.py`
-* `atr/post/draft.py`
-
-GET interfaces:
-
-* `atr/get/sbom.py`
-
-Storage writers:
-
-* `atr/storage/writers/sbom.py`
-
-Templates:
-
-* `atr/templates/draft-tools.html`
-* `atr/templates/check-selected-path-table.html`
+The Quality section only has something to show once the checks behind it have run, so if it is empty, give it a moment and reload.
## Related documentation
-Additional SBOM-related behavior is described in:
-
-* [Checks](checks)
-* [Running the server](running-the-server)
-* [Overview of the code](overview-of-the-code)
+* [Checks](checks) covers the wider set of automated checks a release goes through, including how the SBOM report is reached.
+* [License checks](license-checks) explains the license checking that ATR applies to the release as a whole.
+* [SBOM architecture](sbom-architecture) describes how these workflows are built, for developers working on ATR itself.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tooling.apache.org
For additional commands, e-mail: commits-help@tooling.apache.org