---
name: exact-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: workspace-write
    cwd_policy: skill-directory
    network: true
    writable_paths:
      - artifacts
    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.
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/exact-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.

## When to use this skill

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 not to use this skill

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.

## 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.
- `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

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.

## Edge cases and stop conditions

- 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.

## Output schema

The scan emits:

```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": { "artifact": { "path": "artifacts/report.md" } },
  "evidence": {
    "summary": "human-readable audit summary",
    "observations": [],
    "artifact": { "path": "artifacts/evidence.json" }
  }
}
```

The graph adds `verification.json`, `delivery.json`, and a sealed
`runx.receipt.v1` graph receipt with child receipt lineage.

## Worked example

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 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.

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.