cve-audit · diff
git:20260716.c3487c6 to git:20260723.6e5370b
78 added, 139 removed. Audit A to A.
---
name: cve-audit
- description: Audit exact npm dependency versions against OSV and emit a reproducible evidence packet with zero unverified findings.
- source:
- type: cli-tool
- command: node
- args:
- - scan.mjs
- - core.mjs
- timeout_seconds: 120
- sandbox:
- profile: network
- cwd_policy: skill-directory
- network: true
- require_enforcement: false
- inputs:
- target_name:
- type: string
- required: true
- description: Human-readable name of the audited project.
- target_repo:
- type: string
- required: true
- description: Public source repository URL.
- target_commit:
- type: string
- required: true
- description: Full immutable Git commit containing the lockfile.
- lockfile_url:
- type: string
- required: true
- description: Public HTTPS package-lock.json URL pinned to target_commit.
- dependency_scope:
- type: string
- required: false
- default: direct-production
- description: direct-production or all-installed.
+ description: Audit exact npm dependency versions against OSV through Runx native HTTP and emit replay-verified evidence with no unverified findings.
runx:
category: security
tags:
- cve
- dependencies
- osv
- artifacts:
- named_emits:
- audit_result: audit_result
- report: report
- evidence: evidence
links:
source: https://github.com/jaasieldelgado131/runx-exact-cve-audit
registry: https://runx.ai/x/jaasieldelgado131/cve-audit
advisory_source: https://osv.dev
---
# Exact CVE Audit
- ## What this skill does
-
- This skill audits exact npm versions from an immutable `package-lock.json`
- against the public OSV API. It emits a machine-readable audit result,
- `evidence.json`, and a finding-by-finding Markdown report. The governed graph in
- `X.yaml` independently replays every query and seals a delivery packet only
- when the reported and replayed advisory sets match exactly.
-
- It does not install dependencies, execute target code, mutate the target
- repository, repair packages, or publish vulnerability claims.
+ Audit exact npm versions from an immutable `package-lock.json` against OSV.
+ Runx owns every network request, response bound, retry, host admission, and
+ receipt. Package code owns only lockfile inventory and OSV result semantics.
- ## When to use this skill
+ The audit is read-only. It does not install dependencies, execute target code,
+ repair packages, publish advisories, or treat missing OSV data as proof of
+ safety.
- Use it when a reviewer needs checkable evidence for the advisories affecting
- the exact npm versions in a public, immutable lockfile. It is suitable for
- dependency review, release triage, and reproducible security evidence where a
- package-name-only or loose-range match would create false positives.
+ ## When to use it
- ## When not to use this skill
+ Use `cve-audit` when a reviewer needs reproducible evidence for the advisories
+ affecting exact npm versions in a public immutable lockfile. It is appropriate
+ for dependency review, release triage, and the evidence stage before
+ `vuln-triage`. Exact-version matching matters: package-name or loose-range scans
+ can turn possible exposure into false findings.
- Do not use it for a mutable branch URL, a manifest without exact installed
- versions, a private lockfile without explicit read authority, non-npm
- ecosystems, exploit development, or claims about transitive coverage when the
- selected scope is `direct-production`. Do not treat missing OSV data as proof
- that a package is safe.
+ Do not use it for mutable branch URLs, private repositories without a declared
+ reader, non-npm ecosystems, exploit development, or coverage claims broader
+ than the selected dependency scope.
## Inputs
- - `target_name`: display name for the audited project.
- - `target_repo`: public HTTPS source repository.
- - `target_commit`: full 40-character immutable Git commit.
- - `lockfile_url`: public HTTPS lockfile URL containing that commit.
+ - `target_name`: human-readable project name.
+ - `target_repo`: public `https://github.com/...` repository URL.
+ - `target_commit`: full 40-character Git commit.
+ - `lockfile_url`: `raw.githubusercontent.com` package-lock URL containing that
+ commit in its path.
- `dependency_scope`: `direct-production` by default, or `all-installed`.
- The caller authorizes only public reads of the pinned lockfile and OSV. No
- credential, token, local project file, or private payload is an accepted input.
-
- ## Procedure
+ Private repositories, credentials, mutable branch URLs, abbreviated commits,
+ and non-npm lockfiles are outside this runner.
- 1. Validate that the repository and lockfile URLs use HTTPS, the commit is a
- full Git hash, and the lockfile URL is pinned to that hash.
- 2. Fetch the lockfile and record its SHA-256 digest before parsing it.
- 3. Extract exact installed versions from lockfile versions 2 or 3. Preserve the
- requested scope in every artifact.
- 4. Query OSV with `{ ecosystem: npm, package, version }` for every inventory
- entry. Exclude withdrawn advisories.
- 5. Record each finding with dependency, exact version, advisory ID, OSV URL,
- aliases, installed path, and the exact query that produced it.
- 6. In the governed graph, replay every exact-version query in a separate step.
- Fail closed if an advisory is unsupported, omitted, withdrawn, or changed.
- 7. Emit the report, evidence, verification, delivery packet, and sealed receipt.
+ ## Execution contract
- ## Edge cases and stop conditions
+ 1. Validate the immutable GitHub target before any network call.
+ 2. Read the pinned lockfile with native `http.read`, retaining its transport
+ digest and refusing truncation.
+ 3. Extract exact installed versions from package-lock versions 2 or 3. The
+ inventory is capped at 10,000 entries.
+ 4. Query OSV in batches of 500 with native `http.query`. This is a POST-only,
+ read-only query boundary; it is not a mutation lane.
+ 5. Refuse the audit if any OSV query result carries a page token. A partial
+ provider result must never be reported as complete.
+ 6. Read each returned advisory with native `http.read`, validate advisory
+ identity, and exclude withdrawn advisories. The verified advisory set is
+ capped at 50; a larger set stops instead of being truncated.
+ 7. Assemble the audit, report, and evidence from the exact inventory and full
+ advisory records.
+ 8. Repeat the OSV query and advisory reads in separate graph steps. Compare
+ dependency path, exact version, advisory id, and withdrawal state. Finalize
+ only when the two complete sets match.
- - Refuse non-HTTPS or mutable lockfile URLs.
- - Refuse abbreviated commits and lockfiles that do not contain the commit.
- - Refuse unsupported lockfile versions or entries without exact versions.
- - Return `needs_input` when the target, commit, or lockfile evidence is not
- immutable enough to support reproducible review.
- - Stop if OSV times out, returns malformed data, or changes between scan and
- independent replay.
- - Stop if any false hit or missing hit is detected.
- - Report the selected dependency scope; never imply broader coverage.
- - Keep tokens, credentials, private source, and target code out of artifacts.
+ Native HTTP admits only the declared exact hosts, rejects credentials in URLs,
+ blocks private-network resolution, limits each response to 8 MiB or less, and
+ limits total batch output. The skill has no private HTTP client and no networked
+ JavaScript sandbox.
- ## Output schema
+ ## Outputs
- The scan emits:
+ - `audit_result` (`runx.security.exact_cve_audit.v1`): immutable target,
+ selected inventory, findings, and counts.
+ - `report` (`runx.security.exact_cve_report.v1`): Markdown report bound by
+ digest.
+ - `evidence` (`runx.security.exact_cve_evidence.v1`): exact queries and
+ returned non-withdrawn advisory ids.
+ - `verification` (`runx.security.exact_cve_verification.v1`): independent
+ replay comparison, including false, missing, changed, and withdrawn counts.
+ - `delivery` (`runx.security.exact_cve_delivery.v1`): digests of every final
+ packet, emitted only after successful verification.
- ```json
- {
- "audit_result": {
- "schema": "runx.security.exact_cve_audit.v1",
- "target": {
- "repo": "https://github.com/owner/repo",
- "commit": "40-character hash",
- "lockfile_sha256": "64-character digest"
- },
- "dependency_scope": "direct-production",
- "inventory": [],
- "findings": [],
- "result": {
- "exact_dependencies_queried": 0,
- "advisory_findings": 0,
- "source": "OSV"
- }
- },
- "report": {
- "schema": "runx.security.exact_cve_report.v1",
- "markdown": "# Exact CVE audit: ...",
- "markdown_sha256": "64-character digest"
- },
- "evidence": {
- "summary": "human-readable audit summary",
- "observations": []
- }
- }
- ```
+ The sealed graph receipt records both native provider passes and every derived
+ packet. Checked-in example artifacts are illustrative prior evidence, not live
+ provider proof for a new run.
- The graph adds verification and delivery packets to a sealed `runx.receipt.v1`
- graph receipt with child receipt lineage. The audit remains read-only: it does
- not write unmanaged files into the target workspace or installed skill.
+ ## Stop conditions
- ## Worked example
+ - Target or lockfile URL is mutable, unpinned, non-HTTPS, or outside the
+ declared GitHub hosts.
+ - Lockfile version or shape cannot produce an exact inventory.
+ - Inventory, advisory count, response size, or batch output exceeds a declared
+ bound.
+ - OSV returns an error, malformed shape, identity mismatch, truncated body, or
+ a pagination token the graph cannot complete.
+ - The replay observes any added, removed, changed, or newly withdrawn finding.
- For OWASP NodeGoat at commit
- `c5cb68a7084e4ae7dcc60e6a98768720a81841e8`, the checked-in harness reads the
- pinned lockfile, audits 16 exact direct production versions, reports the OSV
- advisories returned for those versions, and independently requires zero false
- and zero missing hits before sealing.
+ The selected dependency scope is always carried into the output. A
+ `direct-production` result makes no claim about transitive or development
+ dependencies.
- The second harness case audits the repository's immutable clean fixture at
- commit `83d554f904f9f73bd26ce9c15e3786ba7d62b1de`. It verifies that an exact
- dependency with no OSV advisory produces zero findings while still completing
- the independent replay and sealed-receipt path.
+ ## Example
- If the same request points at `main/package-lock.json`, validation returns a
- needs-input failure because the lockfile is mutable and does not contain the
- declared immutable commit. No audit or receipt is presented as complete.
+ For a lockfile pinned to one full Git commit, the skill inventories the exact
+ installed production versions, queries OSV, reads every returned advisory, and
+ then repeats the provider pass. It seals only if both complete finding sets
+ match. The same request pointed at `main/package-lock.json` stops before the
+ network boundary because the target is mutable; a clean finding set still means
+ “OSV returned no matching advisory for this scope,” not “the project is safe.”