Metadata-Version: 2.4
Name: pygarde
Version: 1.0.1
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

### Recommended — global install with pipx

[pipx](https://pypa.github.io/pipx/) installs Python CLI tools in isolated environments and makes them available system-wide. This is the preferred way to install `pyw`.

```bash
# 1. Install pipx (once)
brew install pipx        # macOS
# or: pip install --user pipx

pipx ensurepath          # adds ~/.local/bin to your PATH (restart terminal after)

# 2. Install pygarde globally
pipx install pygarde

# 3. Verify
pyw --version
```

After this, `pyw` is available in **any terminal, any project, any virtualenv** — no activation needed.

### Alternative — pip (current Python only)

```bash
pip install pygarde
pyw --version
```

> ⚠️ With plain `pip`, `pyw` is only available while that Python's environment is active. Use `pipx` for a permanent global install.

### From source (development)

```bash
git clone https://github.com/destbreso/pygarde
cd pygarde
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pyw --version
```

**Requirements:** Python 3.10+

---

## Quick Start

```bash
# 1. Initialize security config in your project
cd my-project
pyw init

# 2. Scan any PyPI package before installing it
pyw scan requests
pyw scan requests --version 2.31.0

# 3. Install packages with pre-install security gate
pyw install requests flask sqlalchemy
pyw install pytest --dev

# 4. Audit all project dependencies
pyw audit
pyw audit --deep          # also scans source code of each dep

# 5. Health check — scores your project security posture
pyw doctor

# 6. Harden your package manager config (pip.conf / poetry.toml / uv.toml)
pyw harden
pyw harden --yes          # auto-apply without prompts

# 7. Compare two versions of a package — detect injected code
pyw diff numpy
pyw diff requests --target 2.32.0 --show-diff
```

---

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