@conterra/vuln-scan 1.0.10 → 1.0.11

package/README.md

@@ -1,609 +1,489 @@
-# ct-vuln-scan
-
-The utility is a wrapper around the following tools:
-
-- [grype](https://github.com/anchore/grype) - Vulnerability scanner for container images and filesystems.
-- [trivy](https://github.com/aquasecurity/trivy) - Comprehensive and versatile security scanner
-- [oss index](https://ossindex.sonatype.org/) - Free catalogue of open source components and scanning tools to help developers identify vulnerabilities
-
-It also supports the [OpenVex](https://github.com/openvex) specification for vulnerability status and justification.
-
-## Pre-Requisites
-
-You need to have `docker` and `node/npm` installed on your machine.
-
-## Installation
-
-The utility is available as an npm package it can be installed globally or locally.
-
-For global installation use:
-
-```sh
-$ npm install -g @conterra/vuln-scan
-```
-
-For local installation use:
-
-```sh
-$ npm install @conterra/vuln-scan
-```
-
-or reference it in your `package.json` file:
-
-```json
-{
-    "dependencies": {
-        "@conterra/vuln-scan": "<current version>"
-    }
-}
-```
-
-After that you have following commands available:
-
-- `ct-vuln-scan`
-    - Triggers the vulnerability scan
-- `ct-vuln-add-vex`
-    - Triggers a process to add a new vex statement to a file
-- `ct-vuln-add-project`
-    - Adds a new project to the configuration file based on an existing project entry and adds it to all vex statements
-- `ct-vuln-remove-project`
-    - Removes a project from the configuration file and all vex statements related to the project.
-    - Or removes a project from all vex statements matching a given vulnerability id.
-- `ct-vuln-add-project-to-vex`
-    - Update vex files to include a new project version. The project is added to each vex file that references the existing project version given.
-    - This step is already included in the `ct-vuln-add-project` command, but it can be run separately to update the vex files for an already existing project entry in the configuration file.
-- `ct-vuln-jira-report`
-    - Reads a `scan-summary.json` produced by `ct-vuln-scan` and creates Jira issues for newly detected vulnerabilities.
-    - Issues are only created when no existing issue with the same vulnerability ID already exists in the target Jira project.
-    - Routing rules in a `jira.json` file control which scan projects are reported to which Jira projects.
-
-### Vulnerability scan
-
-The `ct-vuln-scan` command can be used to scan one or many projects for vulnerabilities.
-It uses the configured scanners to analyze a projects `sbom` file and produces aggregated results.
-The `sbom` file can be provided as a local file or fetched from a maven repository.
-
-You might for example prepare a folder structure like this:
-
-```plain
-/vuln-scan/              # root folder
-├── vuln-scan-conf.json  # configuration file for projects to scan
-├── input                # input to be processed by the scanners
-│   └── sbom             # sbom files
-│   └── vex              # vex files
-│── output               # folder for aggregated scan results
-```
-
-Running the command `ct-vuln-scan` from the root folder will scan all projects defined in the `vuln-scan-conf.json` file.
-By default, output will created in the `output` folder per project.
-
-In the output folder different files per project are generated, see below.
-There are also tow summary files directly in the output folder:
-
-- `scan-summary.txt`
-    - A text file with a summary of the scan results.
-    - It contains the console "scan summary" output, which is printed to the console during the scan.
-- `scan-summary.json`
-    - A json file with a summary of the scan results.
-    - This can be used to post-process the scan results or to integrate them into other tools.
-    - Example:
-
-    ```json
-    {
-        "errors": [
-            {
-                "project": "mapapps@4.18.2",
-                "error": "Failed to fetch sbom file from maven repository: https://repository.conterra.de/repository/maven-mirror-ct/de/conterra/mapapps/ct-mapapps-rollout/4.18.2/ct-mapapps-rollout-4.18.2-sbom.cdx.json"
-            }
-        ],
-        "vulnerabilities": {
-            "CVE-2025-48988": {
-                "id": "CVE-2025-48988",
-                "severity": "HIGH",
-                "title": "tomcat: Apache Tomcat DoS in multipart upload",
-                "description": "Allocation of Resources Without Limits or Throttling vulnerability in Apache Tomcat.\n\nThis issue affects Apache Tomcat: from 11.0.0-M1 through 11.0.7, from 10.1.0-M1 through 10.1.41, from 9.0.0.M1 through 9.0.105.\n\nUsers are recommended to upgrade to version 11.0.8, 10.1.42 or 9.0.106, which fix the issue.",
-                "components": [
-                    "pkg:maven/org.apache.tomcat.embed/tomcat-embed-core@10.1.41"
-                ],
-                "refs": [
-                    "https://avd.aquasec.com/nvd/cve-2025-48988",
-                    "https://github.com/advisories/GHSA-h3gc-qfqq-6h8f"
-                ]
-            },
-            "CVE-2025-49125": {
-                "id": "CVE-2025-49125",
-                "severity": "MEDIUM",
-                "title": "tomcat: Apache Tomcat: Security constraint bypass for pre/post-resources",
-                "description": "Authentication Bypass Using an Alternate Path or Channel vulnerability in Apache Tomcat.  When using PreResources or PostResources mounted other than at the root of the web application, it was possible to access those resources via an unexpected path. That path was likely not to be protected by the same security constraints as the expected path, allowing those security constraints to be bypassed.\n\nThis issue affects Apache Tomcat: from 11.0.0-M1 through 11.0.7, from 10.1.0-M1 through 10.1.41, from 9.0.0.M1 through 9.0.105.\n\nUsers are recommended to upgrade to version 11.0.8, 10.1.42 or 9.0.106, which fix the issue.",
-                "components": [
-                    "pkg:maven/org.apache.tomcat.embed/tomcat-embed-core@10.1.41"
-                ],
-                "refs": [
-                    "https://avd.aquasec.com/nvd/cve-2025-49125",
-                    "https://github.com/advisories/GHSA-wc4r-xq3c-5cf3"
-                ]
-            }
-        },
-        "vulnerabilityToProject": {
-            "CVE-2025-48988": ["smartfinder-sdi@2.7.1-SNAPSHOT"],
-            "CVE-2025-49125": ["smartfinder-sdi@2.7.1-SNAPSHOT"]
-        },
-        "projectToVulnerability": {
-            "smartfinder-sdi@2.7.1-SNAPSHOT": [
-                "CVE-2025-48988",
-                "CVE-2025-49125"
-            ]
-        },
-        "noLongerDetectedVulnerabilities": {
-            "CVE-2023-52070": [
-                "mapapps@4.19.3-SNAPSHOT",
-                "smartfinder-sdi@2.7.1-SNAPSHOT"
-            ]
-        }
-    }
-    ```
-
-## Configuration
-
-You need to create a `vuln-scan-conf.json` file in the root of your project.
-
-A minimal configuration file specifies only the project to scan:
-
-```json
-{
-    "$schema": "./node_modules/@conterra/vuln-scan/dist/schema/conf-schema.json",
-    "projects": [
-        {
-            "name": "mapapps",
-            "version": "4.18.2",
-            "purl": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.18.2",
-            "sbomFile": "./input/sboms/mapapps-4.18.2.cdx.json"
-        }
-    ]
-}
-```
-
-The following sample lists all available options with their default values:
-
-```json
-{
-    "$schema": "./node_modules/@conterra/vuln-scan/dist/schema/conf-schema.json",
-
-    /* Defines if the process should fail or only log a warning or ignore vulnerabilities.
-       If "fail" exit 1 is called.
-       If "warn" the log statement "##vso[task.complete result=SucceededWithIssues;] is issued.
-       If "ignore" nothing happens.
-    */
-    "onNewVulnerabilities": "fail",
-    /* Defines if the process should fail or only log a warning or ignore no longer detected vulnerabilities.
-       If "fail" exit 1 is called.
-       If "warn" the log statement "##vso[task.complete result=SucceededWithIssues;] is issued.
-       If "ignore" nothing happens.
-    */
-    "onNoLongerDetectedVulnerabilities": "ignore",
-    /* The maven repository to fetch sboms from.
-       If the maven repository requires authentication, the environment variables MAVEN_REPO_USER and MAVEN_REPO_PW must be set.
-    */
-    "mavenRepo": "https://repository.conterra.de/repository/maven-mirror-ct",
-    /* The list of scanners to use. Possible values are "grype", "trivy" and "ossindex".
-       Use an optional version number to pin the scanner to a certain version, e.g. `trivy@0.69.3`.
-    */
-    "scanners": ["grype", "trivy", "ossindex"],
-    /* (optional) The list of vex files to download. Default is empty array. */
-    "vexUrls": ["https://example.com/my-vex.json"],
-    /* The directory where the vex files are stored. */
-    "vexDir": "./input/vex",
-    /* The directory where the scan results are written to. */
-    "outDir": "./output",
-    /* The directory where the cache of the grype and trivy is stored. Both tools maintain databases, which are downloaded and stored in the cache directory. */
-    "cacheDir": "./cache",
-    /* Flag if true then for each project a sub  directory is created in the output directory. 
-       If false all files are directly stored in the output dir without a subfolder structure.
-    */
-    "createSubDirsForProject": true,
-    /* (optional) Defines how the console output is reported.
-       Possible values are:
-       - "BY_PROJECT_DETAILED" (default): order by project and print cve details
-       - "BY_PROJECT" : order by project but do not print cve details
-       - "BY_CVE" : order by cve and print cve details
-       - "BY_CVE_DETAILED": order by cve but do not print cve details
-     */
-    "consoleReport": "BY_PROJECT_DETAILED",
-    /* The list of projects to scan. */
-    "projects": [
-        {
-            "name": "mapapps",
-            "version": "4.18.3",
-            /* identifier of the project in the vex files, used to filter the vex statements. */
-            "purl": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.18.3",
-            /* The maven coordinates of the sbom file, used to download the file from the maven remote repository. */
-            "sbomMavenCoordinates": "de.conterra.mapapps:ct-mapapps-rollout:4.18.3:sbom"
-        },
-        {
-            "name": "mapapps",
-            "version": "4.18.2",
-            "purl": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.18.2",
-            /* The location of the sbom file. */
-            "sbomFile": "./input/sboms/mapapps-4.18.2.cdx.json"
-        },
-        {
-            "name": "mapapps-sample-disabled",
-            "version": "4.17.0",
-            /* this project is disabled and not scanned */
-            "enabled": false,
-            "purl": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.17.0",
-            "sbomFile": "./input/sboms/mapapps-4.17.0.cdx.json"
-        },
-        {
-            "name": "mapapps-sample-silent",
-            "version": "4.17.2",
-            /* this project is scanned, but detected vulnerabilities are ignored and will never break the build */
-            "silent": true,
-            "purl": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.17.2",
-            "sbomFile": "./input/sboms/mapapps-4.17.2.cdx.json"
-        },
-        {
-            "name": "mapapps-sample-with-minium-severity",
-            "version": "4.17.2",
-            /* This project is scanned, but only vulnerabilities with a severity >= HIGH will break the build
-               Available values are: "CRITICAL", "HIGH", "MEDIUM", "LOW", "UNKNOWN"
-            */
-            "minimumSeverity": "HIGH",
-            "purl": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.17.2",
-            "sbomFile": "./input/sboms/mapapps-4.17.2.cdx.json"
-        }
-    ]
-}
-```
-
-## Usage - Scan
-
-To scan all projects run following command in the directory where the configuration file is located:
-
-```sh
-$ ct-vuln-scan
-```
-
-To scan a specific project run following command:
-
-```sh
-$ ct-vuln-scan mapapps 4.18.2
-```
-
-To scan all versions of a project run:
-
-```sh
-$ ct-vuln-scan mapapps
-```
-
-You may need following environment variables for a successful scan:
-
-```bash
-# (optional) to fetch sboms from maven repository
-MAVEN_REPO_USER=[username]
-MAVEN_REPO_PW=[password]
-
-# (optional) for oss index authenticated api
-OSS_INDEX_API_USER=[username] # sonatype guide api user name
-OSS_INDEX_API_TOKEN=[token]  # sonatype guide api token
-OSS_INDEX_BASE_URL=[url] # default since 1.0.8 is "https://api.guide.sonatype.com", before that it was "https://ossindex.sonatype.org",
-
-# (optional) for authentication downloading vex files specified by vexUrls option
-VEX_URLS_USER=[username]
-VEX_URLS_PW=[password]
-
-# (optional) helps to fix the rate limit issue during downloading the trivy database from github
-# See <https://aquasecurity.github.io/trivy/v0.38/docs/references/troubleshooting/#github-rate-limiting>
-TRIVY_GITHUB_TOKEN=[token]
-
-# (optional) to enable verbose logging, otherwise only scan results are printed
-VERBOSE=true
-
-# (optional) flag to enable automatic removal of unused statements in the vex files, during a scan.
-AUTO_REMOVE_UNUSED_STATEMENTS=true
-
-```
-
-NOTE: This variables can be set in the `.env` file in the root of the project.
-
-For each project following files are created in the `output` folder:
-
-- `<project-name>-<project-version>-sbom.cdx.json`
-    - Copy of the sbom file.
-- `<project-name>-<project-version>-scan-grype-results.json`
-    - Result of the grype scanner in the grype json format.
-- `<project-name>-<project-version>-scan-trivy-results.json`
-    - Result of the trivy scanner in the trivy json format.
-- `<project-name>-<project-version>-scan-ossindex-results.json`
-    - Result of the sonatype oss index api requests in json format.
-- `<project-name>-<project-version>-scan-aggregated-results.json`
-    - Aggregations of the results of all scanners in an own `@conterra/vuln-scan` json format.
-- `<project-name>-<project-version>-scan-aggregated-results.sarif.json`
-    - Aggregations of the results of all scanners in an own [sarif json](https://sarifweb.azurewebsites.net/) format.
-- `<project-name>-<project-version>-openvex.vex.json`
-    - Aggregation of all vex statements available for the project.
-
-If the `createSubDirsForProject` flag is set to `true`, the scanner will create a sub directory in the `output` folder named `<project-name>-<project-version>` for each project scanned.
-
-### Azure DevOps Pipelines Integration
-
-Attach the output directory as build artifact `CodeAnalysisLogs`.
-
-```yaml
-- task: PublishBuildArtifacts@1
-  inputs:
-      PathtoPublish: "output"
-      ArtifactName: "CodeAnalysisLogs"
-```
-
-Make sure that your Azure DevOps organization has the extension [SARIF SAST Scans Tab](https://marketplace.visualstudio.com/items?itemName=sariftools.scans) installed.
-This extension visualizes the `.sarif.json` files which are part of the `CodeAnalysisLogs`.
-
-If the configuration option `failOnNewVulnerabilities` flag is set to `false`, the pipeline will be set to `SucceededWithIssues` if vulnerabilities are found with no matching vex statement.
-Otherwise the pipeline will be set to `Failed` (because of exit code 1).
-
-## Usage - Add Vex
-
-This is a currently experimental maintenance workflow, where you want to make a decision if a vulnerability is affecting your project or not or if you currently investigating a vulnerability.
-
-To add a new `CVE-<>.json` file in the `vexDir`, run:
-
-```sh
-$ ct-vuln-add-vex
-```
-
-And follow the instructions.
-
-This will create a new `CVE-[id].json` file in the `vexDir` folder.
-
-A `CVE-2023-52070.json` file may look like this:
-
-```json
-{
-    "@context": "https://openvex.dev/ns/v0.2.0",
-    "@id": "https://openvex.dev/docs/public/vex-fc763e6eb63bfbcda20b7cbbddd4e9f8feaaa317fe8d8a6f51a5663a1180343e",
-    "author": "conterra",
-    "timestamp": "2024-10-01T18:54:23.3233227+02:00",
-    "last_updated": "2024-10-01T19:58:13.2159221+02:00",
-    "version": 2,
-    "statements": [
-        {
-            "vulnerability": {
-                "name": "CVE-2023-52070"
-            },
-            "timestamp": "2024-10-01T19:58:13.2159221+02:00",
-            "products": [
-                {
-                    "@id": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.18.2"
-                },
-                {
-                    "@id": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.18.3"
-                }
-            ],
-            "status": "not_affected",
-            "impact_statement": "Reported to JFreeChart library. The CVE was created by an LLM and valued by the JFreeChart team as invalid and bogus. See https://github.com/jfree/jfreechart/issues/396 for more information."
-        }
-    ]
-}
-```
-
-For more information about the OpenVex specification, please refer to the [OpenVex Spec](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md).
-
-Here some valid values for the `status` field:
-
-| Status              | Description                                                                                                                        |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| not_affected        | This product is known to be not affected by this vulnerability.                                                                    |
-| affected            | This product is known to be affected by this vulnerability.                                                                        |
-| fixed               | This product contains a fix for this vulnerability.                                                                                |
-| under_investigation | It is not known yet whether these versions are or are not affected by the vulnerability. However, it is still under investigation. |
-
-Here some valid values for the `justification` field (if status is `not_affected`):
-
-[VEX Status Justification PDF](https://www.cisa.gov/sites/default/files/publications/VEX_Status_Justification_Jun22.pdf)
-
-| Justification                                     | Description                                                                                                                                                                                                                                                                                             |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| component_not_present                             | The vulnerable component is not present in the product.                                                                                                                                                                                                                                                 |
-| vulnerable_code_not_present                       | The vulnerable code is not present. Typically this case occurs when source code is configured or built in a way that excludes the vulnerable code.                                                                                                                                                      |
-| vulnerable_code_not_in_execute_path               | The vulnerable code can not be executed. Typically this case occurs when the product includes the vulnerable code but does not call or use the vulnerable code.                                                                                                                                         |
-| vulnerable_code_cannot_be_controlled_by_adversary | The vulnerable code cannot be controlled by an attacker to exploit the vulnerability.                                                                                                                                                                                                                   |
-| inline_mitigations_already_exist                  | The product includes built-in protections or features that prevent exploitation of the vulnerability. These built-in protections cannot be subverted by the attacker and cannot be configured or disabled by the user. These mitigations completely prevent exploitation based on known attack vectors. |
-
-## Usage - Add Project
-
-To add a new project to the configuration file and all vex statements, run:
-
-```sh
-$ ct-vuln-add-project <project-name> <project-version> <project-version-to-add>
-```
-
-for example:
-
-```sh
-$ ct-vuln-add-project mapapps 4.18.2-SNAPSHOT 4.18.2
-```
-
-This will add a new project entry `mapapps` with version `4.18.2` to the configuration file clone all options from the reference project `mapapps` with version `4.18.2-SNAPSHOT`. It will also add the product-id to all vex statements, where the reference project it listed, too.
-
-This is useful if you release a snapshot version.
-
-## Usage - Remove Project
-
-To remove a project from the configuration file and all vex statements, run:
-
-```sh
-$ ct-vuln-remove-project <project-name> <project-version>
-```
-
-for example:
-
-```sh
-$ ct-vuln-remove-project mapapps 4.18.2-SNAPSHOT
-```
-
-This will remove the project entry `mapapps` with version `4.18.2-SNAPSHOT` from the configuration file and remove the product-id from all vex statements, where the project is listed.
-
-## Usage - Remove Project from vex files matching a vulnerability id
-
-To remove a project from all vex statements matching a vulnerability id, run:
-
-```sh
-$ ct-vuln-remove-project <project-name> <project-version> <vuln-id>
-```
-
-for example:
-
-```sh
-$ ct-vuln-remove-project mapapps 4.18.2-SNAPSHOT CVE-2024-38820
-```
-
-This will remove the product-id from all vex statements matching the given vulnerability.
-This is useful if a vulnerability is no longer detected for a project and you like to remove an existing statement.
-
-## Usage - Add project to vex
-
-Adds a new project version to all vex statements matching a reference project version.
-This step is already included in the `ct-vuln-add-project` command, but it can be run separately to update the vex files for an already existing project entry in the configuration file.
-
-To update vex files to include a new project version, run:
-
-```sh
-$ ct-vuln-add-project-to-vex <existingPurl> <newPurl>
-```
-
-for example:
-
-```sh
-$ ct-vuln-add-project-to-vex pkg:maven/de.conterra.mapapps/ct-mapapps@4.19.0 pkg:maven/de.conterra.mapapps/ct-mapapps@4.19.1
-```
-
-## Usage - Simulate a version release with preparation of the next dev version
-
-By combining the `ct-vuln-add-project` and `ct-vuln-remove-project` commands, you can simulate a version release.
-
-For example, you have a project `mapapps` with version `4.18.3-SNAPSHOT` and you want to release version `4.18.3`
-and prepare the next dev version `4.18.4-SNAPSHOT`, then you can run following commands:
-
-```sh
-$ ct-vuln-add-project mapapps 4.18.3-SNAPSHOT 4.18.3
-$ ct-vuln-remove-project mapapps 4.18.3-SNAPSHOT
-$ ct-vuln-add-project mapapps 4.18.3 4.18.4-SNAPSHOT
-```
-
-## Usage - Jira Report
-
-The `ct-vuln-jira-report` command reads the `scan-summary.json` produced by `ct-vuln-scan` and creates Jira issues for every new vulnerability that has not already been reported.
-
-For each vulnerability the tool:
-
-1. Checks (via JQL) whether an issue with the same vulnerability ID already exists in the target Jira project.
-2. If not, creates a new issue with a structured description including CVE details, affected artefacts, affected products, and placeholder sections for assessment and remediation.
-
-### Environment Variables
-
-```bash
-# Required
-JIRA_USER=user@example.com   # Jira account e-mail address
-JIRA_API_TOKEN=<token>       # Jira API token (https://id.atlassian.com/manage-profile/security/api-tokens)
-```
-
-NOTE: These variables can also be placed in a `.env` file in the working directory.
-
-### Configuration – `jira-conf.json`
-
-Create a `jira-conf.json` file (path is configurable) that defines the Jira instance and the routing rules:
-
-```json
-{
-    "$schema": "./node_modules/@conterra/vuln-scan/dist/schema/jira-config-schema.json",
-    "jiraUrl": "https://myorg.atlassian.net",
-    "issues": [
-        {
-            "jiraProject": "PLATFORM",
-            "issueType": "CVE",
-            "issueLabels": ["security"],
-            "addToBoard": [
-                {
-                    "sprintBoardId": 10,
-                    "issueLabels": ["team-a"],
-                    "matchProjects": ["mapapps@*"]
-                },
-                {
-                    "issueLabels": ["team-b"],
-                    "matchProjects": ["smartfinder@*"]
-                }
-            ],
-            "reportProjects": ["mapapps@*", "smartfinder@4.*"]
-        },
-        {
-            "jiraProject": "OTHER",
-            "issueType": "Bug",
-            "reportProjects": ["*"]
-        }
-    ]
-}
-```
-
-| Field                        | Required | Description                                                                                                                                   |
-| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `jiraUrl`                    | ✓        | Base URL of the Jira instance                                                                                                                 |
-| `issues`                     | ✓        | List of routing rules                                                                                                                         |
-| `issues[].jiraProject`       | ✓        | Jira project key, e.g. `PLATFORM`                                                                                                             |
-| `issues[].issueType`         | ✓        | Jira issue type name, e.g. `Bug`, `CVE`                                                                                                       |
-| `issues[].reportProjects`    | ✓        | Glob patterns (`*` wildcard) for scan project identifiers (`name@version`)                                                                    |
-| `issues[].issueLabels`       | –        | Global labels attached to every issue created by this rule, merged with any labels from `addToBoard` entries                                  |
-| `issues[].addToBoard`        | –        | Per-board routing rules (see table below). Enables Scrum sprint assignment and/or Kanban label routing                                        |
-| `addToBoard[].sprintBoardId` | –        | Scrum board ID. When set, the issue is assigned to the currently active sprint of that board via `customfield_10020`. Omit for Kanban boards. |
-| `addToBoard[].issueLabels`   | –        | Labels contributed by this board entry (see routing rules below)                                                                              |
-| `addToBoard[].matchProjects` | –        | Glob patterns to activate this entry. Defaults to `["*"]` (matches any project)                                                               |
-
-**`addToBoard` routing rules:**
-
-- Each entry in `addToBoard` is checked: its `matchProjects` patterns are tested against the scan projects affected by the current vulnerability. If none match, the entry is skipped.
-- **Scrum (sprintBoardId set):** The **first** matching entry with a `sprintBoardId` claims the sprint. All subsequent matching sprint entries – including their labels – are ignored. This avoids ambiguous multi-sprint assignments, which Jira does not support.
-- **Kanban (no sprintBoardId):** Matching entries always contribute their labels. This allows issues to appear on Kanban boards that filter by label.
-- The final label set on the created issue is: `issueLabels` (top-level) + labels from the winning sprint entry (if any) + labels from all matching Kanban entries.
-
-**`reportProjects` routing:** The `reportProjects` patterns are matched against each scan project identifier (`name@version`). The `*` wildcard matches any sequence of characters. Each routing rule is evaluated independently, so a vulnerability can be reported to multiple Jira projects. Rules that match no project are silently skipped.
-
-### CLI Usage
-
-```sh
-$ ct-vuln-jira-report [options]
-```
-
-```
-Options:
-  -c, --jira-config <path>   Path to jira-conf.json configuration file
-                             (default: ./jira-conf.json)
-  -s, --summary <path>       Path to scan-summary.json produced by ct-vuln-scan
-                             (default: ./output/scan-summary.json)
-      --dry-run              Print what would be created without calling Jira
-  -h, --help                 Show help
-```
-
-Examples:
-
-```sh
-# Use defaults (./jira-conf.json + ./output/scan-summary.json)
-$ ct-vuln-jira-report
-
-# Custom paths
-$ ct-vuln-jira-report --jira-config ./config/jira-conf.json --summary ./output/scan-summary.json
-
-# Preview without creating issues
-$ ct-vuln-jira-report --dry-run
-```
-
-## Dev Notes
-
-Setup:
-
-1. Checkout via git
-2. Run `pnpm install`
-
-Run tests (vitest): `pnpm test` (watch mode)
-To run tests once (without watch), use `pnpm test run`.
-
-Build the project (esbuild): `pnpm run build` (or `watch`)
+# ct-vuln-scan
+
+The utility is a wrapper around the following tools:
+
+- [grype](https://github.com/anchore/grype) - Vulnerability scanner for container images and filesystems.
+- [trivy](https://github.com/aquasecurity/trivy) - Comprehensive and versatile security scanner.
+- [oss index](https://ossindex.sonatype.org/) - Free catalogue of open source components and scanning tools to help developers identify vulnerabilities.
+
+It also supports the [OpenVex](https://github.com/openvex) specification for vulnerability status and justification.
+
+For an architectural overview see [ARCHITECTURE.md](./ARCHITECTURE.md).
+For build, test and contribution guidelines see [AGENTS.md](./AGENTS.md).
+
+## Pre-Requisites
+
+You need to have `docker` and `node` (>= 20) installed on your machine.
+
+## Installation
+
+The utility is published as an npm package and can be installed globally or locally.
+
+```sh
+# global
+$ npm install -g @conterra/vuln-scan
+
+# local
+$ npm install @conterra/vuln-scan
+```
+
+After installation the following commands are available:
+
+- `ct-vuln-scan` - Triggers the vulnerability scan.
+- `ct-vuln-add-vex` - Interactive helper to add a new vex statement to a file.
+- `ct-vuln-add-project` - Adds a new project to the configuration file based on an existing project entry and adds it to all vex statements.
+- `ct-vuln-remove-project` - Removes a project from the configuration file and all vex statements (or only from vex statements matching a given vulnerability id).
+- `ct-vuln-add-project-to-vex` - Updates vex files to include a new project version. Already part of `ct-vuln-add-project`.
+- `ct-vuln-jira-report` - Reads a `scan-summary.json` and creates Jira issues for newly detected vulnerabilities.
+- `ct-vuln-auto-vex` - Auto-creates OpenVEX statements for newly detected vulnerabilities below a configurable severity threshold.
+
+## Configuration
+
+Create a `vuln-scan-conf.json` file in the working directory.
+
+Minimal configuration:
+
+```json
+{
+    "$schema": "./node_modules/@conterra/vuln-scan/dist/schema/conf-schema.json",
+    "projects": [
+        {
+            "name": "mapapps",
+            "version": "4.18.2",
+            "purl": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.18.2",
+            "sbomFile": "./input/sboms/mapapps-4.18.2.cdx.json"
+        }
+    ]
+}
+```
+
+Full configuration with all available options and their defaults:
+
+```jsonc
+{
+    "$schema": "./node_modules/@conterra/vuln-scan/dist/schema/conf-schema.json",
+
+    // Action on newly detected vulnerabilities: "fail" | "warn" | "ignore"
+    // - "fail": exits with code 1
+    // - "warn": logs ##vso[task.complete result=SucceededWithIssues;]
+    // - "ignore": no effect
+    "onNewVulnerabilities": "fail",
+    // Action on vulnerabilities no longer detected, same values as above.
+    "onNoLongerDetectedVulnerabilities": "ignore",
+    // Maven repository to fetch sboms from.
+    // Set MAVEN_REPO_USER / MAVEN_REPO_PW for authentication.
+    "mavenRepo": "https://repository.conterra.de/repository/maven-mirror-ct",
+    // Scanners to use. Pin a version with `<scanner>@<version>`, e.g. `trivy@0.69.3`.
+    "scanners": ["grype", "trivy", "ossindex"],
+    // (optional) URLs of additional vex files to download.
+    "vexUrls": ["https://example.com/my-vex.json"],
+    // Directory containing vex files.
+    "vexDir": "./input/vex",
+    // Directory for scan output.
+    "outDir": "./output",
+    // Cache directory for grype/trivy databases.
+    "cacheDir": "./cache",
+    // If true, results for each project are written to a sub-directory of outDir.
+    "createSubDirsForProject": true,
+    // Console output style:
+    //   "BY_PROJECT_DETAILED" (default) - group by project, print CVE details
+    //   "BY_PROJECT"                    - group by project, no CVE details
+    //   "BY_CVE"                        - group by CVE, no CVE details
+    //   "BY_CVE_DETAILED"               - group by CVE, print CVE details
+    "consoleReport": "BY_PROJECT_DETAILED",
+    "projects": [
+        {
+            "name": "mapapps",
+            "version": "4.18.3",
+            // identifier used to match vex statements
+            "purl": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.18.3",
+            // maven coordinates used to download the sbom from mavenRepo
+            "sbomMavenCoordinates": "de.conterra.mapapps:ct-mapapps-rollout:4.18.3:sbom"
+        },
+        {
+            "name": "mapapps",
+            "version": "4.18.2",
+            "purl": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.18.2",
+            // local sbom file
+            "sbomFile": "./input/sboms/mapapps-4.18.2.cdx.json",
+            // (optional) skip this project
+            "enabled": true,
+            // (optional) scan but never break the build
+            "silent": false,
+            // (optional) only break the build for severities >= this value.
+            // One of: "CRITICAL", "HIGH", "MEDIUM", "LOW", "UNKNOWN"
+            "minimumSeverity": "HIGH"
+        }
+    ]
+}
+```
+
+## Usage - Scan
+
+Run from the directory containing `vuln-scan-conf.json`:
+
+```sh
+# scan all projects
+$ ct-vuln-scan
+
+# scan all versions of one project
+$ ct-vuln-scan mapapps
+
+# scan a specific project version
+$ ct-vuln-scan mapapps 4.18.2
+```
+
+A typical working directory layout:
+
+```plain
+/vuln-scan/              # working directory
+├── vuln-scan-conf.json
+├── input/
+│   ├── sbom/            # sbom files
+│   └── vex/             # vex files
+└── output/              # aggregated scan results
+```
+
+### Environment variables
+
+```bash
+# (optional) maven repo authentication for sbom download
+MAVEN_REPO_USER=[username]
+MAVEN_REPO_PW=[password]
+
+# (optional) sonatype OSS Index authenticated API
+OSS_INDEX_API_USER=[username]
+OSS_INDEX_API_TOKEN=[token]
+OSS_INDEX_BASE_URL=[url]   # default: https://api.guide.sonatype.com (since 1.0.8)
+
+# (optional) authentication for vex files referenced via vexUrls
+VEX_URLS_USER=[username]
+VEX_URLS_PW=[password]
+
+# (optional) helps with the trivy DB GitHub rate limit
+# https://aquasecurity.github.io/trivy/v0.38/docs/references/troubleshooting/#github-rate-limiting
+TRIVY_GITHUB_TOKEN=[token]
+
+# (optional) verbose logging
+VERBOSE=true
+
+# (optional) if "true", a project's product-id is automatically removed
+# from vex statements covering vulnerabilities no longer detected for that project.
+AUTO_REMOVE_UNUSED_STATEMENTS=true
+```
+
+These variables can also be defined in a `.env` file in the working directory.
+
+### Output files
+
+Two summary files are written directly into `outDir`:
+
+- `scan-summary.txt` - The console "scan summary" output as plain text.
+- `scan-summary.json` - Machine-readable summary, for post-processing or downstream tools. Example (truncated):
+
+    ```json
+    {
+        "errors": [
+            {
+                "project": "mapapps@4.18.2",
+                "error": "Failed to fetch sbom file ..."
+            }
+        ],
+        "vulnerabilities": {
+            "CVE-2025-48988": {
+                "id": "CVE-2025-48988",
+                "severity": "HIGH",
+                "title": "tomcat: Apache Tomcat DoS in multipart upload",
+                "description": "...",
+                "components": ["pkg:maven/org.apache.tomcat.embed/tomcat-embed-core@10.1.41"],
+                "refs": ["https://avd.aquasec.com/nvd/cve-2025-48988"]
+            }
+        },
+        "vulnerabilityToProject": {
+            "CVE-2025-48988": ["smartfinder-sdi@2.7.1-SNAPSHOT"]
+        },
+        "projectToVulnerability": {
+            "smartfinder-sdi@2.7.1-SNAPSHOT": ["CVE-2025-48988"]
+        },
+        "noLongerDetectedVulnerabilities": {
+            "CVE-2023-52070": ["mapapps@4.19.3-SNAPSHOT"]
+        }
+    }
+    ```
+
+For each scanned project, raw scanner output, an aggregated JSON, a [SARIF](https://sarifweb.azurewebsites.net/) file (used by the Azure DevOps SARIF tab) and the matching OpenVEX statements are written to a `<project-name>-<project-version>/` sub-directory (when `createSubDirsForProject` is `true`). See [ARCHITECTURE.md §5](./ARCHITECTURE.md#5-output-folder-layout) for the full file layout.
+
+### Azure DevOps Pipelines integration
+
+Publish the output directory as build artifact `CodeAnalysisLogs`:
+
+```yaml
+- task: PublishBuildArtifacts@1
+  inputs:
+      PathtoPublish: "output"
+      ArtifactName: "CodeAnalysisLogs"
+```
+
+The [SARIF SAST Scans Tab](https://marketplace.visualstudio.com/items?itemName=sariftools.scans) extension visualizes the `.sarif.json` files in the artifact.
+
+If `onNewVulnerabilities` is set to `warn`, the pipeline will be marked as `SucceededWithIssues` when new vulnerabilities are found. With the default `fail`, the pipeline fails (exit code 1).
+
+## Usage - Add Vex
+
+Experimental maintenance workflow for recording a decision about whether a vulnerability affects a project.
+
+```sh
+$ ct-vuln-add-vex
+```
+
+The interactive prompt creates a `CVE-<id>.json` file in `vexDir`, e.g.:
+
+```json
+{
+    "@context": "https://openvex.dev/ns/v0.2.0",
+    "@id": "https://openvex.dev/docs/public/vex-fc763e6e...",
+    "author": "conterra",
+    "timestamp": "2024-10-01T18:54:23+02:00",
+    "last_updated": "2024-10-01T19:58:13+02:00",
+    "version": 2,
+    "statements": [
+        {
+            "vulnerability": { "name": "CVE-2023-52070" },
+            "timestamp": "2024-10-01T19:58:13+02:00",
+            "products": [
+                { "@id": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.18.2" },
+                { "@id": "pkg:maven/de.conterra.mapapps/ct-mapapps@4.18.3" }
+            ],
+            "status": "not_affected",
+            "impact_statement": "<short rationale>"
+        }
+    ]
+}
+```
+
+For details see the [OpenVex spec](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md).
+
+Valid `status` values:
+
+| Status              | Description                                                                |
+| ------------------- | -------------------------------------------------------------------------- |
+| not_affected        | The product is known to be not affected by this vulnerability.             |
+| affected            | The product is known to be affected by this vulnerability.                 |
+| fixed               | The product contains a fix for this vulnerability.                         |
+| under_investigation | It is not yet known whether the product is affected; still being assessed. |
+
+Valid `justification` values when `status` is `not_affected` (full text in the [VEX Status Justification PDF](https://www.cisa.gov/sites/default/files/publications/VEX_Status_Justification_Jun22.pdf)):
+
+| Justification                                     | Short description                                            |
+| ------------------------------------------------- | ------------------------------------------------------------ |
+| component_not_present                             | Vulnerable component is not present in the product.          |
+| vulnerable_code_not_present                       | Vulnerable code is excluded by configuration or build.       |
+| vulnerable_code_not_in_execute_path               | Vulnerable code is shipped but never called.                 |
+| vulnerable_code_cannot_be_controlled_by_adversary | Attacker cannot influence the vulnerable code path.          |
+| inline_mitigations_already_exist                  | Built-in, non-disable-able mitigations prevent exploitation. |
+
+## Usage - Add Project
+
+Add a new project entry to the configuration and propagate it to vex statements:
+
+```sh
+$ ct-vuln-add-project <reference-name> <reference-version> <new-version>
+
+# example: clone mapapps@4.18.2-SNAPSHOT into a new mapapps@4.18.2 entry
+$ ct-vuln-add-project mapapps 4.18.2-SNAPSHOT 4.18.2
+```
+
+The new entry inherits all options from the reference project, and its product-id is added to every vex statement that already references the reference project.
+
+## Usage - Remove Project
+
+Remove a project entry from the configuration and all matching vex statements:
+
+```sh
+$ ct-vuln-remove-project <name> <version>
+
+$ ct-vuln-remove-project mapapps 4.18.2-SNAPSHOT
+```
+
+### Remove project from vex files matching a vulnerability id
+
+Useful when a single vulnerability is no longer relevant for a project but the project itself remains:
+
+```sh
+$ ct-vuln-remove-project <name> <version> <vuln-id>
+
+$ ct-vuln-remove-project mapapps 4.18.2-SNAPSHOT CVE-2024-38820
+```
+
+## Usage - Add Project to Vex
+
+Add a new project version to all vex statements that already reference an existing version. Already part of `ct-vuln-add-project`; useful when the configuration entry already exists.
+
+```sh
+$ ct-vuln-add-project-to-vex <existingPurl> <newPurl>
+
+$ ct-vuln-add-project-to-vex \
+    pkg:maven/de.conterra.mapapps/ct-mapapps@4.19.0 \
+    pkg:maven/de.conterra.mapapps/ct-mapapps@4.19.1
+```
+
+## Usage - Simulate a release
+
+Combine the project commands to simulate releasing `4.18.3` and preparing the next dev version `4.18.4-SNAPSHOT`:
+
+```sh
+$ ct-vuln-add-project mapapps 4.18.3-SNAPSHOT 4.18.3
+$ ct-vuln-remove-project mapapps 4.18.3-SNAPSHOT
+$ ct-vuln-add-project mapapps 4.18.3 4.18.4-SNAPSHOT
+```
+
+## Usage - Jira Report
+
+`ct-vuln-jira-report` reads `scan-summary.json` produced by `ct-vuln-scan` and creates Jira issues for new vulnerabilities. For each vulnerability the tool:
+
+1. Checks (via JQL) whether an issue with the same vulnerability ID already exists in the target Jira project.
+2. If not, creates a new issue with a structured description (CVE details, affected artefacts and products, placeholders for assessment and remediation) and tags every currently-affected scan project as a `proj:<name>_v<version>` label on the issue.
+3. If an issue already exists, the project tags are compared with the current scan result. For every newly-affected project the issue is updated:
+    - the missing `proj:` label is added,
+    - a comment is posted listing only the additional projects (without re-emitting the CVE details),
+    - and if the issue is currently in status category `done` it is transitioned to status `Open` and re-added to the active sprint of its routed scrum board (when one is configured).
+
+Project tags use the form `proj:<name>_v<version>` (the `@` separator is replaced with `_v` to keep labels JQL-friendly). On the very first run after upgrading, existing Jira issues will not yet carry these labels, so every currently-matching project will be added at once and a single follow-up comment will be posted.
+
+When an issue is updated because new projects became affected, any `addToBoard` `issueLabels` that *would now match* (per the same first-sprint-wins / Kanban-aggregate rules used at creation) are added to the issue retroactively. Labels already present on the issue are not re-emitted. Sprint placement is **not** changed for issues that are still in progress; only when a closed issue is re-opened is it placed in the active sprint of whichever scrum entry currently matches first — which may differ from the original sprint if the routing config has been edited since the issue was created.
+
+### Environment variables
+
+```bash
+JIRA_USER=user@example.com   # Jira account e-mail
+JIRA_API_TOKEN=<token>       # https://id.atlassian.com/manage-profile/security/api-tokens
+```
+
+These can also be set in a `.env` file in the working directory.
+
+### Configuration - `jira-conf.json`
+
+```json
+{
+    "$schema": "./node_modules/@conterra/vuln-scan/dist/schema/jira-config-schema.json",
+    "jiraUrl": "https://myorg.atlassian.net",
+    "issues": [
+        {
+            "jiraProject": "PLATFORM",
+            "issueType": "CVE",
+            "issueLabels": ["security"],
+            "addToBoard": [
+                {
+                    "sprintBoardId": 10,
+                    "issueLabels": ["team-a"],
+                    "matchProjects": ["mapapps@*"]
+                },
+                {
+                    "issueLabels": ["team-b"],
+                    "matchProjects": ["smartfinder@*"]
+                }
+            ],
+            "reportProjects": ["mapapps@*", "smartfinder@4.*"]
+        },
+        {
+            "jiraProject": "OTHER",
+            "issueType": "Bug",
+            "reportProjects": ["*"]
+        }
+    ]
+}
+```
+
+| Field                             | Required | Description                                                                                                                                        |
+| --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jiraUrl`                         | yes      | Base URL of the Jira instance.                                                                                                                     |
+| `issues`                          | yes      | Routing rules. Each rule is evaluated independently, so a vulnerability can be reported to multiple projects.                                      |
+| `issues[].jiraProject`            | yes      | Jira project key, e.g. `PLATFORM`.                                                                                                                 |
+| `issues[].issueType`              | yes      | Jira issue type, e.g. `Bug`, `CVE`.                                                                                                                |
+| `issues[].reportProjects`         | yes      | Glob patterns (`*` wildcard) matched against scan project identifiers (`name@version`).                                                            |
+| `issues[].issueLabels`            | no       | Labels added to every issue created by this rule, merged with labels from matching `addToBoard` entries.                                           |
+| `issues[].addToBoard`             | no       | Per-board routing rules; see below.                                                                                                                |
+| `addToBoard[].sprintBoardId`      | no       | Scrum board id. If set, the issue is assigned to the board's active sprint via `customfield_10020`.                                                |
+| `addToBoard[].issueLabels`        | no       | Labels contributed by this entry.                                                                                                                  |
+| `addToBoard[].matchProjects`      | no       | Glob patterns to activate this entry. Defaults to `["*"]`.                                                                                         |
+| `autoCloseBelowSeverity`          | no       | Default auto-close threshold inherited by every `issues[]` entry that does not override it. One of `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. |
+| `issues[].autoCloseBelowSeverity` | no       | Per-rule override of the top-level threshold.                                                                                                      |
+
+`addToBoard` resolution: only entries whose `matchProjects` cover the vulnerability's affected scan projects are considered. The **first** matching scrum entry (with `sprintBoardId`) claims the sprint; further scrum entries are ignored. Kanban entries (no `sprintBoardId`) all contribute their labels.
+
+#### Auto-close low-severity issues
+
+When `autoCloseBelowSeverity` (top-level or per-issue rule) is set, newly-created issues whose vulnerability severity is **strictly below** the threshold are immediately transitioned to a status whose Jira status category is `done` (the first such transition exposed by the workflow is used, regardless of the status's display name and locale). The board/sprint assignment, labels and comment described above still happen *before* the transition, so the issue is reachable on the configured board even though it starts out closed. A short German-language comment is added explaining the auto-closure.
+
+For *existing* issues, the threshold only suppresses re-opening: when a closed sub-threshold issue gains a newly-affected project, the project label and "Zusätzlich gemeldet für" comment are added as usual, but the issue is **not** re-opened (and never re-closed). Issues at or above the threshold keep the existing re-open + re-add-to-active-sprint behavior.
+
+Threshold semantics mirror `ct-vuln-auto-vex`: with `"HIGH"`, severities `MEDIUM`, `LOW` and `UNKNOWN` are auto-closed, while `HIGH` and `CRITICAL` stay open.
+
+### CLI
+
+```
+Options:
+  -c, --jira-config <path>   Path to jira-conf.json (default: ./jira-conf.json)
+  -s, --summary <path>       Path to scan-summary.json (default: ./output/scan-summary.json)
+      --dry-run              Print what would be created without calling Jira
+  -h, --help                 Show help
+```
+
+Examples:
+
+```sh
+$ ct-vuln-jira-report
+$ ct-vuln-jira-report --jira-config ./config/jira-conf.json --summary ./output/scan-summary.json
+$ ct-vuln-jira-report --dry-run
+```
+
+## Usage - Auto VEX
+
+`ct-vuln-auto-vex` is a post-processor for `ct-vuln-scan`. It auto-creates OpenVEX statements for newly detected vulnerabilities whose severity is **strictly below** a configurable threshold, reducing manual triage noise for low-impact CVEs.
+
+Generated files are written to `<vexDir>/<subDir>/<CVE-ID>.json` and are picked up automatically by the next scan run (the vex store recurses into sub-directories). Manual VEX files in `vexDir` always take precedence: any existing statement covering a CVE suppresses it from the "new vulnerabilities" list before this tool runs.
+
+### Configuration - `auto-vex-conf.json`
+
+Place this file next to `vuln-scan-conf.json`.
+
+```json
+{
+    "$schema": "./node_modules/@conterra/vuln-scan/dist/schema/auto-vex-config.schema.json",
+    "impactStatement": "Auto-acknowledged: no evidence of exploitability in our deployment context.",
+    "maxSeverity": "HIGH",
+    "author": "conterra",
+    "subDir": "auto"
+}
+```
+
+| Field             | Required | Default      | Description                                                                                                                                                                                |
+| ----------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `impactStatement` | yes      | -            | `impact_statement` written into every auto-generated VEX statement.                                                                                                                        |
+| `maxSeverity`     | no       | `"HIGH"`     | Exclusive threshold; CVEs strictly below this severity get a statement. One of `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. With the default, `MEDIUM` is auto-vexed but `HIGH` is not. |
+| `author`          | no       | `"conterra"` | `author` field of the OpenVEX document.                                                                                                                                                    |
+| `subDir`          | no       | `"auto"`     | Sub-directory of `vexDir` for generated files.                                                                                                                                             |
+
+### Usage
+
+```bash
+# defaults: ./auto-vex-conf.json + ./output/scan-summary.json + vexDir from vuln-scan-conf.json
+$ ct-vuln-auto-vex
+
+# custom paths
+$ ct-vuln-auto-vex --auto-vex-config ./config/auto-vex-conf.json --summary ./output/scan-summary.json
+
+# preview without writing files
+$ ct-vuln-auto-vex --dry-run
+```
+
+### Behaviour
+
+- Only entries from `summary.vulnerabilities` are processed; this map already contains only newly detected CVEs, so previously declared vulnerabilities are never re-processed.
+- If `<vexDir>/<subDir>/<CVE-ID>.json` already exists, the new statement is **appended** (document version is bumped). Manual edits in the same file are preserved.
+- The generated statement uses `status: "not_affected"` and the configured `impactStatement`. No `justification` is set.
+- Affected scan project identifiers (`name@version`) are used as the product `@id`, matching what `VexStore` expects when populated from the scan summary.
+
+## Contributing
+
+See [AGENTS.md](./AGENTS.md) for toolchain, build, lint and test conventions.