feat(security): advisory early-warning correlation and audit provenance records

[Dongni-Yang]

Summary

Implements the non-operational, code-shaped acceptance criteria of #7338: a correlation library and local CLI that surface public advisories before they reach the reviewed corpus npm audit enforces, and provenance records for every audit so disclosure-to-detection timelines are provable from retained artifacts.

Scope note (review follow-up): per review, the scheduled workflow (issues: write) and its operating-policy documentation were split out to #7398, which stays draft until product/security owners record sign-off on #7338's scope / rescan-ownership / alert-destination / response-expectation criterion. This PR defines no operational surface: nothing here is scheduled, holds write permissions, or encodes policy.

Changes

• Correlation module (scripts/lib/advisory-early-warning.mts, dependency-free): parses GitHub Security Advisory records and correlates them against the reviewed-graph package inventories (ci/reviewed-npm-audit.json specs + locked-graph package-locks, alias-aware). Exact npm package + parseable-range matches emit investigate signals; ambiguous or CPE-style matches stay informational — per the issue, ambiguous matches never block or mutate anything. Unparseable ranges fail safe (noisy, never silent).
• Scan CLI (scripts/advisory-early-warning-scan.mts): local-file-only driver over the module. --list-packages emits inventory package names (the input for /advisories API queries); --advisories <file> [--output <file>] correlates fetched records and prints/writes structured signals. Exits 0 with or without signals; no network or tokens; it does not modify inputs or external state, and --output writes the requested local signals file.
• Provenance sidecars: scripts/audit-reviewed-npm-graph.mts (reviewed graphs) and .github/actions/ci-wechat-runtime-audit/audit.sh (wechat runtime graph) now write a *.provenance.json next to each raw report: scanner identity, npm/node versions, configured registry and derived bulk advisory endpoint, run start/end times, audited package identity, raw report path, extracted GHSA ids — and a failure marker whenever the audit attempt itself failed, including npm's dominant failure mode of parseable error JSON (verified against a captured dead-registry npm audit --json output), so a failed attempt can never masquerade as a clean non-detection. Sidecars ride the existing artifact uploads.
• Docs (docs/security/advisory-early-warning.md): how the correlation works, what each advisory type contributes, CLI usage, and the provenance recorded per audit. Scheduled operation and the proposed policy defaults now live in feat(security): schedule the advisory early-warning scan #7398's version of this page, gated on Detect public advisories before reviewed ecosystem mappings reach scanners #7338 sign-off.

Scope notes

• Covered from the issue's acceptance criteria: pre-reviewed-advisory fixture + correlation signal, ambiguous-match non-blocking, reviewed-audit enforcement untouched and authoritative, per-audit provenance incl. actual endpoint (verified empirically: npm ≥7 posts to the bulk endpoint only — the sidecar records no fictitious fallback).
• Moved to feat(security): schedule the advisory early-warning scan #7398 (gated on the product/security-owner criterion): scheduled rescans on advisory-data changes, alert routing, and the policy defaults (scope, rescan ownership, alert destination, response SLAs).
• Explicitly left as proposals or follow-ups: the npm advisory database snapshot time (not exposed by npm audit; the sidecar records endpoints + run window instead, and "last comparable non-detection" comes from diffing advisoryIds across retained runs), per-upstream-repo advisory polling (needs a package→repo map; named in the doc as the natural extension), Trivy/image-digest provenance, and the fix(images): backport historical OpenClaw security patches #7276 post-mortem classification.

Testing

• 67/67 across the two touched suites (advisory-early-warning 49, reviewed-npm-audit 18 incl. an integration-style test proving sidecar-write-before-rethrow with a fake npm); tsc strict clean; biome clean; shellcheck/bash -n clean.
• Empirical verification on top of unit tests: live GitHub /advisories API calls (parameter semantics, pagination truncation repro, type=malware affects filtering), a captured dead-registry npm audit fixture for the failure-marker path, and standalone heredoc runs for the shell sidecar matrix.
• Three adversarial local review rounds (premise incl. live-API ground-truthing, correctness incl. empirical repros, contract+security incl. injection tracing); final round dry apart from two Low findings fixed and re-verified before this PR.

Refs #7338

Signed-off-by: Dongni-Yang dongniy@nvidia.com

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added scheduled “Security / Advisory Early Warning” scan (every 6 hours) with manual trigger support, producing non-blocking correlation signals.
  • Added structured npm audit provenance sidecars (npm-audit.provenance.json) next to raw audit output, capturing timing, versions, and extracted advisory identifiers.

