---
name: dependency-vuln-scanning
description: Run dependency vulnerability scans on every new deployment/migration and monthly thereafter. Covers Node, Python, and general OS/library scanning.
---

# Dependency Vulnerability Scanning

Dependency vulnerabilities are not a one-time checklist item. They should be
scanned on every new deployment or migration into the fleet, and then re-scanned
periodically thereafter. For this fleet size, **monthly** is a reasonable
cadence.

## When to run

- Before marking a new jail/container/app as "live" after provisioning or
  migration.
- Before merging a dependency update.
- Monthly, against every actively maintained app and host.

This applies to Docker-host deployments too — a container image is just another
artifact with dependencies. Cross-reference the provisioning checklist in
`skills/bastille-jail-provisioning/SKILL.md` and add a vulnerability-scan step
before considering any new jail complete.

## Tooling by stack

### Node.js / npm

```bash
npm audit
```

Use `npm audit --audit-level=moderate` to filter noise if the project is large.
For a CI-friendly exit code, `npm audit --audit-level=high` will fail only on
high/critical findings. Always review the full output at least once.

If the project uses `pnpm` or `yarn`, use their equivalents (`pnpm audit`,
`yarn audit`). The Node ecosystem is common on this fleet — expect to use this
one often.

### Python

```bash
pip-audit
```

Run inside the project's virtualenv so it sees the same packages the app will
actually use. If `pip-audit` is not installed, add it to the dev tooling in the
virtualenv rather than the system Python.

### General / OS / multi-ecosystem fallback

```bash
osv-scanner -r /path/to/project
```

`osv-scanner` is the best general fallback: it understands lockfiles from npm,
PyPI, Go, Rust, Maven, and others, and queries the OSV database. Use it when a
project mixes ecosystems or when you want a single scanner across a whole host.

## What to do with findings

1. **Triage, do not blindly upgrade.** A CVE in a dev-only dependency is not the
   same as one in the runtime path of a public-facing service.
2. **Patch or pin.** Prefer a real upstream upgrade. If the upstream fix is not
   available yet and the risk is real, consider pinning, removing the dependency,
   or a temporary local patch (tracked via `skills/modded-app-update-pattern`).
3. **Re-scan after the fix.** A green `npm audit` or `pip-audit` output is the
   only proof the finding is resolved.
4. **Record exceptions.** If a finding is accepted (e.g. internal-only tool,
   no reachable attack path), write the justification down in the deployment
   notes or the issue tracker, not just in someone's memory.

## What not to do

- Do not treat vulnerability scanning as optional for "internal-only" tools.
  Internal tools often have the same dependencies and the same CVEs.
- Do not run a scan and ignore the output because it is long. Parse it, triage
  it, file issues for anything that needs follow-up.
- Do not rely solely on the language-specific scanner when the project also
  pulls in OS packages or container base-image packages; add `osv-scanner` or
  the image scanner as a second opinion.