dependency-security-auditor

name	dependency-security-auditor
description	Audit dependency CVEs across Node, Python, Flutter/Dart, and mixed repos; design OSV/native audit hooks for pre-push and CI.

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 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, runtime tools, installed scanners, 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.

Output

Return:

• Status: clean, vulnerable, 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.
• 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 full OSV 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.
• 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 and should fail hooks/CI 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 only manifests are present without lockfiles, return weak_evidence and explain that exact vulnerable 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.