Dependency Scanning skill for Codex

A dependency scan is useful when it ends in action: upgrade, pin, replace, or document a justified ignore. The goal is not zero alerts — it is no exploitable, fixable vulnerability left unpatched, and a flow that keeps it that way. Reachability and a real fix matter more than the raw count.

Inspect first

• Read AGENTS.md and detect the ecosystem(s) from lockfiles: package-lock.json/ pnpm-lock.yaml/yarn.lock, poetry.lock/requirements.txt/uv.lock, go.sum, Cargo.lock, pom.xml/gradle.lockfile, Gemfile.lock.
• Scanning reads the lockfile, so a lockfile must exist and be committed. If it is missing, generate and commit it first — results are only meaningful against pinned versions.
• Some scanners fetch advisory data over the network; Codex’s sandbox may block that. Note when a step needs network, and prefer tools with an offline/local DB where possible.

Tool per ecosystem

Ecosystem	Primary	Notes
npm/pnpm/yarn	npm audit / pnpm audit / yarn npm audit	Fast; --omit=dev to focus prod; noisy transitive deps
Python	pip-audit	Uses PyPI + OSV; pip-audit -r requirements.txt or against the env
Go	govulncheck ./...	Best-in-class: reports only vulns your code actually calls
Rust	cargo audit	RustSec advisory DB
Java/Kotlin	OWASP Dependency-Check or gradle dependencyCheckAnalyze	Slower; needs NVD data
Any / polyglot	osv-scanner -r .	One tool across ecosystems; reads many lockfiles; OSV DB

osv-scanner is the pragmatic default for a mixed repo:

osv-scanner --lockfile=package-lock.json --lockfile=go.sum --format table .
# or recursively discover lockfiles
osv-scanner -r .

Triage: separate signal from noise

A scanner lists everything with a known CVE; most reports are over-counted. Triage each:

1. Is it reachable? A vuln in a dev-only tool, a code path you never call, or a feature you do not use is lower priority. govulncheck tells you call-reachability for Go; elsewhere reason about it (is the package a runtime or build dependency? is the vulnerable function imported?).
2. Is there a fix? Check the advisory’s “patched versions”. If yes → upgrade. If no → pin, replace the package, or apply a documented workaround.
3. Severity and context. Use CVSS plus your exposure: a High CVSS in an internet-facing path outranks a Critical in an offline dev script.
4. Direct vs transitive. Direct deps you bump yourself; transitive ones you fix by bumping the parent or using an override (overrides in npm, resolutions in yarn/pnpm, Go replace, Cargo [patch]).

Decide one outcome per finding: upgrade, override/pin, replace, or ignore with justification (record the advisory ID, why it is not reachable/exploitable, and a review date).

Fixing

npm audit fix                 # safe, semver-compatible bumps
npm audit fix --force         # only after reading the breaking changes; retest
npm update <pkg>              # targeted bump

• Prefer the smallest bump that clears the advisory; read the changelog for the jump.
• For transitive-only fixes, add an override pinning the fixed version rather than forcing a major upgrade of the whole tree.
• After any bump, run the test suite and the scanner again; a “fix” that breaks the build or reintroduces another vuln is not done.

Automate so it stays fixed

Wire one of these (hand off CI specifics to github-actions-workflows / secrets-in-ci):

• Dependabot (.github/dependabot.yml): package-ecosystem, directory, schedule. Group minor/patch updates to cut PR noise; enable security updates.
• Renovate: more configurable grouping, automerge rules, dependency dashboard.
• Run the scanner in CI and fail only on fixable vulns at/above a chosen severity, so the gate stays actionable instead of perpetually red.

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule: { interval: "weekly" }
    groups:
      minor-patch:
        update-types: ["minor", "patch"]

Verification

• Re-run the scanner after fixes: the finding is gone and no new ones appeared.
• Lockfile diff is minimal and intentional; the app’s tests pass.
• CI gate fails on a newly introduced fixable High, and passes when clean.

Output contract

## Dependency scan — <repo> (<date>)
Ecosystems: <list>. Tools: <list>.

### Findings (actionable)
| Advisory | Package (dep type) | Installed → Fixed | Severity | Reachable? | Action |
|----------|--------------------|-------------------|----------|-----------|--------|
| GHSA-xxxx | lodash (transitive) | 4.17.19 → 4.17.21 | High | yes | override to 4.17.21 |

### Ignored (justified)
- <advisory> — dev-only, not shipped — review <date>

### Automation: <Dependabot/Renovate config added>. CI gate: <severity threshold>.

Hard rules

• Scan a committed lockfile; results against unpinned ranges are not trustworthy.
• Never audit fix --force or jump a major version without reading the changelog and retesting — a blind bump can break prod worse than the CVE.
• Do not mark a finding resolved without re-scanning; do not blanket-ignore to make CI green.
• A committed secret found incidentally is out of scope here — hand off to secret-scanning.