@intentsolutionsio/penetration-tester 2.0.0 → 3.0.4

package/skills/auditing-python-dependencies/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: auditing-python-dependencies
+description: |
+  Audit a Python project's installed dependencies for known CVEs by
+  wrapping pip-audit (PyPA's official vulnerability auditor) and
+  emitting findings in the canonical penetration-tester schema.
+  Detects vulnerable direct AND transitive packages, normalizes
+  pip-audit's severity output via OSV severity bands, falls back to
+  pip list --outdated when pip-audit isn't installed, and supports
+  requirements.txt, pyproject.toml (PEP 621), Pipfile.lock, and
+  poetry.lock as input sources.
+  Use when: pre-merge gate on a Python project, post-incident sweep
+  after a PyPI compromise (e.g. ctx, request-toolbelt typosquats,
+  ultralytics 8.3.42 compromise), SOC2 evidence collection, or
+  inheriting an unfamiliar Python codebase.
+  Threshold: any HIGH or CRITICAL CVE in the resolved dependency
+  tree. MODERATE / LOW reported informationally.
+  Trigger with: "audit python deps", "pip vulnerability scan",
+  "check pypi packages for CVEs", "pip-audit run".
+allowed-tools:
+  - Read
+  - Bash(pip:*)
+  - Bash(pip-audit:*)
+  - Bash(python3:*)
+  - Glob
+disallowed-tools:
+  - Bash(rm:*)
+  - Bash(curl:*)
+  - Bash(wget:*)
+  - Write(.env)
+  - Edit(.env)
+  - Bash(pip install:*)
+  - Bash(pip uninstall:*)
+version: 3.0.0-dev
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatibility: Designed for Claude Code
+tags:
+  - security
+  - dependency-audit
+  - python
+  - pypi
+  - cve
+  - pentest
+---
+
+# Auditing Python Dependencies
+
+## Overview
+
+PyPI hosts north of 500,000 packages, with several thousand new
+releases every day. The package-install model is identical to npm in
+the relevant ways: a `pip install` resolves a transitive graph,
+runs each package's `setup.py` (which executes arbitrary Python at
+install time), and writes the result to your site-packages. The CVE
+attack surface is therefore the same shape: known vulnerabilities,
+maintainer-account takeovers, typosquats, and protestware.
+
+The PyPA-blessed auditor is `pip-audit`. It queries the Open Source
+Vulnerabilities (OSV) database (which mirrors PyPA's advisory feed
+plus aggregated CVE / GHSA records) and reports per-package
+vulnerable versions. `pip-audit` integrates with `requirements.txt`,
+`pyproject.toml`, `Pipfile.lock`, and `poetry.lock`, so most Python
+project layouts are first-class.
+
+This skill wraps `pip-audit`, normalizes its severity vocabulary to
+the shared `Severity` enum, and emits Findings in the canonical
+penetration-tester schema. If `pip-audit` isn't installed on the
+host, the skill falls back to `pip list --outdated` and emits
+INFO-level findings recommending the operator install pip-audit
+for accurate vulnerability detection.
+
+## When the skill produces findings
+
+| Finding | Severity | Threshold | Affected control |
+|---|---|---|---|
+| Critical CVE in installed package | **CRITICAL** | OSV severity band corresponds to CVSS ≥ 9.0 | CWE-1104 |
+| High CVE in installed package | **HIGH** | OSV severity band corresponds to CVSS 7.0–8.9 | CWE-1104 |
+| Medium CVE in installed package | **MEDIUM** | OSV severity band corresponds to CVSS 4.0–6.9 | CWE-1104 |
+| Low CVE in installed package | **LOW** | OSV severity band corresponds to CVSS 0.1–3.9 | CWE-1104 |
+| Vulnerable package with no patch | **HIGH** | finding has no `fix_versions` and severity ≥ medium | CWE-1395 |
+| Outdated package (no CVE) | **INFO** | pip list --outdated reports a newer version | (operational) |
+| pip-audit not installed | **INFO** | binary not on PATH; scanner fell back to pip list | (operational) |
+| Audit DB unreachable | **INFO** | pip-audit network error reaching OSV | (operational) |
+
+OSV is the upstream of record. pip-audit also consults the PyPA
+advisory database for Python-specific records that may not yet have
+a CVE assigned.
+
+## Prerequisites
+
+- Python 3.9+
+- `pip-audit` installed (`pip install pip-audit`); skill falls back
+  to `pip list --outdated` if absent
+- Target project containing at minimum one of: `requirements.txt`,
+  `pyproject.toml`, `Pipfile.lock`, `poetry.lock`
+- Network access to OSV (`api.osv.dev`) and PyPI (`pypi.org`)
+
+## Instructions
+
+### Step 1 — Identify the scan target
+
+Locate the project directory. The scanner auto-detects requirement
+files in order of preference:
+
+1. `poetry.lock` (most precise — exact resolved tree)
+2. `Pipfile.lock`
+3. `requirements.txt` (and `requirements-*.txt` siblings)
+4. `pyproject.toml` (PEP 621 dependencies)
+5. Installed environment via `pip list` (last resort)
+
+### Step 2 — Run the audit
+
+```bash
+python3 ./scripts/audit_python.py /path/to/python-project
+```
+
+Options:
+
+```
+Usage: audit_python.py PATH [OPTIONS]
+
+Options:
+  --output FILE      Write findings to FILE (default: stdout)
+  --format FMT       json | jsonl | markdown (default: markdown)
+  --min-severity SEV (default: info)
+  --requirement FILE Override auto-detection; specify a particular
+                     requirements file (repeatable)
+  --include-dev      Include development dependencies (default: prod
+                     only when project layout allows the distinction)
+  --strict           Treat pip-audit warnings as errors
+```
+
+### Step 3 — Interpret findings
+
+CRITICAL / HIGH = block release.
+
+MEDIUM / LOW = track but don't block; many Python advisories report
+edge-case theoretical issues that don't apply to your usage.
+
+INFO = log only; e.g. "outdated but no known CVE" is information for
+your release cadence, not a security action.
+
+### Step 4 — Remediation
+
+For a vulnerable package with `fix_versions`:
+
+1. Bump the version pin in your requirements file:
+
+   ```diff
+   - requests==2.20.0
+   + requests==2.31.0
+   ```
+
+2. Run `pip install -r requirements.txt --upgrade` (or
+   `poetry lock --no-update && poetry update <pkg>`).
+
+3. Run the test suite. CVE fixes occasionally include behavioral
+   changes you didn't expect.
+
+4. Commit the lock file diff alongside the requirements bump.
+
+For a vulnerable transitive dep (one you didn't declare directly):
+
+1. Find the parent: `pip show <vulnerable-package>` lists the parents
+   in its "Required-by" line.
+
+2. Check whether bumping the parent picks up the fix. `pip index
+   versions <parent>` lists available versions.
+
+3. If parent doesn't have a newer release that floors the vulnerable
+   dep above the fix version, pin the transitive dep yourself in
+   your requirements file. pip will use the more specific pin.
+
+For a vulnerable package with NO fix available:
+
+1. Subscribe to PyPA advisory notifications for that package.
+
+2. If the vulnerability is exploitable in your usage, either
+   replace the package or vendor + patch locally.
+
+3. Document the exception in your security register with a
+   re-evaluation date.
+
+## Examples
+
+### Example 1 — Pre-merge gate
+
+```bash
+python3 ./scripts/audit_python.py . --min-severity high --format json --output audit.json
+jq -e '. == []' audit.json || { echo "High/critical Python CVE — fix before merge"; exit 1; }
+```
+
+### Example 2 — CI scan on every push
+
+```yaml
+- name: pip-audit
+  run: pip install pip-audit
+- name: Run audit
+  run: |
+    python3 plugins/security/penetration-tester/skills/auditing-python-dependencies/scripts/audit_python.py \
+        . --min-severity high --format markdown --output py-audit.md
+```
+
+### Example 3 — SOC2 evidence collection
+
+```bash
+mkdir -p evidence/CC7/
+python3 ./scripts/audit_python.py . --include-dev --format json \
+    --output evidence/CC7/py-audit-$(date +%Y%m%d).json
+```
+
+`--include-dev` for SOC2: include dev/test deps so auditors see the
+full surface, not just production.
+
+## Output
+
+JSON / JSONL / Markdown per `lib/report.py`. Exit codes: 0 clean, 1
+high/critical, 2 error.
+
+Each Finding includes:
+
+- `id` — synthesized as `pypi-audit::<cve-id>` (or `pypi-audit::<ghsa>` / `pypi-audit::<pypa-id>` when no CVE)
+- `severity` — CRITICAL / HIGH / MEDIUM / LOW / INFO
+- `category` — `dependency-vulnerability`
+- `summary` — short CVE / GHSA title
+- `evidence` — affected package, affected version, fix versions, advisory ID
+- `references` — OSV URL, CVE URL, PyPA advisory URL
+
+## Error Handling
+
+- **pip-audit not installed** → falls back to `pip list --outdated`,
+  emits an INFO Finding flagging the degraded scan, and proceeds.
+- **No requirement file found** → emits an INFO Finding "no Python
+  project structure recognized" and exits 2.
+- **OSV API unreachable** → emits an INFO Finding documenting the
+  outage and exits 0 (no actionable security finding).
+- **pip-audit returns malformed JSON** → emits an INFO Finding with
+  the raw output truncated to 500 chars and exits 2.
+
+## Resources
+
+- `references/THEORY.md` — PyPI supply-chain history, OSV vs NVD vs
+  PyPA advisory scopes, why ecosystem-specific severity matters,
+  Python-specific install-time risks (setup.py execution, eager
+  dependency resolution), pip-audit vs Safety vs Snyk trade-offs
+- `references/PLAYBOOK.md` — Per-toolchain remediation patterns
+  (pip + requirements.txt, poetry, pipenv, uv, conda), monorepo /
+  workspace scanning, override-equivalent patterns in Python
+  ecosystem, GitHub Dependabot ecosystem mapping, SOC2 evidence
+  retention

package/skills/auditing-python-dependencies/references/PLAYBOOK.md

@@ -0,0 +1,193 @@
+# PLAYBOOK — Remediating Python Findings
+
+## Per-toolchain remediation patterns
+
+### Plain requirements.txt + pip
+
+```bash
+# Edit requirements.txt to bump the pinned version
+sed -i 's/requests==2.20.0/requests==2.31.0/' requirements.txt
+pip install -r requirements.txt --upgrade
+pytest                           # confirm no behavior regressions
+git add requirements.txt && git commit -m "fix: bump requests to 2.31.0 (CVE-XXXX)"
+```
+
+If you have a separate `requirements-lock.txt` generated by
+`pip-compile`:
+
+```bash
+pip-compile --upgrade-package requests requirements.in
+```
+
+### Poetry
+
+```bash
+poetry add requests@^2.31.0
+poetry lock --no-update          # refresh just the affected entry
+poetry install
+pytest
+git add pyproject.toml poetry.lock
+```
+
+For a transitive bump (a dep not declared directly):
+
+```bash
+poetry add requests@^2.31.0 --lock   # forces resolution even if not direct
+```
+
+Or use the `dependencies` table to pin transitive deps without
+adding them as your project's direct deps.
+
+### Pipenv
+
+```bash
+pipenv update requests
+pipenv lock
+pipenv install --deploy --ignore-pipfile     # smoke test
+```
+
+### uv (modern fast resolver)
+
+```bash
+uv pip install --upgrade requests
+uv pip freeze > requirements.txt        # if you track frozen requirements
+```
+
+### conda environments
+
+`pip-audit` does not natively audit conda packages, only pip
+packages installed inside a conda environment. If a vulnerability
+affects a conda-installed package, fix via `conda update <pkg>`
+and document the manual remediation; pip-audit will not see the
+finding go away on its own.
+
+## Transitive dependency overrides
+
+Python has no first-class `overrides` equivalent like npm 8.3+.
+The patterns:
+
+### Pin in requirements (works in pip)
+
+If `boto3` pulls in `urllib3<2.0` and you need `urllib3>=2.0.2`:
+
+```
+urllib3>=2.0.2
+boto3==1.34.0
+```
+
+pip's resolver prefers the more specific version. This sometimes
+causes conflicts the resolver flags ("ResolutionImpossible"); when
+that happens, the parent itself needs to be bumped.
+
+### Poetry constraints
+
+```toml
+[tool.poetry.dependencies]
+boto3 = "^1.34.0"
+urllib3 = "^2.0.2"           # add as a direct dep to force the floor
+```
+
+This makes the transitive dep your direct dep, which is messy but
+effective.
+
+### Reset and re-resolve
+
+When a transitive override produces conflicts, sometimes the cleanest
+fix is to delete the lock file, bump everything, and re-resolve.
+Reserve for major version refreshes or when you have a release window
+to validate the full diff.
+
+## Monorepo / workspace scanning
+
+For monorepos that have multiple Python projects (often `services/*`
+or `apps/*` layout):
+
+```bash
+for project in services/*/; do
+    if [ -f "$project/pyproject.toml" ] || [ -f "$project/requirements.txt" ]; then
+        python3 plugins/security/penetration-tester/skills/auditing-python-dependencies/scripts/audit_python.py \
+            "$project" --format json --output "audit-$(basename $project).json"
+    fi
+done
+```
+
+The skill scans one project at a time by design — keeps the
+per-project blast radius clear and lets CI parallelize.
+
+## GitHub Dependabot ecosystem mapping
+
+Dependabot's "pip" ecosystem auto-PRs requirements.txt and
+pyproject.toml bumps. It does NOT audit poetry.lock — for that,
+use the "poetry" ecosystem entry:
+
+```yaml
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: pip            # poetry is reported as "pip" too in newer versions
+    directory: /services/api
+    schedule:
+      interval: weekly
+```
+
+For uv, Dependabot support was added in 2025; check Dependabot's
+docs for the current ecosystem name.
+
+## SOC2 evidence retention
+
+For Trust Service Category CC7 (System Operations):
+
+```bash
+mkdir -p evidence/CC7/
+python3 ./scripts/audit_python.py . --include-dev \
+    --format json \
+    --output evidence/CC7/py-audit-$(date +%Y%m%d).json
+```
+
+Retain at minimum one audit per quarter, plus the audit run that
+preceded each release. Auditors look for evidence that:
+
+1. The audit ran on a defined cadence.
+2. Findings were triaged within the window your vuln-response
+   policy commits to (typically 7 days for HIGH, 30 days for
+   MEDIUM, 90 days for LOW).
+3. Exceptions are documented with re-evaluation dates.
+
+## Common false positives
+
+Three patterns produce findings that aren't actionable:
+
+1. **Dev-only test fixtures pinning old versions** — e.g. tests
+   that intentionally exercise an old `requests` to verify backward
+   compat. Mark the source file as dev-only via `--include-dev`
+   filtering or split test requirements into a separate file.
+
+2. **Yanked releases on PyPI** — a release pulled by the maintainer
+   may still have an open advisory while no longer installable.
+   pip-audit handles yanked correctly in recent versions; older
+   versions may still flag.
+
+3. **CVEs that don't apply in your usage** — a vulnerability in the
+   FTP transport of `urllib3` is irrelevant if you only use HTTPS.
+   Don't blanket-suppress; document the per-finding rationale in
+   your security register.
+
+## When to vendor + patch
+
+If a package has an unpatched CRITICAL/HIGH CVE and replacement
+isn't feasible:
+
+1. Fork the upstream source into a private vendored copy in your
+   repo (e.g. `vendor/<package>/`).
+2. Apply the upstream patch (cherry-pick from the maintainer's PR
+   if one exists).
+3. Install from your vendored path: `pip install ./vendor/<package>`.
+4. Set a calendar reminder to re-evaluate quarterly; switch back to
+   upstream once a published fix is available.
+
+Vendor + patch is a maintenance burden; track it in your security
+register the same way you'd track any other exception.

package/skills/auditing-python-dependencies/references/THEORY.md

@@ -0,0 +1,122 @@
+# THEORY — Why Python Dependency Audits Matter
+
+## The Python install model
+
+`pip install <package>` does three things in sequence:
+
+1. Resolves a transitive dependency graph from PyPI metadata.
+2. Downloads each resolved package as a wheel (`.whl`) or sdist
+   (`.tar.gz`).
+3. For sdists, executes the package's `setup.py` (which is arbitrary
+   Python) at install time. For wheels, runs any post-install hooks.
+
+The `setup.py` execution step is the load-bearing detail. A
+compromised PyPI package can read environment variables, write to
+the user's home directory, exfiltrate data, and pivot to other
+systems — all on `pip install`, before the package is ever imported.
+
+## PyPI supply-chain incidents that drove audit adoption
+
+| Year | Event | Mechanism |
+|---|---|---|
+| 2017 | Typosquat wave (PyTorch, RoboGirl, ...) | Names one character off from popular packages. Some shipped credential-stealing setup.py. |
+| 2022 | `ctx` | Maintainer account compromise. Replaced legitimate package with a credential exfiltrator. ~22k weekly downloads. |
+| 2022 | `request-toolbelt` (typosquat of `requests-toolbelt`) | Same week, same actor, similar tactics. |
+| 2023 | `tornado` typosquats | Multiple variants targeting Tornado web framework users. |
+| 2024 | `ultralytics` 8.3.42 / 8.3.43 | YOLO ML library hijacked through GitHub Actions cache poisoning. Crypto miner in the wheel. |
+| 2025 | `requests-darwin-lite` | Targeted macOS users; trojanized binary inside an otherwise innocent wheel. |
+
+Each case relied on either (a) someone installing the malicious
+package by name without checking, or (b) a transitive dep updating
+to a malicious version that an existing project pulled in
+automatically.
+
+## OSV, PyPA, and the audit data sources
+
+`pip-audit` queries the Open Source Vulnerabilities (OSV) database
+(osv.dev), maintained by Google as an aggregator of ecosystem-specific
+advisory feeds. For Python, OSV ingests the PyPA Advisory Database
+(github.com/pypa/advisory-database), which is the upstream of record
+for Python-specific vulnerabilities.
+
+Why OSV and not NVD?
+
+- **OSV is ecosystem-aware.** A finding tagged "PyPI" affects exactly
+  the packages installed via pip. NVD's CVE list is package-agnostic
+  and requires manual mapping to ecosystem.
+- **PyPA records often pre-date CVE assignment.** A vulnerability
+  in a Python package can be published in PyPA's database before
+  NIST assigns a CVE number. Tools that only query NVD miss the
+  early window.
+- **Severity bands are normalized.** OSV maps CVSS scores to a
+  consistent severity vocabulary across ecosystems.
+
+The skill consumes pip-audit's output (which already does the OSV
+query) rather than querying OSV directly. Reasons: pip-audit's
+parser is mature, handles edge cases (yanked releases, retracted
+advisories), and integrates with PEP 621 / poetry / pipenv project
+layouts natively.
+
+## Python-specific install-time risks
+
+Two install-time behaviors make Python uniquely vulnerable:
+
+### setup.py execution
+
+Sdists run `setup.py` to build. `setup.py` is arbitrary Python.
+A malicious sdist can do anything Python can do at install time,
+including:
+
+- Read `~/.aws/credentials`, `~/.ssh/id_*`, `.env` files.
+- Open a reverse shell via socket.
+- Modify other installed packages in site-packages.
+
+`pip install <package> --only-binary :all:` refuses sdists,
+forcing wheels — but most published packages still publish sdists
+alongside wheels.
+
+### Eager dependency resolution
+
+Pre-pip 20.3, pip's resolver was first-match-wins, leading to
+inconsistent dependency trees across environments. Pip's modern
+resolver (PEP 517 + 2020-resolver) is consistent but slower; some
+CI pipelines disable it for speed, reintroducing the inconsistency.
+
+Inconsistent resolution = the audit on your laptop may show
+different packages than the audit in CI. Locking via `pip-tools`,
+`poetry`, or `uv` is the only durable fix.
+
+## pip-audit vs Safety vs Snyk
+
+Three audit tools compete in the Python space.
+
+| Tool | Backed by | Strengths | Weaknesses |
+|---|---|---|---|
+| pip-audit | PyPA | Official; consumes the PyPA advisory DB directly; supports requirements/poetry/pipenv | Severity normalization is sometimes coarser than CVSS |
+| Safety | safetycli.com | Commercial advisory DB with curated severity; web UI | Free tier rate-limited; relies on a third-party DB |
+| Snyk | Snyk Inc. | Commercial advisory DB; rich vulnerability metadata; web UI | Auth required; commercial pricing for production use |
+
+The skill standardizes on pip-audit because it's PyPA-blessed,
+zero-cost, and ships with the data quality SOC2 auditors expect to
+see in evidence packages.
+
+## Why severity normalization matters
+
+OSV emits severity as free-text strings or CVSS vectors. NVD emits
+CVSS scores. GitHub uses 4 levels. PyPA uses ecosystem-specific
+labels. The penetration-tester `Severity` enum (`lib/finding.py`)
+is the canonical mapping target so downstream consumers (executive
+reports, SOC2 evidence collection, dashboards) see one vocabulary
+across every tool.
+
+## When "no fix" is itself a finding
+
+A vulnerability with no `fix_versions` is not less severe — it's
+MORE remediation-bound. You can't `pip install -U` your way out of
+it. The skill bumps such findings to at-least HIGH severity to make
+this visible in the report. Operator options are limited:
+
+1. Pin to an older safe version (if one exists pre-vulnerability).
+2. Vendor the package locally and patch it in-tree.
+3. Replace the package with an alternative.
+4. Accept the risk with an explicit security-register exception.