Add pen-test design and automation scripts

.gitignore

@@ -32,3 +32,7 @@
 
 # Visual Studio cache/options directory
 .vs/
+
+# pentest run & results
+/pentest/*/results/
+__pycache__/

pentest/README.md

@@ -0,0 +1,33 @@
+# GPA Pen-Test Harness
+
+Two parallel harnesses — one per OS — exercising the same scenario set
+(`A1` / `B1b` / `C7` / `IMDS-S6` / …) against the Guest Proxy Agent. Each
+folder is self-contained: its own scripts, its own design doc, its own
+report generator, its own `results/` directory.
+
+| Folder | Language | Report generator | Run from |
+|---|---|---|---|
+| [linux/](linux/) | Bash + Python | `linux/generate_report.py` | Bash on the GPA Linux VM (`bash linux/run_all.sh`) |
+| [windows/](windows/) | PowerShell | `windows/Generate-Report.ps1` | Elevated PowerShell on the GPA Windows VM (`.\windows\Run-AllPenTests.ps1`) |
+
+Findings on either platform are written as TSV rows with the same schema:
+
+```
+<iso-utc>\t<test-id>\t<PASS|FAIL|INFO>\t<short-message>
+```
+
+so a Linux `findings.tsv` and a Windows `findings.tsv` can be diffed
+test-by-test.
+
+## Pick a side
+
+- **Linux harness** — see [linux/README.md](linux/README.md) and
+  [linux/DESIGN.md](linux/DESIGN.md).
+- **Windows harness** — see [windows/README.md](windows/README.md) and
+  [windows/DESIGN.md](windows/DESIGN.md).
+
+The Windows DESIGN doc has a cross-platform mapping table at the bottom
+([windows/DESIGN.md §5](windows/DESIGN.md)) that lists each Linux concept
+(eBPF redirect, `bpftool`, `tcpdump`, POSIX modes, `unshare -Cr`, …) next
+to its Windows equivalent (WFP, `netsh wfp show filters`, `pktmon`, ACLs,
+Containers feature, …).

pentest/linux/README.md

@@ -0,0 +1,87 @@
+# GPA Pen-Test Harness
+
+Local pen-test scaffolding for the Guest Proxy Agent running on this VM.
+
+Mirror of the Windows harness under [../windows/](../windows/), with the
+same scenario IDs and the same `findings.tsv` schema; design rationale
+lives in [DESIGN.md](DESIGN.md).
+
+## Layout
+
+| File | Purpose |
+|------|---------|
+| [lib/common.sh](lib/common.sh) | Shared helpers: endpoints, paths, `record` (TSV writer), HTTP helpers, root check. |
+| [test_catalog.py](test_catalog.py) | Per-test metadata (title / design / automation / repro / fix) consumed by the report. |
+| [phase2_listener/run.sh](phase2_listener/run.sh) | A1, A1b, A2, A3, A4 (CONNECT → 405), A5 (open-proxy), G1 (burst). |
+| [phase3_authn_authz/run.sh](phase3_authn_authz/run.sh) | P3-cap (tcpdump), B1a, B1b (kernel-side `ss -tnp` proof), B3, B4, C1 (low-IL probe via `nobody`), C5 (`unshare -Cr`), C7 (alt-IP-form parity). |
+| [phase4_rules_fuzz/url_diff.py](phase4_rules_fuzz/url_diff.py) | URL / encoding differential (11 variants of the IMDS token URL). |
+| [phase4b_local_rules/run.py](phase4b_local_rules/run.py) | Local-file authorization-rules matrix: IMDS S1–S10 + S11/S12/S17/S18/S19 and WS S1–S10 + S11/S12/S17/S18/S19 (30 scenarios). Mutates `/var/lib/azure-proxy-agent/rules/`. |
+| [phase5_state_fs/audit.sh](phase5_state_fs/audit.sh) | E1 (keys/log/binary/unit mode+owner), F1 (no secrets in observable JSON), F4 (Rules dir mode+owner — admin-only WRITE), bpftool snapshots. |
+| [generate_report.py](generate_report.py) | Renders `results/report.html` from `results/findings.tsv` (+ latest `url_diff.tsv`). |
+| [run_all.sh](run_all.sh) | Driver. Runs phases 2 / 3 / 4 / 4b / 5 + report by default. Flags: `--no-truncate`, `--skip-phase{2,3,4,4b,5}`, `--phase4b-target {both,imds,wireserver}`, `--no-report`. |
+| `results/` | Populated at runtime: `findings.tsv`, `url_diff.tsv`, `report.html`, per-phase pcaps / bpftool snapshots, `phase4b_local_rules.log`. |
+
+## Prereqs
+
+```bash
+sudo apt install -y nmap tcpdump bpftool radamsa python3-scapy wrk jq strace curl
+```
+
+Python ≥ 3.8 (stdlib only — no `pip install` required for the harness or
+the report generator).
+
+The harness assumes:
+- `azure-proxy-agent.service` is active.
+- Listener is at `127.0.0.1:3080`.
+- Fabric endpoints `169.254.169.254:80`, `168.63.129.16:{80,32526}` are reachable.
+- For **Phase 4b**: the fabric has delivered an `AuthorizationRules_*.json`
+  whose decoded JSON contains `useLocalFileRules:true` AND its effective
+  `mode` is `Enforce` for the chosen target(s). Phase 4b's `PRE` row will
+  fast-fail if either pre-condition is missing.
+- For **Phase 5 F4**: the Rules dir (`/var/lib/azure-proxy-agent/rules`)
+  exists on disk so its mode/owner can be audited.
+
+## Run
+
+```bash
+# Default — phases 2, 3, 4, 4b, 5 + HTML report (truncates findings.tsv first):
+sudo ./pentest/linux/run_all.sh
+
+# Append instead of truncating:
+sudo ./pentest/linux/run_all.sh --no-truncate
+
+# Skip the mutating Phase 4b on a production VM:
+sudo ./pentest/linux/run_all.sh --skip-phase4b
+
+# Phase 4b alone, IMDS only:
+sudo python3 pentest/linux/phase4b_local_rules/run.py --target imds
+
+# Re-render the report from the existing findings.tsv:
+python3 pentest/linux/generate_report.py
+```
+
+## Safety
+
+- Phase 2 sends only loopback traffic.
+- Phase 3 sends real requests to the Azure fabric — keep volumes low.
+- Phase 4b *writes* to `/var/lib/azure-proxy-agent/rules/` and bounces the
+  agent's view of the local rule file. Backups of any pre-existing rules
+  files are restored on exit (including `Ctrl+C` / crash); skip with
+  `--skip-phase4b` if running on a fabric that doesn't allow local rules.
+- Snapshot the VM (or back up `/var/lib/azure-proxy-agent` and
+  `/var/log/azure-proxy-agent`) before Phase 5.
+- Do **not** run Phase 5 fault-injection tests (E2 symlink, E3 disk-full,
+  E4 kill, E5 key downgrade) on a production VM; `audit.sh` itself is
+  read-only and safe.
+
+## Result format
+
+Each test appends one TSV row to `results/findings.tsv`:
+
+```
+<iso-timestamp>\t<test-id>\t<PASS|FAIL|INFO>\t<short-message>
+```
+
+A `FAIL` means the GPA invariant was violated (potential finding) and
+warrants triage. Designs, repro steps, and suggested fixes are inlined
+per row in the HTML report.