mirror of
https://github.com/safedep/pmg.git
synced 2026-08-03 07:24:09 +02:00
365deb1897
* feat: Add proxy_install_only config to restrict proxy to download commands Introduces proxy_install_only (default: false) which, when enabled, skips the proxy for package manager commands that do not download packages (e.g. npm ls, pip list), avoiding unnecessary MITM overhead. - Add ProxyInstallOnly to Config and config template - Add IsKnownDownloadCommand / MayDownloadPackages to ParsedCommand - Add DownloadCommands to npm and pypi PM configs covering update, ci, audit, dlx, exec, x, download, run and equivalents per PM - Extract shared runner.Execute used by both proxy flow and guard - Proxy flow short-circuits to runner.Execute for non-download commands when proxy_install_only=true * refactor: Inject CommandExecutor into guard to fix dependency direction guard depended on internal/runner, which inverted the intended layer hierarchy. Now guard defines a CommandExecutor function type and accepts it as a constructor argument. internal/flows (the composition root) creates the executor closure wrapping runner.Execute and injects it, keeping guard free of internal/ dependencies. * refactor: Invert proxy_install_only logic to use known non-download commands Replace the DownloadCommands allowlist (opt-in, fail-open) with a NonDownloadCommands denylist (opt-out, fail-safe). The proxy now runs for all commands except those explicitly known to not download packages. Unknown or future package manager subcommands default to running with the proxy. Includes script runners (run, start, test, stop, restart) that can spin up local servers — setting proxy env vars on these breaks them without providing any security benefit. Also covers removal commands and local operations that never contact the registry. * fix: Support PMG_* env vars regardless of config file state AutomaticEnv only resolves env vars for keys Viper already knows about via AllKeys(). When a key is absent from the config file (commented out, new key added after last setup, or no config file at all), Viper had no knowledge of it and silently skipped the env var. Fix by registering all Config struct fields as Viper defaults via reflection (using mapstructure tags) before reading the config file. This ensures PMG_* env vars work in all cases. Precedence: cobra flags > env vars > config file > defaults. SetDefault is used (not Set) so env vars and config file can still override the Go defaults freely. Tests added covering all precedence levels including the key-absent- from-config-file case that was the original bug report. * fix: Only check first non-flag arg against NonDownloadCommands Scanning all args caused false proxy bypasses when package names or script arguments matched a NonDownloadCommands entry. For example: - npm exec test → "test" matched, proxy incorrectly skipped - npm update config → "config" matched, proxy skipped - npm publish --tag version → "version" matched, proxy skipped Fix by checking only the first non-flag argument (the subcommand). If it is not in NonDownloadCommands we break immediately, so trailing args never influence the classification. Applied to all four parsers: npm, pip/pip3, uv, and poetry. Regression tests added for the false positive cases. * refactor: Replace reflection-based Viper defaults with embedded template Load the embedded config template as the Viper base so all keys are registered upfront, enabling PMG_* env vars to work regardless of whether a key exists in the user's config file. * fix: Restore trusted_packages template entry and revert DefaultConfig change * docs: Document environment variable overrides for config keys * update npm test cmd * refactor: extract shared non-download command detection helper Replaces duplicated first-non-flag-arg detection loops in npm.go and pypi.go (pip + poetry parsers) with a shared isFirstNonFlagArgInList helper in packagemanager.go. https://claude.ai/code/session_01AHaKF3vc2Haj9tK3jgUBAs --------- Co-authored-by: Claude <noreply@anthropic.com>
Package Manager Guard (PMG)
Why PMG?
Developers and AI coding agents install packages every day. Each npm install or pip install executes thousands of lines of code that nobody reviews.
Malicious packages ship constantly in popular ecosystems:
- litellm 1.82.8 - a popular AI proxy library compromised to exfiltrate credentials
- telnyx 4.87.2 - a legitimate telecom SDK hijacked on PyPI
- pino-sdk-v2 - a typosquat package disguised as the popular pino logger
PMG intercepts every package install and checks it for malware before code executes. Install it once, and every npm install, pip install, and poetry add is protected automatically.
Featured in tl;dr sec and used by engineering teams worldwide.
How PMG Works
- Transparent Protection - PMG wraps
npm,pip, and other package managers to transparently apply protection. Developers and AI agents use their tools as usual with no workflow changes. - Malicious Package Protection - Every intercepted package is analyzed against SafeDep's real-time threat intelligence before installation. Malicious packages are blocked before code executes on the system.
- Sandboxed Installation - Package installation runs inside OS-native sandboxes (macOS Seatbelt, Linux Bubblewrap), preventing install scripts from modifying the system even if a threat evades detection.
- Audit Logging - Every package installation event is logged, providing a verifiable trail of what was installed, when, and from where.
Quick Start
Get protected in seconds.
1. Install
MacOS / Linux (Homebrew)
brew install safedep/tap/pmg
NPM
npm install -g @safedep/pmg
See Installation for additional methods.
2. Setup
Configure your shell to use PMG automatically.
pmg setup install
# Restart your terminal to apply changes
Tip: Re-run
pmg setup installafter upgrading PMG to pick up new configuration options.
3. Use
Use your package managers as usual or let your AI coding agent use them. PMG works silently in the background.
npm install express
# or
pip install requests
Verify PMG is working by installing a test package. This is a harmless package flagged as malicious in the SafeDep database, specifically meant for testing:
npm --prefer-online --no-cache i safedep-test-pkg@0.1.3
Expected output
✗ Malicious package blocked
- safedep-test-pkg@0.1.3
Reference: https://app.safedep.io/community/malysis/01KF5JYDND9XR94WNEJ2G74KY2
✗ PMG: 1 packages analyzed, 1 blocked
Features
| Feature | Description |
|---|---|
| AI Agent Safety Net | Protects against malicious packages installed by AI coding agents (Claude Code, Cursor, Copilot, Windsurf). |
| Malicious Package Protection | Real-time protection against malicious packages using SafeDep. |
| Sandboxing | Enforces least privilege using OS native sandboxing to contain installation scripts. |
| Dependency Analysis | Deep scans of direct and transitive dependencies before they hit your disk. |
| Event Logging | Keeps a verifiable audit trail of all installed packages. |
| Dependency Cooldown | Blocks package versions published within a configurable time window, reducing exposure to supply chain attacks. |
| Zero Config | Works out of the box with sensible security defaults. |
| Cross-Shell | Seamlessly integrates with Zsh, Bash, Fish, and more. |
Supported Package Managers
PMG supports the tools you already use:
| Ecosystem | Tools | Status | Command Example |
|---|---|---|---|
| Node.js | npm |
Yes | npm install <pkg> |
pnpm |
Yes | pnpm add <pkg> |
|
yarn |
Yes | yarn add <pkg> |
|
bun |
Yes | bun add <pkg> |
|
npx |
Yes | npx <pkg> |
|
pnpx |
Yes | pnpx <pkg> |
|
| Python | pip |
Yes | pip install <pkg> |
poetry |
Yes | poetry add <pkg> |
|
uv |
Yes | uv add <pkg> |
Installation
Homebrew (MacOS/Linux)
brew tap safedep/tap
brew install safedep/tap/pmg
NPM (Cross-Platform)
npm install -g @safedep/pmg
Go (Build from Source)
# Ensure $(go env GOPATH)/bin is in your $PATH
go install github.com/safedep/pmg@latest
Binary Download
Download the latest binary for your platform from the Releases Page.
Uninstallation
Remove shell integration:
pmg setup remove
To also remove the PMG configuration file:
pmg setup remove --config-file
Then uninstall PMG itself:
# Homebrew
brew uninstall safedep/tap/pmg
# NPM
npm uninstall -g @safedep/pmg
Trust and Security
Security is our first class requirement. PMG builds are reproducible and signed.
- Attestations: GitHub and npm attestations are used to guarantee artifact integrity.
- Verification: Users can cryptographically prove the binary matches the source code.
- See Trusting PMG for verification steps.
User Guide
Support
If PMG saved you from a bad package, star this repo — it helps others find it.
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines on how to build and test PMG locally.
Telemetry
PMG collects anonymous usage data to improve project stability and reliability.
To disable: export PMG_DISABLE_TELEMETRY=true.