mirror of
https://github.com/safedep/pmg.git
synced 2026-08-03 07:24:09 +02:00
c47776db27
* refactor(flows): extract SetupCACertificate for reuse Move the CA load/generate/merge logic out of proxyFlow into an exported flows.SetupCACertificate so the persistent proxy server can reuse it. * feat(proxy): add persistent proxy server with start/stop/env/status Introduces 'pmg proxy' commands backed by internal/proxyserver: a long-lived MITM proxy that intercepts package managers via env vars (no shims). Supports --daemon (Unix), --state, --port; generic 'env' output that skips cert vars when the CA is OS-trusted; opt-in 'stop --fail-on-violation' (fail-closed on crash) with a synchronous cloud event flush; and the malysis analysis cache. * feat(action): add server-mode for persistent proxy When server-mode=true the action starts the proxy daemon and injects proxy env vars into the job instead of installing shims. * test(proxy): add persistent proxy server E2E workflow * docs(readme): document persistent proxy server mode * fix(proxy): create cache dir before writing state file and daemon log On a fresh CI runner the cache directory does not exist yet; os.OpenFile and os.WriteFile do not create parent dirs, so 'pmg proxy start --daemon' failed with 'no such file or directory'. MkdirAll the parent before writing. * docs: add persistent proxy server architecture doc * refactor proxyserver * fix(proxy): always emit cert env vars instead of skipping on OS-trust status npm/pip/yarn/requests trust the MITM CA inconsistently across tools, versions, and configs; many still use bundled CA stores. Always emitting the cert-path env vars is the conservative choice that works regardless, and is harmless for tools that read the OS store (they ignore the vars). Skipping them when a system CA exists would silently break any tool still on a bundled store. * refactor(proxy): drop redundant audit init in daemon; rely on main.go main.go's PersistentPreRun already initializes the audit pipeline for every command (including the daemon's re-exec'd child) and closes it at process exit. Re-initializing in proxyserver.Run created a second auditor and a second cloud-sync WAL connection, orphaning the first. Removing it makes the daemon consistent with the normal proxy flow, which never self-initializes audit. * fix(proxy): bypass proxy env when flushing events to cloud on stop pmg proxy stop inherits HTTP(S)_PROXY (injected by 'pmg proxy env') pointing at the PMG proxy it just shut down. The cloud sync gRPC client honored those vars and routed api.safedep.io through the dead proxy, failing with 'connection refused' so no events were delivered. Clear the proxy env vars before the sync so PMG's own cloud traffic goes direct. * chore(proxy): address review feedback - configurable bind host via proxy.server.listen_host (default loopback) - proxy commands use ui.ErrorExit instead of returning errors to cobra - rename errcode to ProxyPolicyViolation (covers malware + cooldown) - share cloud sync via audit.DrainToCloud (de-dup with cmd/cloud/sync) - centralize proxy CA bundle path in certmanager - docs: persistent proxy cert trust + bind address * fix(proxy): show real message on fail-on-violation error stopExitError set only WithMsg, but ui.ErrorExit renders HumanError, so the framed error showed 'no human-readable message available'. Set both from one string, and emit the framed error before the stdout summary so the blocked count is stated once. * fix(proxy): flush cloud events from the daemon, not stop The stop process inherits HTTP_PROXY (from 'pmg proxy env'), so its cloud client routed api.safedep.io through the already-stopped proxy and failed with connection refused. Move the flush into the daemon's shutdown, which has no proxy env (it started before env injection) and dials SafeDep directly. - daemon flushes on shutdown via audit.DrainToCloud and records the result in the state file; stop surfaces it (on both success and fail-on-violation paths) since the daemon's own logs aren't visible to stop - coordinate stop's wait with the daemon shutdown budget; on timeout, error out without reading stale state or deleting the file (fail-closed) - persist blocked count before the flush so the gate stays correct if the flush hangs or the daemon is killed mid-flush - remove now-redundant cloud_flush.go * disable auto-sync for proxy cmds * feat(proxy): periodic cloud sync + move proxy env vars to packagemanager - daemon runs a periodic cloud-sync ticker so the shutdown flush stays small; the run total is reported by stop, and shutdown timeouts are coordinated - move EnvVarForProxy from config to packagemanager (it is package-manager knowledge); the shared function now builds the proxy URL and NO_PROXY itself, removing the duplicated construction in the per-command and persistent paths - relocate the #319 yarn and #339 IPv6 regression tests alongside the function - enable cloud sync in the persistent-proxy E2E workflow and fix the stale internal/proxystate path filter * refactor(proxy): rename cloudFlushLockTimeout to cloudFlushLockWait Consistent timeout naming: *LockWait is the lock-acquire bound, *Timeout is the sync-RPC bound. Previously the final-flush pair was cloudFlushLockTimeout vs cloudFlushTimeout — two lookalike names for different operations. * refactor(proxy): extract cloudFlush and trim duplicate shutdown comments The shutdown's final-flush block is now a cloudFlush helper, symmetric with startCloudSyncLoop (one-shot vs loop). Removed the triplicated ticker/lock contention comments, keeping the contract on the function doc and one-line pointers at the call sites. * docs: update persistent proxy cloud sync to daemon-owned model The daemon now owns cloud delivery (periodic sync while serving + final flush on shutdown); stop signals it, waits, and reports the result. Rewrite the Cloud event sync section, fix stop attributions, add the cloud_sync state field, and update the sequence diagram. * docs: move Usage section up below How it works Put the copy-paste recipes near the top so users find them before the internals. * refactor(proxy): address PR review feedback - configurable bind host/port via --host/--port flags + config (listen_host, listen_port), bound directly to config fields per PMG's flag pattern - daemon log path via --log-file and readiness timeout in ProxyDaemonConfig; Daemonize no longer owns path policy (caller validates, fails fast) - gate periodic cloud sync on auto_sync; suppress detached background sync for proxy commands instead of flipping the flag - pmg proxy env --export emits shell-quoted lines for eval (spaces survive) - extract shared flows.BuildCachedMalysisAnalyzer, dropping the analyzer+cache duplication between proxy flow and proxy server - add internal/proxyserver/doc.go documenting the package + boundary vs flows - E2E: assert malicious installs are blocked (drop continue-on-error) - docs: trim Commands/State-file to user contracts; refresh bind address * refactor(proxy): proactive alignment fixes from whole-PR review - gate the shutdown cloud flush on auto_sync too, matching the periodic ticker (auto_sync consistently controls all daemon-driven cloud delivery) - ResolveStatePath takes cacheDir instead of *RuntimeConfig, keeping state.go free of config dependency - drop the empty-host comment in listenAddr; keep the loopback guard so a blank host never silently binds all interfaces * fix: Decouple localdb with malysis analyser construction * fix: Persist global args before proxy server daemon exec * fix: GitHub Action for cloud auto-sync in server mode --------- Co-authored-by: Abhisek Datta <abhisek.datta@gmail.com>
302 lines
11 KiB
Markdown
302 lines
11 KiB
Markdown
<div align="center">
|
|
<h1>Package Manager Guard (PMG)</h1>
|
|
</div>
|
|
|
|
<p align="center">
|
|
<strong>Block malicious npm and pip packages before they install.</strong><br>
|
|
Defense in depth for the package managers you already use.
|
|
</p>
|
|
|
|
<div align="center">
|
|
<img src="./docs/demo/pmg-intro.gif" width="800" alt="pmg in action">
|
|
</div>
|
|
|
|
<br>
|
|
|
|
<div align="center">
|
|
|
|
[](https://docs.safedep.io/pmg/quickstart)
|
|
[](https://safedep.io)
|
|
[](https://discord.gg/kAGEj25dCn)
|
|
[](https://tldrsec.com/p/tldr-sec-316)
|
|
|
|
[](https://goreportcard.com/report/github.com/safedep/pmg)
|
|
|
|
|
|
[](https://api.securityscorecards.dev/projects/github.com/safedep/pmg)
|
|
[](https://github.com/safedep/pmg/actions/workflows/codeql.yml)
|
|
|
|
</div>
|
|
|
|
## 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.
|
|
|
|
Recent compromises in popular ecosystems:
|
|
|
|
- [**Mini Shai-Hulud**](https://safedep.io/mini-shai-hulud-strikes-again-314-npm-packages-compromised/) - 300+ popular packages compromised
|
|
- [**litellm 1.82.8**](https://safedep.io/malicious-litellm-1-82-8-analysis/) - a popular AI proxy library compromised to exfiltrate credentials
|
|
- [**telnyx 4.87.2**](https://safedep.io/malicious-telnyx-pypi-compromise/) - a legitimate telecom SDK hijacked on PyPI
|
|
- [**pino-sdk-v2**](https://safedep.io/malicious-npm-package-pino-sdk-v2-env-exfiltration/) - a typosquat package disguised as the popular pino logger
|
|
|
|
**PMG is free, open source (Apache 2.0), and requires no account or API key.** It intercepts every package install and checks it against [SafeDep's free community API](https://safedep.io) for known malware **before** code executes. Install it once, and it covers every `npm install`, `pip install`, and `poetry add` after that.
|
|
|
|
## How PMG Works
|
|
|
|
PMG takes a defense in depth approach. Zero config, works across Zsh, Bash, and Fish, and each install passes through the enabled protection layers before code runs, plus an audit trail after.
|
|
|
|
<div align="center">
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="./docs/assets/how-pmg-works-dark.svg">
|
|
<img alt="PMG defense in depth: install command intercepted by PMG, passed through Layer 1 Threat Intel, Layer 2 Cooldown, Layer 3 Sandbox, then run with an audit log entry" src="./docs/assets/how-pmg-works-light.svg" width="820">
|
|
</picture>
|
|
</div>
|
|
|
|
<details>
|
|
<summary><strong>Layer details</strong></summary>
|
|
|
|
- **Transparent Interception** - PMG wraps `npm`, `pip`, and other package managers. Developers and AI agents use the same commands. No workflow changes.
|
|
- **Layer 1: Threat Intelligence** - PMG checks every package against [SafeDep's real-time threat intelligence](https://safedep.io) before install. Known-malicious packages are blocked. No key, no login required.
|
|
- **Layer 2: Policy (Dependency Cooldown)** - PMG blocks package versions published inside a configurable cooldown window, so recently compromised versions are skipped during the window.
|
|
- **Layer 3: Opt-in Sandbox** - When sandboxing is enabled and configured, PMG runs installs inside OS-native sandboxes (macOS Seatbelt, Linux Landlock by default, or Bubblewrap fallback) so install scripts have restricted system access even if a threat slips past the first two layers.
|
|
- **Audit Logging** - PMG logs every install (what, when, from where) for a verifiable audit trail.
|
|
|
|
</details>
|
|
|
|
## How PMG Compares
|
|
|
|
PMG is the only free, open-source, install-time package firewall that covers developers and AI agents alike and ships with sandboxing and cooldown out of the box.
|
|
|
|
| Capability | PMG | Socket | safe-chain | Snyk | Dependabot |
|
|
| --------------------------------------- | --- | ------ | ---------- | ---- | ---------- |
|
|
| OSS / built in public | ✓ | ✗ | ✓ | ✗ | ✗ |
|
|
| No account or API key | ✓ | ✓ | ✓ | ✗ | ✗ |
|
|
| Install-time malicious package blocking | ✓ | ✓ | ✓ | ✗ | ✗ |
|
|
| Dependency cooldown policy | ✓ | ✗ | ✓ | ✗ | ✗ |
|
|
| Runtime sandboxing | ✓ | ✗ | ✗ | ✗ | ✗ |
|
|
| Protects AI coding agents transparently | ✓ | ✗ | ✗ | ✗ | ✗ |
|
|
| Local audit logs | ✓ | ✗ | ✗ | ✗ | ✗ |
|
|
| Known-CVE remediation PRs | ✗ | ✗ | ✗ | ✓ | ✓ |
|
|
|
|
## Quick Start
|
|
|
|
### 1. Install
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/safedep/pmg/main/install.sh | sh
|
|
```
|
|
|
|
> See [Installation](#installation) for Homebrew, npm, and other install methods.
|
|
|
|
### 2. Setup
|
|
|
|
Wire PMG into your shell so it intercepts package managers.
|
|
|
|
```bash
|
|
pmg setup install
|
|
# Restart your terminal to apply changes
|
|
```
|
|
|
|
> **Tip:** Re-run `pmg setup install` after upgrading PMG to pick up new configuration options.
|
|
|
|
Validate your installation and verify protection is working:
|
|
|
|
```bash
|
|
pmg setup doctor
|
|
```
|
|
|
|
> **Optional:** PMG inspects HTTPS traffic with an on-the-fly CA that it injects into package
|
|
> managers per run. To persist a single CA across runs and trust it in your OS trust store
|
|
> (needed for tools that ignore CA environment variables, such as Go on macOS and Windows),
|
|
> install it once:
|
|
>
|
|
> ```bash
|
|
> pmg setup cert install # user scope, no sudo
|
|
> pmg setup cert status # check trust state and expiry
|
|
> ```
|
|
>
|
|
> See [Certificate Authority](docs/cert.md) for scopes, rotation, and removal.
|
|
|
|
### 3. Use
|
|
|
|
See PMG blocking threats.
|
|
|
|
```bash
|
|
npm install --no-cache --prefer-online safedep-test-pkg@0.1.3
|
|
```
|
|
|
|
> **Note:** `safedep-test-pkg` is a benign test package flagged as malicious in SafeDep's database for
|
|
> testing and verification purposes.
|
|
|
|
Continue using your package managers as usual, or let your AI coding agent run them. PMG sits in the path, blocking malicious packages.
|
|
|
|
```bash
|
|
npm install express
|
|
# or
|
|
pip install requests
|
|
```
|
|
|
|
## Supported Package Managers
|
|
|
|
PMG supports the tools you already use:
|
|
|
|
| Ecosystem | Tools | Command Example |
|
|
| ----------- | -------- | ------------------- |
|
|
| **Node.js** | `npm` | `npm install <pkg>` |
|
|
| | `pnpm` | `pnpm add <pkg>` |
|
|
| | `yarn` | `yarn add <pkg>` |
|
|
| | `bun` | `bun add <pkg>` |
|
|
| | `npx` | `npx <pkg>` |
|
|
| | `pnpx` | `pnpx <pkg>` |
|
|
| **Python** | `pip` | `pip install <pkg>` |
|
|
| | `pipx` | `pipx run <pkg>` |
|
|
| | `poetry` | `poetry add <pkg>` |
|
|
| | `uv` | `uv add <pkg>` |
|
|
|
|
## Installation
|
|
|
|
<details>
|
|
<summary><strong>Install Script (MacOS/Linux)</strong></summary>
|
|
|
|
Downloads the latest release from GitHub, verifies its SHA-256 checksum, and installs to `$HOME/.local/bin` (if on `PATH`) or `/usr/local/bin`.
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/safedep/pmg/main/install.sh | sh
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Homebrew (MacOS/Linux)</strong></summary>
|
|
|
|
```bash
|
|
brew tap safedep/tap
|
|
brew install safedep/tap/pmg
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>NPM (Cross-Platform)</strong></summary>
|
|
|
|
```bash
|
|
npm install -g @safedep/pmg
|
|
```
|
|
|
|
> **Note:** NPM-based installs can be fragile when Node.js is managed by version managers like [`mise`](https://mise.jdx.dev/) or [`asdf`](https://asdf-vm.com/). The global `npm` bin path changes with the active Node version, so switching versions can leave `pmg` unavailable on `PATH` (or pointing to an old install). For these setups, prefer the install script or Homebrew.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Go (Build from Source)</strong></summary>
|
|
|
|
```bash
|
|
# Ensure $(go env GOPATH)/bin is in your $PATH
|
|
go install github.com/safedep/pmg@latest
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Binary Download</strong></summary>
|
|
|
|
Download the latest binary for your platform from the [Releases Page](https://github.com/safedep/pmg/releases).
|
|
</details>
|
|
|
|
## GitHub Actions
|
|
|
|
Protect CI workflows with one step. PMG analyzes every `npm install`,
|
|
`pip install`, etc. in the job.
|
|
|
|
```yaml
|
|
- uses: safedep/pmg@v1
|
|
with:
|
|
server-mode: true
|
|
|
|
- run: npm ci # intercepted via HTTP_PROXY automatically
|
|
|
|
- name: Enforce PMG policy
|
|
if: always()
|
|
run: pmg proxy stop --fail-on-violation # stops the daemon, fails the job on a block
|
|
```
|
|
|
|
By default you get malware blocking and dependency cooldown. Sandbox isolation
|
|
is opt-in via the `sandbox` input. Tune behavior via inputs (`paranoid`,
|
|
`sandbox`, `cooldown-days`, ...) or point
|
|
`config-file` at a YAML in the repo. See
|
|
[docs/github-action.md](docs/github-action.md) for the full reference.
|
|
|
|
## Uninstallation
|
|
|
|
Remove shell integration:
|
|
|
|
```bash
|
|
pmg setup remove
|
|
```
|
|
|
|
To also remove the PMG configuration file:
|
|
|
|
```bash
|
|
pmg setup remove --config-file
|
|
```
|
|
|
|
Then uninstall PMG itself:
|
|
|
|
```bash
|
|
# Homebrew
|
|
brew uninstall safedep/tap/pmg
|
|
|
|
# NPM
|
|
npm uninstall -g @safedep/pmg
|
|
```
|
|
|
|
## Trust and Security
|
|
|
|
PMG builds are reproducible and signed.
|
|
|
|
- **Attestations**: GitHub and npm attestations guarantee artifact integrity.
|
|
- **Verification**: You can cryptographically prove the binary matches the source code.
|
|
- See [Trusting PMG](docs/trust.md) for verification steps.
|
|
|
|
## User Guide
|
|
|
|
- [Configuration](docs/config.md)
|
|
- [Trusted Packages Configuration](docs/trusted-packages.md)
|
|
- [Dependency Cooldown](docs/dependency-cooldown.md)
|
|
- [Caching](docs/caching.md)
|
|
- [Proxy Mode Architecture](docs/proxy-mode.md)
|
|
- [Persistent Proxy Server](docs/persistent-proxy.md)
|
|
- [Certificate Authority](docs/cert.md)
|
|
- [Sandboxing](docs/sandbox.md)
|
|
|
|
## Support
|
|
|
|
If PMG saved you from a bad package, [star this repo](https://github.com/safedep/pmg). It helps others find it.
|
|
|
|
## Star History
|
|
|
|
<a href="https://star-history.com/#safedep/pmg&Date">
|
|
<picture>
|
|
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=safedep/pmg&type=Date&theme=dark" />
|
|
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=safedep/pmg&type=Date" />
|
|
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=safedep/pmg&type=Date" />
|
|
</picture>
|
|
</a>
|
|
|
|
## Contributing
|
|
|
|
Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for build and test instructions.
|
|
|
|
Thank you to all contributors ❤️
|
|
|
|
<a href="https://github.com/safedep/pmg/graphs/contributors">
|
|
<img src="https://contrib.rocks/image?repo=safedep/pmg" alt="Contributors to PMG" />
|
|
</a>
|
|
|
|
## Telemetry
|
|
|
|
PMG collects anonymous usage data. To disable, either:
|
|
|
|
- Set `disable_telemetry: true` in your PMG config file, or
|
|
- Export `PMG_DISABLE_TELEMETRY=true`.
|