safe-pkgs

Package safety checks for AI agents before install.
Rust MCP server + CLI with allow/deny decisions, risk scoring, and audit logs.

Documentation

At a Glance

safe-pkgs returns machine-readable decisions:

• allow: true or false
• risk: low | medium | high | critical
• reasons: human-readable findings
• metadata: package context (latest, publish date, downloads, advisories)

Supported registries:

• npm (default)
• cargo (crates.io)

Roadmap

These features are "planned" but not yet implemented:

• PyPI registry support
• NVD advisory enrichment
• Optional Snyk advisory provider
• Socket.dev integration
• GitHub Actions integration for CI auditing
• Rate-limit aware registry client with backoff
• Custom Rules
• HTTP Streamable MCP server option
• More validated editor config examples
• Git hook integration for pre-commit checks
• Support for private registries

Quick Start

Build and run MCP server:

cargo build --release
./target/release/safe-pkgs serve --mcp

Windows PowerShell:

.\target\release\safe-pkgs.exe serve --mcp

Run a local audit:

safe-pkgs audit /path/to/project-or-package.json

MCP Config Example

{
  "servers": {
    "safe-pkgs": {
      "type": "stdio",
      "command": "/path/to/safe-pkgs",
      "args": [
        "serve",
        "--mcp"
      ]
    }
  },
  "inputs": []
}

Decision Output Example

{
  "allow": true,
  "risk": "low",
  "reasons": [
    "lodash@3.10.1 is 1 major version behind latest (4.17.21)"
  ],
  "metadata": {
    "latest": "4.17.21",
    "requested": "3.10.1",
    "published": "2015-08-31T00:00:00Z",
    "weekly_downloads": 45000000
  }
}

Development

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test

Coverage

Install:

rustup component add llvm-tools-preview
cargo install cargo-llvm-cov

Summary:

cargo llvm-cov --workspace --all-features --summary-only

HTML report:

cargo llvm-cov --workspace --all-features --html

Report path:

• target/llvm-cov/html/index.html

Local docs

pip install mkdocs mkdocs-material
mkdocs serve