Metadata-Version: 2.4
Name: pkg-defender
Version: 1.0.6
Summary: Stop supply chain attacks before they reach your machine or CI pipeline
Project-URL: Homepage, https://github.com/divisionseven/pkg-defender
Project-URL: Repository, https://github.com/divisionseven/pkg-defender
Project-URL: Funding, https://buymeacoffee.com/divisionseven
Project-URL: Documentation, https://github.com/divisionseven/pkg-defender/blob/main/docs/index.md
Project-URL: Bug Tracker, https://github.com/divisionseven/pkg-defender/issues
Project-URL: Changelog, https://github.com/divisionseven/pkg-defender/blob/main/CHANGELOG.md
Author: divisionseven
Maintainer: divisionseven
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cargo,npm,pypi,security,supply-chain-attack,threat-intelligence
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: aiohttp<4.0,>=3.14.1
Requires-Dist: click<9.0,>=8.4
Requires-Dist: defusedxml<1.0,>=0.7
Requires-Dist: feedparser<7.0,>=6.0
Requires-Dist: idna>=3.15
Requires-Dist: packaging<24.0,>=23.0
Requires-Dist: platformdirs<5.0,>=4.0
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: rich<14.0,>=13.0
Requires-Dist: tomlkit>=0.15.0
Requires-Dist: zstandard<1.0,>=0.22
Provides-Extra: fuzz
Requires-Dist: atheris>=2.3.0; extra == 'fuzz'
Provides-Extra: lint
Requires-Dist: mypy>=1.9; extra == 'lint'
Requires-Dist: pre-commit>=4.0; extra == 'lint'
Requires-Dist: ruff>=0.4; extra == 'lint'
Requires-Dist: types-defusedxml>=0.7; extra == 'lint'
Requires-Dist: types-python-dateutil>=2.9; extra == 'lint'
Provides-Extra: test
Requires-Dist: aioresponses>=0.7.9; extra == 'test'
Requires-Dist: coverage[toml]>=7.0; extra == 'test'
Requires-Dist: hypothesis>=6.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
Requires-Dist: pytest-cov>=7.1.0; extra == 'test'
Requires-Dist: pytest-mock>=3.15.1; extra == 'test'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/divisionseven/pkg-defender/main/docs/assets/brand/logo/pkgd_logo_transparent.svg">
    <img src="https://raw.githubusercontent.com/divisionseven/pkg-defender/main/docs/assets/brand/logo/pkgd_logo_light_mode.svg" alt="PKG-Defender Logo" width="500">
  </picture>

# PKG-Defender (PKGD)

### Stop supply chain attacks *before* they reach your machine or CI pipeline

[![Release][github-binary-releases-badge]][github-binary-releases-link]
[![Snapshot][github-snapshot-releases-badge]][github-snapshot-releases-link]
[![License][license-badge-icon]][license-badge-link]
[![Python][python-badge-icon]][pypi-badge-link]
[![Downloads][pypi-downloads-badge-icon]][pypi-badge-link]
[![Codecov][codecov-badge-icon]][codecov-badge-link]
[![Build][ci-badge-icon]][ci-badge-link]

[![Languages][language-pkgs-badge-icon]][ecosystems-badge-link]
[![Systems][system-pkgs-badge-icon]][ecosystems-badge-link]
[![OpenSSF Best Practices][ossf-bp-badge-icon]][ossf-bp-badge-link]
[![OpenSSF Scorecard][scorecard-badge-icon]][scorecard-badge-link]

</div>

## Highlights

> ***The supply chain attack defense CLI — Cooldown gates, multi-source threat
> intelligence, command wrappers, CI/CD interception, and lock file dependency
> auditing for all major package managers.***

- **Unified Command Wrapper**: `pkgd [OPTIONS] MANAGER SUBCOMMAND [PACKAGE...] [MANAGER_OPTIONS...]`
  - Wrap any [supported][supported-commands] *"dangerous"* package manager
    command (`pkgd pip install requests`, `pkgd npm install express`,
    `pkgd brew upgrade tree`, etc.)
  - *"Dangerous Commands"* are defined as any package manager command that has
    the potential to put software **on** your machine (`install`, `update`,
    `download`, `add`, `sync`, etc.)
- **Auto-Detect Manager**: automatically detects package manager from project
  files or system packages
- **Version Detection**: `get_installed_version()` for all 18 package managers
  across 10 ecosystems enables version comparison
- **Fail-Closed Security**: any failure blocks installation with warning and
  options for informed manual override
- **Alternative PM Coverage**: `python -m pip`, `pipx`, `yarn`, `pnpm` and other
  alt manager calls all [supported][supported-commands]
- **Cooldown Gates**: configurable time-since-release hold window with
  per-package, tracked and auditable overrides (ships with a default of 7
  days)
- **Multi-source Threat Intelligence**: OSV.dev, GHSA, Socket.dev, npm
  advisories, and more all synced and stored locally (with automatic staleness
  detection)
- **Social Intelligence Feeds**: Mastodon, Reddit, RSS, X/Twitter - free sources
  shipped / B.Y.O.K. options available (informational only — non-blocking)
- **Lock File Auditing**: all major formats: `package-lock.json`, `poetry.lock`,
  `requirements.txt`, `yarn.lock`, `pnpm-lock.yaml`, `uv.lock`, `Pipfile.lock`
  ([currently supported formats][targeted-managers])
- **Background Daemon**: automated background intelligence feed sync with
  OS-native launchd / systemd / Task Scheduler
- **CI/CD Integration**: `--fail-on-threat` exits on CRITICAL/HIGH for secure
  pipeline gating

[See Full Documentation Index &rarr;][docs-index]

## Why It Exists

The **overwhelming** frequency of recent supply chain attacks have shown how quickly
malicious packages can spread. The threat landscape has **changed significantly**.
Four of the most significant open-source supply chain attacks ever recorded all
happened within the last few months of writing:

- **[TanStack Router][tanstack-attack]** (*May 2026*): A self-propagating worm
  compromised 42 `@tanstack/*` packages and spread to 160+ others across npm and
  PyPI. The malicious versions carried *valid SLSA Build Level 3 provenance
  attestations*, meaning the supply chain controls that the industry spent years
  building offered zero protection.
- **[Axios][axios-attack]** (*March 2026*): A North Korea-linked threat actor
  compromised the lead maintainer's account of the most popular JavaScript HTTP
  client (~100M weekly downloads) and published a cross-platform RAT targeting
  macOS, Windows, and Linux. The poisoned versions were live for under 3 hours.
  Thousands of installs happened anyway.
- **[LiteLLM][litellm-attack]** (*March 2026*): Using tokens stolen via the
  Trivy compromise, attackers published backdoored releases of a widely-deployed
  AI gateway (~95M monthly downloads). The payload ran a three-stage attack:
  harvest SSH keys, AWS/GCP/Azure credentials, and Kubernetes secrets → move
  laterally across clusters → install a persistent systemd backdoor.
- **[Trivy][trivy-attack]** (*March 2026*): The world's most popular container
  security scanner was weaponized. Attackers spoofed maintainer commits, pushed
  a malicious release, and used Trivy's own CI/CD runner access to steal
  publishing tokens from every downstream project that scanned with it — kicking
  off a cascade of follow-on attacks.

