Safer Dependencies for Claude Code

When AI coding assistants like Claude add packages to your project, they often pick whatever version sounds right — without checking whether it has known security vulnerabilities, whether the package is still actively maintained, or whether the name is a typo away from a malicious lookalike.

safer-dependencies is a security layer for Claude Code: it sits between Claude and your manifest files and runs its security checks automatically: vulnerable installs are denied before they run, and a risky version written to a manifest is corrected on disk right after the write. It detects and fixes risky dependencies — CVEs, typosquats, abandoned packages, and version-age issues, plus a cooldown period on brand-new releases — across npm, PyPI, RubyGems, Maven, Go, Rust, and PHP (Composer). See CAPABILITIES.md for exactly what is and isn't covered.

New here? GETTING-STARTED.md takes you from zero to a working install in about five minutes.

Security & privacy: see SECURITY.md (vulnerability disclosure), PRIVACY.md (data egress, no telemetry), and CAPABILITIES.md (what the tool defends against and what it doesn't).

License (source-available — NOT OSI "open source"): Free to use and modify for your own purposes, including for-profit/company internal use and building products you sell. A separate paid license is required only to monetize the software itself — selling it, shipping it inside a product or service that is sold, or offering its functionality to third parties for a fee (including hosted/SaaS/API). Redistribution and derivatives must keep the license and credit this project. See LICENSE (Section 4 for the commercial restriction); commercial-license requests via github.com/robert-auger.

Contents

• Getting started — zero to installed in about five minutes
• What it does
• What triggers it
• What's in this repo
• Supported ecosystems
• Install
  • Configuration
  • Changing the cooldown period
• Warning levels
• How it works
  • Normal Mode (Manual)
  • Intercept Mode (Automatic)
  • Pre-Install Mode (Bash Hook)
  • Post-Install Mode (Bash Hook)
  • Post-Agent Mode (Agent Hook Pair)
• Audit log
• Requirements
• FAQ

Getting started

GETTING-STARTED.md takes you from zero to a working install in about five minutes — prerequisites, the interactive install, and verification. For the full install reference (global/project/manual installs, Windows specifics, the permissions allowlist, updating, and uninstalling), see INSTALLATION.md.

Everyday use: once the hooks are installed, there's nothing to run — safer-dependencies works automatically in the background. As Claude adds or installs packages, it flags risky dependencies and upgrades vulnerable versions to a safe one in place — and blocks a known-vulnerable install before it even runs — so unsafe packages are caught and corrected without you having to ask. You can still invoke it directly any time: "is axios@1.2.0 safe?", "check safer-dependencies setup", or "show safer-dependencies stats".

What it does

When Claude is about to add a package to your project, safer-dependencies intercepts and runs 5 checks:

1. Provenance -- official registry, typosquat detection (npm/PyPI/RubyGems/Maven/crates.io), package age
2. Version age -- picks the newest stable version published 7+ days ago (cooldown window)
3. Vulnerability scan -- OSV API, with ecosystem-native tools (npm audit, pip-audit, bundle audit) when available
4. Hash-pin integrity -- for PyPI requirements.txt lines with --hash=sha256:... pins, the declared hash is validated against PyPI's published hashes; mismatch emits a WARNING
5. Abandoned & stale packages -- known-abandoned packages (e.g. paperclip, request, pycrypto, github.com/dgrijalva/jwt-go) are hard-blocked immediately with a suggested replacement; packages with no stable release in 2+ years get an advisory STALE: warning. Hard-blocked packages are removed from the manifest and Claude will ask how to proceed; stale-only packages are left in place.

If issues are found, Claude emits warnings and may step back to a safer version. All checks are logged to ~/.claude/safer-dependencies-audit-YYYY-MM.log (one file per calendar month).

What triggers it

The skill fires automatically when Claude:

Manifest / install operations

• Adds or updates a package in package.json, requirements.txt, Gemfile, pom.xml, build.gradle, Cargo.toml, go.mod, or any other supported manifest
• Writes an import, require, or use for a package not already declared in the manifest
• Generates or updates a lock file (checks only new/changed entries)
• Runs a package-manager install via Bash (npm install, bundle install, poetry install, uv sync, go mod tidy, etc.) — Pre-Install audits the command args, Post-Install audits the resulting lockfile
• Writes a Dockerfile or CI workflow (.github/workflows/*.yml, etc.) that embeds pinned package-manager install steps

Selection & recommendation questions

• Library/framework comparisons: "should I use axios or node-fetch?", "moment vs dayjs?", "which is better X or Y?"
• Recommendation requests: "what's a good HTTP client for Python?", "recommend a logging library for Go", "what package handles CSV in Node?"
• Version selection: "what version of Django should I use?", "latest stable Flask?"

Intent-to-use expressions (pre-add)

• "I want to use FastAPI for this", "I'm thinking of adding Celery", "we're looking at Prisma as the ORM", "let's use Tailwind"

Package health and trust questions

• "Is moment.js still maintained?", "is this gem still active?", "is X abandoned?", "is X EOL?", "can I trust this package?", "when was faker last updated?"

Scaffolding commands

• npx create-react-app, npm create vite@latest, django-admin startproject, rails new, cargo new + cargo add, "bootstrap a new FastAPI project"

Implicit package adds (feature requests that imply a new dependency)

• "Add Redis caching to the app", "connect to Postgres", "add JWT auth", "write code to send emails" — fires when no package for that capability is already in the manifest

Migration and porting

• "Migrate from requests to httpx", "move from CRA to Vite", "port from moment to date-fns" — audits the incoming package

It does not fire for:

• Standard library imports (os, fs, java.util.*, etc.)
• Already-declared dependencies that aren't being changed
• Academic discussion of how a package works internally ("explain React's reconciler", "how does webpack's module resolution work?") — comparison and selection questions do still fire
• Installing OS-level apps, runtimes, or IDE extensions (Python itself, Docker, Homebrew, VS Code extensions)

What's in this repo

This is a skill + hook bundle, not a single skill file. A complete install deploys these pieces:

| File | Role | |---|---| | skills/safer-dependencies.md | The skill (SKILL.md once installed). Describes audit procedures and includes management mode for installation/stats. | | skills/safer-dependencies-shim.sh | PostToolUse:Write/Edit hook — audits manifest + lockfile writes and auto-corrects vulnerable versions in place (Intercept Mode). | | skills/safer-dependencies-pretooluse-bash.sh | PreToolUse:Bash hook — pre-flight OSV audit of package-manager install commands; denies vulnerable concrete pins before the install runs (Pre-Install Mode). | | skills/safer-dependencies-posttooluse-bash.sh | PostToolUse:Bash hook — post-flight audit after Bash commands; catches transitive CVEs in freshly-written lockfiles, manifests edited via sed/jq/scripts, and the resolved environment of plain pip install (Post-Install Mode). | | skills/safer-dependencies-pretooluse-agent.sh + skills/safer-dependencies-posttooluse-agent.sh | PreToolUse:Agent + PostToolUse:Agent hook pair — closes the subagent coverage gap. Modes 2–4 only fire for root-session tool calls, so any manifest a subagent writes bypasses them. Post-Agent audits whatever the subagent wrote after each Agent tool-call returns (Post-Agent Mode). | | skills/scripts/ | Shared Python library (safedep/) and standalone resolver scripts used by all hooks. | | skills/scripts/safer_dependencies_manager.py | Management module for interactive installation, usage stats, and setup validation. |

The skill file alone is not enough — without hooks, automatic invocation depends on Claude deciding to reach for the skill. Install all five pieces for full coverage; many skills and slash commands dispatch subagents internally, so the Post-Agent pair matters even if you never explicitly spawn one. (See FAQ.md for why a skill on its own can't guarantee coverage.)

Supported ecosystems

| Ecosystem | Manifest | Lock file | |-----------|----------|-----------| | npm | package.json | package-lock.json, yarn.lock, pnpm-lock.yaml | | PyPI | requirements.txt, pyproject.toml, Pipfile, setup.py, setup.cfg | Pipfile.lock, poetry.lock, uv.lock | | RubyGems | Gemfile, *.gemspec | Gemfile.lock | | Maven | pom.xml, build.gradle, libs.versions.toml | -- | | Go | go.mod | go.sum | | Rust | Cargo.toml | Cargo.lock | | PHP (Composer) | composer.json | composer.lock |

Install

New to the project? Start with GETTING-STARTED.md. The short version:

git clone https://github.com/robert-auger/safer-dependencies /tmp/safer-dependencies
python3 /tmp/safer-dependencies/skills/scripts/safer_dependencies_manager.py interactive_install

The installer prompts for scope (global vs project) and which hooks to enable, then writes settings.json for you — both the hook entries and the permissions allowlist that lets the skill's check commands run without an approval prompt on every audit.

Everything else install-related lives in INSTALLATION.md, the single reference for install mechanics: manual file-by-file installs (global and project-level), Windows specifics, Post-Agent hooks, the permissions allowlist, verifying the setup, updating, pinning to a release tag, and uninstalling.

After install, day-to-day management works via natural language to Claude — install safer-dependencies (re-run / change hooks), show safer-dependencies stats, check safer-dependencies setup — or the /safer-dependencies menu. Updating is in-session too: /safer-dependencies update applies the latest release (update --check for a dry-run, update --rollback to undo); see INSTALLATION.md for the trust model.

Platform note: macOS, Linux, and Windows are supported. Windows needs Git for Windows (provides bash) and Python 3 on PATH — no WSL required. Hands-on testing to date has focused on macOS and Windows; Linux support is exercised by the automated CI matrix.

Configuration

Two things are configurable after install:

• Permissions allowlist — pre-approves the skill's read-only check commands (the exact-form