primer

Pre-install security interceptor for package managers. Scans every package against the OSV vulnerability database before it hits your system.

$ curl --proto '=https' --tlsv1.2 -fsSL https://github.com/callezenwaka/primer/releases/latest/download/primer-installer.sh | sh
GitHub Releases

How it works

$ pip install pillow
→ primer shim intercepts
→ queries OSV vulnerability database
→ found 3 vulnerabilities (1 CRITICAL, 2 HIGH)
pillow 9.0.0 — GHSA-56pw-mpj4-fxjw [CRITICAL]
Fixed in: 9.0.1
→ [prompt] View full details? (y/N)
→ [prompt] Continue install anyway? (y/N)
→ exits 1 on "N"

$ pip install requests
✓ requests: found 0 vulnerabilities

Features

Intercept

Shims sit ahead of your package managers in $PATH. Every install is scanned before execution.

Scan

Run primer scan <pkg> --ecosystem <eco> to check any package on demand without installing it.

Cache

Results cached locally for 24 hours. Repeat installs are instant with stale-on-error fallback.

AI Summary

Local SLM generates plain-English CVE summaries. No cloud dependency, no account required.

Git Hook

Pre-commit hook blocks commits that add vulnerable packages to manifests.

Polyglot

Covers Python, Node.js, Go, and Rust out of the box — one tool across your entire stack.

Transitive Scanning

Diffs the lockfile after install to scan the full dependency tree — not just the package you named. Opt out per-command with --direct-only.

Watch Mode

primer watch monitors manifests for changes and auto-scans on save. Debounced, cross-platform, and exits cleanly on Ctrl+C.

SBOM

primer sbom emits a CycloneDX or SPDX Software Bill of Materials enriched with OSV vulnerability data.

MCP Server

primer mcp exposes a scan_package tool via the Model Context Protocol so AI coding agents (Claude Code, Cursor, Cline) can query vulnerability data before installing packages.

Remediation

primer scan --file audits existing packages and prints a ready-to-run fix command (npm install pkg@fixed, pip install "pkg>=fixed") for every patched vulnerability.

Quick start

# 1. Install
curl --proto '=https' --tlsv1.2 -fsSL \ https://github.com/callezenwaka/primer/releases/latest/download/primer-installer.sh | sh
# 2. Set up shims
primer init
# 3. Use your package manager as normal — primer intercepts automatically
pip install requests npm install express
# 4. Optional: enable AI summaries
primer model add primer scan pillow --ecosystem pypi --ai
# 5. Optional: block vulnerable commits
primer hook install
# 6. Optional: scan on bare restore (npm install, go mod download, …)
primer config set intercept-restore true

CLI reference

Run primer <command> --help for full flag details.

Common

Command Description
primer scan <pkg> --ecosystem <eco> Scan a package for known vulnerabilities. Shows "Fixed in:" and a ready-to-run fix command when OSV provides a patched version. Flags: --version, --force, --verbose, --ai
primer scan --file <manifest|lockfile> Audit all packages in an existing manifest or lockfile. Each vulnerable package shows its fix command (npm install pkg@fixed, pip install "pkg>=fixed", etc.). Use --direct-only to skip transitive deps
primer scan --file <path> Scan all packages in a manifest or lockfile. Manifests: requirements.txt, pyproject.toml, package.json, go.mod, Cargo.toml. Lockfiles: package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.lock, go.sum, uv.lock, poetry.lock. Add --direct-only to skip transitive packages.
primer init Generate shims in ~/.primer/bin and prepend to $PATH
primer info Show PATH order, shim health, cache stats, and active model (alias for doctor)

Management

Command Description
primer allow add <pkg> [--ecosystem] Add a package to .primer-ignore — scanned but never blocked
primer allow remove <pkg> [--ecosystem] Remove a package from the allow-list
primer allow list Print all entries in .primer-ignore
primer cache clear Delete all cached vulnerability results
primer cache stats Show entry count, total size on disk, and oldest/newest entry age
primer config set <key> <value> Write a value to ~/.primer/config.toml. Keys: ai.backend, ai.model, ai.tokenizer, intercept-restore, direct-only, prompt-threshold
primer config get <key> Read a single config value
primer config list Print the full config
primer model add Download the default SmolLM2 model from HuggingFace Hub
primer model add --from <path> Import a local GGUF file (no network)
primer model add --repo <repo> --file <file> Download a specific model from HuggingFace Hub
primer model list List registered models with path and file size
primer model set <target> Set the active inference target. Local: /path/to/model.gguf. Ollama: ollama:llama3.2
primer model remove Interactive select list of all managed models — choose one or "Remove all"
primer model remove <name>... Remove one or more named models without a prompt. Names: filename (smollm2.gguf) or Ollama target (ollama:llama3.2)
primer model remove --all Remove all managed model files and clear config (non-interactive)
primer hook install Write .git/hooks/pre-commit to block vulnerable package additions
primer hook check Scan staged manifest changes manually (also called by the hook itself)
primer watch [--directory <path>] [--scan] Watch manifest files and auto-scan on change. --scan runs an immediate scan on startup. Debounced at 500 ms; exit with Ctrl+C
primer sbom --file <path> Emit a Software Bill of Materials. --format cyclonedx (default) or --format spdx. --output <file> writes to disk. --no-scan skips OSV enrichment
primer mcp Start an MCP server over stdio. Add to .mcp.json so AI agents can call scan_package before installing packages
primer completions <shell> Emit a shell completion script. Shells: bash, zsh, fish, powershell
primer uninit [--purge] Remove shims and $PATH entry. --purge also deletes cache and model files

Supported ecosystems

Ecosystem Intercepted commands
Python pip, uv, poetry
Node.js npm, yarn, pnpm
Go go get, go mod
Rust cargo add, cargo build, cargo fetch, cargo check