Metadata-Version: 2.4
Name: pygarde
Version: 1.0.0
Summary: 🐍 PYGARDE — Python Supply Chain Security Guardian. Scans, audits and hardens Python package manager security.
Project-URL: Homepage, https://github.com/destbreso/pygarde
Project-URL: Repository, https://github.com/destbreso/pygarde
Project-URL: Issues, https://github.com/destbreso/pygarde/issues
Author: destbreso
License: MIT
Keywords: audit,cli,dependency,guardian,malware,obfuscation,pip,poetry,pypi,scanner,security,supply-chain,typosquatting,uv
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: packaging>=24.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: responses>=0.25; extra == 'dev'
Description-Content-Type: text/markdown

# 🐍 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.

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

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
[![PyPI](https://img.shields.io/pypi/v/pygarde)](https://pypi.org/project/pygarde)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

## 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

```bash
# 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

```bash
# 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.

```bash
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.

```bash
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

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```yaml
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

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

---

## License

MIT — see [LICENSE](./LICENSE)
