From 4d3abc455c214fa0542428f4007223ec53bb9434 Mon Sep 17 00:00:00 2001 From: Rein Krul Date: Tue, 17 Nov 2026 14:16:08 +0100 Subject: [PATCH] ci: skip govulncheck findings covered by a VEX statement Assisted by AI --- .github/scripts/govulncheck-vex.sh | 66 +++++++++++++++++++ .../workflows/govulncheck-cron-schedule.yaml | 8 ++- .github/workflows/govulncheck.yaml | 6 ++ .vex/nuts-node.openvex.json | 49 ++++++++++++++ docs/pages/deployment/docker.rst | 17 +++++ 5 files changed, 145 insertions(+), 1 deletion(-) create mode 100755 .github/scripts/govulncheck-vex.sh create mode 100644 .vex/nuts-node.openvex.json diff --git a/.github/scripts/govulncheck-vex.sh b/.github/scripts/govulncheck-vex.sh new file mode 100755 index 000000000..56777d3b8 --- /dev/null +++ b/.github/scripts/govulncheck-vex.sh @@ -0,0 +1,66 @@ +#!/usr/bin/env bash +# Fails when govulncheck reports a vulnerability that is not covered by a VEX statement. +# +# govulncheck can't skip findings itself. This script reads its JSON output and the OpenVEX document +# of this repository, and skips findings for which the document contains a "not_affected" statement. +# A statement is only used for MAX_AGE_DAYS after its timestamp (or last_updated, if set). +# After that the finding fails the check again, until the statement is reviewed and its date is updated. +# +# Usage: govulncheck-vex.sh +set -euo pipefail + +MAX_AGE_DAYS="${MAX_AGE_DAYS:-180}" +findings_file="$1" +vex_file="$2" + +# Vulnerabilities that are called by our code, the same set that makes "govulncheck" (text output) fail. +# Output: one JSON object per vulnerability, with its ID, aliases, summary, module and fixed version. +called=$(jq -c -s ' + (map(select(.osv) | {key: .osv.id, value: .osv}) | from_entries) as $osv + | map(select(.finding and .finding.trace[0].function) | .finding) + | group_by(.osv) + | map({ + id: .[0].osv, + aliases: ($osv[.[0].osv].aliases // []), + summary: ($osv[.[0].osv].summary // ""), + module: .[0].trace[0].module, + fixed: (.[0].fixed_version // "no fix available") + }) + | .[]' "$findings_file") + +# IDs (name and aliases) of "not_affected" statements that are still within MAX_AGE_DAYS. +valid_ids=$(jq -r --argjson maxAge "$MAX_AGE_DAYS" ' + .statements[] + | select(.status == "not_affected") + | select((now - ((.last_updated // .timestamp) | fromdateiso8601)) <= ($maxAge * 86400)) + | .vulnerability | (.name, (.aliases // [])[])' "$vex_file") + +# IDs of "not_affected" statements that are too old. +expired_ids=$(jq -r --argjson maxAge "$MAX_AGE_DAYS" ' + .statements[] + | select(.status == "not_affected") + | select((now - ((.last_updated // .timestamp) | fromdateiso8601)) > ($maxAge * 86400)) + | .vulnerability | (.name, (.aliases // [])[])' "$vex_file") + +failed=0 +while IFS= read -r vuln; do + [ -z "$vuln" ] && continue + id=$(jq -r '.id' <<<"$vuln") + description=$(jq -r '"\(.id) (\(.aliases | join(", "))): \(.summary)\n module: \(.module), fixed in: \(.fixed)"' <<<"$vuln") + ids=$(jq -r '.id, .aliases[]' <<<"$vuln") + + if grep -qxFf <(echo "$ids") <<<"$valid_ids"; then + echo -e "SKIPPED (VEX: not affected) $description" + elif grep -qxFf <(echo "$ids") <<<"$expired_ids"; then + echo -e "::error::VEX statement for $id is older than $MAX_AGE_DAYS days. Review it and update its date in $vex_file.\nFOUND $description" + failed=1 + else + echo -e "::error::$id is called by the code and not covered by a VEX statement.\nFOUND $description" + failed=1 + fi +done <<<"$called" + +if [ "$failed" -ne 0 ]; then + exit 1 +fi +echo "No vulnerabilities found, other than the ones skipped above." diff --git a/.github/workflows/govulncheck-cron-schedule.yaml b/.github/workflows/govulncheck-cron-schedule.yaml index 8ef7a6386..9e34fc860 100644 --- a/.github/workflows/govulncheck-cron-schedule.yaml +++ b/.github/workflows/govulncheck-cron-schedule.yaml @@ -44,7 +44,13 @@ jobs: go-version-file: 'go.mod' # test against go.mod since 'stable' is not valid for older branches go-package: ./... repo-checkout: false # will auto-checkout the default branch if left on true - output-format: 'text' # other values will always result in successful completion of the action, we need it fail on vulnerabilities + # JSON output never fails the action; the next step decides, so findings covered by a VEX statement can be skipped + output-format: 'json' + output-file: 'govulncheck.json' + + - name: Fail on vulnerabilities not covered by a VEX statement + # the script and the VEX document are taken from the branch that is checked + run: .github/scripts/govulncheck-vex.sh govulncheck.json .vex/nuts-node.openvex.json - name: notify slack # this uses our own 'Github notifications' app in slack diff --git a/.github/workflows/govulncheck.yaml b/.github/workflows/govulncheck.yaml index fed9a9c07..3ab949d1e 100644 --- a/.github/workflows/govulncheck.yaml +++ b/.github/workflows/govulncheck.yaml @@ -51,3 +51,9 @@ jobs: with: go-version-input: 'stable' go-package: ./... + # JSON output never fails the action; the next step decides, so findings covered by a VEX statement can be skipped + output-format: 'json' + output-file: 'govulncheck.json' + + - name: Fail on vulnerabilities not covered by a VEX statement + run: .github/scripts/govulncheck-vex.sh govulncheck.json .vex/nuts-node.openvex.json diff --git a/.vex/nuts-node.openvex.json b/.vex/nuts-node.openvex.json new file mode 100644 index 000000000..ab57bd98d --- /dev/null +++ b/.vex/nuts-node.openvex.json @@ -0,0 +1,49 @@ +{ + "@context": "https://openvex.dev/ns/v0.2.0", + "@id": "https://github.com/nuts-foundation/nuts-node/blob/master/.vex/nuts-node.openvex.json", + "author": "Nuts Foundation", + "timestamp": "2026-11-17T00:00:00Z", + "version": 1, + "statements": [ + { + "vulnerability": { + "name": "CVE-2026-118651", + "aliases": ["GO-2026-6875", "GHSA-99jh-6h7p-pp36"] + }, + "timestamp": "2026-11-17T00:00:00Z", + "products": [ + { + "@id": "pkg:golang/github.com/nuts-foundation/nuts-node/v6", + "subcomponents": [{"@id": "pkg:golang/github.com/labstack/echo/v4"}] + }, + { + "@id": "pkg:oci/nuts-node?repository_url=index.docker.io%2Fnutsfoundation%2Fnuts-node", + "subcomponents": [{"@id": "pkg:golang/github.com/labstack/echo/v4"}] + } + ], + "status": "not_affected", + "justification": "vulnerable_code_not_in_execute_path", + "impact_statement": "The vulnerability is in echo's reverse proxy middleware (middleware.Proxy), which the Nuts node does not use. The node also always sets Echo#IPExtractor (http/engine.go), the workaround named in the advisory." + }, + { + "vulnerability": { + "name": "CVE-2026-118653", + "aliases": ["GO-2026-6872", "GHSA-246p-cpwv-v3jq"] + }, + "timestamp": "2026-11-17T00:00:00Z", + "products": [ + { + "@id": "pkg:golang/github.com/nuts-foundation/nuts-node/v6", + "subcomponents": [{"@id": "pkg:golang/github.com/labstack/echo/v4"}] + }, + { + "@id": "pkg:oci/nuts-node?repository_url=index.docker.io%2Fnutsfoundation%2Fnuts-node", + "subcomponents": [{"@id": "pkg:golang/github.com/labstack/echo/v4"}] + } + ], + "status": "not_affected", + "justification": "vulnerable_code_cannot_be_controlled_by_adversary", + "impact_statement": "The vulnerability lets a caller get a new rate limit by sending a spoofed X-Forwarded-For header, when Echo#IPExtractor is not set. The Nuts node always sets Echo#IPExtractor (http/engine.go), and its rate limiter (http/ratelimiter.go) has one shared limit that does not depend on the caller's IP address." + } + ] +} diff --git a/docs/pages/deployment/docker.rst b/docs/pages/deployment/docker.rst index c5f556d8f..95a26257f 100644 --- a/docs/pages/deployment/docker.rst +++ b/docs/pages/deployment/docker.rst @@ -245,6 +245,23 @@ For an embargoed release the commit is not publicly readable until disclosure; u It does not prove that the source code at that commit is free of defects or malicious changes. Review of the source code, and of who may change it, remains the basis of trust. +.. _vulnerability-scanning: + +Scanning images for vulnerabilities +*********************************** + +An image scanner reports a vulnerability when the image contains an affected version of a library, also when the Nuts node does not use the vulnerable part of it. +For vulnerabilities that were analyzed and do not affect the Nuts node, the repository contains a `VEX `_ document: `.vex/nuts-node.openvex.json `_. +Each statement in it names the vulnerability and explains why the Nuts node is not affected. + +Scanners that support OpenVEX can use the document to leave these vulnerabilities out of their report. +Use the document from the branch of the release you run (e.g. ``V6.2``). +For example, with `Trivy `_: + +.. code-block:: shell + + trivy image --vex nuts-node.openvex.json nutsfoundation/nuts-node:latest + Development image *****************