diff --git a/.gitignore b/.gitignore index 3838ac1..2b5005c 100644 --- a/.gitignore +++ b/.gitignore @@ -26,3 +26,4 @@ bin/ .env dist/ +.DS_Store diff --git a/README.md b/README.md index 52e7758..7750e3e 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@

Package Manager Guard (PMG)

+

Prevent supply chain attacks before they happen.

@@ -21,283 +22,187 @@
+
+
-

- PMG protects developers from getting compromised by malicious packages.
- See example -

+ pmg in action
-
- -pmg in action +## Why PMG? -## Key Features +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. -- Wraps your favorite package manager (eg. `npm`, `pnpm`, `pip` and more) -- Blocks malicious packages at install time -- No configuration required, just install and use -- Maintains package installation event log for transparency and audit trail -- Enforces least privilege and defense in depth using OS native sandboxing +**PMG acts as a security middleware layer.** It wraps your package manager to: -PMG guarantees its own artifact integrity using GitHub and npm attestations. Users can cryptographically prove that the binary they run -matches the source code they reviewed, eliminating the risk of tampered or malicious builds. See [why and how to trust PMG](docs/trust.md). +1. **Analyze** packages for malware before they are installed. +2. **Sandbox** the installation process to prevent system modification. +3. **Audit** every package installation event. ## Quick Start -Install `pmg` using your favorite package manager: - -```shell -# MacOS/Linux with Homebrew -brew install safedep/tap/pmg - -# Other platforms -npm install -g @safedep/pmg -``` - -**Note**: More [installation options](#installation) are available. See [why and how to trust PMG](docs/trust.md). - -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: - -```shell -npm install -``` - -```shell -uv pip install -``` - -## Features - -- Malicious package identification using [SafeDep Cloud](https://docs.safedep.io/cloud/malware-analysis) with realtime threat detection -- Proxy based dependency analysis and resolution -- Fast and efficient package verification -- Defense in depth using OS native sandboxing -- 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` | ✅ | `pmg npm install ` | -| `pnpm` | ✅ | `pmg pnpm add ` | -| `bun` | ✅ | `pmg bun add ` | -| `yarn` | ✅ | `pmg yarn add ` | -| `pip` | ✅ | `pmg pip install ` | -| `uv` | ✅ | `pmg uv add ` or `pmg uv pip install ` | -| `poetry` | ✅ | `pmg poetry add ` | -| `npx` | ✅ | `pmg npx ` | -| `pnpx` | ✅ | `pmg pnpx ` | - -> Want us to support your favorite package manager? [Open an issue](https://github.com/safedep/pmg/issues) and let us know! +Get protected in seconds. -## Installation - -### Homebrew +### 1. Install -You can install `pmg` using `homebrew` in MacOS and Linux +**MacOS / Linux (Homebrew)** ```bash -brew tap safedep/tap brew install safedep/tap/pmg ``` -### Binaries - -Download the latest binary from the [releases page](https://github.com/safedep/pmg/releases). - -### Build from Source - -> Ensure $(go env GOPATH)/bin is in your $PATH +**NPM** ```bash -go install github.com/safedep/pmg@latest +npm install -g @safedep/pmg ``` -## Setup - -PMG provides built-in commands to automatically configure shell aliases for seamless integration: +> See [Installation](#installation) for additional methods. -### Install Aliases +### 2. Setup -Set up PMG to intercept package manager commands: +Configure your shell to use PMG automatically. ```bash pmg setup install +# Restart your terminal to apply changes ``` -
-Custom config directory +### 3. Use + +Continue using your favorite package manager tools as usual. PMG works silently in the background. ```bash -PMG_CONFIG_DIR=/path/to/config pmg setup install +npm install express +# or +pip install requests ``` -
-The setup command will: +If a malicious package is detected, PMG blocks it immediately: -- Create a `~/.pmg.rc` file containing package manager aliases -- Automatically add a source line to your shell configuration files -- Create a default config file. See [config template](config/config.template.yml) - -> **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 +```text +[PMG] Blocked malicious package: malicious-lib@1.0.0 +[PMG] Reason: Known malware signature detected +``` -To remove PMG aliases and restore original package manager behavior: +## Features -```bash -pmg setup remove -``` +| Feature | Description | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| **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. | +| **Event Logging** | Keeps a verifiable audit trail of all installed packages. | +| **Zero Config** | Works out of the box with sensible security defaults. | +| **Cross-Shell** | Seamlessly integrates with Zsh, Bash, Fish, and more. | -This will: +## Supported Package Managers -- Remove the source line from your shell configuration files -- Delete the `~/.pmg.rc` file +PMG supports the tools you already use: -> ⚠️ Note: Aliases might still be active in your **current terminal session**. Restart your terminal or use `unalias ` to remove them instantly. +| Ecosystem | Tools | Status | Command Example | +| ----------- | -------- | ------ | ------------------- | +| **Node.js** | `npm` | Yes | `npm install ` | +| | `pnpm` | Yes | `pnpm add ` | +| | `yarn` | Yes | `yarn add ` | +| | `bun` | Yes | `bun add ` | +| | `npx` | Yes | `npx ` | +| | `pnpx` | Yes | `pnpx ` | +| **Python** | `pip` | Yes | `pip install ` | +| | `poetry` | Yes | `poetry add ` | +| | `uv` | Yes | `uv add ` | -## Usage +## Installation
-Paranoid Mode - -Use the `--paranoid` flag to treat suspicous (unverified) packages as malicious packages. +Homebrew (MacOS/Linux) ```bash -pmg --paranoid npm install +brew tap safedep/tap +brew install safedep/tap/pmg ```
-Silent Mode - -Use the `--silent` flag to run PMG in silent mode: +NPM (Cross-Platform) ```bash -pmg --silent npm install +npm install -g @safedep/pmg ```
-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. +Go (Build from Source) ```bash -pmg --dry-run npm install +# Ensure $(go env GOPATH)/bin is in your $PATH +go install github.com/safedep/pmg@latest ```
-Verbose Mode +Binary Download -Use the `--verbose` flag to run PMG in verbose mode: +Download the latest binary for your platform from the [Releases Page](https://github.com/safedep/pmg/releases). +
-```bash -pmg --verbose npm install -``` +## Trust and Security - +Security is our first class requirement. PMG builds are reproducible and signed. -
-Debugging +* **Attestations**: GitHub and npm attestations are used to guarantee artifact integrity. +* **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 -Use the `--debug` flag to enable debug mode: +Treat all unverified or suspicious packages as malicious. ```bash -pmg --debug npm install +pmg --paranoid npm install ``` -Store the debug logs in a file: +### Dry Run + +Simulate installation to check for malware without writing to disk. ```bash -pmg --debug --log /tmp/debug.json npm install +pmg --dry-run npm install ``` -
+### Debugging -
-Insecure Installation +Enable verbose logs for troubleshooting. -Allows bypassing the blocking behavior when malicious packages are detected during installation. +```bash +pmg --debug npm install +``` -> ⚠️ **Warning**: This is a security feature bypass. Use with extreme caution and only when you understand the risks. +### Emergency Bypass +> ⚠️ **Warning**: Bypassing security checks exposes users to risk. ```bash export PMG_INSECURE_INSTALLATION=true -pmg npm install +npm install ``` -
- -## Advanced +## Advanced Documentation -- [Trusted Packages](docs/trusted-packages.md) -- [Proxy Mode](docs/proxy-mode.md) -- [Sandbox](docs/sandbox.md) +* [Trusted Packages Configuration](docs/trusted-packages.md) +* [Proxy Mode Architecture](docs/proxy-mode.md) +* [Sandboxing Details](docs/sandbox.md) ## Contributing -Refer to [CONTRIBUTING.md](CONTRIBUTING.md) - -## Limitations - -
-Private package artifacts inaccessible in non-proxy mode - -If `pmg` cannot retrieve private package artifacts (such as files or metadata), it cannot perform dependency tree analysis. This is a limitation of non-proxy mode, where `pmg` is responsible for resolving dependencies and is unable to resolve transitive dependencies for private (inaccessible) packages. - -This limitation does **not** apply when **Proxy Mode is enabled**. - -
- -
-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. - -
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to build and test PMG locally. ## 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`. - -```bash -export PMG_DISABLE_TELEMETRY=true -``` +PMG collects anonymous usage data to improve project stability and reliability. +To disable: `export PMG_DISABLE_TELEMETRY=true`.