Dependency security auditor

Dependency Security Auditor

Audit application dependencies for known vulnerabilities and freshness risk, then produce a workflow that can run locally, in a git hook, or in CI. Prefer report-first behavior; ask before changing dependencies, lockfiles, hooks, or CI config.

When To Use

Use this when asked to check package CVEs, scan package.json, scan requirements.txt, scan pubspec.yaml, add dependency security CI, add a Husky/pre-push security hook, or create a stack-aware audit workflow.

Core Workflow

1. Detect ecosystems from lockfiles and manifests:
   • Node: package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock.
   • Python: requirements.txt, poetry.lock, uv.lock, Pipfile.lock, pyproject.toml.
   • Flutter/Dart: pubspec.yaml, pubspec.lock.
2. Scan lockfiles first. If a project has only a manifest and no lockfile, report weak evidence because exact resolved versions are unknown. For Node, respect package.json packageManager; conflicting lockfiles are stale evidence, not permission to switch package managers, except Bun projects may use package-lock.json as an explicit npm audit fallback. For Python, pyproject.toml is only a detection signal unless paired with a lockfile or pinned requirements.
3. Run a broad scanner:
   • Prefer OSV-Scanner for cross-ecosystem CVE detection.
   • Use Trivy as an optional CI backstop for repository, container, and SBOM scans.
4. Run native audits when available:
   • Node: npm audit --package-lock-only --json, pnpm audit --json, or yarn npm audit --recursive --json (--all too for Yarn workspaces).
   • Python: pip-audit for environments, requirements files, or local project lockfiles via --locked.
   • Flutter/Dart: OSV-Scanner on pubspec.lock; use dart pub outdated --json or flutter pub outdated --json for freshness, not CVE truth.
5. Detect runtime/tool versions when freshness mode is enabled: Node/npm/pnpm/Yarn/Bun, Python/pip-audit, Flutter/Dart.
6. Compare current locked or installed versions against latest available versions when the ecosystem can do so:
   • Node: npm outdated --json or pnpm outdated --format json.
   • Yarn: skip freshness; Yarn npm plugin does not provide a supported outdated command.
   • Flutter/Dart: dart pub outdated --json or flutter pub outdated --json.
   • Python: installed environment freshness when available; do not confuse this with lockfile CVE truth.
7. Normalize findings by package, version, ecosystem, advisory ID, severity, fixed version, scanner source, and dependency path when available.
8. Separate vulnerable from outdated. Outdated packages are freshness risk, not CVEs.
9. Recommend remediation without applying it unless the user approves package changes.

Bundled Tool

Use scripts/dependency_audit.py for deterministic discovery and scanner orchestration. It detects stacks, passes discovered lockfiles explicitly to OSV-Scanner, runs native audits where available, writes a JSON report, and can fail by severity threshold.

When the skill is installed outside the target repo, set DEPENDENCY_AUDIT_SCRIPT to the script location and call python3 "$DEPENDENCY_AUDIT_SCRIPT" from hooks or CI. Do not assume skills/dependency-security-auditor/... exists in every audited repository.

Example:

python3 skills/dependency-security-auditor/scripts/dependency_audit.py --root . --fail-on high --report dependency-security-report.json

Fast hook example:

python3 skills/dependency-security-auditor/scripts/dependency_audit.py --root . --mode pre-push --skip-freshness --fail-on high

CI freshness example:

python3 skills/dependency-security-auditor/scripts/dependency_audit.py --root . --mode ci --fail-on high --report dependency-security-report.json

Useful flags:

• --dry-run: discover projects and show what would be scanned without running scanners.
• --skip-freshness: skip runtime/latest-version checks for fast hooks.
• --freshness: force runtime/latest-version checks.
• --fail-on-major-outdated: fail when freshness checks find major-version lag.
• --skip-osv / --skip-native: run only native audits or only OSV-Scanner.
• --verbose: print scanner discovery, command execution, missing tools, and non-fatal diagnostics to stderr.

For Husky, pre-commit, and GitHub Actions examples, see references/hook-and-ci-examples.md. For scanner selection and policy guidance, see references/scanner-policy.md. For prompt examples, see references/examples.md. For fixture-backed bootcamp coverage, see references/bootcamp-test-matrix.md.

Output

Return:

• Status: clean, vulnerable, partial vulnerable, partial clean, weak evidence, scanner unavailable, scanner error, or dry run.
• Detected Stacks: ecosystem, project path, and lockfile status.
• Runtime: installed runtime and package-manager versions when checked.
• Findings: severity-ordered CVEs/GHSAs with package, version, path, fixed versions, and source scanner.
• Freshness: current/wanted/latest versions and whether lag is patch, minor, or major.
• False Positive Notes: why a finding may or may not affect runtime.
• Setup Hints: missing or unsupported scanner setup steps, such as installing pip-audit or upgrading Yarn audit support.
• Remediation Plan: minimal safe upgrades or overrides, plus required verification commands.
• Hook/CI Plan: where to attach quick checks versus full scans.

Hook Policy

• pre-commit: keep fast; scan only changed lockfiles or run secrets checks.
• pre-push: run dependency CVE scan and fail on high/critical by default; skip freshness unless the repo is small.
• PR CI: run full dependency audit plus runtime/freshness checks; fail on high/critical or newly introduced vulnerabilities.
• Scheduled CI: run OSV over discovered lockfiles plus optional Trivy/native audits and freshness checks; report all severities and stale major lines.

Guardrails

• Do not install tools, edit hooks, edit lockfiles, or upgrade packages without explicit approval.
• Do not treat outdated packages as vulnerabilities unless a vulnerability advisory applies.
• Do not claim “no issues” from one scanner alone; name the data sources checked.
• Do not switch Node package managers based only on a stale lockfile when package.json declares packageManager.
• Prefer patched minor/patch releases before major upgrades.
• For Node, do not blindly run npm audit fix --force; review suggested downgrades or major jumps.
• For Flutter/Dart applications, require pubspec.lock for actionable CVE scanning.
• Treat Python freshness as installed-environment freshness, not lockfile CVE evidence.
• Treat dependency-free CVSS v4 parsing as severity-gate fallback; prefer scanner-provided severity when available.
• Scanner command failures return scanner_error; if another scanner still produced findings, return partial_vulnerable and keep hooks/CI failing until rerun or triaged.

Scanner Unavailable Policy

• Do not install OSV-Scanner, pip-audit, package managers, or other tools without explicit approval.
• If OSV-Scanner is missing, run available native audits and mark the evidence as incomplete.
• If no CVE scanner for the detected stack is available, return scanner_unavailable and provide exact install/setup options.
• If a package manager is installed but cannot run the required audit command, mark it unsupported rather than a generic scanner crash.
• If only manifests are present without lockfiles, return weak_evidence and explain that exact vulnerable versions are unknown.
• If requirements files contain unpinned entries or include other requirements files, mark Python CVE evidence weak because resolved versions are unknown.

Final Checks

• Findings are tied to exact locked versions.
• Missing lockfiles are reported.
• Runtime/freshness checks are clearly separated from CVEs.
• Scanner sources are named.
• Recommended hook/CI placement matches scan cost.
• Any proposed dependency changes include verification commands.