Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions .github/scripts/govulncheck-vex.sh
Original file line number Diff line number Diff line change
@@ -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 <govulncheck JSON output> <OpenVEX document>
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."
8 changes: 7 additions & 1 deletion .github/workflows/govulncheck-cron-schedule.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions .github/workflows/govulncheck.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
49 changes: 49 additions & 0 deletions .vex/nuts-node.openvex.json
Original file line number Diff line number Diff line change
@@ -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."
}
]
}
17 changes: 17 additions & 0 deletions docs/pages/deployment/docker.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://openvex.dev/>`_ document: `.vex/nuts-node.openvex.json <https://github.com/nuts-foundation/nuts-node/blob/master/.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 <https://trivy.dev/>`_:

.. code-block:: shell

trivy image --vex nuts-node.openvex.json nutsfoundation/nuts-node:latest

Development image
*****************

Expand Down
Loading