README
¶
Package Manager Guard (PMG)
Created and maintained by https://safedep.io with contributions from the community 🚀
🤖 PMG protects developers from getting compromised by malicious packages. See example
- Wraps your favorite package manager (eg.
npm,pnpm,pipand more) - Blocks malicious packages at install time
- No configuration required, just install and use
- Maintains package installation event log for transparency and audit trail
PMG in Action
TL;DR
Install pmg using Homebrew:
brew install safedep/tap/pmg
Note: More installation options are available.
Set up pmg to protect your development environment from malicious packages:
pmg setup install
Note: Make sure to restart your terminal or source your shell's config file.
Continue using your favorite package manager as usual:
npm install <package-name>
uv pip install <package-name>
Features
- Malicious package identification using SafeDep Cloud with realtime threat detection
- Deep dependency analysis and transitive dependency resolution
- Fast and efficient package verification
- Seamless integration with existing package managers
- Automated shell integration with cross-shell support
- Package installation tracking and event logging
Supported Package Managers
PMG supports the following package managers:
| Package Manager | Status | Command |
|---|---|---|
npm |
✅ Active | pmg npm install <package> |
pnpm |
✅ Active | pmg pnpm add <package> |
bun |
✅ Active | pmg bun add <package> |
yarn |
✅ Active | pmg yarn add <package> |
pip |
✅ Active | pmg pip install <package> |
uv |
✅ Active | pmg uv add <package> or pmg uv pip install <package> |
poetry |
✅ Active | pmg poetry add <package> |
npx |
✅ Active | pmg npx <package> <action> |
pnpx |
✅ Active | pmg pnpx <package> <action> |
Want us to support your favorite package manager? Open an issue and let us know!
Installation
Homebrew
You can install pmg using homebrew in MacOS and Linux
brew tap safedep/tap
brew install safedep/tap/pmg
Binaries
Download the latest binary from the releases page.
Build from Source
Ensure $(go env GOPATH)/bin is in your $PATH
go install github.com/safedep/pmg@latest
Setup
PMG provides built-in commands to automatically configure shell aliases for seamless integration:
Install Aliases
Set up PMG to intercept package manager commands:
pmg setup install
Custom config directory
PMG_CONFIG_DIR=/path/to/config pmg setup install
The setup command will:
- Create a
~/.pmg.rcfile containing package manager aliases - Automatically add a source line to your shell configuration files
- Create a default config file. See config template
Note: After running
pmg setup install, restart your terminal or runsource ~/.zshrc(or your shell's config file) to activate the aliases.
Remove Aliases
To remove PMG aliases and restore original package manager behavior:
pmg setup remove
This will:
- Remove the source line from your shell configuration files
- Delete the
~/.pmg.rcfile
⚠️ Note: Aliases might still be active in your current terminal session. Restart your terminal or use
unalias <cmd>to remove them instantly.
Usage
Active Scanning
Use the --paranoid flag to perform active malware scanning on unknown packages (requires SafeDep Cloud credentials):
pmg --paranoid npm install <package-name>
Silent Mode
Use the --silent flag to run PMG in silent mode:
pmg --silent npm install <package-name>
Dry Run
Use the --dry-run flag to skip actual package installation. When enabled pmg will not execute
package manager commands. Useful for checking packages and their transitive dependencies for malware.
pmg --dry-run npm install <package-name>
Verbose Mode
Use the --verbose flag to run PMG in verbose mode:
pmg --verbose npm install <package-name>
Debugging
Use the --debug flag to enable debug mode:
pmg --debug npm install <package-name>
Store the debug logs in a file:
pmg --debug --log /tmp/debug.json npm install <package-name>
Insecure Installation
Allows bypassing the blocking behavior when malicious packages are detected during installation.
⚠️ Warning: This is a security feature bypass. Use with extreme caution and only when you understand the risks.
export PMG_INSECURE_INSTALLATION=true
pmg npm install <package-name>
Advanced
Contributing
Refer to CONTRIBUTING.md
Limitations
Approximate dependency version resolution
pmg resolves the transitive dependencies of a package to be installed. It does it by querying
package registry APIs such as npmjs and pypi. However, almost always, dependency versions are
specified as ranges instead of specific version. Different package managers have different ways of
resolving these ranges. It also depends on peer or host dependencies already available in the application.
pmg is required to block a malicious package before it is installed. Hence it applies its own heuristic
to choose a version from a version range for evaluation. This is fine when all versions of a given package
is malicious. However, there is a possibility of inconsistency when a specific version of a package is malicious.
PyPI registry scanning only
pmg only scans packages available in the PyPI registry when using any python package manager. Packages installed from
alternative sources such as Git URLs, local file paths, or private registries are not analyzed for
malware detection. This limitation applies to direct installations and transitive dependencies sourced
from non-PyPI locations.
Telemetry
pmg collects anonymous telemetry to help us understand how it is used and
improve the product. To disable telemetry, set PMG_DISABLE_TELEMETRY environment
variable to true.
export PMG_DISABLE_TELEMETRY=true
Documentation
¶
There is no documentation for this package.
Source Files
Directories