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)
• Blocks malicious packages at install time
• No configuration required, just install and use

🔥 PMG in Action

📦 TL;DR

Install pmg

brew install safedep/tap/pmg

Set up pmg to protect you development environment from malicious packages:

pmg setup install

Continue using your favorite package manager as usual:

npm install <package-name>

uv pip install <package-name>

📑 Table of Contents

• Package Manager Guard (PMG)
  • 🔥 PMG in Action
  • 📦 TL;DR
  • 📑 Table of Contents
  • 🔥 Features
  • Supported Package Managers
  • Installation
    • Homebrew
    • Binaries
    • Build from Source
  • Setup
    • Install Aliases
    • Remove Aliases
  • Usage
    • Recommended: Automated Setup
    • Alternative: Manual Commands
    • Lockfile Installation
    • Silent Mode
    • Dry Run
    • Verbose Mode
    • Debugging
  • Environment Variables
  • 🤝 Contributing
  • 🚫 Limitations

🔥 Features

• 🚫 Malicious package identification using SafeDep Cloud
• 🌲 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

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>
pip	✅ Active	pmg pip install <package>
uv	✅ Active	pmg uv add <package> or pmg uv pip install <package>
poetry	✅ Active	pmg poetry add <package>
yarn	🚧 Planned

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

This command will:

• Create a ~/.pmg.rc file containing package manager aliases
• Automatically add a source line to your shell configuration files
• Supports bash, zsh and fish shell

Note

: After running pmg setup install, restart your terminal or run source ~/.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.rc file

⚠️ Note: Aliases might still be active in your current terminal session. Restart your terminal or use unalias <cmd> to remove them instantly.

Usage

Recommended: Automated Setup

For the best experience, use the automated setup:

pmg setup install

After setup, use your package managers normally:

npm install <package-name>
pnpm add <package-name>
bun add <package-name>

pip install <package-name>

uv add <package-name>
uv pip install <package-name>

poetry add <package-name>

Alternative: Manual Commands

You can also run PMG manually without aliases:

pmg npm install <package-name>
pmg pnpm add <package-name>
pmg bun add <package-name>

pmg pip install <package-name>

pmg uv add <package-name>
pmg uv pip install <package-name>

pmg poetry add <package-name>

Lockfile Installation

PMG seamlessly protects lockfile-based installations:

npm install          # Uses package-lock.json
pnpm install         # Uses pnpm-lock.yaml
bun install          # Uses bun.lock

pip install -r requirements.txt   # Uses requirements file

uv sync                           # Installs packages from uv.lock
uv pip sync requirements.txt      # Sync from requirements file
uv pip install -r requirements.txt

poetry install      # Installs from poetry.lock

PMG scans the exact package versions specified in lockfiles and blocks installation if malicious packages are detected.

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>

Environment Variables

PMG_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>

🤝 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