docs: Update README (#97)

* docs: Update README * docs: Update README
2026-08-03 07:24:09 +02:00 · 2026-01-07 18:54:18 +00:00
parent 1c319eba0e
commit 0603df8c25
1 changed files with 47 additions and 120 deletions
@@ -13,23 +13,26 @@
 🤖 PMG protects developers from getting compromised by malicious packages.
 See [example](https://safedep.io/malicious-npm-package-express-cookie-parser/)

-   Wraps your favorite package manager (eg. `npm`)
-   Blocks malicious packages at install time
-   No configuration required, just install and use
+- 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

-## 🔥 PMG in Action
+## PMG in Action

 <img src="./docs/assets/pmg-intro.png" width="600" alt="pmg in action">

-## 📦 TL;DR
+## TL;DR

-Install `pmg`
+Install `pmg` using Homebrew:

 ```shell
 brew install safedep/tap/pmg
 ```

-Set up `pmg` to protect you development environment from malicious packages:
+**Note**: More [installation options](#installation) are available.
+
+Set up `pmg` to protect your development environment from malicious packages:

 ```
 pmg setup install
@@ -45,43 +48,14 @@ npm install <package-name>
 uv pip install <package-name>
 ```

-## 📑 Table of Contents
+## Features

- [Package Manager Guard (PMG)](#package-manager-guard-pmg)
-  - [🔥 PMG in Action](#-pmg-in-action)
-  - [📦 TL;DR](#-tldr)
-  - [📑 Table of Contents](#-table-of-contents)
-  - [🔥 Features](#-features)
-  - [Supported Package Managers](#supported-package-managers)
-  - [Installation](#installation)
-    - [Homebrew](#homebrew)
-    - [Binaries](#binaries)
-    - [Build from Source](#build-from-source)
-  - [Setup](#setup)
-    - [Install Aliases](#install-aliases)
-    - [Remove Aliases](#remove-aliases)
-  - [Usage](#usage)
-    - [Recommended: Automated Setup](#recommended-automated-setup)
-    - [Alternative: Manual Commands](#alternative-manual-commands)
-    - [Lockfile Installation](#lockfile-installation)
-    - [Active Scanning](#active-scanning)
-    - [Silent Mode](#silent-mode)
-    - [Dry Run](#dry-run)
-    - [Verbose Mode](#verbose-mode)
-    - [Debugging](#debugging)
-  - [Environment Variables](#environment-variables)
-    - [PMG\_INSECURE\_INSTALLATION](#pmg_insecure_installation)
-  - [🤝 Contributing](#-contributing)
-  - [🚫 Limitations](#-limitations)
-  - [Telemetry](#telemetry)
-
-## 🔥 Features
-
-   🚫 Malicious package identification using [SafeDep Cloud](https://docs.safedep.io/cloud/malware-analysis)
-   🌲 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
+- Malicious package identification using [SafeDep Cloud](https://docs.safedep.io/cloud/malware-analysis) with realtime threat detection
+- 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
+- Package installation tracking and event logging

 ## Supported Package Managers

@@ -136,9 +110,9 @@ 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
+- 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.

@@ -152,77 +126,15 @@ pmg setup remove

 This will:

-   Remove the source line from your shell configuration files
-   Delete the ~/.pmg.rc file
+- 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:
-
-```bash
-pmg setup install
-```
-
-After setup, use your package managers normally:
-
-```bash
-npm install <package-name>
-pnpm add <package-name>
-bun add <package-name>
-yarn 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:
-
-```bash
-pmg npm install <package-name>
-pmg pnpm add <package-name>
-pmg bun add <package-name>
-pmg yarn 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:
-
-```bash
-npm install          # Uses package-lock.json
-pnpm install         # Uses pnpm-lock.yaml
-bun install          # Uses bun.lock
-yarn install         # Uses yarn.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
+<details>
+<summary>Active Scanning</summary>

 Use the `--paranoid` flag to perform active malware scanning on unknown packages (requires [SafeDep Cloud credentials](https://docs.safedep.io/cloud/authentication#api-key-authentication)):

@@ -230,7 +142,10 @@ Use the `--paranoid` flag to perform active malware scanning on unknown packages
 pmg --paranoid npm install <package-name>
 ```

-### Silent Mode
+</details>
+
+<details>
+<summary>Silent Mode</summary>

 Use the `--silent` flag to run PMG in silent mode:

@@ -238,7 +153,10 @@ Use the `--silent` flag to run PMG in silent mode:
 pmg --silent npm install <package-name>
 ```

-### Dry Run
+</details>
+
+<details>
+<summary>Dry Run</summary>

 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.
@@ -247,7 +165,10 @@ package manager commands. Useful for checking packages and their transitive depe
 pmg --dry-run npm install <package-name>
 ```

-### Verbose Mode
+</details>
+
+<details>
+<summary>Verbose Mode</summary>

 Use the `--verbose` flag to run PMG in verbose mode:

@@ -255,7 +176,10 @@ Use the `--verbose` flag to run PMG in verbose mode:
 pmg --verbose npm install <package-name>
 ```

-### Debugging
+</details>
+
+<details>
+<summary>Debugging</summary>

 Use the `--debug` flag to enable debug mode:

@@ -269,9 +193,10 @@ Store the debug logs in a file:
 pmg --debug --log /tmp/debug.json npm install <package-name>
 ```

-## Environment Variables
+</details>

-### PMG_INSECURE_INSTALLATION
+<details>
+<summary>Insecure Installation</summary>

 Allows bypassing the blocking behavior when malicious packages are detected during installation.

@@ -282,11 +207,13 @@ export PMG_INSECURE_INSTALLATION=true
 pmg npm install <package-name>
 ```

-## 🤝 Contributing
+</details>
+
+## Contributing

 Refer to [CONTRIBUTING.md](CONTRIBUTING.md)

-## 🚫 Limitations
+## Limitations

 <details>
 <summary>Approximate dependency version resolution</summary>