Skip to content

me2resh/apexyard / .claude/skills/audit-deps

audit-deps

Verified

Audit dependencies for vulnerabilities, outdated packages, and license compliance.

Writing: read docs/skills/shared/writing-rule.md before you write a durable artifact.

/audit-deps — Dependency Audit

Audit project dependencies for security vulnerabilities, outdated packages, and license compliance across npm and Python.

The skill, Munir (.claude/agents/dependency-auditor.md), and golden-paths/pipelines/dependency-audit.yml share one contract. The shared helper is the source of truth for discovery, severity, licences, and remediation:

golden-paths/pipelines/scripts/dependency-audit.py

Adopters copy that helper beside the workflow as .github/scripts/dependency-audit.py. Compare helper_revision when refreshing. The current helper revision is 4.

Design: AgDR-0176.

Usage

/audit-deps
/audit-deps path/to/project
/audit-deps path/to/project --ecosystem=python
/audit-deps path/to/project --language=ts
/audit-deps path/to/project --runner=osv

Path resolution

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
projects_dir=$(portfolio_projects_dir)
workspace_dir=$(portfolio_workspace_dir)
HELPER="$(git rev-parse --show-toplevel)/golden-paths/pipelines/scripts/dependency-audit.py"

Run against a managed project under workspace/<name>/, or an explicit project path. Refuse the ops-fork root when it only holds framework files.

Process

1. Detect ecosystems (manifests, not source counts)

EcosystemDetection
npmpackage.json
Pythonrequirements*.txt, dev-requirements.txt, pyproject.toml, Pipfile, Pipfile.lock, poetry.lock, uv.lock

Search the project tree. Skip node_modules, .venv, vendor, dist, build, .next, and .git.

Default: audit every detected supported ecosystem. --ecosystem= filters. --language=js|ts|python is an alias. Reject conflicting filters. --runner= must match the selected ecosystem. Report detected ecosystems that the filter excludes. Report known unsupported manifests as not scanned. A tooling-only pyproject.toml with no dependency groups is not_applicable.

Known unsupported manifests

The helper does not scan these files. It records each file in not_scanned.

PatternEcosystem
*.csproj, *.fsproj, *.vbproj, packages.config, Directory.Packages.propsnuget
libman.jsonlibman
go.modgo
Cargo.tomlcargo
Gemfilebundler
pom.xmlmaven
build.gradle, build.gradle.ktsgradle
composer.jsoncomposer
Package.swiftswift
pubspec.yamlpub
mix.exsmix

Each not_scanned entry has path, ecosystem, and reason. The path is relative to the scanned root. The helper does not add a NuGet runner. Discovery uses the same walk and the same ignored directories as npm and Python.

The helper exits 3 for unsupported manifests only when both conditions are true. No npm or Python dependency set is selected for checks. A tooling-only pyproject.toml does not count, because it has no dependencies to check. No --ecosystem filter is given. The --language flag selects the same filter. A Critical finding still exits 1. Every other case keeps the normal exit code. The helper still records each file in not_scanned. The Markdown report keeps the Not scanned section. The helper keeps the coverage note. This skill and the helper use that same exit rule. A tree with no dependency manifest exits 0. The helper adds the note no dependency manifests found.

The CI template starts a scan only when it finds an npm or Python manifest. Run the helper directly for a tree that has only unsupported manifests.

2. Invoke the shared helper

python3 -I "$HELPER" "$PROJECT_PATH" \
  ${ECOSYSTEM:+--ecosystem="$ECOSYSTEM"} \
  ${LANGUAGE:+--language="$LANGUAGE"} \
  ${RUNNER:+--runner="$RUNNER"} \
  --json-out /tmp/dep-audit.json \
  --md-out "$projects_dir/<name>/quality/dependency-audit-$(date -u +%Y-%m-%d).md"

Use a trusted interpreter. Do not put the audited checkout on PYTHONPATH.

3. Vulnerability scan

EcosystemRunner
npmnpm audit --json
PythonPrefer pip-audit==2.10.0 with -s osv --no-deps --disable-pip on data-only exact pins. If that trusted scanner is absent, query OSV directly for the same pins. An explicit --runner=pip-audit reports a missing tool and exits 3. A scanner failure stays failed. Never silently fall back to a clean result.

Python inventory is data-only. Parse lockfiles and pinned requirements as data. Never run Poetry, uv, Pipenv, build backends, or checkout plugins.

4. Severity mapping

EvidenceReport severity
npm critical / high / moderate / lowCritical / High / Medium / Low
Recognised OSV labelMODERATE → Medium. Preserve other matching levels.
Valid CVSS base scoreCritical 9.0–10.0, High 7.0–8.9, Medium 4.0–6.9, Low above 0 and below 4.0
Missing, unsupported, or unparseableUnknown, with reason
Label and score disagreeHighest recognised severity. Keep conflict evidence.

Unknown findings need manual triage. They stay visible in totals.

5. Outdated packages

  • npm: npm outdated --json
  • Python: compare exact pins with version-specific public PyPI metadata via packaging==25.0

Recommend updates through the project's package manager and lockfile workflow. Never emit npm update for a Python package.

6. Licence compliance

Preserve each package's exact version, metadata source, and raw claim.

Allowed (exact SPDX): MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, CC0-1.0, 0BSD, Unlicense

Restricted (require review, current SPDX): GPL-2.0-only, GPL-2.0-or-later, GPL-3.0-only, GPL-3.0-or-later, LGPL-2.0-only, LGPL-2.0-or-later, LGPL-2.1-only, LGPL-2.1-or-later, LGPL-3.0-only, LGPL-3.0-or-later, AGPL-3.0-only, AGPL-3.0-or-later, MPL-2.0, CDDL-1.0, CDDL-1.1

Banned: UNLICENSED, Proprietary

Pending review (not banned): Unknown, missing metadata, compound SPDX expressions, deprecated identifiers pending remapping, classifier-only claims without an exact SPDX id.

Pending review still blocks licence clearance. Unknown never becomes allowed by default.

7. Mixed repository report

Produce one report. Include per-directory dependency sets and per-ecosystem sections. Name every ecosystem and manifest. Combine severity totals across ecosystems. Deduplicate by ecosystem, package name, version, and advisory identity. Keep every affected manifest path.

8. Exit codes

ExitMeaning
0Complete selected checks. No Critical or Unknown vulnerability findings.
1Known Critical vulnerability findings.
2Invalid arguments or incompatible runner override.
3Missing selected tool, failed check, or incomplete selected coverage.
4Complete selected coverage with Unknown vulnerability findings.

The helper exits 3 for unsupported manifests only when both conditions are true. No npm or Python dependency set is selected for checks. A tooling-only pyproject.toml does not count, because it has no dependencies to check. No --ecosystem filter is given. A Critical finding still exits 1. Every other case keeps the normal exit code. The not_scanned list, the Not scanned section, and the coverage note stay. WARN or incomplete coverage does not install tools automatically. Print per-ecosystem install advice.

9. Install advice (missing tools)

npm          — install Node.js + npm for the project
pip-audit    — pip install pip-audit==2.10.0 packaging==25.0
               (trusted env only; see golden-paths/pipelines/scripts/dependency-audit-tools.lock.json)
OSV fallback — no extra install. Needs network to api.osv.dev

Output

Write the markdown report under projects/<name>/quality/ when a portfolio project name is known. Print the JSON summary on stdout.

Invokes: Dependency Auditor Agent (Munir / Guardian)


Part of ApexYard — multi-project SDLC framework for Claude Code · MIT.

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall