From e31a11e8e2851de0e60659b20cf26c6986c24ad9 Mon Sep 17 00:00:00 2001 From: Abhisek Datta Date: Wed, 11 Mar 2026 11:04:05 +0530 Subject: [PATCH] docs: Update README (#182) * docs: Update README * docs: Update README --- README.md | 69 ++++++++++++++++++++----------------------------------- 1 file changed, 25 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 7750e3e..a8fe6d7 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,6 @@

Package Manager Guard (PMG)

-

Prevent supply chain attacks before they happen.

@@ -30,14 +29,24 @@ ## Why PMG? -Modern software development relies heavily on open-source packages. However, standard package managers (`npm`, `pip`, etc.) prioritize convenience over security, executing arbitrary code (like `postinstall` scripts) on your machine without validation. This vector is frequently exploited by attackers to steal credentials or inject backdoors. +AI coding agents install packages you didn't choose. Claude Code, Cursor, Copilot, Windsurf all run `npm install` and `pip install` autonomously, and you have no idea what they just put on your machine. -**PMG acts as a security middleware layer.** It wraps your package manager to: +PMG ensures every package is checked for malware before it executes, whether you picked it or an AI agent did. 1. **Analyze** packages for malware before they are installed. 2. **Sandbox** the installation process to prevent system modification. 3. **Audit** every package installation event. +Install PMG once, and every `npm install`, `pip install`, and `poetry add` is protected automatically. + +> Featured in [tl;dr sec](https://tldrsec.com/p/tldr-sec-316) and used by engineering teams worldwide to secure their software supply chain. + +## How PMG is Different + +Most security tools scan after installation and report vulnerabilities. By then, malicious code has already executed on your machine. + +PMG intercepts package managers **before** code executes, blocking malicious packages at install time, not flagging them after the damage is done. Detection is powered by [SafeDep's malicious package analysis engine](https://safedep.io). For defense in depth, PMG sandboxes the installation process using OS-native isolation, so even zero-day malware that evades detection cannot modify your system. + ## Quick Start Get protected in seconds. @@ -69,7 +78,7 @@ pmg setup install ### 3. Use -Continue using your favorite package manager tools as usual. PMG works silently in the background. +Use your package managers as usual — or let your AI coding agent use them. PMG works silently in the background. ```bash npm install express @@ -77,17 +86,21 @@ npm install express pip install requests ``` -If a malicious package is detected, PMG blocks it immediately: +When an AI agent (or you) tries to install a malicious package, PMG blocks it: ```text -[PMG] Blocked malicious package: malicious-lib@1.0.0 -[PMG] Reason: Known malware signature detected +✗ Malicious package blocked + + - safedep-test-pkg@1.0.0 + +✗ 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](https://docs.safedep.io/cloud/malware-analysis). | | **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. | @@ -156,48 +169,16 @@ Security is our first class requirement. PMG builds are reproducible and signed. * **Verification**: Users can cryptographically prove the binary matches the source code. * See [Trusting PMG](docs/trust.md) for verification steps. -## Usage Guide - -PMG runs transparently, but you can control it when needed. - -### Paranoid Mode - -Treat all unverified or suspicious packages as malicious. - -```bash -pmg --paranoid npm install -``` - -### Dry Run - -Simulate installation to check for malware without writing to disk. - -```bash -pmg --dry-run npm install -``` - -### Debugging - -Enable verbose logs for troubleshooting. - -```bash -pmg --debug npm install -``` - -### Emergency Bypass -> ⚠️ **Warning**: Bypassing security checks exposes users to risk. - -```bash -export PMG_INSECURE_INSTALLATION=true -npm install -``` - -## Advanced Documentation +## User Guide * [Trusted Packages Configuration](docs/trusted-packages.md) * [Proxy Mode Architecture](docs/proxy-mode.md) * [Sandboxing Details](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. + ## Contributing Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to build and test PMG locally.