From a651761636af42f934f4be04e7e628cc230c6401 Mon Sep 17 00:00:00 2001 From: Abhisek Datta Date: Tue, 26 May 2026 22:15:14 +0530 Subject: [PATCH] docs: Update README (#296) * docs: Update README * docs: Add diagram for how PMG works * docs: Updated featured docs * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Abhisek Datta * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Abhisek Datta * Update README.md Co-authored-by: Sahil Bansal Signed-off-by: Abhisek Datta --------- Signed-off-by: Abhisek Datta Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Sahil Bansal --- CONTRIBUTING.md | 76 ++++++++++----------------- README.md | 80 ++++++++++++++++++++++------- SECURITY.md | 5 ++ docs/assets/how-pmg-works-dark.svg | 52 +++++++++++++++++++ docs/assets/how-pmg-works-light.svg | 52 +++++++++++++++++++ 5 files changed, 196 insertions(+), 69 deletions(-) create mode 100644 SECURITY.md create mode 100644 docs/assets/how-pmg-works-dark.svg create mode 100644 docs/assets/how-pmg-works-light.svg diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 21be236..da9965e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,34 +1,18 @@ - # Contributing Guide -You can contribute to `pmg` and help make it better. Apart from bug fixes, -features, we particularly value contributions in the form of: +Thanks for your interest in improving `pmg`. Beyond bug fixes and features, we particularly value: - Documentation improvements - Bug reports -- Using `pmg` in your projects and providing feedback +- Using `pmg` in your projects and sharing feedback -## How to contribute +## Reporting a bug -1. Fork the repository -2. Add your changes -3. Submit a pull request +Open a new issue with the `bug` label. -## How to report a bug +## Suggesting a feature -Create a new issue and add the label `bug`. - -## How to suggest a new feature - -Create a new issue and add the label `enhancement`. - -## Development workflow - -When contributing changes to repository, follow these steps: - -1. Ensure tests are passing -2. Ensure you write test cases for new code -3. `Signed-off-by` line is required in commit message (use `-s` flag while committing) +Open a new issue with the `enhancement` label. ## Developer Setup @@ -38,49 +22,41 @@ When contributing changes to repository, follow these steps: - Git - Make -### Getting Started +### Getting started -1. Clone your fork: +Clone your fork and build: ```shell git clone https://github.com/YOUR_USERNAME/pmg.git cd pmg -``` - -2. Install dependencies: - -```shell go mod tidy -``` - -3. Build the project: - -```shell make all ``` -### Development Workflow +## Development Workflow 1. Create a branch: -```shell -git checkout -b feature/your-feature -``` + ```shell + git checkout -b feature/your-feature + ``` -2. Make your changes and test: +2. Make your changes. Add tests for new code. -```shell -make test -``` +3. Run the test suite: -3. Commit with sign-off: + ```shell + make test + ``` -```shell -git commit -s -m "feat: add new feature" -``` +4. Commit with a [DCO](https://developercertificate.org/) sign-off (the `-s` flag is required): -4. Push and create PR: + ```shell + git commit -s -m "feat: add new feature" + ``` -```shell -git push origin feature/your-feature -``` +5. Push and open a pull request: + + ```shell + git push origin feature/your-feature + ``` diff --git a/README.md b/README.md index f6384ad..82c7110 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ [![Docs](https://img.shields.io/badge/Docs-docs.safedep.io-2b9246?style=flat-square)](https://docs.safedep.io/pmg/quickstart) [![Website](https://img.shields.io/badge/Website-safedep.io-3b82f6?style=flat-square)](https://safedep.io) [![Discord](https://img.shields.io/discord/1090352019379851304?style=flat-square)](https://discord.gg/kAGEj25dCn) +[![Featured in tl;dr sec](https://img.shields.io/badge/Featured%20in-tl%3Bdr%20sec-FF6B35?style=flat-square)](https://tldrsec.com/p/tldr-sec-316) [![Go Report Card](https://goreportcard.com/badge/github.com/safedep/pmg)](https://goreportcard.com/report/github.com/safedep/pmg) ![License](https://img.shields.io/github/license/safedep/pmg) @@ -38,21 +39,45 @@ Recent compromises in popular ecosystems: - [**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. - -> Featured in [tl;dr sec](https://tldrsec.com/p/tldr-sec-316). +**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. Each install passes through the enabled protection layers before code runs, plus an audit trail after. +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. + +
+ + + 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 + +
+ +
+Layer details - **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 never reach disk. -- **Layer 2: Policy (Dependency Cooldown)** - PMG blocks package versions published inside a configurable cooldown window, so freshly compromised versions cannot land before the ecosystem has had time to flag them. -- **Layer 3: Optional 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. +- **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. +
+ +## 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 | 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 @@ -82,7 +107,16 @@ pmg setup doctor ### 3. Use -Run your package managers as usual, or let your AI coding agent run them. PMG sits in the path. +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 @@ -90,15 +124,6 @@ npm install express pip install requests ``` -## Features - -| Feature | Description | -| ------------------------ | ------------------------------------------------------------------------------------------------------------ | -| **AI Agent Safety Net** | Catches malicious packages installed by AI coding agents (Claude Code, Cursor, Copilot, Windsurf). | -| **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** | Integrates with Zsh, Bash, Fish, and more. | - ## Supported Package Managers PMG supports the tools you already use: @@ -219,19 +244,36 @@ PMG builds are reproducible and signed. ## User Guide +- [Configuration](docs/config.md) - [Trusted Packages Configuration](docs/trusted-packages.md) - [Dependency Cooldown](docs/dependency-cooldown.md) - [Proxy Mode Architecture](docs/proxy-mode.md) -- [Sandboxing Details](docs/sandbox.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 + + + + + + Star History Chart + + + ## Contributing Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for build and test instructions. +Thank you to all contributors ❤️ + + + Contributors to PMG + + ## Telemetry PMG collects anonymous usage data. To disable, either: diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..d660310 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,5 @@ +# Security Policy + +See SafeDep's organization-wide security policy for how to report vulnerabilities and our disclosure process: + +https://github.com/safedep/.github/blob/main/SECURITY.md diff --git a/docs/assets/how-pmg-works-dark.svg b/docs/assets/how-pmg-works-dark.svg new file mode 100644 index 0000000..dd531a8 --- /dev/null +++ b/docs/assets/how-pmg-works-dark.svg @@ -0,0 +1,52 @@ + + + + + + + + PMG Defense in Depth + + + Dev or AI agent + npm / pip install + + + + + PMG + Interception + + + + + Layer 1 + Threat Intel + block known malware + + + + + Layer 2 + Cooldown + block fresh versions + + + + + Layer 3 + Sandbox (opt-in) + restrict install scripts + + + + + Install runs + ✓ + + + + + Audit Log + what / when / from + diff --git a/docs/assets/how-pmg-works-light.svg b/docs/assets/how-pmg-works-light.svg new file mode 100644 index 0000000..121c040 --- /dev/null +++ b/docs/assets/how-pmg-works-light.svg @@ -0,0 +1,52 @@ + + + + + + + + PMG Defense in Depth + + + Dev or AI agent + npm / pip install + + + + + PMG + Interception + + + + + Layer 1 + Threat Intel + block known malware + + + + + Layer 2 + Cooldown + block fresh versions + + + + + Layer 3 + Sandbox (opt-in) + restrict install scripts + + + + + Install runs + ✓ + + + + + Audit Log + what / when / from +