cve-audit

Files (18)

• SKILL.md
• audit-result.json · artifacts/
• delivery.json · artifacts/
• evidence.json · artifacts/
• report.md · artifacts/
• verification.json · artifacts/
• core.mjs
• cve.mjs
• clean-fixture-direct-production.yaml · fixtures/
• package-lock.json · fixtures/clean/
• package.json · fixtures/clean/
• composes-in-graph.yaml · fixtures/
• mutable-lockfile-refused.yaml · fixtures/
• composed.graph · fixtures/support/
• package.json
• catalog.md · references/
• run.yaml
• core.test.mjs · tests/

SKILL.md (first lines)

# Exact CVE Audit

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.

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.

## When to use it

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

Private repositories, credentials, mutable branch URLs, abbreviated commits,
and non-npm lockfiles are outside this runner.

## Execution contract

1. Validate the immutable GitHub target before any network call.
2. Read the pinned lockfile through the `web` connector's `page.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 the `osv` connector's
   `vulnerabilities.query`. It sends POSTs but is a read; 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 `osv/vulnerabilities.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.

The connectors admit only their declared hosts, reject credentials in URLs, and
block private-network resolution. The skill has no private HTTP client and its
deterministic JavaScript worker has no network access.

## Outputs

- `audit_result` (`runx/cve-audit.audit.v1`): immutable target,
  selected inventory, findings, and counts.
- `report` (`runx/cve-audit.report.v1`): Markdown report bound by
  digest.
- `evidence` (`runx/cve-audit.evidence.v1`): exact queries and
  returned non-withdrawn advisory ids.
- `verification` (`runx/cve-audit.verification.v1`): independent
  replay comparison, including false, missing, changed, and withdrawn counts.
- `delivery` (`runx/cve-audit.delivery.v1`): digests of every final
  packet, emitted only after successful verification.

The sealed graph receipt records both native provider passes and every derived
packet.

## Stop conditions

- 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, or
  a pagination token the graph cannot complete.
- The replay observes any added, removed, changed, or newly withdrawn finding.

The selected dependency scope is always carried into the output. A
`direct-production` result makes no claim about transitive or development
dependencies.

## Example

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

From runxhq/runx, Apache-2.0.

More from runxhq/runx