• Bug Fixes

  • Improved resilience to malformed/non-JSON audit output and strengthened “fails closed” provenance failure reporting.

• Documentation

  • Expanded security documentation to describe early-warning correlation logic and provenance artifacts.

• Tests

  • Added/updated coverage for early-warning correlation and audit provenance generation behavior.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PR adds npm audit provenance sidecars with timing, registry, graph, advisory, and failure metadata. It also adds advisory-to-inventory correlation utilities, a non-blocking CLI, tests, and security documentation.

Changes

Security monitoring

Layer / File(s)	Summary
npm audit provenance sidecars .github/actions/ci-wechat-runtime-audit/audit.sh, scripts/audit-reviewed-npm-graph.mts, test/reviewed-npm-audit.test.ts, test/wechat-runtime-audit-workflow.test.ts, docs/security/advisory-early-warning.md	Audits record timing and status, generate provenance sidecars, extract GHSA IDs, preserve failure details, and pass graph/runtime context through audit calls.
Advisory parsing and correlation scripts/lib/advisory-early-warning.mts, test/advisory-early-warning.test.ts	Advisories and reviewed inventories are parsed, semver ranges are evaluated, and exact or ambiguous signals are produced with corresponding actions.
Correlation CLI scripts/advisory-early-warning-scan.mts, docs/security/advisory-early-warning.md	The CLI loads local inventories and advisory files, optionally writes signals, prints results, and remains non-blocking for correlation findings.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant Inventory
  participant AdvisoryFile
  participant Correlator
  CLI->>Inventory: load reviewed and locked-graph packages
  CLI->>AdvisoryFile: load advisory JSON
  CLI->>Correlator: correlate advisories with inventory
  Correlator-->>CLI: return sorted signals
  CLI-->>CLI: print or write signals

Loading

Possibly related issues

• Issue 7338 — Covers the early-warning advisory correlation, provenance, and future alert-routing requirements implemented or documented by this PR.

Possibly related PRs

• NVIDIA/NemoClaw#7345 — Both PRs modify the reviewed npm audit pipeline, including scripts/audit-reviewed-npm-graph.mts.

Suggested labels: area: docs, area: packaging

Suggested reviewers: cjagwani, apurvvkumaria, cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main changes: advisory early-warning correlation plus audit provenance records.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dongniy/7338-audit-provenance

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-7354.docs.buildwithfern.com/nemoclaw

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit fd99f88 in the dongniy/7338-audit-p... branch remains at 96%, unchanged from commit f084837 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit fd99f88 in the dongniy/7338-audit-p... branch remains at 80%, unchanged from commit f084837 in the main branch.

Show a code coverage summary of the most impacted files.

File	main f084837	dongniy/7338-audit-p... fd99f88	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/state/m...ock-identity.ts	95%	95%	0%
src/lib/state/m...lock-storage.ts	97%	97%	0%
src/lib/tunnel/services.ts	73%	73%	0%
src/lib/state/m...-acquisition.ts	84%	89%	+5%

---

