pygarde 1.0.0

🐍 PYGARDE — Python Supply Chain Security Guardian. Scans, audits and hardens Python package manager security.

🐍 PYGARDE (pyw)

Python Supply Chain Security Guardian

PYGARDE is a CLI security tool that scans, audits and hardens your Python package ecosystem against supply-chain attacks — before malicious code ever runs on your machine.

  ██████╗ ██╗   ██╗██╗    ██╗ █████╗ ██████╗ ██████╗
  ██╔══██╗╚██╗ ██╔╝██║    ██║██╔══██╗██╔══██╗██╔══██╗
  ██████╔╝ ╚████╔╝ ██║ █╗ ██║███████║██████╔╝██║  ██║
  ██╔═══╝   ╚██╔╝  ██║███╗██║██╔══██║██╔══██╗██║  ██║
  ██║        ██║   ╚███╔███╔╝██║  ██║██║  ██║██████╔╝
  ╚═╝        ╚═╝    ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝

---

Features

Feature	Description
Deep scan	Download and scan any PyPI package without installing it
Pre-install gate	Intercept and scan packages before they touch your environment
Dependency audit	Audit all project dependencies against known CVEs and custom rules
RC hardening	Detect and fix misconfigurations in pip.conf, poetry.toml and uv.toml
Version diff	Compare two package versions and scan the code delta for injected threats
Health check	doctor command scores your project's overall security posture

Detection Rules

Rule	Detects
install-scripts	Malicious setup.py hooks, .pth injection
network-access	Suspicious imports and outbound URLs (pastebin, ngrok, hardcoded IPs)
code-execution	eval, exec, os.system, subprocess with shell=True, pickle.loads
obfuscation	base64.b64decode payloads, marshal.loads, high-entropy strings
data-exfiltration	os.environ combined with outbound HTTP, sensitive key access
hidden-chars	Zero-width spaces, Trojan Source (CVE-2021-42574), Cyrillic homoglyphs
typosquatting	Levenshtein-distance ≤ 2 against 80+ popular PyPI packages

---

Installation

# From PyPI (once published)
pip install pygarde

# Or install from source
git clone https://github.com/destbreso/pygarde
cd pygarde
pip install -e ".[dev]"

Requirements: Python 3.10+

---

Quick Start

# Initialize security configuration
pyw init

# Scan a package before installing
pyw scan requests

# Install with security gate
pyw install requests flask

# Audit all project dependencies
pyw audit

# Health check
pyw doctor

# Harden PM configuration
pyw harden

# Compare two versions
pyw diff numpy

---

Commands

pyw scan <package> [--version]

Deep-scan a PyPI package for security threats without installing it.

pyw scan requests
pyw scan requests --version 2.28.0
pyw scan suspicious-pkg --severity high
pyw scan malware --ci --json

Options:

Flag	Description
--version, -v	Version to scan (interactive picker if omitted)
--severity, -s	Minimum severity to display (low | medium | high | critical)
--page-size	Findings per page (default: 20)
--ci	Non-interactive, exits with code 1 if threats found
--json	Machine-readable JSON output

---

pyw install [packages...]

Install packages with a pre-install security scan.

pyw install requests flask sqlalchemy
pyw install pytest --dev
pyw install requests --force        # install despite findings
pyw install requests --skip-scan    # bypass scanning

---

pyw audit [--deep]

Audit all project dependencies.

• Runs native PM audit (pip-audit, pipenv check, etc.)
• With --deep: downloads and static-scans each dependency

pyw audit
pyw audit --deep
pyw audit --ci --json

---

pyw doctor

Security health check. Scores your project 0–100% across:

• .pygarde.yml present
• Lockfile present
• PM config security (via RC analyzer)
• No dangerous PM settings
• All detection rules enabled
• Allowlist not overly permissive

---

pyw diff <package> [--target]

Compare two versions of a package and scan the diff for injected code.

pyw diff requests
pyw diff numpy --target 1.26.0
pyw diff attrs --show-diff       # show line-level diffs

pygarde highlights:

• Added / removed / modified files
• New attack patterns in the diff (eval, subprocess, network calls)

---

pyw harden [--yes] [--dry-run]

Audit and fix PM security configuration files.

pyw harden
pyw harden --yes              # auto-apply at configured level
pyw harden --dry-run          # show issues only

Harden levels:

Level	Scope
minimal	Critical + high — the non-negotiables
recommended	Critical + high + medium — solid baseline (default)
strict	All findings including low-impact settings

pip.conf settings managed:

Setting	Level	Why
require-hashes = true	critical	Prevents MITM/tampered packages
no-binary (avoid for critical pkgs)	medium	Prefer auditable source
index-url	medium	Ensure official PyPI registry
trusted-host (danger)	critical	Disables SSL verification

---

pyw init

Interactive wizard to generate .pygarde.yml and apply RC hardening.

---

pyw config [show|edit|reset|path]

Manage configuration.

pyw config show         # display current config
pyw config path         # print config file path
pyw config edit         # open in $EDITOR
pyw config reset        # reset to defaults

---

Configuration

pygarde reads .pygarde.yml in the project root.

severity:
  threshold: medium       # ignore findings below this level
  fail_ci: high           # exit 1 in CI when findings reach this level

rules:
  install_scripts: true
  network_access: true
  code_execution: true
  obfuscation: true
  data_exfiltration: true
  hidden_chars: true
  typosquatting: true

policies:
  enforce_rc_security: true
  enforce_lockfile: true
  enforce_exact_versions: false
  audit_on_install: true
  registry_url: "https://pypi.org/simple/"
  harden_level: recommended   # minimal | recommended | strict

allowlist:
  - urllib3      # known false-positive
  - certifi

blocklist:
  - malicious-pkg
  - evil-package

---

Supported Package Managers

PM	Detection	Install	Audit	Harden
pip	✔	✔	✔ (pip-audit)	✔ (pip.conf)
poetry	✔	✔	✔	✔ (poetry.toml)
uv	✔	✔	—	✔ (uv.toml)
pipenv	✔	✔	✔ (pipenv check)	—
pdm	✔	✔	—	—
conda	✔	—	—	—

---

Running Tests

pip install -e ".[dev]"
pytest
pytest -v tests/test_rules.py
pytest --tb=short

---

License

MIT — see LICENSE