safe-pkgs
Package safety checks for AI agents before install.
Rust MCP server + CLI with allow/deny decisions, risk scoring, and audit logs.
Documentation ·
GitHub Action
Without safe-pkgs
With safe-pkgs
What It Is
safe-pkgs checks package risk before dependency actions and returns one machine-enforceable decision.
Decision payload includes:
- allow: true or false
- risk: low · medium · high · critical
- reasons: human-readable findings
- evidence: structured findings (kind, stable id, severity, message, facts)
- metadata: package context (latest, publish date, downloads)
- fingerprints: deterministic hashes (config, policy)
Install + Run in 60 Seconds
Install once:```bash
cargo install --path . --locked
Run MCP server:```bash
safe-pkgs serve
Run a one-off audit:```bash
safe-pkgs audit /path/to/project-or-lockfile
safe-pkgs audit /path/to/requirements.txt --registry pypi
Preview the decision without enforcing it (what-if):```bash
safe-pkgs simulate /path/to/project-or-lockfile
Windows MCP hosts (Claude Desktop, etc.) should use:```powershell
safe-pkgs-mcp.exe
## No Subscription Required
`safe-pkgs` does not require a paid plan, hosted account, or API key for built-in checks.
- Runs locally as a Rust binary (MCP server or CLI).
- Uses public package/advisory endpoints by default:
- npm registry + npm downloads API + npms popularity index
- crates.io API
- PyPI JSON API + pypistats + top-pypi index
- OSV advisory API
- Stores cache and audit logs locally on your machine.
## Registry and Check Support
Supported registries:
- `npm` (default)
- `cargo` (crates.io)
- `pypi` (Python packages)
View support map:
- Command: `safe-pkgs support-map`
### Private / Authenticated Registries
Point a registry client at a private mirror and authenticate with a bearer token via environment variables.
Base URL overrides (each defaults to the public endpoint when unset):
- npm:
- `SAFE_PKGS_NPM_REGISTRY_API_BASE_URL` (package metadata; default `https://registry.npmjs.org`)
- `SAFE_PKGS_NPM_DOWNLOADS_API_BASE_URL` (downloads; default `https://api.npmjs.org`)
- `SAFE_PKGS_NPM_POPULAR_INDEX_API_BASE_URL` (popularity index; default `https://api.npms.io`)
- pypi:
- `SAFE_PKGS_PYPI_PACKAGE_API_BASE_URL` (package metadata; default `https://pypi.org/pypi`)
- `SAFE_PKGS_PYPI_DOWNLOADS_API_BASE_URL` (downloads; default `https://pypistats.org/api/packages`)
- `SAFE_PKGS_PYPI_POPULAR_INDEX_URL` (popularity index; default top-pypi-packages JSON)
- cargo: no base-URL override env var yet; all calls use the crates.io API base (`https://crates.io/api/v1`).
Bearer-token auth — when set, requests send `Authorization: Bearer `:
- `SAFE_PKGS_NPM_REGISTRY_TOKEN`
- `SAFE_PKGS_PYPI_REGISTRY_TOKEN`
- `SAFE_PKGS_CARGO_REGISTRY_TOKEN`
The token is sent ONLY to the registry metadata/API host, to avoid leaking it to non-registry hosts:
- npm and pypi: the token is sent only to the package-metadata host. The downloads and popularity hosts (e.g. `api.npmjs.org`, `api.npms.io`, `pypistats.org`) receive no token, since they are separate third-party services.
- cargo: every request targets the same crates.io API base, so all of them (metadata, downloads, popular-crate listing) carry the token.
Empty or whitespace-only token values are treated as unset (no auth header is sent).
## Configuration
Global file:
- `~/.config/safe-pkgs/config.toml`
Project override:
- `.safe-pkgs.toml` (merged on top of global)
Minimal example:```toml
min_version_age_days = 7
min_weekly_downloads = 50
max_risk = "medium"
[cache]
ttl_minutes = 30
[allowlist]
packages = ["my-internal-pkg"]
[denylist]
packages = ["event-stream@3.3.6"]
Full configuration schema:
- docs/configuration-spec.md
MCP Config Example
macOS/Linux:```json
{
"servers": {
"safe-pkgs": {
"type": "stdio",
"command": "/path/to/safe-pkgs",
"args": ["serve"]
}
},
"inputs": []
}
Windows (no console window):```json
{
"servers": {
"safe-pkgs": {
"type": "stdio",
"command": "safe-pkgs-mcp.exe"
}
},
"inputs": []
}
Decision Output Example```json
{
"allow": true,
"risk": "low",
"reasons": [
"lodash@3.10.1 is 1 major version behind latest (4.17.21)"
],
"evidence": [
{
"kind": "check",
"id": "staleness.behind_latest",
"severity": "low",
"message": "lodash@3.10.1 is 1 major version behind latest (4.17.21)",
"facts": {
"package_name": "lodash",
"resolved_version": "3.10.1",
"latest_version": "4.17.21",
"major_gap": 1
}
}
],
"fingerprints": {
"config": "c7d9f5b8b9a8f2a9f6b1f42f0e8e8c8a63f2b2ef8fdde1f3cd9ea4f5a2c08a0b",
"policy": "fca103ee4fd5b86595a6a6e933f8a5f87db0ce087f80744dc1ea9cdbf58f7a6f"
},
"metadata": {
"latest": "4.17.21",
"requested": "3.10.1",
"published": "2015-08-31T00:00:00Z",
"weekly_downloads": 45000000
}
}
## Lockfile Audit Output Example (`dependency_ancestry`)
Input lockfile (`package-lock.json`) used for this example:```json
{
"name": "demo",
"lockfileVersion": 2,
"dependencies": {
"react": {
"version": "18.2.0",
"dependencies": {
"loose-envify": {
"version": "1.4.0"
}
}
}
}
}
Audit output:```json
{
"allow": true,
"risk": "low",
"total": 2,
"denied": 0,
"packages": [
{
"name": "react",
"requested": "18.2.0",
"allow": true,
"risk": "low",
"reasons": [],
"evidence": []
},
{
"name": "loose-envify",
"requested": "1.4.0",
"allow": true,
"risk": "low",
"reasons": [],
"evidence": [],
"dependency_ancestry": {
"paths": [
{ "ancestors": ["react"] }
]
}
}
],
"fingerprints": {
"config": "<sha256>",
"policy": "<sha256>"
}
}
`paths[].ancestors` lists only ancestors (root to immediate parent), excluding the package itself.
For direct dependencies, `dependency_ancestry` is omitted.
`evidence.id` is stable and machine-oriented:
- Built-in checks: `.` (example: `staleness.behind_latest`)
- Custom rules: `custom_rule.` (example: `custom_rule.low-downloads`)
- Policy/runtime items: explicit IDs (example: `denylist.package`, `risk.medium_pair_escalation`)
## Trust and Security Posture
- Fail-closed behavior: check/runtime failures are surfaced and do not silently allow installs.
- Local audit trail: append-only audit log for decision review, with an optional remote HTTP backend (see `[audit]` in the configuration spec).
- Deterministic policy context: responses include `policy_snapshot_version`, config and policy fingerprints, and enabled check set.
- Local cache: SQLite cache keyed by policy fingerprint + package tuple with TTL expiry.
## Disclaimer
`safe-pkgs` works as an MCP tool that AI agents can call before installing packages. However, **we cannot guarantee that an AI agent will always choose to call this tool** — agentic models that autonomously select tools may proceed with package installation without invoking `check_package` or `check_lockfile` first, depending on the model, prompt context, and system prompt configuration.
If your AI agent skipped `safe-pkgs` when it should have called it, please open an issue with the prompt and response so we can improve tool descriptions and usage guidance.
## Roadmap
Prioritized planned work:
### Now
- [x] Dependency confusion defenses for internal/private package names
- [x] Policy simulation mode (`what-if`) without enforcement
- [x] Metrics/log schema for latency, cache hit ratio, and registry error rates
- [x] Support remote audit storage backends
- [x] Support remote config sources (GitHub repo, HTTP endpoint, etc.)
- [x] Support for private registries
### Next
- [ ] Policy waivers with expiry
- [ ] Package provenance checks (where ecosystem metadata supports it)
- [ ] Publisher trust signals (account age, maintainer churn, ownership changes)
- [x] Performance/scale improvements for large lockfiles:
- [x] Configurable bounded concurrency (default: 5 parallel evaluations)
- [x] Inter-batch delay to prevent API rate limiting (default: 100ms)
- [x] Cache hit tracing for visibility
- [ ] Additional performance improvements (request coalescing for duplicate packages)
### Later
- [ ] NVD advisory enrichment
- [ ] Optional Snyk advisory provider
- [ ] Socket.dev integration
- [ ] GitHub Actions integration for CI auditing
- [ ] Registry-driven MCP schema and docs generation (single source of truth)
- [ ] HTTP Streamable MCP server option
- [ ] More validated editor config examples
- [ ] Git hook integration for pre-commit checks
## Development```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test
Coverage
Install:```bash
rustup component add llvm-tools-preview
cargo install cargo-llvm-cov
Summary:```bash
cargo llvm-cov --workspace --all-features --summary-only
HTML report:```bash
cargo llvm-cov --workspace --all-features --html
Report path:
- `target/llvm-cov/html/index.html`
## Local Docs```bash
pip install zensical
zensical serve
> Note: This project now uses Zensical instead of MkDocs.
> MkDocs 2.0 drops the plugin system and breaks backward compatibility with no migration path (announcement).
Deterministic Evaluation Clock (Optional)
Set SAFE_PKGS_EVALUATION_TIME to an RFC3339 timestamp to force a fixed policy evaluation time (useful for replay/debug runs):bash
SAFE_PKGS_EVALUATION_TIME=2026-01-01T00:00:00Z safe-pkgs audit /path/to/project
``````powershell
$env:SAFE_PKGS_EVALUATION_TIME = "2026-01-01T00:00:00Z"
safe-pkgs audit C:\path\to\project