These incidents succeed because fresh packages are often installed based on
trust alone. PKG-Defender adds a practical and secure defense layer: **local
threat intelligence** and **dependency auditing** combined with a configurable
**cooldown window** to catch the latest threats *before* they land on your
machine, your dependency tree, or your production pipelines.

## Installation

[![Platforms][platforms-badge-icon]][github-binary-releases-link]

### From PyPI

```bash
# Recommended with uv
uv pip install pkg-defender

# Alternative with pip
pip install pkg-defender
```

### From Homebrew (macOS/Linux)

```bash
brew tap divisionseven/pkg-defender
brew install pkg-defender
```
**Tap Trust (Homebrew 6.0.0+)**

As of Homebrew 6.0.0, brew's automatic trust evaluation requires explicit
trust confirmation for taps. If needed, users may be prompted to run:

```bash
brew trust divisionseven/pkg-defender
```

> [!TIP]
> The tap formula is available at the `homebrew-pkg-defender` repository.
> [View Tap &rarr;](https://github.com/divisionseven/homebrew-pkg-defender)

### From Binary (macOS/Linux/Windows)

Pre-built standalone binaries are attached to every
[GitHub Release](https://github.com/divisionseven/pkg-defender/releases):

- **macOS (arm64):** `pkgd-darwin-arm64`
- **macOS (x86_64):** `pkgd-darwin-amd64`
- **Linux (x86_64):** `pkgd-linux-amd64`
- **Windows (x86_64):** `pkgd-windows-amd64.exe`

Each binary has a matching `.sha256` checksum file. Download, verify, and run:

```bash
# Example for macOS arm64
curl -LO https://github.com/divisionseven/pkg-defender/releases/latest/download/pkgd-darwin-arm64
curl -LO https://github.com/divisionseven/pkg-defender/releases/latest/download/pkgd-darwin-arm64.sha256
shasum -a 256 -c pkgd-darwin-arm64.sha256
chmod +x pkgd-darwin-arm64
./pkgd-darwin-arm64 --help
```

### From Source

```bash
git clone https://github.com/divisionseven/pkg-defender
cd pkg-defender

# Using uv (recommended)
uv sync --dev

# Using pip
pip install -e ".[test,lint]"
```

[See Full Installation Guide &rarr;][install-guide]

## Quick Start

```bash
# Simple setup wizard to configure settings,
# add optional secrets, sync intelligence feeds
pkgd setup

# Start the background daemon to keep your threat intel
# feeds up to date 24/7 (optional)
pkgd daemon start

# Use the command wrapper pattern to intercept supported commands:
pkgd pip install requests
pkgd npm install express
pkgd brew install tree
# ...and so on
```

<div align="center">
  <a href="https://raw.githubusercontent.com/divisionseven/pkg-defender/main/docs/assets/demo/1-0-5/1280x720_25fps/pkgd_pip_install-1.0.5.gif">
    <img src="https://raw.githubusercontent.com/divisionseven/pkg-defender/main/docs/assets/demo/1-0-5/1280x720_25fps/pkgd_pip_install-1.0.5.gif" alt="pkgd pip install demo" width="auto">
  </a>
  <p><em>Wrap dangerous package manager commands to seamlessly check for threats before every install</em></p>
</div>

[See Full Quick Start Guide &rarr;][quick-start]

### CI/CD Usage

[![PKGD Github Action Release][pkgd-action-release-badge-icon]][pkgd-action-release-badge-link]
[![PKGD Action CI][pkgd-action-ci-badge-icon]][pkgd-action-ci-badge-link]
[![PKGD Snapshot Build][snapshot-action-badge-icon]][snapshot-action-badge-link]

PKG-Defender integrates into automated pipelines via non-interactive CI mode:

```bash
# Use --ci flag to skip all prompts
pkgd --ci pip install axios

# Or set the environment variable
export PKGD_CI=1
pkgd pip install axios
```

CI mode is auto-detected in many CI environments — see the [full CI/CD guide](docs/guides/ci-cd.md) for details.

#### GitHub Action

The [pkg-defender-action](https://github.com/divisionseven/pkg-defender-action)
is the easiest way to add threat auditing to GitHub Actions workflows. It's a
thin wrapper that installs `pkgd`, discovers lock files, and runs the audit.

**Inputs:**

| Input        | Default                               | Description                                                                                                   |
| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `fail-on`    | `high`                                | Minimum severity to fail: `critical`, `high`, `medium`, `low`, `none`. CRITICAL and HIGH trigger exit code 4. |
| `lock-files` | `**/package-lock.json,**/yarn.lock,…` | Glob pattern for lock files to scan (default covers all 7 supported formats).                                 |

**Outputs:**

| Output      | Description                                                          |
| ----------- | -------------------------------------------------------------------- |
| `findings`  | JSON array of threats with package, version, ecosystem, and severity |
| `summary`   | Human-readable summary (e.g., "3 threats found: 1 CRITICAL, 2 HIGH") |
| `exit-code` | Exit code from `pkgd audit` (0 = pass, 4 = threat detected)          |

**Minimal usage:**

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: divisionseven/pkg-defender-action@v1
```

**With custom threshold and lock file filter:**

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: divisionseven/pkg-defender-action@v1
    with:
      fail-on: critical
      lock-files: "**/package-lock.json"
```

The action passes `--fail-on-threat` to `pkgd audit` when `fail-on` is
`critical` or `high`. For `medium`, `low`, or `none`, the audit runs
informational-only (exit always 0).

[See PKGD Action Repository &rarr;](https://github.com/divisionseven/pkg-defender-action)

#### Manual CI Setup (all CI platforms)

For non-GitHub CI platforms (GitLab CI, Azure Pipelines, Jenkins, CircleCI,
etc.) or when you need full control over the install, use `pkgd` directly.

The CLI offers two approaches to prepare the threat database:

| Approach         | Command                       | Time    | Freshness    | Best for                           |
| ---------------- | ----------------------------- | ------- | ------------ | ---------------------------------- |
| **Fast path**    | `pkgd db snapshot --download` | ~5–10s  | Up to 6h old | Frequent CI runs, cache-friendly   |
| **Current path** | `pkgd intel sync`             | ~30–60s | Always fresh | One-off audits, post-deploy checks |

```bash
# Fast path: download pre-built snapshot (cacheable)
pkgd db snapshot --download
pkgd audit --fail-on-threat --output json

# Current path: sync from all threat feeds (always fresh)
pkgd intel sync
pkgd audit --fail-on-threat --output json
```

Use the fast path for routine PR checks where ~6-hour-old threat data is
acceptable. Use the current path for release gates or post-deployment
verification where the absolute latest intelligence matters.

For local development, `pkgd` can also be used as a [pre-commit hook](docs/guides/ci-cd.md#pre-commit-hook).

#### How Snapshots Work

A *"snapshot"* is a pre-built threat intelligence database published to
[GitHub Releases: `snapshot-latest`](https://github.com/divisionseven/pkg-defender/releases/tag/snapshot-latest)
every 6 hours. It contains known threats from our Tier 1 feeds — **OSV.dev**,
**GitHub Security Advisories (GHSA)**, and **OSSF Malicious Packages** —
covering npm, PyPI, Cargo, RubyGems, Go, Maven, NuGet, and Packagist.

**Safety guarantees:**

- **SHA256 verification** — Every snapshot ships with a `.sha256` checksum
  file; `pkgd db snapshot --download` verifies the hash before use
- **Integrity check** — The snapshot CI pipeline runs `PRAGMA integrity_check`
  on the database before publishing
- **Anomaly detection** — Record count is compared against the previous build;
  suspicious inflation (>5x) or drops (<0.01x) abort the publish

The snapshot is built by a scheduled GitHub Actions workflow
(`.github/workflows/snapshot.yml`, cron `0 */6 * * *`) that runs
`scripts/build_snapshot.py`. The result is an always-available download
that's safe to use in automated pipelines.

#### How Everything Works Together

The CI/CD integration has three layers:

1. **Threat intelligence feeds → Snapshot builder** — Tier 1 feeds (OSV, GHSA,
   OSSF) are synced every 6 hours by a scheduled GitHub Actions workflow
   (`scripts/build_snapshot.py`), producing a compressed, verified SQLite
   database published to GitHub Releases.
2. **CI pipeline** — The GitHub Action runs `pkgd --ci setup` (writes config,
   initializes the database, and syncs all feeds). The manual CLI can also
   download a pre-built snapshot with SHA256 verification via
   `pkgd db snapshot --download`.
3. **pkgd CLI → Audit results** — The CLI scans discovered lock files against
   the local database, produces JSON or rich output, and exits with code 4 if
   threats exceed the `--fail-on-threat` threshold.

```
┌─────────────────────────────────────────────────────────────────┐
│                     CI/CD USAGE ARCHITECTURE                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  PATH A: divisionseven/pkg-defender-action@v1                   │
│      │                                                          │
│      ├──▶ read inputs (fail-on, lock-files)                     │
│      │                                                          │
│      ├──▶ pip install pkg-defender                              │
│      │                                                          │
│      ├──▶ pkgd --ci setup                                       │
│      │        │                                                 │
│      │        ├──▶ write config file                            │
│      │        ├──▶ initialize threat DB                         │
│      │        └──▶ intel_sync -- ALL 9 feeds, LIVE              │
│      │                  (snapshot release not used)             │
│      │                                                          │
│      ├──▶ glob lock files                                       │
│      │        └──▶ none found? exit 0 (empty findings)          │
│      │                                                          │
│      ├──▶ for each lock file:                                   │
│      │        └──▶ pkgd --ci audit <file> --json                │
│      │                  [--fail-on-threat if high/critical]     │
│      │                  └──▶ merge findings into one array      │
│      │                                                          │
│      ├──▶ set outputs (findings, summary, exit-code)            │
│      │                                                          │
│      └──▶ any non-zero evit code? ──▶ core.setFailed()          │
│                                                                 │
│ ······························································· │
│                                                                 │
│  PATH B: pkgd CLI (compatible with any CI platform)             │
│      │                                                          │
│      ├──▶ SNAPSHOT PATH (~5-10s, cacheable)                     │
│      │        └──▶ pkgd db snapshot --download                  │
│      │                  ├──▶ fetch db.gz + .sha256              │
│      │                  └──▶ verify SHA256 (64KB chunks)        │
│      │                            ├──▶ FAIL: return False       │
│      │                            └──▶ MATCH: atomic DB swap    │
│      │                                                          │
│      ├──▶ FEED SYNC PATH (~30-60s, always fresh)                │
│      │        └──▶ pkgd intel sync -- ALL 9 feeds, LIVE         │
│      │                                                          │
│      └──▶ pkgd audit --fail-on-threat                           │
│                ├──▶ CRITICAL/HIGH found? exit 4                 │
│                └──▶ clean? exit 0                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
         │                                             ▲
         │          GitHub Snapshot Releases           │
         │      ┌───────────────────────────────┐      │
         └─────▶│  threats-latest.db.gz         │──────┘
                │  threats-latest.db.gz.sha256  │
                └───────────────────────────────┘
                                ▲
             Published          │    Fetched
             every 6 hours      │    only by PATH B
             (GitHub Actions)   │    (fastest path)
                                │

       ⚠  PATH A never reaches this release — it always
          live-syncs all 9 feeds directly for latest data

┌─────────────────────────────────────────────────────────────────┐
│                  SNAPSHOT BUILD & DISTRIBUTION                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ GH Action cron: "0 */6 * * *"  (always running, independent)    │
│     │                                                           │
│     └──▶ build_snapshot.py                                      │
│               │                                                 │
│               ├──▶ fetch Tier 1 feeds                           │
│               │        ├──▶ OSV.dev        (7 ecosystems)       │
│               │        ├──▶ GHSA           (last 365 days)      │
│               │        └──▶ OSSF Malicious Packages             │
│               │                                                 │
│               ├──▶ run safety checks (ALL must pass)            │
│               │        ├──▶ F1  integrity_check == "ok"         │
│               │        ├──▶ F3  >= 3 ecosystems have data       │
│               │        └──▶ F2  count within 0.01x-5x prior     │
│               │                                                 │
│               └──▶ gzip + sha256sum ──▶ publish                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

*Fig 1: End-to-end data flow from threat feeds through snapshot distribution to CI pipeline audit.*

#### Environment Variables

| Variable                    | Description                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| `PKGD_CI`                   | Enable non-interactive CI mode (`1` to enable)                                             |
| `PKGD_GITHUB_TOKEN`         | GHSA API token for higher rate limits; alternatively set `feeds.ghsa_token` in `pkgd.toml` |
| `PKGD_FEEDS_SOCKET_API_KEY` | Socket.dev API key for real-time threat signals                                            |
| `PKGD_DATABASE_PATH`        | Custom path for the threat database (overrides default data directory)                     |
| `PKGD_CONFIG_FILE`          | Alternative name for `PKGD_CONFIG_PATH` — path to config file override                     |

[See Full CI/CD Guide &rarr;][ci-cd-guide]

## How It Works

1. **Intercept** — Command wrappers (`pkgd pip install`, `pkgd npm install`)
   wrap package manager commands across 18 package managers in 10 ecosystems.
2. **Check** — `check_package()` queries the local SQLite threat database (zero
   network I/O).
3. **Inform** — social intelligence feeds add community-sourced early warnings
   (never blocks).
4. **Cooldown** — Package age is checked against the configured window (default:
   7 days).
5. **Decide** — Threats scoring ≥ 0.3 are blocked; social feed findings are
   informational only.
6. **Sync** — Background daemon periodically refreshes threat intelligence from
   9 feeds.

[See Full Threat Scoring Concepts &rarr;][threat-scoring]

### Threat Intelligence

PKG-Defender syncs from 9 feeds: 6 structured (OSV.dev, GHSA, npm advisory,
OSSF Malicious Package List, RSS, Homebrew) and 3 social (Mastodon, Reddit,
X/Twitter). Socket.dev is also available as a point-query source (not bulk
sync). Structured feeds can block installs; social feeds are informational only.
Feeds sync on configurable intervals with staleness detection.

<div align="center">
  <a href="https://raw.githubusercontent.com/divisionseven/pkg-defender/main/docs/assets/demo/1-0-5/1280x720_25fps/pkgd_intel_report-1.0.5.gif">
    <img src="https://raw.githubusercontent.com/divisionseven/pkg-defender/main/docs/assets/demo/1-0-5/1280x720_25fps/pkgd_intel_report-1.0.5.gif" alt="pkgd intel report demo" width="auto">
  </a>
  <p><em>Sync and query the latest threat intelligence data</em></p>
</div>

[See Full Threat Feed Guide &rarr;][threat-feeds]

### Auditing

Scan 7 lock file formats for known threats and cooldown-pending packages. Output
in rich terminal, JSON, or CSV. Use `--fail-on-threat` for CI/CD pipeline gating
(exits 4 on CRITICAL/HIGH only).

<div align="center">
  <a href="https://raw.githubusercontent.com/divisionseven/pkg-defender/main/docs/assets/demo/1-0-5/1280x720_25fps/pkgd_audit-1.0.5.gif">
    <img src="https://raw.githubusercontent.com/divisionseven/pkg-defender/main/docs/assets/demo/1-0-5/1280x720_25fps/pkgd_audit-1.0.5.gif" alt="pkgd audit scanning demo" width="auto">
  </a>
  <p><em>Audit project lock files and get threat reports in rich, JSON, or CSV formats</em></p>
</div>

[See Full Auditing Guide &rarr;][auditing-guide]

### Tab Completion

Automatic tab completion for `pkgd` commands in bash, zsh, and fish. Generated
via `pkgd completion generate`.

> [!NOTE]
> PowerShell and Nushell are accepted as CLI arguments for consistency
> with other shell commands, but Click's built-in completion only supports bash,
> zsh, and fish natively. Custom completion scripts for PowerShell/Nushell will
> be added in a future release if demand is proven.

```sh
# Bash (one of):
pkgd completion generate bash > /etc/bash_completion.d/pkgd  # system-wide
pkgd completion generate bash > ~/.local/share/bash-completion/completions/pkgd  # user

# Zsh
pkgd completion generate zsh > ~/.zsh/completions/_pkgd

# Fish
pkgd completion generate fish | source
```

Restart your shell after installation to enable completion.

[See Full Tab Completion Guide &rarr;][completion-guide]

## Configuration

### Config Loading Order

Configuration is loaded in this order (later sources override earlier):

   1. [Built-In Defaults][config-ref]
   2. System Config (`/etc/pkgd/pkgd.toml`) — loaded first, can be overridden
   3. User Config (`~/.config/pkg-defender/pkgd.toml`, platform equivalent) — overrides system
   4. Project Config (`./pkgd.toml` or nearest parent) — highest file priority
   5. `PKGD_CONFIG_PATH` environment variable — only consulted if `config_path param` is `None`
   6. `PKGD_*` environment variable overrides — highest priority, always applied

### Config TOML File

Default *global* config file with all values — automatically generated during `pkgd setup` for
effortless customization. Generated at *project-level* with `cd path/to/project && pkgd setup --init`

```toml
[cooldown]

# Minimum age in days before a new package version is allowed.
# Default: 7
default_days = 7

# Whether cooldown checking is active. Set false to disable entirely.
# Default: True
enabled = true

# If True, audit exits non-zero when threats are found during cooldown enforcement.
# If False, audit exits zero even with threats (weakened security posture).
# Default: True
strict_mode = true

# If True, a reason must be provided when bypassing the cooldown.
# Default: True
bypass_require_reason = true

# Number of days to retain bypass audit log entries.
# Note: Displayed in config listings only — no auto-prune enforcement code.
# Default: 90
bypass_log_retention_days = 90

[cooldown.overrides]
# Per-package cooldown days override (package name → days).
# Package names must be quoted to avoid TOML parsing errors.
# Examples:
#   "react" = 14
#   "@babel/core" = 21
#   "some-package" = 7

[cooldown.per_ecosystem]
# Per-ecosystem cooldown window overrides (ecosystem → days).
# Examples:
#   npm = 7
#   pypi = 14

# …continued
```

[See Complete Default Config TOML File &rarr;][pkgd-config-toml-ref]

[See Full Configuration Reference Guide &rarr;][config-ref]

## Command Reference

| Base Command Group       | Description                                               |
| ------------------------ | --------------------------------------------------------- |
| `pkgd audit`             | Scan lock files for threats and cooldown-pending packages |
| `pkgd status`            | Show recent threats, bypasses, and feed state             |
| `pkgd bypass`            | Create bypass for a blocked package                       |
| `pkgd health`            | Check system health                                       |
| `pkgd reset`             | Reset all data (database, config, feeds)                  |
| `pkgd setup`             | Interactive first-run setup wizard                        |
| `pkgd audit-logs`        | Query and manage audit event logs                         |
| `pkgd logs`              | View and manage pkg-defender logs                         |
| `pkgd completion`        | Generate shell completion scripts                         |
| `pkgd hooks`             | Generate shell functions for wrapped manager commands     |
| `pkgd intel sync`        | Sync all threat intelligence feeds                        |
| `pkgd intel search`      | Search local threat database                              |
| `pkgd intel report`      | Threat intelligence dashboard                             |
| `pkgd config view`       | Display current configuration                             |
| `pkgd config list`       | List all configuration values with sources                |
| `pkgd config set`        | Set a config value (dot notation)                         |
| `pkgd config set-secret` | Set a secret configuration value with hidden input        |
| `pkgd config get`        | Get a specific configuration value                        |
| `pkgd config reset`      | Reset to defaults                                         |
| `pkgd config options`    | List all configurable options with descriptions           |
| `pkgd daemon`            | Background daemon for periodic sync                       |
| `pkgd db snapshot`       | Download/verify database snapshots                        |
| `pkgd db verify`         | Verify local database integrity and report summary        |

### Global Flags

These flags apply to every `pkgd` command:

| Flag(s)                     | Description                                              |
| --------------------------- | -------------------------------------------------------- |
| `--version`, `-V`           | Show version information                                 |
| `--help`                    | Show help message and exit                               |
| `--config`, `-c`            | Path to configuration file (default: platform-dependent) |
| `--quiet`, `-q`             | Suppress all non-error output                            |
| `--verbose`, `-v`           | Increase verbosity (`-v`=INFO, `-vv`=DEBUG)              |
| `--no-verbose`              | Disable verbose output (overrides `PKGD_OUTPUT_VERBOSE`) |
| `--debug`, `-d`             | Show full tracebacks for unexpected errors               |
| `--no-color`                | Disable colored terminal output                          |
| `--ascii`                   | Force ASCII-only output (useful on Windows or CI)        |
| `--yes`, `-y`               | Auto-confirm all prompts                                 |
| `--force`, `-f`             | Force operations (skip confirmations, overwrite files)   |
| `--dry-run`, `-n`           | Show what would happen without making changes            |
| `--ci`, `--non-interactive` | Run in non-interactive CI/CD mode (reads `PKGD_CI`)      |
| `--explain`                 | Show detailed explanation of why packages were blocked   |
| `--json`                    | Output results as JSON                                   |

### Command-Specific Flags

| Command                 | Flag(s)                  | Description                                                                    |
| ----------------------- | ------------------------ | ------------------------------------------------------------------------------ |
| `pkgd audit`            | `--deep`, `-d`           | Perform deep scan (include cooldown status checks)                             |
| `pkgd audit`            | `--fail-on-threat`, `-f` | Exit with code 4 if CRITICAL or HIGH threats detected (CI/CD)                  |
| `pkgd audit`            | `--since`                | Only flag threats seen within duration (e.g., `7d`, `24h`)                     |
| `pkgd audit`            | `--output`, `-o`         | Output format: `rich`, `json`, `csv` (default: `rich`)                         |
| `pkgd status`           | `--feeds`                | Show per-feed health status                                                    |
| `pkgd health`           | `--output`, `-o`         | Output format: `rich`, `json` (default: `rich`)                                |
| `pkgd setup`            | `--init`, `-i`           | Create `pkgd.toml` with defaults                                               |
| `pkgd setup`            | `--shell`, `-s`          | Override auto-detected shell                                                   |
| `pkgd bypass`           | `--manager`, `-m`        | Package manager (default: `npm`)                                               |
| `pkgd bypass`           | `--reason`               | Reason for bypass (required)                                                   |
| `pkgd bypass`           | `--expires`              | Bypass expiry duration (e.g., `24h`, `7d`, `30m`)                              |
| `pkgd intel sync`       | `--exclude-feed`         | Exclude a specific feed (repeatable)                                           |
| `pkgd logs view`        | `--lines`, `-n`          | Number of lines to show (default: 100)                                         |
| `pkgd db snapshot`      | `--download`, `-d`       | Download latest threat intelligence snapshot                                   |
| `pkgd db snapshot`      | `--verify`, `-v`         | Verify local database integrity                                                |
| `pkgd reset`            | `--teardown`, `-t`       | Full teardown (remove database and config)                                     |
| `pkgd audit-logs query` | `--ecosystem`            | Filter audit log entries by ecosystem                                          |
| `pkgd audit-logs query` | `--verdict`              | Filter by verdict (`PASS`, `PARTIAL_PASS`, `FAIL`, `BLOCKED`, `WARN`, `ERROR`) |

### Environment Variables

| Variable              | Affects             | Description                                            |
| --------------------- | ------------------- | ------------------------------------------------------ |
| `PKGD_DRY_RUN`        | `--dry-run` default | When set to `1`, enables dry-run mode by default       |
| `PKGD_OUTPUT_VERBOSE` | `--no-verbose`      | Override verbose output at the environment level       |
| `PKGD_CI`             | `--ci` mode         | When set to `1`, forces CI mode (non-interactive)      |
| `PKGD_CONFIG_PATH`    | Config loading      | Path to configuration file (alternative to `--config`) |

[See Full CLI Reference Guide &rarr;][cli-ref]

## Supported Ecosystems

> #### Ecosystem Coverage Tier Key:
>
> The ecosystem's package publication timestamp source/availability (for use in cooldown calculation) determines the tier assignment:
>
> - `FULL`: Threat check runs, cooldown check runs, *verified* publish timestamps available
> - `PARTIAL`: Threat check runs, cooldown check runs, *proxied* publish timestamps available
> - `AUDIT`: Threat check runs, cooldown check is SKIPPED (no reliable registry publish timestamp source available)
>
> `FULL` and `PARTIAL` are functionally identical in terms of what checks run. The difference is in the *quality* of the timestamp source:
>
> - `FULL` means the timestamps are cryptographically verified/authoritative (PyPI native API, npm registry, etc.)
> - `PARTIAL` means they're proxied/approximate but still usable for cooldown (GitHub Releases/Tags API, Libraries.io, etc.)

| Ecosystem | Manager                       | Registry Adapter | Coverage Tier      | Lock File                                            | Wrapper |
| --------- | ----------------------------- | ---------------- | ------------------ | ---------------------------------------------------- | ------- |
| npm       | npm, yarn, pnpm, bun          | Yes              | `FULL` / `PARTIAL` | package-lock.json, yarn.lock, pnpm-lock.yaml         | Yes     |
| PyPI      | pip, pipx, poetry, pipenv, uv | Yes              | `FULL` / `PARTIAL` | requirements.txt, poetry.lock, Pipfile.lock, uv.lock | Yes     |
| Cargo     | cargo                         | Yes              | `FULL`             | —                                                    | Yes     |
| RubyGems  | gem, bundler                  | Yes              | `FULL` / `PARTIAL` | —                                                    | Yes     |
| Packagist | composer                      | Yes              | `FULL`             | —                                                    | Yes     |
| Homebrew  | brew                          | Yes              | `PARTIAL`          | —                                                    | Yes     |
| APT       | apt                           | Yes              | `AUDIT`            | —                                                    | Yes     |
| Yum       | yum                           | Yes              | `AUDIT`            | —                                                    | Yes     |
| DNF       | dnf                           | Yes              | `AUDIT`            | —                                                    | Yes     |
| Conda     | conda                         | Yes              | `FULL`             | —                                                    | Yes     |

[See Full Ecosystem Guide &rarr;][ecosystems]

## Dependencies

> [!IMPORTANT]
> Each dependency below includes a pre-crafted audit link: a
> Google-dorking search query scoped to supply chain attacks, compromises, and
> security advisories for that package, filtered to the past year.
>
> **This is intentional**. PKG-Defender exists because developers install
> packages on trust alone; we think that habit should stop, including with tools
> like ours. Before installing PKG-Defender in a sensitive environment, we
> encourage you to click through and do a 30-second check on each of our
> dependencies. That's exactly the kind of scrutiny this project was built to
> promote.

| PyPI Link                        | Purpose                                       | Audit Link                            |
| -------------------------------- | --------------------------------------------- | ------------------------------------- |
| [aiohttp][dep-aiohttp]           | Async HTTP for feed sync and registry lookups | [AUDIT ME &rarr;][audit-aiohttp]      |
| [click][dep-click]               | CLI framework                                 | [AUDIT ME &rarr;][audit-click]        |
| [defusedxml][dep-defusedxml]     | Safe XML parsing for RPM repodata             | [AUDIT ME &rarr;][audit-defusedxml]   |
| [feedparser][dep-feedparser]     | Atom/RSS feed parsing                         | [AUDIT ME &rarr;][audit-feedparser]   |
| [packaging][dep-packaging]       | Python version spec parsing                   | [AUDIT ME &rarr;][audit-packaging]    |
| [platformdirs][dep-platformdirs] | Platform-appropriate config/data directories  | [AUDIT ME &rarr;][audit-platformdirs] |
| [pyyaml][dep-pyyaml]             | YAML parsing for pnpm-lock.yaml lock files    | [AUDIT ME &rarr;][audit-pyyaml]       |
| [rich][dep-rich]                 | Terminal output formatting                    | [AUDIT ME &rarr;][audit-rich]         |
| [tomlkit][dep-tomlkit]           | TOML config file read/write (setup wizard)    | [AUDIT ME &rarr;][audit-tomlkit]      |
| [zstandard][dep-zstandard]       | Zstandard decompression for RPM repodata      | [AUDIT ME &rarr;][audit-zstandard]    |

[See Current Dependency List &rarr;][pyproject]

## Contributing

### Makefile

For common development tasks, you can use the Makefile:

| Command          | Description                        |
| ---------------- | ---------------------------------- |
| `make install`   | Install all dependencies           |
| `make lint`      | Check code style                   |
| `make typecheck` | Type checking                      |
| `make test`      | Run tests                          |
| `make check`     | Run lint, typecheck, and tests     |
| `make build`     | Build the package                  |
| `make clean`     | Clean build artifacts              |
| `make man`       | regenerate the man page troff file |

### Direct

Use uv directly:

```bash
uv run pytest
uv build
# continued...
```

See [CONTRIBUTING.md &rarr;][contributing]

## Support & Community

### PKG-Defender Sponsors

[![GitHub Sponsors][gh-sponsors-badge-icon]][gh-sponsors-badge-link]
[![BuyMeACoffee][buymeacoffee-badge-icon]][buymeacoffee-badge-link]

> [!NOTE]
> PKG-Defender is free and open-source software, built and maintained independently.
> If the tool provides value to your workflow or organization, consider supporting its
> continued development, and starring the project so that others can find it.
>
> Your support helps fund ongoing maintenance, feature development, and infrastructure
> costs — keeping the project available to everyone at no cost. Thank you.

### Join the Conversation

[![GitHub Issues][gh-issues-badge-icon]][gh-issues-badge-link]
[![GitHub Discussions][gh-discussions-badge-icon]][gh-discussions-badge-link]

- [Report Issues &rarr;][gh-issues-badge-link]
- [Join Discussions &rarr;][gh-discussions-badge-link]

## Security

> [!CAUTION]
> While PKG-Defender aims to provide practical defense against
> supply chain threats, no tool can ever guarantee complete protection. Threats
> may evolve faster than intelligence feeds, and sophisticated attacks may evade
> public detection. This tool is intended to be used as one layer of a broader
> security strategy — not as a silver bullet.
>
> PKG-Defender is in active development and we strive to continually evolve in
> response to the modern threat landscape.

See [SECURITY.md &rarr;][security]

See [DISCLAIMER.md &rarr;][disclaimer]

## Security Model Limitations (v1)

PKG-Defender is a practical defense layer, not a guarantee. Understanding its
architectural boundaries helps you calibrate expectations and deploy it where it
adds the most value for you and your organization.

### Shell Functions Protect Interactive CLI Use Only

PKG-Defender protects interactive `pip install`, `npm install`, and similar CLI
commands by wrapping package manager invocations via shell functions, or via direct
invocation. If you do not directly wrap manager commands in non-interactive
environments (`pkgd [OPTIONS] MANAGER SUBCOMMAND [PACKAGE...] [MANAGER_OPTIONS...]`),
your configured shell functions will **not** protect:

- **Dockerfiles / container builds** — `RUN pip install` inside a Dockerfile
  does not pass through pkgd shell functions.
- **CI/CD scripts** — Unless explicitly configured to use `pkgd <manager>`
  instead of the bare manager command.
- **Automated / headless installs** — Scripts, Makefiles, or system package
  operations that call the package manager directly.

After clearing a command, `os.execvp()` replaces the pkgd process with the real
package manager, leaving zero runtime overhead.

### No Transitive Dependency Resolution

`pkgd audit` currently inspects top-level packages only. Transitive dependency
scanning is planned for a future release.

### Post-Execution Audit Gap

PKG-Defender records its pre-install assessment in the audit log — the verdict,
config state, and threat analysis at decision time. However, because
`os.execvp()` replaces the process, pkgd **cannot** verify whether the install
actually succeeded or whether the package manager encountered an error. To
confirm outcomes, cross-reference pkgd's audit log (`pkgd audit-logs`) with your
package manager's actual installed state.

### AUDIT-Tier Managers Have No Cooldown Protection

Package managers on the `AUDIT` coverage tier (apt, yum, dnf) receive
threat-detection-only protection — the threat database **IS** queried, but cooldown
verification is skipped (these ecosystems lack reliable publish timestamps).

### Scoring Threshold Is a Tunable Heuristic

The block threshold (0.3 in `checker.py`) is a starting value chosen through
reasoned defaults, not empirical validation against real-world attack data. It
may produce false positives (blocking legitimate packages) or false negatives
(allowing malicious packages whose threat signals don't reach the threshold).
Users deploying in sensitive environments should test and adjust this value.

### Pre-Existing Attacks

PKG-Defender cannot protect against attacks that are already in motion at
install time. The tool assesses threat signals from intelligence feeds,
not runtime behavior.

### Signal-Based Cooldown

The v1 release provides signal-based cooldown escalation where threat severity
can dynamically extend cooldown windows. Verified advisories trigger an
immediate block, and Tier 3 social signals extend the cooldown window. However,
users cannot configure per-signal thresholds or escalation policies directly;
the behavior is hard-coded in the `step_check_cooldown()` pipeline.

## License

PKG-Defender is distributed under [Apache-2.0 &rarr;][license]

## Acknowledgements

PKG-Defender would not be possible without the following external projects,
services, data sources, libraries, and tools. Thank you for your contributions.

### Threat Intelligence Data Sources

- [OSV.dev][osv-dev] — Open Source Vulnerability database (Google)
- [GitHub Security Advisories][ghsa] — GHSA database
- [Socket.dev][socket-dev] — Supply chain security signals
- [OpenSSF Malicious Packages][ossf-malicious] — OpenSSF malicious package database

### Package Registries

- [npm][reg-npm] — npm registry (npm, Inc.)
- [PyPI][reg-pypi] — Python Package Index (Python Software Foundation)
- [RubyGems][reg-rubygems] — Ruby gem server
- [crates.io][reg-crates] — Rust package registry
- [Packagist][reg-packagist] — PHP/Composer package repository
- [Homebrew][reg-homebrew] — macOS/Linux package manager (formulae.brew.sh)
- [Anaconda][reg-anaconda] — Python/R data science distribution (Anaconda Inc.)
- [conda-forge][reg-condaforge] — Community-led conda package channel

### Timestamp Resolution Services

- [libraries.io][ts-librariesio] — Package metadata and release timestamps
- [Fedora Koji][ts-koji] — Fedora build system hub
- [Fedora Bodhi][ts-bodhi] — Fedora updates system
- [Ubuntu Archive][ts-ubuntu] — Ubuntu package archive
- [Debian Snapshot Archive][ts-debian] — Debian snapshot archive

### Social & Community Data Sources

- [Mastodon / infosec.exchange][social-mastodon] — Decentralized social platform
- [Reddit / PullPush.io][social-pullpush] — Reddit comment and submission archive
- [X/Twitter API v2][social-twitter] — Social media platform (opt-in, BYOK)

### Security Blog RSS Feeds

Security intelligence aggregated from blog RSS feeds:

- Socket.dev blog, Snyk blog, OpenSSF blog, GitHub Security blog,
  GitGuardian blog, Sonatype blog

### Runtime Dependencies

PKG-Defender's runtime dependencies are listed in the [Dependencies](#dependencies) table
above with full transparency audit links.

- [aiohttp][dep-aiohttp] — Async HTTP for feed sync and registry lookups
- [click][dep-click] — CLI framework
- [defusedxml][dep-defusedxml] — Safe XML parsing for RPM repodata
- [feedparser][dep-feedparser] — Atom/RSS feed parsing
- [packaging][dep-packaging] — Python version spec parsing
- [platformdirs][dep-platformdirs] — Platform-appropriate config/data directories
- [PyYAML][dep-pyyaml] — YAML parsing for pnpm-lock.yaml lock files
- [rich][dep-rich] — Terminal output formatting
- [tomlkit][dep-tomlkit] — TOML config file read/write (setup wizard)
- [zstandard][dep-zstandard] — Zstandard decompression for RPM repodata

### Development & Build Tools

- [Hatchling][dev-hatchling] — Python build backend
- [pytest][dev-pytest] — Testing framework
- [ruff][dev-ruff] — Python linter and formatter (Astral)
- [mypy][dev-mypy] — Static type checker
- [pre-commit][dev-precommit] — Git hook framework
- [PyInstaller][dev-pyinstaller] — Standalone binary packaging
- [aioresponses][dev-aioresponses] — Async HTTP test mocking

### CI/CD & Infrastructure

- [GitHub Actions][infra-ghactions] — CI/CD and snapshot automation
- [Codecov][infra-codecov] — Code coverage reporting
- [shields.io][infra-shields] — Badge generation service
- [Trivy][infra-trivy] — Container image vulnerability scanner (Aqua Security)
- [Docker][infra-docker] — Container runtime and image distribution

### Community Standards

- [Contributor Covenant][std-covenant] — Code of conduct
- [Conventional Commits][std-convcommits] — Commit message standard
- [no-color.org][std-nocolor] — NO_COLOR standard

### ASCII Art & Branding

- [artty][brand-artty] — ASCII art generation for the PKG-Defender
  logo banner (used offline in development for asset generation)

---

<div align="center">

<strong>Last Updated: 2026-07-20</strong></br>

<em><small>These days, people trust software blindly by default. Reading this far means you don't. That's rarer than it should be.</small></em>
<em><small>Traditionally this is the part where I'm supposed to ask you to star the repo, and... I'm not above tradition.</small></em></br>
<em><small>— Division 7</small></em>

</div>

---

<!-- Header Badge Icons -->

[license-badge-icon]: https://img.shields.io/badge/license-Apache_2.0-blue?style=plastic&logo=apache&color=black&logoColor=white&label=License
[python-badge-icon]: https://img.shields.io/pypi/pyversions/pkg-defender?style=plastic&logo=python&color=black&logoColor=white&label=Python
[pypi-downloads-badge-icon]: https://img.shields.io/pepy/dt/pkg-defender?style=plastic&logo=pypi&color=black&logoColor=white&label=Downloads
[github-binary-releases-badge]: https://img.shields.io/github/v/release/divisionseven/pkg-defender?filter=v*&style=plastic&color=black&logo=git&logoColor=white&label=Release
[github-snapshot-releases-badge]: https://img.shields.io/github/v/tag/divisionseven/pkg-defender?filter=snapshot-latest&style=plastic&logo=sqlite&logoColor=white&color=black&label=Threat%20DB
[codecov-badge-icon]: https://img.shields.io/codecov/c/github/divisionseven/pkg-defender?logo=codecov&style=plastic&color=black&logoColor=white&label=Codecov
[ci-badge-icon]: https://img.shields.io/github/actions/workflow/status/divisionseven/pkg-defender/ci.yml?branch=main&logo=github&style=plastic&color=black&logoColor=white&label=Build
[language-pkgs-badge-icon]: https://img.shields.io/badge/Language_Packages-npm_%7C_PyPI_%7C_Cargo_%7C_RubyGems_%7C_Packagist-black?style=plastic
[system-pkgs-badge-icon]: https://img.shields.io/badge/System_Packages-Homebrew_%7C_APT_%7C_Yum_%7C_DNF_%7C_Conda-black?style=plastic
[ossf-bp-badge-icon]: https://img.shields.io/badge/openssf%20best%20practices-passing-black?style=plastic&color=black&label=OpenSSF%20Best%20Practices
[scorecard-badge-icon]: https://img.shields.io/ossf-scorecard/github.com/divisionseven/pkg-defender?style=plastic&color=black&logoColor=white&label=OpenSSF%20Scorecard

<!-- Header Badge Links -->

[license-badge-link]: https://opensource.org/licenses/Apache-2.0
[pypi-badge-link]: https://pypi.org/project/pkg-defender/
[github-binary-releases-link]: https://github.com/divisionseven/pkg-defender/releases
[github-snapshot-releases-link]: https://github.com/divisionseven/pkg-defender/releases/tag/snapshot-latest
[codecov-badge-link]: https://app.codecov.io/gh/divisionseven/pkg-defender
[ci-badge-link]: https://github.com/divisionseven/pkg-defender/actions/workflows/ci.yml
[ecosystems-badge-link]: docs/reference/package-managers.md
[ossf-bp-badge-link]: https://www.bestpractices.dev/projects/13679
[scorecard-badge-link]: https://securityscorecards.dev/viewer/?uri=github.com/divisionseven/pkg-defender

<!-- Body Badge Icons -->

[platforms-badge-icon]: https://img.shields.io/badge/Compatible_Platforms-macOS%20ARM64%2Fx86__64%20%7C%20Linux%20x86__64%20%7C%20Windows%20x86__64-black?style=plastic
[pkgd-action-release-badge-icon]: https://img.shields.io/github/v/release/divisionseven/pkg-defender-action?filter=v*&style=plastic&color=black&logo=git&logoColor=white&label=PKGD%20GitHub%20Action%20Release
[pkgd-action-ci-badge-icon]: https://img.shields.io/github/actions/workflow/status/divisionseven/pkg-defender-action/ci.yml?branch=main&logo=github&style=plastic&color=black&logoColor=white&label=PKGD%20GitHub%20Action%20Build
[snapshot-action-badge-icon]: https://img.shields.io/github/actions/workflow/status/divisionseven/pkg-defender/snapshot.yml?branch=main&logo=github&style=plastic&color=black&logoColor=white&label=PKGD%20Snapshot%20Build
[gh-issues-badge-icon]: https://img.shields.io/github/issues/divisionseven/pkg-defender?color=black&style=plastic&label=Issues
[gh-discussions-badge-icon]: https://img.shields.io/github/discussions/divisionseven/pkg-defender?color=black&style=plastic&label=Discussions
[gh-sponsors-badge-icon]: https://img.shields.io/badge/GitHub%20Sponsors-Donate-green?logo=githubsponsors
[buymeacoffee-badge-icon]: https://img.shields.io/badge/BuyMeACoffee-Donate-green?logo=buymeacoffee

<!-- Body Badge Links -->

[pkgd-action-release-badge-link]: https://github.com/divisionseven/pkg-defender-action/releases
[pkgd-action-ci-badge-link]: https://github.com/divisionseven/pkg-defender-action/actions/workflows/ci.yml
[snapshot-action-badge-link]: https://github.com/divisionseven/pkg-defender/actions/workflows/snapshot.yml
[gh-issues-badge-link]: https://github.com/divisionseven/pkg-defender/issues
[gh-discussions-badge-link]: https://github.com/divisionseven/pkg-defender/discussions
[gh-sponsors-badge-link]: https://github.com/sponsors/divisionseven
[buymeacoffee-badge-link]:https://buymeacoffee.com/divisionseven

<!-- External Supply-Chain Attack Report Links -->

[tanstack-attack]: https://tanstack.com/blog/npm-supply-chain-compromise-postmortem
[axios-attack]: https://github.com/axios/axios/issues/10636
[litellm-attack]: https://docs.litellm.ai/blog/security-update-march-2026
[trivy-attack]: https://www.aquasec.com/blog/trivy-supply-chain-attack-what-you-need-to-know/

<!-- Dependencies — PyPI Links -->

[dep-aiohttp]: https://pypi.org/project/aiohttp/
[dep-click]: https://pypi.org/project/click/
[dep-defusedxml]: https://pypi.org/project/defusedxml/
[dep-feedparser]: https://pypi.org/project/feedparser/
[dep-packaging]: https://pypi.org/project/packaging/
[dep-platformdirs]: https://pypi.org/project/platformdirs/
[dep-pyyaml]: https://pypi.org/project/PyYAML/
[dep-rich]: https://pypi.org/project/rich/
[dep-tomlkit]: https://pypi.org/project/tomlkit/
[dep-zstandard]: https://pypi.org/project/zstandard/

<!-- Dependencies — Audit Dorking Links-->

[audit-aiohttp]: https://www.google.com/search?q=aiohttp+%28%22supply+chain+attack%22+OR+%22account+takeover%22+OR+compromised+OR+%22malicious+package%22+OR+backdoor+OR+typosquat%29+-site:stackoverflow.com&tbs=qdr:y
[audit-click]: https://www.google.com/search?q=%28%22pallets%2Fclick%22+OR+%22pip+install+click%22%29+%28%22supply+chain+attack%22+OR+%22account+takeover%22+OR+compromised+OR+%22malicious+package%22+OR+backdoor+OR+typosquat%29+-site:stackoverflow.com&tbs=qdr:y
[audit-defusedxml]: https://www.google.com/search?q=defusedxml+%28%22supply+chain+attack%22+OR+%22account+takeover%22+OR+compromised+OR+%22malicious+package%22+OR+backdoor+OR+typosquat%29+-site:stackoverflow.com&tbs=qdr:y
[audit-feedparser]: https://www.google.com/search?q=feedparser+%28%22supply+chain+attack%22+OR+%22account+takeover%22+OR+compromised+OR+%22malicious+package%22+OR+backdoor+OR+typosquat%29+-site:stackoverflow.com&tbs=qdr:y
[audit-packaging]: https://www.google.com/search?q=%22pypa%2Fpackaging%22+%28%22supply+chain+attack%22+OR+%22account+takeover%22+OR+compromised+OR+%22malicious+package%22+OR+backdoor+OR+typosquat%29&tbs=qdr:y
[audit-platformdirs]: https://www.google.com/search?q=platformdirs+%28%22supply+chain+attack%22+OR+%22account+takeover%22+OR+compromised+OR+%22malicious+package%22+OR+backdoor+OR+typosquat%29+-site:stackoverflow.com&tbs=qdr:y
[audit-pyyaml]: https://www.google.com/search?q=pyyaml+%28%22supply+chain+attack%22+OR+%22account+takeover%22+OR+compromised+OR+%22malicious+package%22+OR+backdoor+OR+typosquat%29+-site:stackoverflow.com&tbs=qdr:y
[audit-rich]: https://www.google.com/search?q=%28%22Textualize%2Frich%22+OR+%22pip+install+rich%22%29+%28%22supply+chain+attack%22+OR+%22account+takeover%22+OR+compromised+OR+%22malicious+package%22+OR+backdoor+OR+typosquat%29+-site:stackoverflow.com&tbs=qdr:y
[audit-tomlkit]: https://www.google.com/search?q=tomlkit+%28%22supply+chain+attack%22+OR+%22account+takeover%22+OR+compromised+OR+%22malicious+package%22+OR+backdoor+OR+typosquat%29+-site:stackoverflow.com&tbs=qdr:y
[audit-zstandard]: https://www.google.com/search?q=zstandard+%28%22supply+chain+attack%22+OR+%22account+takeover%22+OR+compromised+OR+%22malicious+package%22+OR+backdoor+OR+typosquat%29+-site:stackoverflow.com&tbs=qdr:y

<!-- Internal Documentation Links -->

[docs-index]: docs/index.md
[install-guide]: docs/tutorials/getting-started.md
[quick-start]: docs/tutorials/getting-started.md
[threat-scoring]: docs/explanation/scoring.md
[threat-feeds]: docs/reference/threat-feeds.md
[completion-guide]: docs/reference/cli.md
[auditing-guide]: docs/guides/auditing.md
[config-ref]: docs/reference/configuration.md
[pkgd-config-toml-ref]: docs/examples/config/pkgd.toml
[cli-ref]: docs/reference/cli.md
[ci-cd-guide]: docs/guides/ci-cd.md
[ecosystems]: docs/reference/package-managers.md
[supported-commands]: docs/reference/package-managers.md
[targeted-managers]: docs/reference/package-managers.md
[pyproject]: pyproject.toml
[contributing]: CONTRIBUTING.md
[security]: SECURITY.md
[disclaimer]: DISCLAIMER.md
[license]: LICENSE

<!-- External Acknowledgement Links -->

[osv-dev]: https://osv.dev
[ghsa]: https://github.com/advisories
[socket-dev]: https://socket.dev
[ossf-malicious]: https://github.com/ossf/malicious-packages
[reg-npm]: https://www.npmjs.com
[reg-pypi]: https://pypi.org
[reg-rubygems]: https://rubygems.org
[reg-crates]: https://crates.io
[reg-packagist]: https://packagist.org
[reg-homebrew]: https://brew.sh
[reg-anaconda]: https://anaconda.org
[reg-condaforge]: https://conda-forge.org
[ts-librariesio]: https://libraries.io
[ts-koji]: https://koji.fedoraproject.org/kojihub
[ts-bodhi]: https://bodhi.fedoraproject.org
[ts-ubuntu]: https://archive.ubuntu.com
[ts-debian]: https://snapshot.debian.org
[social-mastodon]: https://infosec.exchange
[social-pullpush]: https://pullpush.io
[social-twitter]: https://twitter.com
[dev-hatchling]: https://pypi.org/project/hatchling/
[dev-pytest]: https://pypi.org/project/pytest/
[dev-ruff]: https://pypi.org/project/ruff/
[dev-mypy]: https://pypi.org/project/mypy/
[dev-precommit]: https://pypi.org/project/pre-commit/
[dev-pyinstaller]: https://pypi.org/project/pyinstaller/
[dev-aioresponses]: https://pypi.org/project/aioresponses/
[infra-ghactions]: https://github.com/features/actions
[infra-codecov]: https://codecov.io
[infra-shields]: https://shields.io
[infra-trivy]: https://trivy.dev
[infra-docker]: https://www.docker.com
[std-covenant]: https://www.contributor-covenant.org
[std-convcommits]: https://www.conventionalcommits.org
[std-nocolor]: https://no-color.org
[brand-artty]: https://github.com/divisionseven/artty
