@conterra/vuln-scan v0.0.3

ct-vuln-scan

The project is a utility to scan sbom files in CycloneDX json format for CVEs. The utility is a wrapper around grype and trivy and oss index. It also supports the 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:

$ npm install -g @conterra/vuln-scan

For local installation use:

$ npm install @conterra/vuln-scan

or reference it in your package.json file:

{
  "dependencies": {
    "@conterra/vuln-scan": "<current version>"
  }
}

After that you have two 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

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:

{
  "$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:

{
    "$schema": "./node_modules/@conterra/vuln-scan/dist/schema/conf-schema.json",
    
    /* Defines if the process should fail or only log a warning.
       If true the process ends with exit code 1 if a vulnerability is detected without a vex information.
       Otherwise only the log statement "##vso[task.complete result=SucceededWithIssues;]NEW_VULNERABILITIES_DETECTED" is issued.
    */
    "failOnNewVulnerabilities": false, 
    /* 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". */
    "scanners": ["grype", "trivy", "ossindex"],
    /* 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,
    /* 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"
        }
    ]
}

Usage - Scan

To scan all projects run following command in the directory where the configuration file is located:

$ ct-vuln-scan

To scan a specific project run following command:

$ ct-vuln-scan mapapps 4.18.2

You may need following environment variables for a successful scan:

# (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]
OSS_INDEX_API_TOKEN=[token]

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 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 for each project a sub directory in the output folder named <project-name>-<project-version>.

Azure DevOps Pipelines Integration

Attach the output directory as build artifact CodeAnalysisLogs.

- task: PublishBuildArtifacts@1
  inputs:
     PathtoPublish: "output"
     ArtifactName: "CodeAnalysisLogs"

Make sure that your Azure DevOps organization has the extension SARIF SAST Scans Tab 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:

$ 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:

{
    "@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.

Here some valid values for the status field:

Here some valid values for the justification field (if status is not_affected):

VEX Status Justification PDF