nodewright-managing-openvex
Skill78 starsChanged 11 days agoApache-2.0View on GitHub
Triage findings from the Image Vulnerability Scan workflow and maintain `.openvex.json`, the repository's OpenVEX v0.2.0 document. Use when asked to suppress a CVE, mark a finding not affected, write or edit a VEX statement, review Grype code scanning alerts on the operator or agent image, or work out why a suppression did not take effect. Suppression happens in `.openvex.json` and never by dismissing a code scanning alert, because every release attests this document as signed evidence onto its images.
In this repository3 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- nodewright-cross-reviewSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 32
Read .claude/skills/nodewright-managing-openvex/vex-state.yaml before doing anything else.
- Distinctive: line 40
Do not dismiss a code scanning alert to make a finding go away.
- Very specific: line 110
If main already carries the fix, stop.
- Distinctive: line 237
If the count does not move, the statement is decorative.
- Very specific: line 262
If a justification is present it must be one of exactly these five.
- Very specific: line 271
If none of the five is honestly true, use an impact_statement and say why in prose, or do not write the statement at all.
- Very specific: line 343
Update timestamp to the current UTC time in RFC 3339.
- Very specific: line 344
Leave @id, author, role, and tooling alone.
- Very specific: line 375
Before finishing, write back to .claude/skills/nodewright-managing-openvex/vex-state.yaml:
- Distinctive: line 386
Every entry must state what would invalidate it.
- Distinctive: line 401
Run the workflow on demand rather than waiting for the next day:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Managing .openvex.json
Operating instructions for triaging container image vulnerability findings and maintaining the repository's OpenVEX document.
Files this skill owns
| Path | Role |
.openvex.json | The OpenVEX v0.2.0 document. The only suppression mechanism. |
.grype.yaml | Scan config: path excludes, plus an ignore: list that is not for suppression (see below). |
.github/workflows/vuln-scan-images.yaml | Daily 09:00 UTC scan of the main-built operator and agent images (filed under main) and of each component's newest stable release, CLI included at linux/amd64 and windows/amd64 (filed under that release's branch); operator and agent at linux/amd64 and linux/arm64; SARIF categories grype-operator, grype-operator-arm64, grype-agent, grype-agent-arm64, grype-cli and grype-cli-windows. Never fails a build. |
.github/actions/vuln-gate | The release gate: every operator, agent and CLI tag fails on a fixable critical or high finding .openvex.json does not suppress, read from the tag's own checkout. Prints no findings; make vuln-scan IMAGE=... reproduces them locally. |
.claude/skills/nodewright-managing-openvex/vex-state.yaml | Working notes and open verifications for this skill. |
Step 1 (always first): read vex-state.yaml
Read .claude/skills/nodewright-managing-openvex/vex-state.yaml before doing
anything else. It records checks that could not finish in an earlier session,
negative results nobody should repeat, and decisions not to act. Doing the
triage without it means redoing work that was already done, or silently
reversing a decision someone made deliberately.
Step 2: suppress in .openvex.json, never in the Security tab
Do not dismiss a code scanning alert to make a finding go away.
Grype applies .openvex.json at scan time through the workflow's vex: input,
so a suppressed finding never becomes an alert in the first place. A UI
dismissal is invisible to the document, so the two drift apart. That matters
beyond tidiness: every operator, agent and CLI release attests .openvex.json,
projected per platform, as signed evidence on its images, and nSpect imports
it from there. A suppression living only in the GitHub UI makes the signed
artifact the wrong one, and the signed artifact is the one consumers read.
A statement written after a release does not reach that release's images by
itself. Once it is on the component's release branch, publish it with
vex-reattest.yaml (docs/contributing/release-process.md, "Correcting VEX on a
released image").
.grype.yaml's ignore: list is not the alternative. It is reserved for the
opposite case: a finding that is reachable in our code and has no fixed
version upstream yet, which is accepted risk rather than "not affected". Its own
header states the four things every entry must record. If you are reaching for
it, reread that header first.
Step 3: check main before writing any statement
The workflow files each finding under the branch that produced the image:
main for the main-built images, and the release branch for the newest
stable release (what latest carries), which lags main. make vuln-status
shows both side by side.
The CLI is the exception: it is built only from tags, so there is no main CLI
scan, and a CLI finding missing from main says nothing about whether it is
fixed. For a CLI finding, answer the question from operator/go.mod (the CLI
is built from the operator module) with the checks below, never from the
Security tab's main view.
So a finding can mean either of two very different things:
- Unfixed. The dependency is still vulnerable on
main. Fix it, or write a VEX statement if we are genuinely not affected. - Already fixed on
main, not yet released. Nothing is wrong with the code. The remedy is cutting a release.
Issue #629 is exactly case 2: the released operator image reports 2 HIGH that
operator/go.mod already fixed. Writing a VEX statement for that would be
false. The document would assert we are not affected when we simply have not
shipped the fix.
Check before writing:
Which file answers the question depends on where the package came from, and for
these images most findings are not direct dependencies. Check the artifact
type in the scan output first (.matches[].artifact.type) and follow it:
# Go modules (artifact.type == "go-module"): operator and agent.
grep -n '<module-path>' operator/go.mod agent/go.mod
git log --oneline -5 -- operator/go.mod agent/go.mod
# Base-image contents (artifact.type == "deb" or "binary") come from the
# distroless base, not from our source. Nothing in this repo pins their
# versions: `scripts/latest-distroless.sh` resolves the newest base at build
# time, so "is it fixed on main?" means "does a newer base carry the fix?".
grep -n 'DISTROLESS_VERSION\|FROM nvcr.io' containers/agent.Dockerfile containers/operator.DockerfileFor a base-image finding, compare the base directly rather than guessing. Scan
the base tag the released image was built on (its
org.opencontainers.image.base.name label) against the newest available tag. If
the newer base clears it, the remedy is a rebuild and release, not a statement.
That is #628.
If main already carries the fix, stop. Record the finding on the release
issue, not in .openvex.json.
The one exception is a released image that is genuinely not affected, where
the fix on main is only a version bump. Agent v7.0.0's Go 1.27.1 findings are
the example: the vulnerable packages are not linked into the binary at all,
and nSpect requires a VEX statement for each finding on the shipped image. A
statement is then true for that image and belongs in .openvex.json, pinned to
the exact vulnerable version in its subcomponent purl so it stops matching
main's builds by itself. Establish "not linked" from the main package's build
(go list -deps ./cmd/agent and govulncheck in source mode at the release
tag, with the image's GOOS and Go version), never from govulncheck
-mode=binary on the stripped image binary, which reports every advisory's
symbols as found. Publish it with vex-reattest.yaml.
Step 4: get the vulnerability ID right
vulnerability.name in a statement must equal grype's primary ID, the
.matches[].vulnerability.id field. For ecosystem advisories (Go, PyPI, npm)
that is usually the GHSA, with the CVE appearing only under
relatedVulnerabilities.
OpenVEX matches by exact string, across @id, name, and aliases. A statement
naming only a CVE will not match a finding whose primary ID is a GHSA: it will
look correct and suppress nothing. Read the alias warning below before reaching
for aliases to fix that.
Pull the primary ID and its aliases out of a scan:
GRYPE_DB_VALIDATE_AGE=false GRYPE_CHECK_FOR_APP_UPDATE=false \
grype ghcr.io/nvidia/nodewright/operator:latest -o json \
| jq -r '.matches[]
| select(.vulnerability.severity | ascii_downcase | IN("high","critical"))
| "\(.vulnerability.id)\t\(.vulnerability.severity)\t\(.artifact.name)@\(.artifact.version)\taliases=\([.relatedVulnerabilities[]?.id] | join(","))"'The first column is what goes in vulnerability.name.
aliases is also a match key, so do not treat it as searchable decoration.
go-vex matches a statement against a finding by checking @id, name, and
every entry in aliases. Adding the CVE alongside a GHSA therefore widens the
statement to any other finding in the image whose primary ID is that CVE, in
a package you never reasoned about. That is live here: in the agent image most
HIGH+ findings are Debian packages whose primary ID is a CVE, while the Go and
PyPI ones are GHSA-primary with CVE aliases. List an alias only when you mean
the statement to cover it.
Narrowing with subcomponents is not optional here, and it is what keeps an
alias from doing damage. Grype passes the matched package's purl as the
subcomponent identifier, so a product with no subcomponents matches the entire
image for that vulnerability ID. The validator rejects that product, and rejects
a subcomponent purl with no version. See Step 6 for the shape and the reasoning.
GRYPE_DB_VALIDATE_AGE=false GRYPE_CHECK_FOR_APP_UPDATE=false is a local-only
workaround: this sandbox blocks grype's database and update hosts, so without
it grype refuses a stale local DB. It must never appear in a workflow. CI has
network access and a stale database there would silently under-report.
Step 5: get the product PURL right
Grype derives the OCI product PURL from the registry repository basename,
not from the org.opencontainers.image.title label. For these images that makes
the expected values:
pkg:oci/operatorpkg:oci/agentpkg:oci/cli, for the CLI artifact atghcr.io/nvidia/nodewright/cli. Its statements are bound into the signed VEX on each CLI platform manifest like the images'. Each CLI platform is a one-layer image, so the scan pullsghcr.io/nvidia/nodewright/cli:latestfrom the registry like the images, once for linux/amd64 and once for windows/amd64 (Windows links modules the others do not), and matchespkg:oci/clithe same way. Assess every shipped CLI platform before writing apkg:oci/clistatement. The CLI has no platform-scoped product: one statement is bound into the VEX on every platform manifest (linux, darwin and windows on amd64 and arm64) and suppresses the finding in both scan legs. Build-tagged sources link different code per platform, so anot_affectedjustification checked only on Linux can be false on Windows. If it does not hold for every platform, leave the finding open rather than writing the statement.
pkg:oci/operator is verified: a test statement carrying it dropped the
image's HIGH+ count from 2 to 1. pkg:oci/agent is inferred rather than
measured, but follows by the same code path: grype derives
pkg:oci/<basename>@sha256:...?repository_url=... from the image's
RepoDigests, and a version-less, qualifier-less purl matches it.
A mismatched PURL silently suppresses nothing while looking perfectly correct in review, which is the worst failure mode this document has.
Carry the PURL in both @id and identifiers.purl on every product, with
the same value. OpenVEX v0.2.0 has no products[].purl field: a product is a
Component carrying @id, identifiers, and hashes, so the purl lives at
identifiers.purl. Grype will in practice also match a @id that begins with
pkg:, so writing both is belt and braces rather than strictly required, but it
is what the sibling project's working document does on every statement and it
costs nothing.
Every statement must be verified empirically before it is merged, not just
the first one. This is not a one-time bootstrap. A mistyped status is the
clearest reason why: "not-affected" with a hyphen instead of an underscore
makes grype exit 0 with no warning and suppress nothing. So do a wrong purl, a
CVE where the primary ID is a GHSA, and a typo'd package name. None of them
produce an error; all of them produce a document that reads correctly and does
nothing.
The measurement is the only thing that distinguishes a working statement from a
decorative one. Do not verify by reading; verify by measuring the HIGH+ count
with and without --vex against the same image:
IMG=ghcr.io/nvidia/nodewright/operator:latest
COUNT='[.matches[] | select(.vulnerability.severity | ascii_downcase | IN("high","critical"))] | length'
before=$(GRYPE_DB_VALIDATE_AGE=false GRYPE_CHECK_FOR_APP_UPDATE=false \
grype "$IMG" -o json | jq "$COUNT")
after=$(GRYPE_DB_VALIDATE_AGE=false GRYPE_CHECK_FOR_APP_UPDATE=false \
grype "$IMG" --vex .openvex.json -o json | jq "$COUNT")
echo "before=$before after=$after"after must be lower than before by exactly the number of findings the new
statement covers. If the counts are identical, the statement matched nothing:
suspect the PURL first, then the vulnerability ID. Do not merge a statement that
has not moved the count.
If the count does not move, the statement is decorative. Do not merge it.
The exception is a finding grype does not report at all but nSpect does, which
happens for Go standard-library advisories it has not picked up yet. There is
no count to move, so measure what grype can see (it must not regress), validate
the projection with go run ./cmd/openvex in tools/, and record the statement
in vex-state.yaml under known_negatives with what would make it measurable.
The check that it works is nSpect listing the finding as source-managed OCI VEX
after the release (or re-attest) publishes it.
Step 6: write the statement to the v0.2.0 contract
status must be one of exactly:
not_affectedaffectedfixedunder_investigation
Two hard requirements:
- A
not_affectedstatement must carry ajustificationor animpact_statement. - An
affectedstatement must carry anaction_statement.
If a justification is present it must be one of exactly these five. There is
no free-text justification:
component_not_presentvulnerable_code_not_presentvulnerable_code_not_in_execute_pathvulnerable_code_cannot_be_controlled_by_adversaryinline_mitigations_already_exist
If none of the five is honestly true, use an impact_statement and say why in
prose, or do not write the statement at all. Picking the nearest-sounding
justification is how a signed document ends up asserting something false.
Shape:
{
"vulnerability": {
"name": "GHSA-xxxx-xxxx-xxxx",
"aliases": ["CVE-2026-NNNNN"]
},
"products": [
{
"@id": "pkg:oci/operator",
"identifiers": { "purl": "pkg:oci/operator" },
"subcomponents": [
{ "@id": "pkg:golang/google.golang.org/grpc@v1.82.1" }
]
}
],
"status": "not_affected",
"justification": "vulnerable_code_not_in_execute_path",
"impact_statement": "One or two sentences naming the specific call path we do not take."
}Subcomponents are required, and so is the version
The validator rejects a product with no subcomponents, and rejects a subcomponent purl carrying no version.
A statement naming only the product asserts that the whole image is unaffected. That is never what the assessment was: it was about one package, which the impact statement already names in prose. The subcomponent puts that in the part a machine reads, and downstream VEX consumers need the full package name and the version matching the scan output.
The version is the part worth insisting on, because it makes the suppression expire by itself. Measured against a real finding, varying only the subcomponent purl:
| subcomponent purl | suppresses |
pkg:golang/<module>@<exact version> | yes |
pkg:golang/<module> (no version) | yes |
pkg:golang/<module>@<wrong version> | no |
pkg:golang/<other module>@<version> | no |
So a versioned statement stops applying the moment the package is upgraded: the next scan re-reports the finding against the new version and someone reassesses it. A version-less one keeps suppressing whatever ships, including a version nobody looked at.
Take the purl verbatim from the scan rather than composing it by hand:
GRYPE_DB_VALIDATE_AGE=false GRYPE_CHECK_FOR_APP_UPDATE=false \
grype ghcr.io/nvidia/nodewright/agent:latest -o json \
| jq -r '.matches[] | select(.vulnerability.id == "<GHSA or CVE>") | .artifact.purl'purl puts the version before the qualifiers, as in pkg:deb/debian/libssl3t64@3.5.6-1~deb13u1?arch=arm64. An @ inside a qualifier value is not a version, and the validator does not accept one as a substitute.
Step 7: keep document-level fields as identifiers, not prose
@id, author, role, timestamp, version, and tooling are metadata
fields. They identify the document. They are not a place to explain reasoning.
tooling in particular. A sibling NVIDIA project let that field grow into an
8,010-byte changelog, which then shipped, signed, on seven release images before
anyone noticed (NVIDIA/aicr#2706). Ours reads
manual curation (.claude/skills/nodewright-managing-openvex) and should stay
that length.
Working notes, open questions, and rejected options go in vex-state.yaml.
Reasoning a reader needs goes in the statement's impact_statement, which is
the field designed for it. Nothing narrative goes in a document-level field.
On every change to the document:
- Bump
version(integer, monotonic). - Update
timestampto the current UTC time in RFC 3339. - Leave
@id,author,role, andtoolingalone.
Step 8: triage by severity, not by alert count
The uploaded SARIF contains every finding with an available fix, not only
HIGH and above. severity-cutoff: high in the workflow neither filters the
report nor grades it: the SARIF level is a pure function of the finding's own
severity (critical and high become error, medium becomes warning, anything
lower becomes note). All severity-cutoff does is set grype's --fail-on,
which is inert while fail-build is false; it is kept so the scan and the
release gate (--fail-on high) name the same threshold.
Grype sets a security-severity (CVSS) property on each rule, so GitHub grades
alerts correctly and the Security tab can filter by severity. Use that filter.
Triage HIGH and CRITICAL. Low and Medium findings do not need a statement. Writing one for every Low alert is how the document stops being reviewable.
Filter existing alerts by category and severity:
gh api -X GET repos/NVIDIA/nodewright/code-scanning/alerts \
-f state=open -f tool_name=grype --paginate \
| jq -r '.[]
| select(.rule.security_severity_level | IN("high","critical"))
| "\(.most_recent_instance.category)\t\(.rule.security_severity_level)\t\(.rule.id)"' \
| sort | uniq -cStep 9 (always last): update vex-state.yaml
Before finishing, write back to
.claude/skills/nodewright-managing-openvex/vex-state.yaml:
- Delete any
deferred_verificationsentry whose check has now been run and passed. A failed check is not a resolution; it is the finding you are now triaging. - Delete any
known_negativesordeliberate_exclusionsentry whoseinvalidated_bycondition has fired. Do not rewrite it as history. - Add an entry for anything this session could not finish, already ruled out, or deliberately chose not to do.
Every entry must state what would invalidate it. An entry that cannot state that is not state; it is prose, and it belongs in a PR description or nowhere. The file's header explains the lifecycle rules in full.
Quick reference: local scan
GRYPE_DB_VALIDATE_AGE=false GRYPE_CHECK_FOR_APP_UPDATE=false \
grype ghcr.io/nvidia/nodewright/agent:latest \
--config .grype.yaml \
--vex .openvex.json \
--only-fixed \
-o tableRun the workflow on demand rather than waiting for the next day:
gh workflow run "Image Vulnerability Scan" --repo NVIDIA/nodewright
gh run list --workflow "Image Vulnerability Scan" --repo NVIDIA/nodewright --limit 3Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