_{Updated July 23, 2026 22:31 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 2 warnings · 7 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 more warning, 7 more suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: None

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Add a process-level test for the advisory scan CLI

• Location: scripts/advisory-early-warning-scan.mts:51
• Category: tests
• Problem: The new CLI has unit coverage for its library, but no test invokes the CLI with its repository-relative inventory input and `--output` contract.
• Impact: A regression in argument parsing, repository-relative inventory loading, exit behavior, or signal-file output can ship while library unit tests continue to pass.
• Recommendation: Add a temporary-repository subprocess test that invokes the CLI with a fixture advisory and `--output`, then asserts status 0, emitted signal text, and the written JSON signals file.
• Verification: Inspect test/advisory-early-warning.test.ts for a test that spawns scripts/advisory-early-warning-scan.mts and asserts its output-file behavior.
• Test coverage: A Vitest subprocess test runs the CLI against a temporary repository fixture with an affected advisory and verifies exit status, stdout summary, and the JSON written by `--output`.
• Evidence: scripts/advisory-early-warning-scan.mts lines 51-96 implement CLI argument parsing, repository-relative inventory loading, and `--output` writing. test/advisory-early-warning.test.ts tests correlation and parsing exports but does not invoke the CLI executable. The test context identifies runtime validation as recommended for changed process boundaries.

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[Dongni-Yang]

Note on the build-sandbox-images failures — pre-existing advisory breakage, not introduced by this PR.

The failing step is Dockerfile.base's mcporter runtime gate: npm --prefix .../mcporter-runtime audit --omit=dev --audit-level=low. It fails on advisories that reached the GitHub-reviewed corpus after the runtime lock was pinned — the log shows @hono/node-server <2.0.5 (moderate, GHSA-frvp-7c67-39w9) and @modelcontextprotocol/sdk >=1.25.0 against the pinned mcporter@0.7.3 graph.

Why it fires here and not on sibling PRs: this PR adds a file under scripts/lib/, which is part of the image build context for that stage, so the Docker layer cache is invalidated and the audit actually re-runs against today's advisory database. PRs that don't touch the image inputs ride the cached layer and pass (e.g. #7353, ~30 min earlier). Any PR touching scripts/ or Dockerfile.base will now hit this until the mcporter runtime lock is remediated (related in-flight work: #7355, #7332).

For what it's worth, this is a live instance of the propagation-window problem this PR is about: the advisories existed upstream before the reviewed records started enforcing overnight — the early-warning scan added here would have surfaced them ahead of the red CI.

Signed-off-by: Dongni-Yang dongniy@nvidia.com

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/security/advisory-early-warning.md (1)

5-11: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoff

Keep one sentence per line in Markdown source.

This page wraps sentences across multiple lines (e.g. Lines 5-11, 27-30, 46-57). The repository docs convention is one sentence per line, which keeps diffs reviewable. Please reflow the prose so each sentence occupies its own line.

As per coding guidelines: "Keep one sentence per line in Markdown and MDX source files."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/security/advisory-early-warning.md` around lines 5 - 11, Reflow the
prose in advisory-early-warning.md so every sentence is contained on a single
Markdown source line, including the sections currently wrapped across lines
5-11, 27-30, and 46-57. Preserve all wording, formatting, and content while
applying the repository’s one-sentence-per-line convention.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/security/advisory-early-warning.md`:
- Line 1: Add the repository’s standard two-line SPDX license header to the top
of the Markdown document before the “Advisory Early Warning and Audit
Provenance” heading, using valid Markdown comment syntax and matching the
headers used by the other files in this change.

---

Nitpick comments:
In `@docs/security/advisory-early-warning.md`:
- Around line 5-11: Reflow the prose in advisory-early-warning.md so every
sentence is contained on a single Markdown source line, including the sections
currently wrapped across lines 5-11, 27-30, and 46-57. Preserve all wording,
formatting, and content while applying the repository’s one-sentence-per-line
convention.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d91862a4-76b0-493f-951a-8bb23eb5db11

📥 Commits

Reviewing files that changed from the base of the PR and between 5087eb4 and 79d6625.

📒 Files selected for processing (8)

• .github/actions/ci-wechat-runtime-audit/audit.sh
• .github/workflows/advisory-early-warning.yaml
• docs/security/advisory-early-warning.md
• scripts/advisory-early-warning-scan.mts
• scripts/audit-reviewed-npm-graph.mts
• scripts/lib/advisory-early-warning.mts
• test/advisory-early-warning.test.ts
• test/reviewed-npm-audit.test.ts

[cjagwani]

This needs the product/security scope gate resolved before it enters the approval path. #7338 is still labeled needs: triage; its acceptance criterion requiring product/security owners to define supported historical-image scope, rescan ownership, alert destination, and response expectations is unchecked. The PR also correctly describes those defaults as proposals pending confirmation. Because this adds a scheduled operational workflow with issues: write and documents its operating policy, green code/CI is not enough to establish the supported surface. Please obtain explicit product/security-owner sign-off on those choices, record it on #7338, and update the documentation from proposed to accepted behavior (or narrow the PR to non-operational/provenance-only pieces). Then refresh and rerun the cancelled WSL lane for the exact revision.

[Dongni-Yang]

@cjagwani Agreed the scope gate isn't mine to green-light, so I took the narrowing option:

• This PR is now non-operational/provenance-only (05bcaf5, after a refresh merge of main): the correlation module, the local scan CLI (no network, no tokens, no writes), the per-audit provenance sidecars, and mechanics-only docs. The scheduled workflow (issues: write) and the operating-policy documentation are removed from this PR.
• The operational slice moved to feat(security): schedule the advisory early-warning scan #7398, a draft stacked on this branch and explicitly marked do-not-merge until product/security owners record sign-off on Detect public advisories before reviewed ecosystem mappings reach scanners #7338. I've asked for that decision on the issue, with the previously-proposed defaults as a concrete starting point.
• The branch is refreshed to current main, and the new revision re-runs every lane including wsl-e2e; if it gets cancelled by supersession again I'll rerun it for the final revision.

The PR body is updated to describe the narrowed diff.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/security/advisory-early-warning.md`:
- Around line 56-58: Update the CLI behavior description in
advisory-early-warning.md to remove the claim that it never mutates anything.
Clarify that it does not modify input files or external state, while writing the
requested local signals.json output when --output is supplied.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 0a5df7f5-d153-4635-adce-2a3b393a3b33

📥 Commits

Reviewing files that changed from the base of the PR and between 1b53bb7 and 05bcaf5.

📒 Files selected for processing (2)

• docs/security/advisory-early-warning.md
• scripts/audit-reviewed-npm-graph.mts

🚧 Files skipped from review as they are similar to previous changes (1)

• scripts/audit-reviewed-npm-graph.mts

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

docs/security/advisory-early-warning.md (1)

7-8: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Keep each sentence on one physical line.

Several new sentences are hard-wrapped across multiple source lines. Reflow them to comply with the documentation convention while retaining the existing periods.

As per coding guidelines: “Keep one sentence per line in Markdown and MDX source files.”

Also applies to: 10-17, 19-20, 22-31, 33-36, 40-54

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/security/advisory-early-warning.md` around lines 7 - 8, Reflow the
affected prose in the advisory document so every sentence occupies one physical
Markdown source line, including the sentences around the scheduled operation and
response policy. Preserve all existing wording, punctuation, and periods while
removing hard wraps across the referenced sections.

Source: Coding guidelines

test/wechat-runtime-audit-workflow.test.ts (1)

62-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use the established POSIX PATH separator.

Use : here rather than path.delimiter; these tests run on POSIX CI runners and the suite intentionally standardizes this construction.

Based on learnings, “prefer the established POSIX PATH separator :” in these tests.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/wechat-runtime-audit-workflow.test.ts` at line 62, Update the PATH
construction in the test environment setup to use the literal POSIX separator
“:” instead of path.delimiter. Keep the existing targetRoot/bin and
process.env.PATH values unchanged.

Source: Learnings

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/wechat-runtime-audit-workflow.test.ts`:
- Around line 82-105: Update installFakeAuditNpm so auditReport can be supplied
as raw output text while preserving serialized JSON behavior for structured
reports; then add a table-driven test case using malformed output such as
"{not-json" that asserts the action reports a “parseable JSON report” failure.

---

Nitpick comments:
In `@docs/security/advisory-early-warning.md`:
- Around line 7-8: Reflow the affected prose in the advisory document so every
sentence occupies one physical Markdown source line, including the sentences
around the scheduled operation and response policy. Preserve all existing
wording, punctuation, and periods while removing hard wraps across the
referenced sections.

In `@test/wechat-runtime-audit-workflow.test.ts`:
- Line 62: Update the PATH construction in the test environment setup to use the
literal POSIX separator “:” instead of path.delimiter. Keep the existing
targetRoot/bin and process.env.PATH values unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 42e35416-7d9e-4bbd-b939-ad51fca6e905

📥 Commits

Reviewing files that changed from the base of the PR and between 05bcaf5 and 20f2e8a.

📒 Files selected for processing (3)

• .github/actions/ci-wechat-runtime-audit/audit.sh
• docs/security/advisory-early-warning.md
• test/wechat-runtime-audit-workflow.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• .github/actions/ci-wechat-runtime-audit/audit.sh

Dismissed as stale after exact-head revalidation. The operational scheduled workflow and issues: write scope were removed from this PR and moved to draft #7398 pending #7338 product/security sign-off. The current exact head 7b2a512 has zero unresolved threads, all required checks and E2E lanes green, Verified DCO commits, and fail-closed audit-report coverage.

[apurvvkumaria]

Exact-head re-review complete at 7b2a512. The prior blocking scope concern is satisfied: operational scheduling and issues:write moved to draft #7398, while this PR is non-operational. Exact-head WSL and all required CI/E2E/advisor checks pass, all commits are Verified/DCO-compliant, and there are no unresolved review threads. Remaining documentation/POSIX suggestions are nonblocking fix-forward nits.