review-dependency

Dependency Security Review

Perform a security-focused review of a dependency update.

Argument: $ARGUMENTS — the dependency name (e.g., github.com/lib/pq, express, tokio), optionally with version range (e.g., github.com/lib/pq 1.11.1..1.11.2). If empty, auto-detect from the current branch by diffing the dependency manifest against the main branch.

1. Identify the Dependency Change

Detect the project ecosystem and locate the dependency manifest:

Ecosystem	Manifest files
Go	go.mod, go.sum
Rust	Cargo.toml, Cargo.lock
Python	pyproject.toml, requirements*.txt, Pipfile.lock, poetry.lock
Node.js	package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
Other	Identify automatically

Diff the manifest against the base branch to extract: package name, old version, new version, and any other dependency changes bundled in the same commit.

2. Gather Upstream Intelligence

Run these steps in parallel:

2a. Changelog and Diff

• Fetch release notes from the upstream repository's releases/tags page
• Fetch the comparison between old and new versions
• Summarize: what changed, how many commits, which files, nature of changes

2b. Clone the Library

Create a session temp dir (if not already created) and clone the new version into it.

SESSION_DIR=$(mkdir -p /tmp/claude && mktemp -d /tmp/claude/XXXXXX)

Input validation: Before using the package name in any shell command, validate that it contains only alphanumeric characters, hyphens, underscores, dots, forward slashes, and @ symbols. Reject any input containing shell metacharacters (;, |, &, $, `, (, ), <, >, !, #, ~, {, }).

git clone --depth=100 --config core.hooksPath=/dev/null -- <upstream-repo-url> "$SESSION_DIR/<package-name>"

2c. Known Vulnerability Scan

Search for CVEs and security advisories using ecosystem-appropriate sources:

Source	Method
OSV.dev	POST https://api.osv.dev/v1/query with package name and ecosystem
GitHub Advisory Database	gh api /advisories?ecosystem=<eco>&affects=<pkg>
NVD	Web search for package CVEs
Ecosystem-specific	govulncheck (Go), cargo audit (Rust), npm audit (Node), pip-audit (Python)
Web search	<package-name> CVE vulnerability security advisory

Check if there are commonly confused packages with similar names that may pollute search results.

3. Security Audit of the Library

Spawn a security-engineer-smythe agent to review the cloned library source at $SESSION_DIR/<package-name>.

Scope

• Primary: All changes between old and new version (the diff)
• Secondary: Full audit of security-critical code paths in the library

Audit Checklist

Select and apply relevant categories based on the library's purpose:

Network / Protocol libraries — TLS certificate validation and defaults, protocol message parsing and length validation, authentication mechanisms (password handling, token security), connection string / URL parsing injection, buffer safety and unbounded allocations from network data

Data access libraries — Query injection (SQL, NoSQL, LDAP, etc.), input escaping and parameterization, connection security defaults, credential exposure in errors or logs

HTTP libraries — SSRF and redirect following, header injection (CRLF), request smuggling, cookie security, response body size limits

Cryptographic libraries — Algorithm strength, CSPRNG usage, nonce/IV reuse, side-channel resistance, key management and zeroing

Serialization libraries — Deserialization attacks and type confusion, resource exhaustion (recursion bombs, billion laughs), malformed input handling

All libraries — Input validation and sanitization, memory safety and resource limits, error handling and information disclosure, concurrency safety (races, deadlocks), file system operations (path traversal, symlink attacks), transitive dependency risk, debug/logging modes that may leak sensitive data

Output Format

Rate findings: CRITICAL / HIGH / MEDIUM / LOW / INFO (see severity skill for definitions). Include: file:line references, CWE IDs where applicable, impact, and remediation.

4. Vulnerability Research

Spawn an architect-nagatha agent in parallel with step 3. The agent must:

• Query all major vulnerability databases listed in step 2c
• Search the library's issue tracker for security-related discussions and responsible disclosures
• Identify unregistered security fixes — code fixes that were never assigned CVEs/GHSAs
• Assess library security posture: SECURITY.md presence, disclosure process, CVE registration discipline, maintainer activity
• Check if ecosystem vulnerability tooling actually covers this library

5. Codebase Impact Assessment

After upstream review completes, assess how the dependency is used in our codebase:

• How is the library imported? Direct API use vs transitive/side-effect import?
• Which APIs are called? Any deprecated or known-insecure APIs?
• How are configurations (connection strings, URLs, credentials) constructed? From trusted sources?
• Are errors from this library exposed to end users or external APIs?
• Are security-critical settings (TLS mode, auth method, timeouts) explicitly configured or left to defaults?
• Is there input validation on data passed to this library from untrusted sources?

6. Consolidated Report

Present a single report:

Change Summary

Package, old version, new version, commit count, nature of changes (bug fix / feature / security fix / breaking change).

Known Vulnerabilities

Table of CVEs/advisories found (or "None found"), affected versions, whether the new version is impacted. Note any commonly confused packages.

Library Audit Findings

Table: Severity | Finding | Location | CWE — grouped by severity, CRITICAL first.

Codebase Compliance

Table: Recommendation | Status | Action Needed? — for each finding, assess whether our usage is affected.

Risk Assessment

• Overall rating: Safe / Low Risk / Medium Risk / High Risk / Do Not Upgrade
• Key concerns and mitigations
• Flag if the library has poor CVE registration discipline (automated scanning may be blind)

Recommendations

Numbered actionable items for our codebase, plus long-term considerations (e.g., migration to alternatives).

7. Cleanup

rm -rf "$SESSION_DIR"