---
name: dependency-audit
description: >-
  Audits project dependencies for known vulnerabilities, license risks, maintenance
  status, and unnecessary bloat. Use when preparing a release, conducting security
  reviews, or user asks to "check dependencies" or "audit packages".
  NOT for upgrading dependencies, fixing vulnerabilities, or choosing new packages.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---

## Identity & Scope

**Executor:** either
**Model tier:** haiku
**Scope:** Dependency manifests (package.json, requirements.txt, Cargo.toml, go.mod), lock files, audit tool output
**Off-limits:** Installing or upgrading packages, modifying lock files, running app code
**Hard rules:** No credentials in output. No deleting files. No spending money. Report via structured output.

## Essential Principles

1. **Audit transitive, not just direct** — Vulnerabilities hide in transitive deps the project never chose. Guards against: missing CVEs in nested packages.
2. **License compatibility is non-negotiable** — GPL in an MIT project is a legal problem. Guards against: accidental license violations in shipped products.
3. **Maintenance status matters** — No commits in 2+ years with single maintainer = supply-chain risk. Guards against: depending on abandoned packages.

## When to Use
- Monthly or pre-release security review of dependencies
- User asks to "check dependencies", "audit packages", or "are we vulnerable"
- Evaluating whether to adopt a new dependency
- Investigating a reported CVE affecting the project
- Compliance review requiring SBOM

## When NOT to Use
- Upgrading or patching dependencies — use dependency-update skill
- Choosing between packages — use architecture skill
- Debugging dependency conflicts — use bug-debugging skill
- Setting up dependency tooling — use devops skill

## Rationalizations to Reject

| Shortcut | Why it's wrong |
|----------|----------------|
| "No direct CVEs, we're clean" | Transitive deps have vulnerabilities too |
| "It's a dev dependency, doesn't matter" | Dev deps run in CI and dev machines — still attack surface |
| "Low severity, skip it" | Low severity + high exposure = real risk; report everything |
| "Popular so it's maintained" | Popular packages get abandoned too; check commit dates |

## Workflow

### Phase 1: Inventory
**Entry:** Project with dependency manifests accessible
**Actions:**
1. Locate all manifests: package.json, requirements.txt, Cargo.toml, go.mod, etc.
2. List all direct dependencies with pinned versions
3. Read lock file to identify transitive dependencies
4. Count total tree size (direct + transitive)
**Exit:** Complete dependency inventory with versions

### Phase 2: Vulnerability Scan
**Entry:** Inventory complete
**Actions:**
1. Run audit tool: `pip audit`, `npm audit`, `cargo audit`, `govulncheck`
2. Parse results: CVE, affected package, severity, fix version
3. Cross-reference against actual usage — is vulnerable code path reachable?
4. Categorize: critical (no fix), high (fix available), medium, low
**Exit:** Vulnerability report with severity and remediation status

### Phase 3: Health and License Check
**Entry:** Vulnerability scan complete
**Actions:**
1. Check each direct dep: last commit, open issues, maintainer count
2. Flag deps with no activity in 2+ years or single maintainer
3. Check license compatibility against project license
4. Flag copyleft (GPL, AGPL) in permissive-licensed projects
5. Assess necessity: can any dep be replaced with inline code?
**Exit:** Health and license report for all direct deps

### Phase 4: Verify
**Entry:** All checks complete
**Actions:**
1. Confirm direct AND transitive deps scanned for vulns
2. Confirm all licenses checked for compatibility
3. Confirm maintenance status assessed for every direct dep
4. Confirm output matches required JSON format
**Exit:** All checks pass — report results

## Output Format

```json
{
  "skill": "dependency-audit",
  "status": "completed",
  "worker": "worker-id",
  "summary": "Audited 45 direct + 312 transitive: 2 critical CVEs, 1 GPL conflict, 3 unmaintained",
  "findings": [
    {"item": "CVE-2024-1234 in requests 2.28.0 — SSRF", "severity": "critical", "detail": "Fix in requests>=2.31.0. Vulnerable path reachable via api_client.py redirect handling."},
    {"item": "reportlab 3.6.0 AGPL — incompatible with MIT", "severity": "high", "detail": "AGPL requires source disclosure. Replace with weasyprint (BSD) or get commercial license."},
    {"item": "legacy-utils 0.2.1 — last commit 2021-03", "severity": "medium", "detail": "Single maintainer, used for date formatting (2 sites). Consider inlining 15-line function."}
  ],
  "errors": [],
  "elapsed_seconds": 18.7
}
```

**Bad example:** `{"summary": "Dependencies look okay", "findings": [{"item": "No major issues"}]}` — no dep count, no specifics, no license check, unverifiable.

## Escalation Triggers

STOP and report to boss when:
- Critical CVE with no available fix in a direct dependency
- License conflict with legal implications for shipped products
- Audit tool fails or produces unreliable results
- Dependency appears compromised (typosquatting, suspicious maintainer change)
- Dependency tree too large to audit completely

## Success Criteria

- [ ] All direct dependencies listed with versions
- [ ] Vulnerability scan covers direct and transitive deps
- [ ] License compatibility checked for every direct dep
- [ ] Maintenance status assessed for every direct dep
- [ ] All findings include package names, versions, actionable details
- [ ] Output matches JSON format above
- [ ] No unresolved escalation triggers
