Skip to content
Back to search

Transilience Community Security Tools

MarketplaceWorks with Claude CodeGitHub

Claude Code plugins for authorized security testing, bug bounty hunting, AI threat testing, and recon

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/transilienceai-communitytools/badge.svg)](/listings/transilienceai-communitytools)

HTML

<a href="/listings/transilienceai-communitytools"><img src="/api/listings/transilienceai-communitytools/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

- **Claude Code** — [Install Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview) - **Playwright** — Required for client-side testing, HackTheBox/HackerOne automation, and browser-based evidence capture. Install via: `npm install -g @playwright/mcp && npx playwright install chromium` - **Python 3** — Required for tools (`env-reader.py`, `nvd-lookup.py`, `slack-send.py`) - **Kali Linux tools** (optional) — nmap, gobuster, ffuf, sqlmap, testssl, etc. Only needed for network/infrastructure testing

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 31 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "Transilience Community Security Tools",
  3. "description": "Claude Code plugins for authorized security testing, bug bounty hunting, AI threat testing, and recon",
  4. "plugins": [
  5. {
  6. "name": "pentest",
  7. "path": "plugins/pentest",
  8. "description": "Full penetration testing framework — 100+ attack categories covering OWASP, injection, authentication, cloud, and more"
  9. },
  10. {
  11. "name": "hackerone",
  12. "path": "plugins/hackerone",
  13. "description": "HackerOne bug bounty integration — report generation, CSV parsing, and platform-ready submissions"
  14. },
  15. {
  16. "name": "ai-threat-testing",
  17. "path": "plugins/ai-threat-testing",
  18. "description": "AI security testing — OWASP LLM Top 10 with dedicated agents for prompt injection, model extraction, and more"
  19. },
  20. {
  21. "name": "techstack-identification",
  22. "path": "plugins/techstack-identification",
  23. "description": "Tech stack reconnaissance — 26 skills and 5 agents for DNS, cloud detection, subdomain enumeration, and more"
  24. },
  25. {
  26. "name": "skill-update",
  27. "path": "plugins/skill-update",
  28. "description": "Skill creation meta-tool — automates skill generation, validation, and PR submission for Claude Code plugins"
  29. }
  30. ]
  31. }
README.md · README · 379 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Transilience AI Community Security Tools
  2. <div align="center">
  3. [![Built by Transilience](https://img.shields.io/badge/Built%20by-Transilience.ai-4A90D9)](https://www.transilience.ai)
  4. [![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
  5. [![GitHub stars](https://img.shields.io/github/stars/transilienceai/communitytools)](https://github.com/transilienceai/communitytools/stargazers)
  6. [![Claude AI](https://img.shields.io/badge/Powered%20by-Claude%20AI-blue)](https://claude.ai)
  7. **Open-source Claude Code skills and agents for AI-powered penetration testing, bug bounty hunting, AI threat testing, and security reconnaissance — from the team at [Transilience.ai](https://www.transilience.ai)**
  8. [Quick Start](#-quick-start) | [Skills](#-skills) | [Architecture](#-architecture) | [Contributing](CONTRIBUTING.md) | [Website](https://www.transilience.ai)
  9. </div>
  10. ---
  11. ## Announcement
  12. **Practice Makes Perfect: Teaching an AI to Hack by Learning from Its Mistakes** (March 2026)
  13. We built an autonomous pentesting agent that scores **100% (104/104)** on a published CTF benchmark suite — using only structured markdown skill files, no fine-tuning. Starting from a bare 89.4% baseline, we ran a simple loop roughly 15 times: run the benchmarks, find a failure, diagnose the missing technique, write it into a skill file, and run again. The same skills transfer cross-model: Claude Sonnet 4.6 reaches 96.2% and Claude Haiku 4.5 reaches 62.5%. This repository contains the full skill set described in the paper.
  14. **[Read the paper](papers/practice-makes-perfect.pdf)**
  15. ---
  16. ## Overview
  17. **Transilience AI Community Tools** is a consolidated Claude Code security testing suite — **26 skills** and **3 tool integrations** that cover the full penetration testing lifecycle from reconnaissance to reporting. Agent roles (coordinator, executor, validator) are defined in `skills/coordination/` with reference material in `skills/coordination/reference/`, and spawned dynamically via `Agent(prompt=...)`.
  18. ### Why Choose Transilience Community Tools?
  19. - **AI-Powered Automation** — Claude coordinates intelligent security testing workflows
  20. - **Complete OWASP Coverage** — 100% OWASP Top 10 + OWASP LLM Top 10
  21. - **Professional Reporting** — CVSS 4.0 (primary; v3.1/v3.0/v2.0 fallback), CWE, MITRE ATT&CK, Transilience-branded PDF reports
  22. - **Playwright Integration** — Browser automation for client-side vulnerability testing
  23. - **Payload-Enriched References** — 160+ reference files with inline PayloadsAllTheThings techniques
  24. - **Open Source** — MIT licensed for commercial and personal use
  25. ---
  26. ## Prerequisites
  27. ### Local Setup
  28. - **Claude Code** — [Install Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview)
  29. - **Playwright** — Required for client-side testing, HackTheBox/HackerOne automation, and browser-based evidence capture. Install via: `npm install -g @playwright/mcp && npx playwright install chromium`
  30. - **Python 3** — Required for tools (`env-reader.py`, `nvd-lookup.py`, `slack-send.py`)
  31. - **Kali Linux tools** (optional) — nmap, gobuster, ffuf, sqlmap, testssl, etc. Only needed for network/infrastructure testing
  32. ### Docker Setup (Recommended)
  33. A single script spins up a Kali Linux container with Claude Code, Playwright (headed via Xvfb), and all Kali security tools pre-installed:
  34. ```bash
  35. bash scripts/kali-claude-setup.sh projects/pentest
  36. ```
  37. This builds a Docker image with Kali Rolling + Node.js + Claude Code + Playwright + Chromium, mounts the project workspace, and launches Claude Code with `--dangerously-skip-permissions`. Use `--rebuild` to force a fresh image build.
  38. ---
  39. ## Quick Start
  40. ### 1. Clone and enter the project
  41. ```bash
  42. git clone https://github.com/transilienceai/communitytools.git
  43. cd communitytools/projects/pentest
  44. ```
  45. ### 2. Open Claude Code and run skills
  46. ```bash
  47. claude # Launch Claude Code from the projects/pentest directory
  48. ```
  49. Then use slash commands inside the Claude session:
  50. ```
  51. Pentest https://target.com # Full penetration test (skills/coordination/)
  52. /hackthebox # HackTheBox challenge automation
  53. /hackerone # Bug bounty workflow
  54. /techstack-identification # Passive tech stack recon
  55. /reconnaissance target.com # Attack surface mapping
  56. /source-code-scanning ./app # Static code analysis
  57. ```
  58. ---
  59. ## Skills
  60. All canonical skill and tool definitions live at the **repo root** (`skills/`, `tools/`). Each project under `projects/` symlinks only the ones it needs — see [Repository Structure](#repository-structure) for details.
  61. Agent roles (coordinator, executor, validator) are defined in `skills/coordination/` with reference material in `skills/coordination/reference/`, spawned dynamically via `Agent(prompt=...)`.
  62. ### Skills by Category (26)
  63. #### Vulnerability Testing (10)
  64. | Skill | Coverage |
  65. |-------|----------|
  66. | `/injection` | SQL, NoSQL, OS Command, SSTI, XXE, LDAP/XPath |
  67. | `/client-side` | XSS (Reflected/Stored/DOM), CSRF, Clickjacking, CORS, Prototype Pollution |
  68. | `/server-side` | SSRF, HTTP Smuggling, Path Traversal, File Upload, Deserialization, Host Header |
  69. | `/authentication` | Auth Bypass, JWT, OAuth, Password Attacks, 2FA Bypass, CAPTCHA Bypass |
  70. | `/api-security` | GraphQL, REST API, WebSockets, Web LLM |
  71. | `/web-app-logic` | Business Logic, Race Conditions, Access Control, Cache Poisoning/Deception, IDOR |
  72. | `/cloud-containers` | AWS, Azure, GCP, Docker, Kubernetes |
  73. | `/system` | Active Directory, Privilege Escalation (Linux/Windows), Exploit Development |
  74. | `/infrastructure` | Port Scanning, DNS, MITM, VLAN Hopping, IPv6, SMB/NetBIOS |
  75. | `/social-engineering` | Phishing, Pretexting, Vishing, Physical Security |
  76. #### Reconnaissance (3)
  77. | Skill | Purpose |
  78. |-------|---------|
  79. | `/reconnaissance` | Subdomain discovery, port scanning, endpoint enumeration, API discovery, attack surface mapping |
  80. | `/osint` | Repository enumeration, secret scanning, git history analysis, employee footprint |
  81. | `/techstack-identification` | Passive tech stack inference across 17 intelligence domains |
  82. #### Specialized (5)
  83. | Skill | Purpose |
  84. |-------|---------|
  85. | `/ai-threat-testing` | OWASP LLM Top 10 — prompt injection, model extraction, data poisoning, supply chain |
  86. | `/blockchain-security` | Smart contract security, EVM storage, delegatecall, CREATE/CREATE2, DeFi exploits |
  87. | `/cve-poc-generator` | CVE research, NVD lookup, safe Python PoC generation, vulnerability reports |
  88. | `/dfir` | Digital forensics, incident response, Windows event logs, PCAP analysis, AD attack detection |
  89. | `/source-code-scanning` | SAST — OWASP Top 10, CWE Top 25, dependency CVEs, hardcoded secrets |
  90. #### Platform Integrations (2)
  91. | Skill | Purpose |
  92. |-------|---------|
  93. | `/hackerone` | Scope CSV parsing, parallel asset testing, PoC validation, platform-ready submissions |
  94. | `/hackthebox` | Playwright-based login, challenge browsing, VPN management, automated solving |
  95. #### Tooling (6)
  96. | Skill | Purpose |
  97. |-------|---------|
  98. | `/essential-tools` | Burp Suite, Playwright automation, methodology, reporting standards |
  99. | `/patt-fetcher` | On-demand payload extraction from PayloadsAllTheThings |
  100. | `/script-generator` | Optimized, syntax-validated script generation |
  101. | `formats/transilience-report-style` | Transilience-branded PDF report generation (ReportLab) |
  102. | `/github-workflow` | Git branching, commits, PRs, issues, code review |
  103. | `/skill-update` | Skill scaffolding, validation, GitHub workflow automation |
  104. ### Tool Integrations (3)
  105. | Tool | Purpose |
  106. |------|---------|
  107. | **Playwright** | Browser automation for client-side testing via MCP |
  108. | **Kali Linux Tools** | nmap, masscan, nikto, gobuster, ffuf, sqlmap, testssl, and more |
  109. | **NVD / CVE Risk Score** | Auto-invoked CVE lookup (`/cve-risk-score`) — CVSS score, severity, CWE from NVD |
  110. ### MCP Servers
  111. Local Model Context Protocol servers that expose Transilience APIs to MCP-capable clients (Claude Desktop, Cline, Zed, etc.). Each server is self-contained under `mcp/<name>/` with its own `pyproject.toml` and install instructions.
  112. | Server | Purpose |
  113. |--------|---------|
  114. | [`mcp/transilience-vuln`](./mcp/transilience-vuln) | Single-CVE and bulk CVE enrichment (CVSS, EPSS, KEV, impact taxonomy, vendor advisories) via the Transilience Vulnerability API. |
  115. ---
  116. ## Architecture
  117. The suite uses a **skills-only** architecture with canonical definitions at the repo root, symlinked into isolated project environments:
  118. - **Skills** (`skills/` at root, symlinked into each project's `.claude/skills/`) — User-triggered workflows invoked with `/skill-name`. Each skill contains a `SKILL.md` definition and `reference/` directory with attack techniques, cheat sheets, payloads, and agent role prompts.
  119. - **Coordination** (`skills/coordination/`) — Defines the 3 agent roles (coordinator, executor, validator) as a skill with role-based context injection. Read at runtime and passed to `Agent(prompt=...)`.
  120. - **Tools** (`tools/` at root, symlinked into each project's `.claude/tools/`) — Utility scripts for environment reading, integrations.
  121. ### Multi-Agent Execution Flow
  122. ```mermaid
  123. sequenceDiagram
  124. participant User
  125. participant Coord as Coordinator (inline)
  126. participant Roles as Role Definitions (skills/coordination/)
  127. participant Agents as Spawned Agents
  128. participant Output as Standardized Outputs
  129. User->>Coord: Pentest https://target.com
  130. Coord->>Roles: Read skills/coordination/SKILL.md
  131. Coord->>Coord: Execute coordinator workflow inline
  132. Coord->>Roles: Read skills/coordination/reference/executor-role.md
  133. Coord->>Agents: Agent(prompt=executor_role + chain + skills) × N
  134. Note over Agents: SQL/XSS/SSRF/JWT/OAuth/SSTI/XXE...
  135. Agents-->>Output: findings/*.json + evidence/*.png
  136. Coord->>Roles: Read skills/coordination/reference/validator-role.md
  137. Coord->>Agents: Agent(prompt=validator_role + evidence ONLY) × N
  138. Note over Agents: Blind review — no attack chain context
  139. Agents-->>Output: validated/*.json
  140. Coord->>Output: Phase 6: Generate reports
  141. Output-->>User: Executive + technical reports
  142. ```
  143. ### Repository Structure
  144. ```
  145. communitytools/
  146. ├── CLAUDE.md # Project instructions
  147. ├── marketplace.json # Machine-readable project manifest
  148. ├── papers/ # Research papers
  149. ├── benchmarks/ # XBOW benchmark runner
  150. │
  151. ├── skills/ # ← Canonical skill definitions (source of truth)
  152. │ ├── coordination/ # ← Agent roles + coordination reference
  153. │ │ ├── SKILL.md # Coordinator logic (entry point)
  154. │ │ └── reference/
  155. │ │ ├── executor-role.md # Executor role prompt
  156. │ │ ├── validator-role.md # Validator role prompt (blind review)
  157. │ │ ├── context-injection.md # What context each role receives
  158. │ │ ├── ATTACK_INDEX.md # 53 attack types mapped to skills
  159. │ │ ├── OUTPUT_STRUCTURE.md # Engagement output directory spec
  160. │ │ ├── VALIDATION.md # 5-check finding validation framework
  161. │ │ ├── GIT_CONVENTIONS.md # Branch/commit/PR standards
  162. │ │ └── PATT_STANDARD.md # PayloadsAllTheThings integration
  163. │ ├── injection/
  164. │ │ ├── SKILL.md
  165. │ │ └── reference/
  166. │ ├── reconnaissance/
  167. │ ├── server-side/
  168. │ └── ... # 27 skill directories total
  169. │
  170. ├── tools/ # ← Canonical tool integrations (source of truth)
  171. │ ├── env-reader.py
  172. │ └── slack-send.py
  173. │
  174. └── projects/ # ← Isolated project environments
  175. └── pentest/
  176. └── .claude/
  177. ├── skills/ # Real directory, contents are symlinks
  178. │ ├── injection/ → ../../../../skills/injection/
  179. │ └── ... # Each project picks what it needs
  180. └── tools/ # Real directory, contents are symlinks
  181. ├── env-reader.py → ../../../../tools/env-reader.py
  182. └── ...
  183. ```
  184. ### Why This Structure?
  185. **Canonical root directories** (`skills/`, `tools/`) hold the single source of truth for all definitions. No duplication, no drift.
  186. **Project directories** (`projects/`) are isolated environments designed to be run independently with `claude` from within the project folder. Each project has its own `.claude/` directory with real `skills/` and `tools/` folders — but the contents are **symlinks** pointing back to the canonical sources.
  187. This design gives you:
  188. - **Isolation** — Each project is a self-contained working directory. Run `claude` from `projects/pentest/` and it discovers only the skills that project has symlinked.
  189. - **Single source of truth** — Edit a skill once in `skills/`, and every project that symlinks it gets the update immediately.
  190. - **Selective inclusion** — A new project doesn't need all 23 skills. Symlink only what's relevant.
  191. - **Claude Code compatibility** — Claude Code resolves symlinks transparently via the OS.
  192. **Adding a new project:**
  193. ```bash
  194. mkdir -p projects/myproject/.claude/{skills,tools}
  195. cd projects/myproject/.claude/skills
  196. # Symlink only the skills this project needs
  197. ln -s ../../../../skills/injection injection
  198. # Coordination is a skill like any other — symlink if needed
  199. ln -s ../../../../skills/coordination coordination
  200. ln -s ../../../../skills/reconnaissance reconnaissance
  201. # ... add more as needed
  202. # Same for tools
  203. cd ../tools
  204. ln -s ../../../../tools/env-reader.py env-reader.py
  205. ```
  206. ---
  207. ## Contributing
  208. We welcome contributions from the security community!
  209. **Read the full guide:** [CONTRIBUTING.md](CONTRIBUTING.md)
  210. **Quick path using Skill Update:**
  211. ```bash
  212. /skill-update
  213. # Select: CREATE → provide details → automated GitHub workflow
  214. # Handles: issue creation, branch, skill generation, validation, commit, PR
  215. ```
  216. ---
  217. ## Security & Legal
  218. **IMPORTANT: These tools are designed for authorized security testing ONLY.**
  219. **Authorized & Legal Use:**
  220. - Penetration testing with written authorization
  221. - Bug bounty programs within scope
  222. - Security research on your own systems
  223. - CTF competitions and training environments
  224. - Educational purposes with proper permissions
  225. **Prohibited & Illegal Use:**
  226. - Unauthorized testing of any systems
  227. - Malicious exploitation of vulnerabilities
  228. - Data theft or system disruption
  229. - Any use that violates local or international laws
  230. **Users are solely responsible for compliance with all applicable laws and regulations.**
  231. ### Responsible Disclosure
  232. If you discover a vulnerability using these tools:
  233. 1. Do not exploit beyond proof-of-concept
  234. 2. Report immediately to the vendor/organization
  235. 3. Follow responsible disclosure timelines (typically 90 days)
  236. 4. Document thoroughly for remediation
  237. ---
  238. ## Community & Support
  239. - [GitHub Discussions](https://github.com/transilienceai/communitytools/discussions) — Ask questions, share ideas
  240. - [GitHub Issues](https://github.com/transilienceai/communitytools/issues) — Report bugs, request features
  241. - [Transilience.ai](https://www.transilience.ai) — See what else we're building
  242. - [LinkedIn](https://linkedin.com/company/transilienceai) — Follow our work
  243. - [Email](mailto:contact@transilience.ai) — Get in touch
  244. ---
  245. ## Project Stats
  246. | Category | Count |
  247. |----------|-------|
  248. | **Skills** | 27 |
  249. | **Role Prompts** | 3 (in coordination skill) |
  250. | **Tool Integrations** | 3 |
  251. | **Attack Types** | 53 |
  252. | **Reference Files** | 160+ |
  253. **Coverage:**
  254. - OWASP Top 10 (2021) — 100%
  255. - OWASP LLM Top 10 (2025) — 100%
  256. - SANS Top 25 CWE — 90%+
  257. - MITRE ATT&CK TTPs — mapped for all findings
  258. ---
  259. ## License
  260. MIT License — Copyright (c) 2026 Transilience AI. See [LICENSE](LICENSE) for details.
  261. ---
  262. ## Contributors
  263. <a href="https://github.com/transilienceai/communitytools/graphs/contributors">
  264. <img src="https://contrib.rocks/image?repo=transilienceai/communitytools" />
  265. </a>
  266. ---
  267. <div align="center">
  268. **Built by [Transilience AI](https://www.transilience.ai)**
  269. We build AI-driven cloud security and compliance automation. These open-source tools reflect how we think about security — if you're curious about the platform behind them, [take a look](https://www.transilience.ai).
  270. [![Star this repository](https://img.shields.io/badge/Star%20this%20repo-yellow?style=for-the-badge)](https://github.com/transilienceai/communitytools)
  271. [Website](https://www.transilience.ai) | [Issues](https://github.com/transilienceai/communitytools/issues) | [Discussions](https://github.com/transilienceai/communitytools/discussions)
  272. `claude-code` `ai-security` `penetration-testing` `bug-bounty` `owasp` `llm-security` `ai-threat-testing` `security-automation` `ethical-hacking` `cybersecurity` `appsec` `web-security` `hackerone` `hackthebox` `multi-agent`
  273. </div>
.claude/workflows/pentest-engagement.js · Bundled script · 1,547 lines · 1 finding marked
  1. export const meta = {
  2. name: 'pentest-engagement',
  3. description: 'Orchestrate a scoped penetration engagement end-to-end. THREE auto-detected modes. MOBILE (a .apk/.aab/.ipa artifact, app-store id, or package/bundle id): acquire + hash + decompile, deterministic SAST, then emit TWO separately-gated surfaces — the app bundle (MASVS/MASTG classes) AND the backend API recovered FROM the bundle (the ordinary OWASP API classes, because that half is not browser-reachable and is systematically under-tested) — plus an emulator/simulator DAST preflight whose only way past the gate is a real device or a machine-verified obstruction. WEB (apex domains / app URLs): MANDATORY surface expansion (CT-log/passive-DNS/origin-discovery) -> per-asset OWASP attack-class coverage loop -> validate. NETWORK (a list of IPs/CIDRs, e.g. 1500 hosts): a machine-prudent, BATCHED, tool-first nmap sweep — host discovery (reachability unknown) + full-range -p- port/service scan on every reachable host (message-bus + non-443-TLS aware; light profile = bounded for large/fast sweeps) + CVE surfacing + a source-IP/geo-allowlist auto-probe from a 2nd geography — writing a UNIFORM per-IP output tree, then bounded coordinator-loop deep-dives on ONLY the highest-value hosts -> validate. Both modes then stitch cross-asset attack paths + risk-rank -> Transilience PDF. Completion gates on coverage (web) / scan-completion (network), not flags.',
  4. whenToUse: 'Run a professional pentest, a network vulnerability scan, or a mobile app assessment (MAPT) from a scope. MOBILE: {scope_file naming a .apk/.aab/.xapk/.apks/.ipa, or inline {mobile_artifacts:[{path,platform}]} / {apk:"..."} / {ipa:"..."}}; options {mobile_platform:"android|ios|both", device_serial, emulator}. A mobile scope that ALSO names apex domains keeps its web half (surface expansion runs alongside the bundle-recovered backends). There is deliberately no flag that skips DAST. WEB: {scope_file} or {scope:{engagement_name,apex_domains[],assets[],creds_env[],roe,business_tier}}. NETWORK: a scope listing IPs/CIDRs/ranges (inline {targets:["10.0.0.0/24","192.0.2.5",...]} or scope_file with a newline list, or assets of type ip/network); the workflow detects it and runs the batched nmap sweep — agents scale with SLICES (dozens), never with IP count. Options: {maxConcurrent (default = prudent, derived from CPU cores — never hundreds/thousands of parallel tasks), scan_profile:"light|standard|full" (default standard = full-range -p- on every reachable host; light = bounded 1-1024 + curated less-common for large/fast sweeps; full = -p- + UDP), udp, slice_size, deepen_top (default 10 deep-dives, 0 to skip), geo_vantages (<=2 gcp zones for the 2nd-vantage allowlist re-probe; overrides the US+EU default), auto_provision (default true; false = detect+flag, no cloud spend), dryRun, max_experiments, business_tier, report}. On a source-IP/geo-allowlist signature the workflow auto-provisions a 2nd-geography vantage and re-probes the filtered hosts. Parent ORCHESTRATOR; coordinator-loop + validate-findings are the engines. Sibling to htb-solve.',
  5. phases: [
  6. { title: 'Setup', detail: 'creds (env-reader), parse scope, classify kind (web|network), read CPU cores -> prudent parallel-task cap, OUTPUT_DIR base projects/pentest/, STARTED Slack' },
  7. { title: 'Expand', detail: 'WEB: MANDATORY surface expansion (CT-log/passive-DNS/origin-discovery) across every apex; merge handoff + discovered hosts into the work list; seed per-asset coverage matrix' },
  8. { title: 'Scan', detail: 'NETWORK: slice the IP/CIDR set into machine-prudent batches; one nmap worker per slice (host discovery + bounded common+less-common port/service scan + CVE surfacing); uniform per-IP output tree' },
  9. { title: 'Acquire', detail: 'MOBILE: acquire+hash the .apk/.aab/.ipa, fingerprint the framework, decompile (apktool/jadx/hermes-dec/plutil) + deterministic SAST (mobile_manifest_facts.py, apk_control_wiring.py), recover the backend endpoint table, and emit BOTH gated surfaces via mobile_surface_build.py — the app bundle (mobile-surface/v1) AND the backend it talks to (surface/v2)' },
  10. { title: 'Device', detail: 'MOBILE: tools/mobile_device_check.py emulator/simulator preflight (adb/simctl, API level, root, frida-server, MITM CA), then instrumented bring-up. Only exit 0 is ready; anything else must produce a machine-verified obstruction record + a client-input request — there is no flag that skips DAST' },
  11. { title: 'GeoProbe', detail: 'NETWORK: on a source-IP/geo-allowlist signature, auto-provision a 2nd-geography vantage and re-probe the filtered hosts' },
  12. { title: 'Infra', detail: 'WEB: bounded probes of scope-adjacent infrastructure surfaced during expansion' },
  13. { title: 'Assess', detail: 'WEB: per asset coordinator-loop (coverage) -> validate-findings. NETWORK: bounded coordinator-loop deep-dives on ONLY the highest-value hosts. MOBILE: one fan-out over both surfaces — the app bundle (platform:mobile, MASVS classes) and every recovered backend (platform:web, API classes)' },
  14. { title: 'Correlate', detail: 'attack-path-stitcher across all validated findings -> risk-prioritiser -> ranked org roadmap' },
  15. { title: 'Report', detail: 'Transilience PDF over the validated+ranked set; gated COMPLETE (web: coverage; network: scan completion; mobile: both surfaces emitted AND DAST resolved — run or substantiated-deferred)' },
  16. ],
  17. }
  18. // ============================================================================
  19. // PENTEST-ENGAGEMENT — the general web/API/cloud analogue of htb-solve.
  20. //
  21. // Architecture (faithful to skills/coordination + the gap-analysis fixes):
  22. // ORCHESTRATOR = this workflow. Owns creds, scope parsing, OUTPUT_DIR, the
  23. // MANDATORY surface-expansion phase, cross-asset correlation,
  24. // the Transilience report, and the coverage-gated COMPLETE
  25. // decision. The only layer allowed to touch Slack.
  26. // COORDINATOR = the `coordinator-loop` workflow in COVERAGE mode, run once
  27. // per asset via workflow() (one level of nesting). It runs the
  28. // recon/think/execute/integrate loop driven by the attack-class
  29. // coverage matrix, with reversible-active-exploitation + root-
  30. // cause severity, and writes a Transilience per-asset source.
  31. // VALIDATOR = the `validate-findings` workflow (sibling, one level below),
  32. // reused VERBATIM as the authoritative per-asset validator.
  33. //
  34. // Pipeline (no barrier within Assess): each asset flows assess -> validate
  35. // independently; targets chunked by maxConcurrent. Correlate + Report run after
  36. // the Assess barrier (they need every asset's validated set).
  37. //
  38. // AGENT-CAP NOTE: child workflows SHARE this run's 1000-agent lifetime counter.
  39. // Each coordinator-loop runs to CONVERGENCE (full coverage + a dry tail), backstopped
  40. // by an honest per-asset agent slice (assessBudget.perAsset). Because a run cannot
  41. // exceed 1000 agents, resumeSchedule converges only as many assets as fit their slice
  42. // this run and DEFERS the rest to a resume run (resume_dir), reserving headroom for
  43. // Expand + Correlate + Report.
  44. //
  45. // Sandbox: no Date.now()/Math.random()/new Date() — agents shell out to `date`.
  46. // ============================================================================
  47. // ---- helpers ---------------------------------------------------------------
  48. function chunk(arr, n) {
  49. const out = []
  50. for (let i = 0; i < arr.length; i += n) out.push(arr.slice(i, i + n))
  51. return out
  52. }
  53. // ============================================================================
  54. // DETERMINISTIC HELPERS — inline copy of .claude/workflows/lib/wf-helpers.mjs
  55. // (sandbox has no import). Kept logic-identical; parity.test.mjs guards drift.
  56. // ============================================================================
  57. const SEVERITY = ['Critical', 'High', 'Medium', 'Low', 'Info']
  58. function severityBand(score) {
  59. const s = Number(score)
  60. if (!(s > 0)) return 'Info'
  61. if (s >= 9.0) return 'Critical'
  62. if (s >= 7.0) return 'High'
  63. if (s >= 4.0) return 'Medium'
  64. return 'Low'
  65. }
  66. function normalizeAssess(v, asset) {
  67. const lo = v || {}
  68. const degraded = !!(lo.blocked_reason || lo.status === 'FAILED' || lo.coverage_status === 'FAILED')
  69. return {
  70. tag: asset.tag, key: asset.key, output_dir: asset.output_dir || lo.output_dir || null, type: asset.type || null,
  71. business_tier: asset.business_tier || null,
  72. coverage_status: lo.coverage_status || lo.status || 'UNKNOWN',
  73. coverage_ratio: typeof lo.coverage_ratio === 'number' ? lo.coverage_ratio : null,
  74. findings_total: lo.findings_total != null ? lo.findings_total : (Array.isArray(lo.findings_confirmed) ? lo.findings_confirmed.length : 0),
  75. validation: lo.validation || null, degraded,
  76. blocked_reason: lo.blocked_reason || (degraded ? 'assessment degraded' : null),
  77. }
  78. }
  79. function reconcileAssessed(expected, assessed, keyOf) {
  80. const seen = new Set(assessed.map((a) => a.key))
  81. const backfilled = expected.filter((e) => !seen.has(keyOf(e))).map((e) => ({
  82. tag: e.tag, key: keyOf(e), output_dir: e.output_dir || null, type: e.type || null,
  83. business_tier: e.business_tier || null, coverage_status: 'MISSING', coverage_ratio: null,
  84. findings_total: 0, validation: null, degraded: true, blocked_reason: 'no result returned',
  85. }))
  86. const all = assessed.concat(backfilled)
  87. const gaps = all.filter((a) => a.degraded || a.coverage_status !== 'COVERAGE_COMPLETE')
  88. return { all, backfilled, gaps, complete: gaps.length === 0 }
  89. }
  90. function finalizeGate({ report_data_ok, report_data_lint_ok, renderGateOk, coverage_complete, coverage_untested, renderBlockedReason }) {
  91. const ok = !!(report_data_ok && report_data_lint_ok && renderGateOk && coverage_complete)
  92. const blocked_reason = ok ? null
  93. : !report_data_ok ? 'report_data_build failed'
  94. : !report_data_lint_ok ? 'report_data lint failed (schema/escaping)'
  95. : !renderGateOk ? (renderBlockedReason || 'render failed')
  96. : `attack-class coverage < 100% (${coverage_untested} cell(s) untested)`
  97. return { ok, status: ok ? 'COMPLETE' : 'BLOCKED', blocked_reason }
  98. }
  99. function bumpVersion(priorVersion) {
  100. if (!priorVersion) return 'v1.0'
  101. const m = String(priorVersion).match(/v?(\d+)(?:\.(\d+))?/i)
  102. if (!m) return 'v1.0'
  103. return `v${Number(m[1]) + 1}.0`
  104. }
  105. function scopeDiff(priorScope, currentScope) {
  106. const P = new Set((priorScope || []).map(String))
  107. const C = new Set((currentScope || []).map(String))
  108. const added = [...C].filter((x) => !P.has(x)).sort()
  109. const removed = [...P].filter((x) => !C.has(x)).sort()
  110. const unchanged = [...C].filter((x) => P.has(x)).sort()
  111. return { added, removed, unchanged, changed: added.length > 0 || removed.length > 0 }
  112. }
  113. // Prompt > prior > default. Prior SCOPE is METADATA-ONLY (display diff, never a work list).
  114. function resolveEngagementMeta({ prior, prompt, currentScope, dateTag, explicitVersion } = {}) {
  115. const p = prior || {}, pr = prompt || {}
  116. const pick = (k) => (pr[k] != null && pr[k] !== '' ? pr[k] : p[k]) || null
  117. const meta = {}
  118. for (const k of ['title', 'title_lines', 'subtitle', 'sector', 'target', 'classification', 'method', 'prepared_by', 'duration']) meta[k] = pick(k)
  119. meta.version = explicitVersion || bumpVersion(p.version || ((p.report_id || '').match(/v\d+(\.\d+)?/i) || [])[0])
  120. meta.supersedes = p.report_id || p.version || null
  121. const base = (meta.title || meta.sector || 'ENGAGEMENT').replace(/[^A-Za-z0-9]+/g, '-').slice(0, 24).toUpperCase().replace(/-+$/, '')
  122. meta.report_id = pr.report_id || `${base}-${dateTag || '000000'}-${meta.version}`
  123. meta.scope_changes = scopeDiff(p.scope, currentScope)
  124. return meta
  125. }
  126. // Source-IP/geo-allowlist SIGNATURE from per-slice scan results. The cost-bound
  127. // discriminator is the workers' filtered[] set (existence-confirmed-but-dark
  128. // hosts); genuinely-down hosts stay in dead_count and never fire it.
  129. function detectAllowlist(sliceResults) {
  130. const slices = Array.isArray(sliceResults) ? sliceResults : []
  131. const liveCount = slices.reduce((n, s) => n + ((s && Array.isArray(s.live)) ? s.live.length : 0), 0)
  132. const filteredHosts = []
  133. const seen = new Set()
  134. for (const s of slices) {
  135. for (const f of ((s && Array.isArray(s.filtered)) ? s.filtered : [])) {
  136. if (f && f.ip && !seen.has(f.ip)) { seen.add(f.ip); filteredHosts.push({ ip: f.ip, signal: f.signal || 'host-up-but-all-filtered' }) }
  137. }
  138. }
  139. return { signature: liveCount >= 1 && filteredHosts.length >= 1, filteredHosts }
  140. }
  141. // Resolve the <=2 second-vantage gcp ZONES. Explicit geoVantages honored (dedup
  142. // + cap 2); else the default US+EU pair minus the primary's continent.
  143. function resolveGeoZones({ geoVantages, primaryGeo } = {}) {
  144. const DEFAULTS = ['us-central1-a', 'europe-west1-b']
  145. const dedupCap = (zs) => { const o = []; for (const z of zs) { if (!o.includes(z)) o.push(z); if (o.length === 2) break } return o }
  146. const override = (Array.isArray(geoVantages) ? geoVantages : []).map((s) => (s == null ? '' : String(s).trim())).filter(Boolean)
  147. if (override.length) return dedupCap(override)
  148. const primary = String(primaryGeo || '').toUpperCase()
  149. const US = ['US', 'CA', 'MX']
  150. const EU = ['DE', 'NL', 'ES', 'FR', 'IT', 'GB', 'UK', 'IE', 'BE', 'CH', 'AT', 'SE', 'NO', 'FI', 'DK', 'PL', 'PT', 'CZ', 'RO', 'HU', 'GR']
  151. const cont = US.includes(primary) ? 'us' : (EU.includes(primary) ? 'eu' : null)
  152. const regionOf = (z) => (z.startsWith('us-') || z.startsWith('northamerica-')) ? 'us' : (z.startsWith('europe-') ? 'eu' : 'other')
  153. const kept = cont ? DEFAULTS.filter((z) => regionOf(z) !== cont) : DEFAULTS.slice()
  154. return dedupCap(kept.length ? kept : DEFAULTS)
  155. }
  156. // How many INCOMPLETE assets to fully converge THIS run so each gets a real agent
  157. // slice and the worst-case total stays under the runtime cap; the rest defer to a
  158. // resume run. Always runs >=1 when any work remains (else the engagement stalls).
  159. function resumeSchedule({ incompleteCount, agentCap, deepSlice, overhead } = {}) {
  160. const cap = Math.max(0, Math.floor(Number(agentCap) || 0) - Math.max(0, Math.floor(Number(overhead) || 0)))
  161. const slice = Math.max(1, Math.floor(Number(deepSlice) || 1))
  162. const capacity = Math.floor(cap / slice)
  163. const inc = Math.max(0, Math.floor(Number(incompleteCount) || 0))
  164. const assetsThisRun = inc === 0 ? 0 : Math.max(1, Math.min(inc, capacity))
  165. return { assetsThisRun, deferred: inc - assetsThisRun }
  166. }
  167. // Tri-state engagement status from the per-asset rows + the deferred (not-run-this-
  168. // run) tags. A genuinely-stuck asset (INCOMPLETE_COVERAGE / degraded) blocks COMPLETE
  169. // and is surfaced for a human; resumable + deferred assets (and stuck ones, retried
  170. // each run) populate the resume list that drives the next run.
  171. function classifyEngagement(assetRows, deferredTags) {
  172. const rows = Array.isArray(assetRows) ? assetRows : []
  173. const stuck = rows.filter((r) => r && (r.coverage_status === 'INCOMPLETE_COVERAGE' || r.degraded)).map((r) => r.tag)
  174. const resumable = rows.filter((r) => r && r.coverage_status === 'INCOMPLETE_RESUMABLE').map((r) => r.tag)
  175. const remaining = [...new Set([...resumable, ...stuck, ...(Array.isArray(deferredTags) ? deferredTags : [])])]
  176. const engagement_status = stuck.length ? 'INCOMPLETE_coverage' : (remaining.length ? 'INCOMPLETE_resumable' : 'COMPLETE')
  177. const resume = remaining.length
  178. ? { remaining_assets: remaining, deferred_reason: stuck.length ? 'mixed: stuck + deferred' : 'agent-slice / per-run budget', rerun_hint: 'resume_dir=<engagement_dir>' }
  179. : { remaining_assets: [], deferred_reason: null, rerun_hint: null }
  180. return { engagement_status, resume }
  181. }
  182. // ============================================================================
  183. // finalizeEngagement — the deterministic Report -> Package -> Summarize lane,
  184. // shared by WEB and NETWORK. NO agent authors the report_data or the PDF: JS
  185. // hands the engagement block + exact commands to ONE tool-runner, which writes
  186. // engagement-meta.json verbatim, runs tools/report_data_build.py (the sole-owner
  187. // assembler), the format-dispatched renderer, and the packager — and reports the
  188. // real facts. JS then hard-gates on those facts.
  189. // ============================================================================
  190. const FINALIZE_SCHEMA = {
  191. type: 'object', additionalProperties: true,
  192. required: ['report_data_ok', 'findings', 'render_ok'],
  193. properties: {
  194. report_data_ok: { type: 'boolean' }, report_data_path: { type: 'string' }, report_data_sha: { type: 'string' },
  195. report_data_lint_ok: { type: 'boolean', description: 'tools/report_data_lint.py exited 0 (schema + RAW-field escaping/tag-allowlist gate before render)' },
  196. report_data_lint_errors: { type: 'array', items: { type: 'string' } },
  197. netscan_sound: { type: 'boolean', description: 'tools/netscan_guard.py found no host-timeout-truncation signature over the slice service XMLs' },
  198. netscan_rescan_hosts: { type: 'array', items: { type: 'string' }, description: '0-open up-hosts under --host-timeout to re-scan before calling dead' },
  199. netscan_notes: { type: 'array', items: { type: 'string' } },
  200. coverage_deferred: { type: 'number', description: 'count of client-input-deferred coverage cells (MFA/OTP/allowlist), disclosed in the report' },
  201. exports_ok: { type: 'boolean', description: 'tools/report_export.py produced both the CSV and XML machine-readable findings exports' },
  202. export_paths: { type: 'array', items: { type: 'string' }, description: 'the CSV/XML export paths that landed in the deliverable zip' },
  203. findings: { type: 'number' }, demoted: { type: 'number' }, severity_counts: { type: 'object', additionalProperties: true },
  204. render_ok: { type: 'boolean' }, report_path: { type: 'string' }, pdf_bytes: { type: 'number' },
  205. assets_provenance: { type: 'boolean', description: 'generate_report printed the [assets: .../formats/transilience-report-style] tag' },
  206. zip_ok: { type: 'boolean' }, deliverable_zip: { type: 'string' }, zip_entries: { type: 'number' },
  207. protect_ok: { type: 'boolean', description: 'an AES-256 password-protected deliverable was produced' },
  208. protected_zip: { type: ['string', 'null'] }, protected_pdf: { type: ['string', 'null'] },
  209. deliverable_password: { type: ['string', 'null'], description: 'the AES-256 passphrase (relay OUT-OF-BAND; also in <dir>/DELIVERABLE-PASSWORD.txt, excluded from the zip)' },
  210. protection_algos: { type: ['string', 'null'] }, protection_limitations: { type: 'array', items: { type: 'string' } },
  211. summary_path: { type: 'string' }, elapsed: { type: 'string' }, generator_stdout: { type: 'string' },
  212. tools_used_count: { type: 'number' }, source_ips_count: { type: 'number' }, reconciliation_gaps: { type: 'array', items: { type: 'string' } },
  213. coverage_complete: { type: 'boolean', description: 'the deterministic coverage gate reported reports/coverage-matrix.json "complete":true' },
  214. coverage_ratio: { type: ['number', 'null'] }, coverage_untested: { type: 'number', description: 'count of missing_cells from the gate' },
  215. // CERT-In Audit Metadata export (additional, non-blocking deliverable; only present when certin_export:true).
  216. certin_ok: { type: 'boolean', description: 'the CERT-In metadata build exited 0' },
  217. certin_json: { type: ['string', 'null'] }, certin_xlsx: { type: ['string', 'null'] },
  218. certin_needs_manual: { type: 'array', items: { type: 'string' }, description: 'CERT-In fields still needing a manual value' },
  219. },
  220. }
  221. async function finalizeEngagement(opts) {
  222. const { engagementDir, engagement, reportFormat, customReportCmd, engagementStatus, agentCount, conclusion } = opts
  223. const fmt = reportFormat === 'custom' ? 'custom' : 'transilience'
  224. // CERT-In Audit Metadata: an ADDITIONAL, NON-BLOCKING deliverable produced alongside the
  225. // report when the engagement declared certin_export:true. It never enters finalizeGate.
  226. const wantCertin = opts.certinExport === true
  227. const certinCfgJson = (wantCertin && opts.certin && typeof opts.certin === 'object') ? JSON.stringify(opts.certin) : null
  228. const certinInstr = wantCertin
  229. ? `\n2c. (CERT-In Audit Metadata export — ADDITIONAL deliverable, NON-BLOCKING; MUST run before step 5 so both files land in the zip) ${certinCfgJson ? `First, if ${engagementDir}/input/certin.json does NOT already exist, \`mkdir -p ${engagementDir}/input\` and write this EXACT JSON to ${engagementDir}/input/certin.json (do not infer/add fields): ${certinCfgJson}. ` : ''}Then run EXACTLY \`python3 tools/certin_metadata_build.py --engagement-dir ${engagementDir}\`. It prints a JSON summary on its last stdout line — set certin_ok iff exit 0, certin_json=its "out", certin_xlsx=its "xlsx", certin_needs_manual=its "needs_manual". A non-zero exit or ANY error is NOT an engagement failure: set certin_ok=false, append one line to ${engagementDir}/reports/summary.md ("CERT-In export: failed — <reason>"), and CONTINUE. NEVER let certin_* affect zip_ok, render_ok, coverage_complete, or any gate.\n`
  230. : ''
  231. const wantProtect = opts.protect !== false // default ON: also emit an AES-256 password-protected copy
  232. const engBlockJson = JSON.stringify(engagement, null, 2)
  233. const conclJson = conclusion ? JSON.stringify(conclusion, null, 2) : null
  234. const reportId = engagement.report_id || 'engagement'
  235. const zipName = `${reportId}_deliverable.zip`
  236. const pdfRel = fmt === 'custom' ? 'reports/report.md' : 'reports/Penetration-Test-Report.pdf'
  237. // Step 6: a deterministic AES-256 protected copy (qpdf/pypdf for the PDF, 7z for the zip),
  238. // ALONGSIDE the plaintext PDF+zip. AES-256 or nothing (no weak ZipCrypto). The password is
  239. // auto-generated, printed for OUT-OF-BAND relay, and written to a root file EXCLUDED from the zip.
  240. const protectInstr = wantProtect
  241. ? `\n6. PASSWORD-PROTECT the deliverable (AES-256; the plaintext PDF+zip are KEPT): run EXACTLY \`python3 tools/protect_deliverable.py --engagement-dir ${engagementDir} --report-id ${reportId} --pdf ${pdfRel}\`. It prints a JSON summary — set protect_ok=its "ok", protected_zip=its "protected_zip", protected_pdf=its "protected_pdf", deliverable_password=its "password", protection_algos=(its "protected_zip_algo" + " / " + its "protected_pdf_algo"), protection_limitations=its "limitations". The password is ALSO written to ${engagementDir}/DELIVERABLE-PASSWORD.txt (chmod 600, at the engagement ROOT so it is EXCLUDED from the zip). Then APPEND ONE line to ${engagementDir}/reports/summary.md: "Protected deliverable: <basename of protected_zip> (AES-256) — password in DELIVERABLE-PASSWORD.txt at the engagement root; share it OUT-OF-BAND". NEVER write the password VALUE into summary.md or into any file under reports/input/logs/artifacts.\n`
    • Note: Quoted as data in code: Asks you to extract a password-protected archive, the usual way malware droppers get past scanners
    • Line 245 on GitHub
  242. : '\n6. (protection disabled) set protect_ok=false, protected_zip=null, protected_pdf=null, deliverable_password=null, protection_limitations=["protection disabled by caller"].\n'
  243. const genCmd = `python3 skills/transilience-report-style/reference/generate_report.py ${engagementDir}/reports/report_data.json -o ${engagementDir}/reports/Penetration-Test-Report.pdf`
  244. const renderInstr = fmt === 'custom' && customReportCmd
  245. ? `Custom render: run \`${customReportCmd}\` (it receives ${engagementDir}/reports/report_data.json and writes into ${engagementDir}/reports/). render_ok iff it exits 0 and produced a non-empty output file; assets_provenance=false.`
  246. : fmt === 'custom'
  247. ? `Custom format, no command given: the report_data.json IS the deliverable; also write ${engagementDir}/reports/report.md (a plain Markdown render of report_data.json). Every finding in report.md MUST always show BOTH its CVSS score (numeric, or \`n/a\` when no CVSS applies) AND its severity label (Critical/High/Medium/Low/Info) — never omit either. render_ok iff report.md is non-empty; assets_provenance=false; pdf_bytes=0.`
  248. : `Transilience PDF (the ONE canonical skill): run EXACTLY \`${genCmd}\`. Parse its stdout line \`WROTE <path> (<bytes> bytes) [assets: <dir>]\`: render_ok iff it printed WROTE and bytes>0; pdf_bytes=<bytes>; assets_provenance=true iff the \`[assets: .../formats/transilience-report-style]\` tag is present; report_path=<path>; put the full line in generator_stdout.`
  249. const runner = await agent(
  250. `ROLE: FINALIZE RUNNER (deterministic; run the given commands, report facts — do NOT compose or judge report content). cwd is repo root.\n` +
  251. `ENGAGEMENT_DIR: ${engagementDir}\nFORMAT: ${fmt}\n\n` +
  252. `1. MERGE engagement metadata (do NOT clobber Setup's file): read ${engagementDir}/engagement-meta.json if it exists (Setup wrote {engagement_name, started, roe, ...}); set its "engagement" key to EXACTLY this object (verbatim)${conclJson ? ' AND its "conclusion" key to the conclusion object below' : ''}, preserving every other existing key; write it back:\nengagement = ${engBlockJson}\n${conclJson ? `conclusion = ${conclJson}\n` : ''}\n` +
  253. `1a. SCAN-SOUNDNESS GUARD (network mode; a harmless no-op when there are no scans): run EXACTLY \`python3 tools/netscan_guard.py --xml '${engagementDir}/recon/slice-*-services.xml' --suppress-cves\`. It exits 0 (SOUND) / 20 (UNSOUND — a --host-timeout connect scan left up-hosts at 0 open, i.e. possible truncation, NOT proof of "dead") / 3 (no XML). Set netscan_sound = (exit != 20). If UNSOUND, set netscan_rescan_hosts = its guards.host_timeout_truncation.rescan_hosts and add one netscan_notes line per host ("netscan: <ip> 0-open under --host-timeout — re-scan before calling it dead"). Also add any guards.udp_states.ambiguous_open_filtered as a netscan_notes "open|filtered ≠ open" line. This records the caveat so an all-zero host is never silently reported clean/dead; finalize does NOT re-scan.\n` +
  254. `1b. DETERMINISTIC COVERAGE GATE (MUST run before step 2 so the Attack Pattern Coverage section is populated): run EXACTLY \`python3 tools/network_coverage_map.py --engagement-dir ${engagementDir}\` (writes swept-host cell evidence for any network hosts; a harmless no-op when there are no hosts/), then run EXACTLY \`python3 tools/coverage_gate.py --engagement-dir ${engagementDir} --accept-deferrals\` (it enumerates the applicable (surface-unit × attack-class) cells by code and writes ${engagementDir}/reports/coverage-matrix.json; --accept-deferrals lets a SUBSTANTIATED MFA/OTP/allowlist-deferred cell finalize COMPLETE-with-caveat — an all-deferred scope still never completes). Do NOT treat a non-zero exit as a failure — READ that JSON and set coverage_complete = its "complete" boolean, coverage_ratio = its "coverage_ratio", coverage_untested = the length of its "missing_cells" array, coverage_deferred = its "deferred".\n\n` +
  255. `2. Assemble the canonical report_data.json (the sole-owner merge — no LLM authoring): run EXACTLY \`python3 tools/report_data_build.py --engagement-dir ${engagementDir} -o ${engagementDir}/reports/report_data.json\`. It prints a JSON summary — set report_data_ok iff exit 0, and copy its findings/demoted/severity_counts/sha256(->report_data_sha)/out(->report_data_path). ALSO copy tools_used_count, source_ips_count, and reconciliation_gaps from that same printed JSON summary into the return.\n\n` +
  256. `2b. REPORT-DATA LINT (HARD GATE before render): run EXACTLY \`python3 tools/report_data_lint.py ${engagementDir}/reports/report_data.json\`. Set report_data_lint_ok iff exit 0. If it exits non-zero, copy its printed errors[] into report_data_lint_errors and DO NOT render (skip step 3) — a report_data with a bare '&'/disallowed tag (\`<img>\`/\`<a href>\`) in a RAW field, a string-not-list narrative, or an invalid severity must never reach the client PDF. (generate_report.py also fail-closes on the crash-invariants, but this is the richer gate.)\n\n` +
  257. certinInstr +
  258. `3. Render. ${renderInstr}\n\n` +
  259. `3b. MACHINE-READABLE EXPORTS (ADDITIONAL deliverables, NON-BLOCKING; MUST run before step 5 so both files land in the zip): run EXACTLY \`python3 tools/report_export.py ${engagementDir}/reports/report_data.json --format csv -o ${engagementDir}/reports/findings.csv\` and then EXACTLY \`python3 tools/report_export.py ${engagementDir}/reports/report_data.json --format xml -o ${engagementDir}/reports/findings.xml\`. Set exports_ok iff BOTH exit 0, and export_paths to the two paths that exist. A non-zero exit is NOT an engagement failure: set exports_ok=false, append one line to ${engagementDir}/reports/summary.md ("Machine-readable exports: failed — <reason>"), and CONTINUE. NEVER let exports_* affect zip_ok, render_ok, coverage_complete, or any gate. These are the same rows as the PDF's findings register — a projection, never a re-derivation.\n\n` +
  260. `4. Summary: write ${engagementDir}/reports/summary.md — a SHORT stats block: engagement_status=${engagementStatus}; agents=${agentCount != null ? agentCount : 'unavailable'}; findings + the severity_counts from step 2; tokens/cost="unavailable (no runtime token counter)"; elapsed = the human duration (e.g. "18m 42s") from engagement-meta.json's "started" ISO timestamp to now — compute with \`python3 -c "import datetime as d,json; s=json.load(open('${engagementDir}/engagement-meta.json')).get('started'); t=(d.datetime.now(d.timezone.utc)-d.datetime.fromisoformat(s.replace('Z','+00:00'))).total_seconds(); print(f'{int(t//60)}m {int(t%60)}s')"\` (else "unavailable"). ALSO include an "Activity log" line noting tools_used_count tools captured and source_ips_count source IP(s); if reconciliation_gaps (from step 2) is non-empty, add a line "⚠ egress-reconciliation gaps: <the gaps>". If netscan_sound (from step 1a) is false, add a line "⚠ scan-soundness: re-scan <netscan_rescan_hosts> before calling them dead" plus each netscan_notes line. If coverage_deferred (from step 1b) > 0, add a line "ℹ deferred coverage: <coverage_deferred> cell(s) pending client input (MFA/OTP/test account) — see the coverage-matrix.json deferred_cells". Return that elapsed string.\n\n` +
  261. `5. Package the deliverable (idempotent, directory-based so empty globs never fail): run EXACTLY \`cd ${engagementDir} && rm -f ${zipName}; zip -r ${zipName} reports input logs artifacts -x "*tool-invocations.jsonl" 2>/dev/null; unzip -l ${zipName} | tail -1\`. (Any of those dirs may be absent — zip warns and continues; reports/ always exists.) zip_ok iff the zip exists and is non-empty; deliverable_zip=${engagementDir}/${zipName}; zip_entries = the trailing "<N> files" count from \`unzip -l ... | tail -1\`.\n` +
  262. protectInstr +
  263. `\nReturn FINALIZE_SCHEMA with the real facts.`,
  264. { schema: FINALIZE_SCHEMA, agentType: 'general-purpose', label: 'finalize', phase: 'Report' }
  265. ).catch((err) => ({ report_data_ok: false, findings: 0, render_ok: false, _error: String(err) }))
  266. // JS HARD GATES on the runner's reported facts — including the deterministic
  267. // attack-class coverage gate (fails closed: a missing/false coverage_complete blocks).
  268. const r = runner || {}
  269. const renderGateOk = fmt === 'custom' ? !!r.render_ok : (r.render_ok && Number(r.pdf_bytes) > 0 && r.assets_provenance)
  270. const renderBlockedReason = !r.render_ok ? 'render failed' : Number(r.pdf_bytes) > 0 ? 'missing branded-assets provenance' : 'PDF is empty'
  271. const coverageUntested = Number(r.coverage_untested) || 0
  272. const gate = finalizeGate({ report_data_ok: r.report_data_ok, report_data_lint_ok: r.report_data_lint_ok, renderGateOk, coverage_complete: r.coverage_complete, coverage_untested: coverageUntested, renderBlockedReason })
  273. return {
  274. ok: gate.ok,
  275. status: gate.status,
  276. blocked_reason: gate.blocked_reason,
  277. format: fmt,
  278. report_data_path: r.report_data_path || `${engagementDir}/reports/report_data.json`,
  279. report_path: r.report_path || `${engagementDir}/reports/Penetration-Test-Report.pdf`,
  280. findings: Number(r.findings) || 0, demoted: Number(r.demoted) || 0, severity_counts: r.severity_counts || {},
  281. pdf_bytes: Number(r.pdf_bytes) || 0,
  282. coverage_complete: r.coverage_complete === true, coverage_ratio: r.coverage_ratio != null ? r.coverage_ratio : null, coverage_untested: coverageUntested,
  283. deliverable_zip: r.zip_ok ? (r.deliverable_zip || `${engagementDir}/${zipName}`) : null,
  284. protected_zip: wantProtect ? (r.protected_zip || null) : null,
  285. protected_pdf: wantProtect ? (r.protected_pdf || null) : null,
  286. deliverable_password: wantProtect ? (r.deliverable_password || null) : null,
  287. password_file: wantProtect && (r.protected_zip || r.protected_pdf) ? `${engagementDir}/DELIVERABLE-PASSWORD.txt` : null,
  288. protection_algos: wantProtect ? (r.protection_algos || null) : null,
  289. protection_limitations: r.protection_limitations || [],
  290. // CERT-In export facts (additional, non-blocking — never part of gate.ok/status/slack_offer).
  291. certin_ok: wantCertin ? (r.certin_ok === true) : false,
  292. certin_json: wantCertin ? (r.certin_json || null) : null,
  293. certin_xlsx: wantCertin ? (r.certin_xlsx || null) : null,
  294. certin_needs_manual: wantCertin ? (r.certin_needs_manual || []) : [],
  295. summary: { engagement_status: engagementStatus, agents: agentCount != null ? agentCount : 'unavailable', findings: Number(r.findings) || 0, severity_counts: r.severity_counts || {}, tokens: 'unavailable (no runtime token counter)', cost: 'unavailable (no runtime token counter)', elapsed: r.elapsed || 'unavailable', tools_used_count: Number(r.tools_used_count) || 0, source_ips_count: Number(r.source_ips_count) || 0, reconciliation_gaps: r.reconciliation_gaps || [], coverage_ratio: r.coverage_ratio != null ? r.coverage_ratio : null, coverage_untested: coverageUntested, summary_path: r.summary_path || `${engagementDir}/reports/summary.md`, protected_zip: wantProtect ? (r.protected_zip || null) : null, deliverable_password: wantProtect ? (r.deliverable_password || null) : null },
  296. // Slack stays gated on a clean gate, deliberately: a completion ping must signal
  297. // a finished engagement, not a status update for a stalled one.
  298. slack_offer: gate.ok,
  299. // The blocked state was previously invisible in the RESULT too — a non-OK gate
  300. // returned no reason and no next step, so a stalled cycle looked like a quiet
  301. // one. These make it legible to the operator without turning it into a ping.
  302. status_signal: gate.ok ? 'GREEN' : (r.report_data_ok ? 'AMBER' : 'RED'),
  303. blocked_reason: gate.ok ? null : (gate.blocked_reason || engagementStatus),
  304. // What is still owed, so a blocked cycle names its own unblock instead of
  305. // leaving the operator to diff the coverage matrix by hand.
  306. outstanding_prerequisites: Array.isArray(r.client_input_requests) && r.client_input_requests.length
  307. ? r.client_input_requests
  308. : (coverageUntested > 0 ? [`${coverageUntested} attack-class cell(s) untested — see reports/coverage-matrix.json`] : []),
  309. }
  310. }
  311. // ---- structured-output schemas --------------------------------------------
  312. const SETUP_SCHEMA = {
  313. type: 'object', additionalProperties: true,
  314. required: ['ok', 'date_tag', 'engagement_dir'],
  315. properties: {
  316. ok: { type: 'boolean' },
  317. date_tag: { type: 'string', description: 'YYMMDD from `date +%y%m%d`' },
  318. engagement_name: { type: 'string' },
  319. engagement_dir: { type: 'string', description: 'projects/pentest/<date>_<engagement>/' },
  320. blocked_global: { type: ['string', 'null'], description: 'non-null ONLY for a true global block (never merely a missing credential — unauth surface is still tested)' },
  321. apex_domains: { type: 'array', items: { type: 'string' } },
  322. assets: {
  323. type: 'array',
  324. items: {
  325. type: 'object', additionalProperties: true,
  326. properties: {
  327. identifier: { type: 'string' }, type: { type: 'string' }, base_url: { type: 'string' },
  328. business_tier: { type: 'string' }, notes: { type: 'string' },
  329. },
  330. },
  331. },
  332. roe: {
  333. type: 'object', additionalProperties: true,
  334. properties: { reversible_writes: { type: 'boolean' }, prohibitions: { type: 'array', items: { type: 'string' } } },
  335. },
  336. creds: { type: 'object', additionalProperties: true, properties: { present: { type: 'array', items: { type: 'string' } }, slack: { type: 'boolean' } } },
  337. business_tier_default: { type: 'string' },
  338. cpu_cores: { type: ['number', 'null'], description: 'logical CPU cores on the runner (getconf _NPROCESSORS_ONLN / sysctl hw.ncpu / nproc)' },
  339. engagement_kind: { type: 'string', enum: ['web', 'network', 'mobile'], description: "mobile iff the scope names a mobile app ARTIFACT (.apk/.aab/.xapk/.apks/.ipa), an app-store id, or a reverse-DNS package/bundle id; else network iff targets are predominantly IPs/CIDRs/ranges; else web" },
  340. mobile_platform: { type: ['string', 'null'], description: 'MOBILE only: android | ios | both' },
  341. mobile_artifacts: {
  342. type: 'array', description: 'MOBILE only: one row per app artifact in scope (located, not yet acquired)',
  343. items: {
  344. type: 'object', additionalProperties: true,
  345. properties: {
  346. platform: { type: 'string', description: 'android | ios' },
  347. kind: { type: 'string', description: 'apk | aab | xapk | apks | ipa | store | unavailable' },
  348. path: { type: ['string', 'null'], description: 'on-disk path EXACTLY as given; null when only a store id is known' },
  349. store_id: { type: ['string', 'null'] },
  350. package_id: { type: ['string', 'null'], description: 'reverse-DNS package (Android) / bundle id (iOS)' },
  351. version_name: { type: ['string', 'null'] },
  352. notes: { type: 'string' },
  353. },
  354. },
  355. },
  356. mobile_test_accounts: {
  357. type: 'array', description: 'MOBILE only: in-app logins the scope supplies — env-var NAMES only, never values',
  358. items: { type: 'object', additionalProperties: true, properties: { role: { type: 'string' }, user_env: { type: 'string' }, pass_env: { type: 'string' }, otp_env: { type: 'string' }, tenant: { type: 'string' }, notes: { type: 'string' } } },
  359. },
  360. mobile_backend_hints: { type: 'array', items: { type: 'string' }, description: 'MOBILE only: backend base URLs NAMED IN THE SCOPE — a scope allow-list seed, never the authoritative endpoint list (that comes from the bundle)' },
  361. network_targets: { type: 'array', items: { type: 'string' }, description: 'NETWORK only: IP / CIDR / range tokens to scan, EXACTLY as given (NOT expanded to individual IPs)' },
  362. host_estimate: { type: ['number', 'null'], description: 'NETWORK only: approximate total host count across network_targets (a /24 ~= 254)' },
  363. primary_ip: { type: ['string', 'null'], description: "the primary runner's egress IP (registered as the primary-runner vantage)" },
  364. primary_geo: { type: ['string', 'null'], description: 'best-effort ISO country code of the primary egress; picks a complementary 2nd-geography vantage on an allowlist signature' },
  365. notes: { type: 'array', items: { type: 'string' } },
  366. resumed: { type: 'boolean', description: 'true iff resume_dir was given and reused (continuing a prior engagement)' },
  367. resume_round: { type: ['number', 'null'], description: 'the prior engagement-meta.json resume_round (0 if fresh)' },
  368. },
  369. }
  370. const EXPAND_SCHEMA = {
  371. type: 'object', additionalProperties: true,
  372. required: ['ok', 'work_list'],
  373. properties: {
  374. ok: { type: 'boolean' },
  375. expanded_hosts: {
  376. type: 'array',
  377. items: { type: 'object', additionalProperties: true, properties: { host: { type: 'string' }, ip: { type: 'string' }, tech: { type: 'string' }, live: { type: 'boolean' }, source: { type: 'string', description: 'handoff|ct-log|origin|brute' } } },
  378. },
  379. work_list: {
  380. type: 'array',
  381. items: {
  382. type: 'object', additionalProperties: true,
  383. required: ['tag', 'identifier', 'output_dir'],
  384. properties: {
  385. tag: { type: 'string' }, identifier: { type: 'string' }, type: { type: 'string' }, base_url: { type: 'string' },
  386. business_tier: { type: 'string' }, output_dir: { type: 'string' },
  387. coverage_matrix: { type: 'array', items: { type: 'object', additionalProperties: true } },
  388. skills_hint: { type: 'string' },
  389. },
  390. },
  391. },
  392. infra_probes: {
  393. type: 'array', description: 'scope-adjacent infra/admin consoles — LIGHT unauthenticated fingerprint only, NOT a full coverage loop',
  394. items: { type: 'object', additionalProperties: true, properties: { host: { type: 'string' }, base_url: { type: 'string' }, why: { type: 'string' } } },
  395. },
  396. excluded: {
  397. type: 'array', description: 'hosts deliberately NOT assessed (out-of-scope prod/env, CDN bundle hosts, non-host components) with a reason',
  398. items: { type: 'object', additionalProperties: true, properties: { host: { type: 'string' }, reason: { type: 'string' } } },
  399. },
  400. tool_limitations: { type: 'array', items: { type: 'string' }, description: 'tool-classes unavailable at runtime (recorded, never silently skipped)' },
  401. notes: { type: 'array', items: { type: 'string' } },
  402. },
  403. }
  404. const CORRELATE_SCHEMA = {
  405. type: 'object', additionalProperties: true,
  406. required: ['ok'],
  407. properties: {
  408. ok: { type: 'boolean' },
  409. attack_paths_path: { type: 'string' }, ranked_path: { type: 'string' },
  410. path_count: { type: 'number' }, notes: { type: 'array', items: { type: 'string' } },
  411. },
  412. }
  413. // (Report is now the deterministic finalizeEngagement lane — no agent REPORT_SCHEMA.)
  414. // ---- normalize inputs ------------------------------------------------------
  415. // args may arrive as an object, a JSON string (named-workflow invocations can
  416. // serialize it), or a bare scope-file path. Handle all three so flags like dryRun
  417. // are never silently lost.
  418. let __raw = args
  419. if (typeof __raw === 'string') {
  420. const s = __raw.trim()
  421. if (s.startsWith('{') || s.startsWith('[')) { try { __raw = JSON.parse(s) } catch (e) { __raw = { scope_file: __raw } } }
  422. else { __raw = { scope_file: __raw } }
  423. }
  424. const input = (__raw && typeof __raw === 'object' && !Array.isArray(__raw)) ? __raw : { scope_file: __raw }
  425. const explicitCap = Number(input.maxConcurrent) > 0 ? Math.floor(Number(input.maxConcurrent)) : 0
  426. let cap = explicitCap > 0 ? explicitCap : 3 // provisional; finalized from CPU cores after Setup (machine-prudent)
  427. const dryRun = !!input.dryRun
  428. const wantReport = input.report !== false
  429. // Convergence knobs (coverage mode). dry_tail = empty batches past 100% coverage
  430. // before an asset is done ("all techniques plus more"). deep_asset_slice = agents
  431. // per fully-converged asset; resumeSchedule fits ~floor((1000-overhead)/slice)
  432. // assets per run and defers the rest to a resume run (input.resume_dir).
  433. const dryTail = Number(input.dry_tail) > 0 ? Math.floor(Number(input.dry_tail)) : 2
  434. const deepAssetSlice = Number(input.deep_asset_slice) > 0 ? Math.floor(Number(input.deep_asset_slice)) : 200
  435. const RESUME_OVERHEAD = 40
  436. // Churn guard: cap how many resume rounds a self-driven /loop will keep re-attempting
  437. // remaining/stuck assets before it stops emitting a rerun hint (surfaces them for a human).
  438. const maxResumeRounds = Number(input.max_resume_rounds) > 0 ? Math.floor(Number(input.max_resume_rounds)) : 3
  439. // Network-mode tuning (used only when Setup classifies engagement_kind === 'network').
  440. // PROFILES: light = bounded 1-1024 + curated less-common; standard (DEFAULT) &
  441. // full = full-range -p- on every reachable host; full additionally forces UDP.
  442. const scanProfile = ['light', 'standard', 'full'].includes(String(input.scan_profile)) ? String(input.scan_profile) : 'standard'
  443. const fullPorts = !!input.full_ports || scanProfile === 'full'
  444. const fullRange = fullPorts || scanProfile === 'standard' // standard is now full-range too
  445. const udpScan = !!input.udp || scanProfile === 'full' // full auto-enables UDP
  446. const explicitSlice = Number(input.slice_size) > 0 ? Math.floor(Number(input.slice_size)) : 0
  447. // null (default) => deep-dive EVERY app-bearing host (tiered coverage); a positive
  448. // number caps the count as an explicit budget override; 0 disables deep-dives.
  449. const deepenTop = (input.deepen_top === 0 || Number(input.deepen_top) > 0) ? Math.floor(Number(input.deepen_top)) : null
  450. // Source-IP/geo-allowlist auto-probe: on a confirmed allowlist signature, provision
  451. // a 2nd-geography vantage and re-probe the filtered hosts. Kill-switch: auto_provision:false.
  452. const autoProvision = input.auto_provision !== false // default true
  453. const geoVantages = Array.isArray(input.geo_vantages) ? input.geo_vantages.map(String).filter(Boolean)
  454. : (typeof input.geo_vantages === 'string' ? input.geo_vantages.split(',').map((s) => s.trim()).filter(Boolean) : [])
  455. const geoProvider = ['gcp', 'aws', 'az'].includes(String(input.geo_provider)) ? String(input.geo_provider) : 'gcp'
  456. const FULL_RANGE_HOST_CAP = Number(input.full_range_host_cap) > 0 ? Math.floor(Number(input.full_range_host_cap)) : 32
  457. // Mobile-mode tuning. There is deliberately NO skip_dast / static_only knob: a run
  458. // that cannot reach a device must produce a MACHINE-VERIFIED obstruction record plus
  459. // a client-input request, never a flag that dodges the gate.
  460. const mobilePlatformArg = ['android', 'ios', 'both'].includes(String(input.mobile_platform)) ? String(input.mobile_platform) : null
  461. const deviceSerial = input.device_serial ? String(input.device_serial) : null
  462. const emulatorAvd = input.emulator ? String(input.emulator) : null
  463. const mobileArtifactsArg = (Array.isArray(input.mobile_artifacts) ? input.mobile_artifacts
  464. : [input.apk, input.ipa, input.app].filter(Boolean).map((p) => ({ path: String(p) }))).filter(Boolean)
  465. const scopeArg = input.scope_file
  466. ? JSON.stringify({ scope_file: input.scope_file })
  467. : JSON.stringify({ scope: input.scope || (input.targets ? { engagement_name: input.engagement_name || 'network-scan', targets: input.targets } : (mobileArtifactsArg.length ? { engagement_name: input.engagement_name || 'mobile-assessment', mobile: mobileArtifactsArg, platform: mobilePlatformArg } : null)) })
  468. // ============================================================================
  469. // PHASE: Setup
  470. // ============================================================================
  471. phase('Setup')
  472. const setupPrompt = `You are the SETUP step of the pentest-engagement orchestrator. cwd is the repo root. Do real work (Bash/Read/Write). Do NOT spawn coordinators or run exploitation — only resolve scope and prepare the engagement. Read skills/pentest-engagement/reference/scope-file-format.md and skills/coordination/reference/credential-loading.md first.
  473. SCOPE_INPUT: ${scopeArg}
  474. RESUME_DIR: ${input.resume_dir || '(none)'}
  475. DRY_RUN: ${dryRun}
  476. Do:
  477. 0) MACHINE & KIND. cpu_cores = $(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || nproc 2>/dev/null || echo 4). Classify engagement_kind with this ORDERED test — FIRST MATCH WINS:
  478. (m) "mobile" iff the scope references a mobile APP ARTIFACT or app IDENTITY: a path/filename ending .apk/.aab/.xapk/.apks/.ipa (whether or not it exists on disk yet), an app-store id (a play.google.com/store/apps/details?id=<pkg> or apps.apple.com/.../id<digits> URL, or a "Play Store"/"App Store"/"TestFlight" reference naming an app), or a reverse-DNS package/bundle id such as com.acme.customer. A mobile scope ALMOST ALWAYS also names backend API URLs and sometimes apex domains — that does NOT make it web; the ARTIFACT is the discriminator. If it matches, ALSO set: mobile_platform ("android" iff only Android artifacts, "ios" iff only iOS, "both" iff both are named or the scope says "the mobile app" without qualifying); mobile_artifacts[] = one row per artifact {platform, kind, path (VERBATIM — never invent a path), store_id, package_id, version_name, notes} — if the scope names an app but supplies no file and no store id, STILL emit a row with kind:"unavailable" and say so in notes (never drop it); mobile_test_accounts[] from any in-app logins (env-var NAMES only); mobile_backend_hints[] = any backend base URLs the scope names. For an artifact given as a local path, VERIFY the file exists (ls) and report the path exactly as given — do not normalise, glob, or substitute a similar file.
  479. (n) else "network" iff the in-scope targets are predominantly IP addresses, CIDR blocks, or IP ranges (e.g. 10.0.0.0/24, 192.168.1.1-50, a list/file of bare IPs) rather than apex domains / web-app URLs.
  480. (w) else "web".
  481. A MOBILE scope that ALSO names apex domains keeps them in apex_domains[] — the mobile branch runs surface expansion over them in addition to the bundle-recovered backends, so a hybrid WAPT+MAPT scope does not lose its web half. For a NETWORK engagement, collect network_targets[] = the raw IP / CIDR / range tokens EXACTLY as given (do NOT expand a CIDR into individual IPs — the scan workers expand them), and host_estimate = the approximate total host count (sum CIDR sizes / range spans; a /24 ~= 254). A scope_file may be a plain newline-separated list of IPs/CIDRs — accept that. The web-only fields (apex_domains, assets[].type routing) may be empty for a network engagement.
  482. 1) PARSE SCOPE (web fields). If scope_file is given, READ it; else use the inline scope object. Normalize to:
  483. - engagement_name (kebab); apex_domains[] (the registrable domains in scope, e.g. example.com — derive from asset hostnames if not explicit);
  484. - assets[]: each {identifier, type (api|portal|spa|docs|admin|infra), base_url, business_tier, notes}. Include EVERY in-scope host/app named.
  485. - roe: {reversible_writes, prohibitions[]}. Default reversible_writes=true UNLESS the scope says read-only (a reversible create-then-delete in the tester's OWN org/tenant is authorized and non-destructive — see skills/coordination/reference/principles.md "Reversible active exploitation"). ALWAYS include prohibitions: ["no DoS / availability disruption","no brute force / credential spraying","no destructive or irreversible writes","no state changes against tenants you do not own","stay within declared scope"]. Merge any extra scope prohibitions.
  486. - creds: run \`python3 tools/env-reader.py <every credential env-var named in the scope> SLACK_BOT_TOKEN PENTEST_SLACK_CHANNEL_ID\`. Parse the ENV_VALUES: block. Record creds.present (var NAMES only, never values) and creds.slack (both Slack vars set). A MISSING credential is NOT a global block — the unauthenticated surface is still fully in scope. Set blocked_global ONLY if there is no reachable in-scope asset at all.
  487. - business_tier_default (from input.business_tier or "unknown").
  488. 2) DATE TAG: date_tag = $(date +%y%m%d).
  489. 3) OUTPUT_DIR: RESUME — if RESUME_DIR above is not "(none)" AND it is an existing directory, REUSE it verbatim as engagement_dir (do NOT mint a new <date_tag>_<engagement_name> dir and do NOT append -2): keep its recon/, per-asset dirs, artifacts/{nvd-cache,validation-cache}, reports/ intact; read its engagement-meta.json "resume_round" (default 0) and return resume_round = that value; set resumed=true. Otherwise (fresh run) engagement_dir = projects/pentest/<date_tag>_<engagement_name>/ (do NOT clobber a non-empty dir — append -2), set resumed=false and resume_round=0. Create it. Write engagement_dir/engagement-scope.json (the normalized scope) and engagement_dir/engagement-meta.json ({engagement_name, started: $(date -u +%Y-%m-%dT%H:%M:%SZ), creds_present, roe, resume_round: (the value returned above — priorRound+1 on a resume, else 0)}). On a resume, PRESERVE the original "started" if already present. Create engagement_dir/{recon/inventory,artifacts,reports} and engagement_dir/recon/inventory. ALSO run \`mkdir -p engagement_dir/logs/activity\` (the deterministic activity/source-IP ledger lives here). Record the active-engagement pointer: \`mkdir -p .claude/state\` (repo-root relative) then write .claude/state/active-engagement containing the ABSOLUTE engagement dir path — compute it with \`"$(cd engagement_dir && pwd)"\`. Then capture the primary runner's egress IP and register it as the primary-runner source vantage: \`PRIMARY_IP=$(curl -s --max-time 5 ifconfig.me || curl -s --max-time 5 https://api.ipify.org || echo unavailable)\` then run \`python3 tools/register_source_ip.py "$PRIMARY_IP" --role primary-runner --engagement "<absolute engagement_dir>"\` (best-effort — never block setup on it). ALSO best-effort geolocate it (metadata only, non-blocking): \`PRIMARY_GEO=$(curl -s --max-time 5 https://ipinfo.io/$PRIMARY_IP/country || echo unknown)\`. Return both primary_ip=$PRIMARY_IP and primary_geo=$PRIMARY_GEO (ISO country code; used to pick a COMPLEMENTARY 2nd-geography vantage if a source-IP/geo allowlist is detected during the scan).
  490. 4) STARTED SLACK (only if creds.slack AND not DRY_RUN): a brief ":satellite: Starting pentest engagement <name> — N assets, apexes <...>" via python3 tools/slack-send.py --token "$SLACK_BOT_TOKEN" --channel "$PENTEST_SLACK_CHANNEL_ID" -. Non-blocking.
  491. 5) DETERMINISM SNAPSHOT (freeze the CVE/KEV operands ONCE for the whole engagement): mkdir -p engagement_dir/artifacts/nvd-cache engagement_dir/artifacts/validation-cache. Then freeze the CISA KEV catalog by running \`python3 tools/kev-lookup.py --cache-dir engagement_dir/artifacts/nvd-cache CVE-2021-44228\` (any valid CVE id — this writes engagement_dir/artifacts/nvd-cache/kev-snapshot.json as a side effect; the verdict itself is irrelevant). Every asset's validators then read the SAME frozen snapshot, so CVE reconciliation is deterministic across a re-run. The validation-cache/ dir holds the C3 replay-cache (populated when validate-findings re-validates the frozen finding dirs). If a fetch fails, note it and continue — validators fall back to create-on-miss.
  492. Always set cpu_cores and engagement_kind; for a NETWORK engagement also set network_targets[] and host_estimate; for a MOBILE engagement also set mobile_platform and mobile_artifacts[] (a mobile classification with an empty mobile_artifacts[] is a contradiction — re-read the scope). Return SETUP_SCHEMA. Never log secret values; reference creds by name.`
  493. const setup = await agent(setupPrompt, { schema: SETUP_SCHEMA, agentType: 'general-purpose', label: 'setup', phase: 'Setup' })
  494. if (!setup || !setup.ok || setup.blocked_global) {
  495. const reason = setup ? (setup.blocked_global || 'setup returned ok:false') : 'no setup result'
  496. log(`Setup blocked: ${reason}`)
  497. return { status: 'BLOCKED', reason, setup }
  498. }
  499. const engagementDir = (setup.engagement_dir || '').replace(/\/+$/, '')
  500. const roe = (setup.roe && typeof setup.roe === 'object') ? setup.roe : { reversible_writes: true, prohibitions: [] }
  501. const tierDefault = setup.business_tier_default || 'unknown'
  502. // Frozen-operand paths (C1) threaded into every coordinator-loop so its inline
  503. // validators read the SAME NVD/KEV snapshots (deterministic CVE reconciliation).
  504. const nvdCacheDir = `${engagementDir}/artifacts/nvd-cache`
  505. const kevSnapshot = `${nvdCacheDir}/kev-snapshot.json`
  506. log(`Setup ok. engagement_dir=${engagementDir}; apexes=${JSON.stringify(setup.apex_domains || [])}; assets=${(setup.assets || []).length}; reversible_writes=${roe.reversible_writes}`)
  507. // ============================================================================
  508. // Machine-prudent concurrency + engagement-kind routing
  509. // ============================================================================
  510. // Finalize the parallel-task cap from the machine's core count UNLESS the caller
  511. // set maxConcurrent explicitly. Prudent rule: ~half the cores, floored at 2,
  512. // hard-capped at 8 — we NEVER launch hundreds/thousands of parallel agents. The
  513. // runtime independently caps concurrency at min(16, cores-2); this is the lower,
  514. // safer app-level bound (and queued work still completes, just fewer at a time).
  515. const cores = Number(setup.cpu_cores) > 0 ? Math.floor(Number(setup.cpu_cores)) : 4
  516. const autoCap = Math.max(2, Math.min(8, Math.floor(cores / 2)))
  517. cap = explicitCap > 0 ? explicitCap : autoCap
  518. // Three-way WHITELIST, not a chain of ternaries: anything unknown or absent still
  519. // falls back to 'web', so a schema/model regression degrades to today's behaviour
  520. // rather than dropping out of every branch.
  521. const KIND = ['network', 'mobile'].includes(setup.engagement_kind) ? setup.engagement_kind : 'web'
  522. log(`Machine: ${cores} core(s) -> parallel-task cap=${cap}${explicitCap ? ' (explicit)' : ' (auto, prudent)'}; engagement_kind=${KIND}.`)
  523. // ============================================================================
  524. // Input-ingest (req 11) + Metadata-intake (req 10)
  525. // Capture every attached/referenced input into <dir>/input/ (idempotent by
  526. // sha256), then, if a prior report was given, extract its engagement metadata
  527. // from the STORED copy. resolveEngagementMeta later reconciles prompt>prior.
  528. // ============================================================================
  529. const INTAKE_SCHEMA = {
  530. type: 'object', additionalProperties: true,
  531. properties: {
  532. input_manifest: {
  533. type: 'array',
  534. items: { type: 'object', additionalProperties: true, properties: { original: { type: 'string' }, stored: { type: 'string' }, bytes: { type: 'number' }, sha256: { type: 'string' }, already_present: { type: 'boolean' } } },
  535. },
  536. prior_meta: {
  537. type: ['object', 'null'], additionalProperties: true,
  538. properties: {
  539. title: { type: ['string', 'null'] }, title_lines: { type: 'array', items: { type: 'string' } },
  540. subtitle: { type: ['string', 'null'] }, sector: { type: ['string', 'null'] }, target: { type: ['string', 'null'] },
  541. scope: { type: 'array', items: { type: 'string' } }, classification: { type: ['string', 'null'] },
  542. method: { type: ['string', 'null'] }, prepared_by: { type: ['string', 'null'] },
  543. report_id: { type: ['string', 'null'] }, version: { type: ['string', 'null'] },
  544. },
  545. },
  546. },
  547. }
  548. const priorReportPath = input.prior_report || null
  549. // Mobile artifacts ride the EXISTING intake path, which already sha256s every file
  550. // and copies it into <dir>/input/ — that satisfies the methodology's hash-before-touch
  551. // requirement for free rather than growing a second copy path.
  552. const extraInputs = [input.scope_file, ...(Array.isArray(input.input_files) ? input.input_files : []),
  553. ...((setup.mobile_artifacts || []).map((m) => m && m.path).filter(Boolean))].filter(Boolean)
  554. let intakeManifest = []
  555. if (priorReportPath || extraInputs.length) {
  556. const intake = await agent(
  557. `ROLE: INPUT-INGEST + METADATA-INTAKE (deterministic file ops + extraction only). cwd is repo root.\n` +
  558. `ENGAGEMENT_DIR: ${engagementDir}\nPRIOR_REPORT: ${priorReportPath || '(none)'}\nOTHER_INPUTS: ${JSON.stringify(extraInputs)}\n\n` +
  559. `1. \`mkdir -p ${engagementDir}/input\`. For EACH input path above: compute \`shasum -a 256\`. If an identical file (same sha256) already exists in ${engagementDir}/input/ OR the path already lives under ${engagementDir}, do NOT copy (already_present=true, stored=the existing/in-tree path). Otherwise \`cp\` it into ${engagementDir}/input/<basename> (already_present=false, stored=that path). Record one input_manifest row per file {original, stored, bytes, sha256, already_present}.\n` +
  560. (priorReportPath
  561. ? `2. Extract prior engagement metadata from the STORED copy of the prior report: if it is a PDF use \`pdftotext -f 1 -l 2 <stored> -\` (cover pages); if JSON read its \`engagement\` block. Return prior_meta {title, title_lines[], subtitle, sector, target, scope[] (the prior in-scope hosts/domains — for a DISPLAY-ONLY diff, NEVER a work list), classification, method, prepared_by, report_id, version}. Leave a field null if not present.\n`
  562. : `2. No prior report — return prior_meta: null.\n`) +
  563. `Return INTAKE_SCHEMA. Do NOT judge or assess anything.`,
  564. { schema: INTAKE_SCHEMA, agentType: 'general-purpose', label: 'input-intake', phase: 'Setup' }
  565. ).catch(() => null)
  566. if (intake) {
  567. const mani = intake.input_manifest || []
  568. intakeManifest = mani
  569. log(`Input-ingest: ${mani.length} file(s) -> input/ (${mani.filter(m => m.already_present).length} already present).`)
  570. if (intake.prior_meta) input.prior = { ...(input.prior || {}), ...intake.prior_meta }
  571. }
  572. }
  573. if (KIND === 'network') {
  574. // ==========================================================================
  575. // NETWORK MODE — tool-first, bounded, UNIFORM per-host scan of an IP/CIDR set.
  576. // Scan : slice targets into machine-prudent batches; ONE nmap worker per
  577. // slice runs the SAME pipeline over its slice, so agent count scales
  578. // with SLICES (~dozens), never with IP count. Per-IP output tree.
  579. // Deepen : bounded coordinator-loop deep-dives on ONLY the top-value hosts.
  580. // This block is fully self-contained and returns; WEB mode falls through to
  581. // the existing Expand/Assess/Correlate/Report code below.
  582. // ==========================================================================
  583. // Curated "less-common" service ports appended to the well-known 1-1024 range.
  584. // This is the LIGHT profile's bounded set (1-1024 + these) for large/fast
  585. // sweeps; standard/full run full-range -p- on every reachable host instead.
  586. const LESS_COMMON_PORTS = '1099,1433,1434,1521,1604,1723,1883,2049,2082,2083,2086,2087,2095,2096,2181,2222,2375,2376,2379,2483,2484,3000,3128,3268,3269,3306,3389,3478,3632,4369,4444,4505,4506,4567,4711,4848,5000,5001,5009,5038,5044,5060,5061,5222,5432,5555,5601,5672,5800,5900,5901,5984,5985,5986,6000,6379,6443,6660,6667,7001,7002,7077,7199,7474,7547,7777,8000,8008,8009,8014,8042,8080,8081,8086,8088,8089,8090,8161,8200,8243,8333,8443,8500,8530,8649,8686,8787,8800,8880,8888,8983,9000,9001,9042,9060,9080,9090,9091,9100,9200,9300,9443,9990,9999,10000,10250,10255,11211,15672,16010,16992,16993,18080,20000,27017,27018,28017,32400,44818,49152,50000,50070,61616'
  587. const SCAN_SLICE_SCHEMA = {
  588. type: 'object', additionalProperties: true, required: ['slice', 'live', 'dead_count'],
  589. properties: {
  590. slice: { type: 'number' },
  591. scanned_tokens: { type: 'array', items: { type: 'string' } },
  592. live: {
  593. type: 'array',
  594. items: {
  595. type: 'object', additionalProperties: true, required: ['ip'],
  596. properties: {
  597. ip: { type: 'string' }, open_ports: { type: 'array', items: { type: 'number' } },
  598. top_services: { type: 'array', items: { type: 'string' } },
  599. cve_count: { type: 'number' }, max_cvss: { type: 'number' }, interesting: { type: 'boolean' },
  600. cves: { type: 'array', description: 'per-CVE {id,cvss,severity,service} — feeds the network cve_register in-memory (M-7)', items: { type: 'object', additionalProperties: true } },
  601. },
  602. },
  603. },
  604. dead_count: { type: 'number' },
  605. filtered: {
  606. type: 'array',
  607. description: 'Hosts with a POSITIVE existence proof yet NO reachable service from THIS vantage (source-IP/geo-allowlist candidates). NOT genuinely-down hosts — those go in dead_count. This set is the allowlist-signature + cost-bound discriminator.',
  608. items: {
  609. type: 'object', additionalProperties: true, required: ['ip'],
  610. properties: {
  611. ip: { type: 'string' },
  612. signal: { type: 'string', description: 'existence proof from this vantage: host-up-but-all-filtered | tcp-rst | icmp-admin-prohibited | ptr-resolves | prior-report-known-live' },
  613. },
  614. },
  615. },
  616. tool_limitations: { type: 'array', items: { type: 'string' } },
  617. },
  618. }
  619. phase('Scan')
  620. const netTargets = (setup.network_targets || []).filter(Boolean)
  621. if (!netTargets.length) {
  622. return { status: 'BLOCKED', reason: 'network engagement but Setup resolved no IP/CIDR targets', engagement_dir: engagementDir, setup }
  623. }
  624. const hostEstimate = Number(setup.host_estimate) > 0 ? Math.floor(Number(setup.host_estimate)) : netTargets.length
  625. const avgPerToken = netTargets.length ? hostEstimate / netTargets.length : 1
  626. // Keep each slice ~<= 64 hosts: many individual IPs -> 64 tokens/slice; CIDR-heavy -> 2 tokens/slice.
  627. const perSlice = explicitSlice > 0 ? explicitSlice : (avgPerToken > 8 ? 2 : 64)
  628. const portSpec = fullRange ? '-p-' : `-p 1-1024,${LESS_COMMON_PORTS}` // standard/full = -p-; light = bounded
  629. const indexedSlices = chunk(netTargets, perSlice).map((slice, idx) => ({ slice, idx }))
  630. log(`Network scan: ${netTargets.length} token(s) (~${hostEstimate} host(s)) -> ${indexedSlices.length} slice(s) of <=${perSlice} token(s); profile=${scanProfile}; udp=${udpScan}; concurrency=${cap}.`)
  631. // Port+service scan instruction — profile-conditional. FULL-RANGE (standard/full)
  632. // uses a host-count-guarded TWO-STAGE (SYN -p- then -sV on found-open ports) so a
  633. // per-port --host-timeout can never truncate high ports; LIGHT stays bounded.
  634. const nseTls = '--script ssl-cert,ssl-enum-ciphers' // fingerprints TLS on ANY port (catches non-443 listeners)
  635. const portScanInstr = fullRange
  636. ? `2. PORT+SERVICE SCAN — FULL-RANGE (-p-), host-count-guarded two-stage (live hosts only):\n` +
  637. ` a. If the slice has MORE than ${FULL_RANGE_HOST_CAP} live hosts, DOWNGRADE to the bounded set to stay fast on dense ranges: \`nmap -sS -sV -n -Pn -p 1-1024,${LESS_COMMON_PORTS} --version-intensity 5 -T4 --max-retries 2 --host-timeout 12m ${nseTls} -oA ${engagementDir}/recon/slice-${idx}-services -iL ${engagementDir}/recon/slice-${idx}-live.txt\`, and record "full-range downgraded to bounded on dense slice (>${FULL_RANGE_HOST_CAP} live hosts)" in tool_limitations.\n` +
  638. ` b. ELSE (<=${FULL_RANGE_HOST_CAP} live hosts) run TWO STAGES so a per-port timeout can never truncate high ports: STAGE A fast SYN sweep of ALL 65535 \`nmap -sS -p- --min-rate 2000 -n -Pn --max-retries 2 -oA ${engagementDir}/recon/slice-${idx}-full-syn -iL ${engagementDir}/recon/slice-${idx}-live.txt\` (rate-paced, NO --host-timeout). Extract the found-open ports. STAGE B version+scripts on ONLY those open ports \`nmap -sS -sV --version-intensity 5 -n -Pn -p <found-open> ${nseTls} --host-timeout 12m -oA ${engagementDir}/recon/slice-${idx}-services -iL ${engagementDir}/recon/slice-${idx}-live.txt\`.\n` +
  639. ` Use -sS if root (\`id -u\`==0) else -sT (a connect scan STILL covers the full range — do NOT shortcut to top-ports). ${udpScan ? 'Then a bounded UDP pass: `nmap -sU -n -Pn --top-ports 50 -T4 --host-timeout 12m -oA <...>-udp -iL <live>`.' : 'No UDP unless a specific host clearly warrants it.'}\n`
  640. : `2. PORT+SERVICE SCAN (bounded LIGHT profile, live hosts only, IDENTICAL for every host): \`nmap -sS -sV -n -Pn ${portSpec} --version-intensity 5 -T4 --max-retries 2 --host-timeout 12m ${nseTls} -oA ${engagementDir}/recon/slice-${idx}-services -iL ${engagementDir}/recon/slice-${idx}-live.txt\`. Use -sS if root (\`id -u\`==0) else -sT. Stay within the listed ports — do NOT expand to all 65535 for this bounded profile. ${udpScan ? 'Then a bounded UDP pass: `nmap -sU -n -Pn --top-ports 50 -T4 --host-timeout 12m -oA <...>-udp -iL <live>`.' : 'No UDP unless a specific host clearly warrants it.'}\n`
  641. const sliceResults = []
  642. for (const grp of chunk(indexedSlices, cap)) {
  643. const r = await parallel(grp.map(({ slice, idx }) => () =>
  644. agent(
  645. `ROLE: NETWORK-SCAN worker for slice ${idx} of an AUTHORIZED vulnerability scan. cwd is repo root. TOOLS FIRST — drive nmap (and nuclei / nmap NSE if installed); never hand-probe ports one by one. Mount skills/infrastructure/reference/scenarios/network-recon/alive-hosts-discovery.md, skills/infrastructure/reference/scenarios/network-recon/port-scanning-tcp-udp.md, skills/infrastructure/reference/service-enum.md.\n` +
  646. `ENGAGEMENT_DIR: ${engagementDir}\nSLICE_TARGETS (IP/CIDR/range tokens — scan ONLY these): ${slice.join(' ')}\nPORT_PROFILE: ${scanProfile} -> nmap ${portSpec}\nUDP: ${udpScan}\nProhibitions (HARD): ${JSON.stringify(roe.prohibitions || ['no DoS', 'no brute force', 'non-destructive only'])}. Rate-limit; NO DoS; NO brute force; NO destructive actions.\n\n` +
  647. `Reachability is UNKNOWN — discover first, then scan only what is alive:\n` +
  648. `1. HOST DISCOVERY: \`nmap -sn -n -PE -PP -PS21,22,23,25,80,135,139,443,445,3389,8080 -PA80 -PU53,161 -oG ${engagementDir}/recon/slice-${idx}-alive.gnmap <SLICE_TARGETS>\`. Extract live IPs to ${engagementDir}/recon/slice-${idx}-live.txt. FILTERED vs DEAD: for any in-slice IP that is EXISTENCE-CONFIRMED (host-up from -sn, a TCP RST, an ICMP admin-prohibited, a resolving PTR, or known-live from a prior report) yet shows NO reachable service from THIS vantage, put it in the returned filtered[] with its existence signal — NOT in dead_count (dead_count is for hosts with NO existence proof at all). You expand CIDRs yourself, so a filtered host inside a /24 must be surfaced as its own IP. If zero live, do a light \`-Pn --top-ports 100\` confirmation on a sample before declaring hosts dead.\n` +
  649. portScanInstr +
  650. `2c. NON-443 TLS: the ${nseTls} scripts above fingerprint TLS on odd ports (e.g. a stale listener on 2234). ONLY where -sV reports an open port whose TLS state is inconclusive, run a BOUNDED fallback (NEVER an unbounded per-port loop — it hangs on non-TLS ports like a ZeroMQ 5558): \`timeout 8 openssl s_client -connect <ip>:<port> -servername <host> </dev/null 2>/dev/null | openssl x509 -noout -subject -dates\`. Record every non-443 TLS listener (subject + expiry) in that host's notable[]; if the cert is expired/weak, also write it as a finding.\n` +
  651. `2d. SCAN-SOUNDNESS SELF-CHECK: run \`python3 tools/netscan_guard.py --xml ${engagementDir}/recon/slice-${idx}-services.xml\` over THIS slice's own scan. If it exits 20 (UNSOUND — a --host-timeout connect scan left up-hosts at 0 open), each host in guards.host_timeout_truncation.rescan_hosts is truncation-suspect: RE-SCAN it (STAGE A with NO --host-timeout, or -sS as root) BEFORE putting it in dead_count/filtered[], and record "host-timeout truncation re-scanned" in tool_limitations. Always treat a literal UDP state "open|filtered" as NOT open (a timeout is not a service).\n` +
  652. `3. CVE SURFACING (tool-first): \`nmap --script vulners,vuln\` if the scripts exist, and/or \`nuclei -severity low,medium,high,critical\` against live HTTP(S) services if nuclei is installed. BEFORE enriching, run \`python3 tools/netscan_guard.py --xml ${engagementDir}/recon/slice-${idx}-services.xml --suppress-cves\` and DROP any CVE it lists under guards.cve_suppression.suppressed (e.g. a MariaDB '5.5.5-' banner mislabeled as MySQL 5.5.5 — ~200 phantom CVEs). Enrich EACH remaining CVE-ID via \`python3 tools/nvd-lookup.py <CVE-ID>\` (authoritative CVSS/CWE). Record any missing tool in tool_limitations — never silently skip.\n` +
  653. `4. PER-HOST OUTPUT (uniform schema): for EACH live host write ${engagementDir}/hosts/<ip>/recon/ (that host's nmap output) and ${engagementDir}/hosts/<ip>/host.json = {ip, live:true, hostname, os_guess, ports:[{port,proto,state,service,product,version,cpe}], cves:[{id,cvss,severity,service}], notable:[...], scanned_profile:"${scanProfile}"}. For a confirmed exposed CVE/weakness also write ${engagementDir}/hosts/<ip>/findings/finding-NNN/description.md (CVSS+CWE) + evidence/raw-source.txt (raw tool lines).\n` +
  654. `Return SCAN_SLICE_SCHEMA (populate live[], dead_count, and filtered[]). interesting=true iff the host has a remotely-exploitable service, an exposed admin/db/mgmt port, or a CVE cvss>=7.`,
  655. { schema: SCAN_SLICE_SCHEMA, label: `scan:slice-${idx}`, phase: 'Scan', agentType: 'general-purpose' }
  656. )
  657. ))
  658. sliceResults.push(...r.filter(Boolean))
  659. }
  660. let allLive = sliceResults.flatMap(s => (s.live || []))
  661. const deadCount = sliceResults.reduce((a, s) => a + (Number(s.dead_count) || 0), 0)
  662. const scanLimitations = [...new Set(sliceResults.flatMap(s => s.tool_limitations || []))]
  663. const scanComplete = sliceResults.length === indexedSlices.length
  664. log(`Scan complete: ${allLive.length} live / ~${deadCount} dead across ${sliceResults.length}/${indexedSlices.length} slice(s). Tool limits: ${JSON.stringify(scanLimitations)}`)
  665. // --- 2nd-geography escalation machinery ----------------------------------
  666. const GEO_ESC_SCHEMA = {
  667. type: 'object', additionalProperties: true, required: ['zone'],
  668. properties: {
  669. zone: { type: 'string' }, egress_ip: { type: 'string' },
  670. newly_reachable: {
  671. type: 'array',
  672. items: {
  673. type: 'object', additionalProperties: true, required: ['ip'],
  674. properties: {
  675. ip: { type: 'string' }, open_ports: { type: 'array', items: { type: 'number' } },
  676. top_services: { type: 'array', items: { type: 'string' } }, max_cvss: { type: 'number' },
  677. cves: { type: 'array', items: { type: 'object', additionalProperties: true } }, interesting: { type: 'boolean' },
  678. },
  679. },
  680. },
  681. error: { type: ['string', 'null'] },
  682. },
  683. }
  684. const engId = (engagementDir.split('/').pop() || 'eng').toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 40)
  685. async function runGeoEscalation({ geos, filteredHosts }) {
  686. const ips = filteredHosts.map(h => h.ip).join(' ')
  687. return (await parallel(geos.map(zone => () =>
  688. agent(
  689. `ROLE: 2nd-geography vantage prober (zone ${zone}) for an AUTHORIZED vuln scan. A source-IP/geo allowlist made these hosts dark from the primary vantage; re-probe them from an EPHEMERAL VM in ${zone}. cwd is repo root. Do everything in ONE bash script with a teardown TRAP so the VM is NEVER leaked:\n\n` +
  690. `DIR="${engagementDir}"; handle=""\n` +
  691. `trap '[ -n "$handle" ] && tools/provision_vantage.sh --teardown "$handle" --engagement "$DIR" >/dev/null 2>&1 || true' EXIT\n` +
  692. `0. CLOUD-AUTH PRECHECK (before spending on any VM): run \`python3 tools/vantage_diagnose.py --provider-auth\`. If its cloud_auth.any is false (no active gcloud / aws / az credential), STOP immediately — do NOT provision — and return GEO_ESC_SCHEMA with newly_reachable:[] and error:"skipped: no-cloud-auth". "No vantage available" is only ever concluded when no cloud provider is authed; a provisioning attempt with no auth just burns time and leaks nothing.\n` +
  693. `1. \`tools/provision_vantage.sh --reap --engagement "$DIR"\` — GC any orphan VM from a prior crash for this engagement.\n` +
  694. `2. \`LINE=$(tools/provision_vantage.sh --provider ${geoProvider} --region ${zone} --engagement "$DIR" --name vantage-${engId}-${zone} --ssh-ready)\` — creates a hardened, labelled, TTL-bounded VM and registers its egress as an attack-vm vantage. Parse: \`handle=$(printf '%s' "$LINE" | sed -n 's/.*handle=\\([^ ]*\\).*/\\1/p')\`.\n` +
  695. `3. From the VM egress (\`gcloud compute ssh vantage-${engId}-${zone} --zone ${zone} --command "..."\`; install nmap if missing), re-probe ONLY these filtered IPs: ${ips}. Run \`nmap -sn -n <ips>\` then STAGE A \`nmap -sS -p- --min-rate 2000 -n -Pn <alive>\` and STAGE B \`nmap -sS -sV -n -Pn -p <found-open> --script ssl-cert,ssl-enum-ciphers <alive>\`. NON-DESTRUCTIVE only; NO brute force / DoS.\n` +
  696. `4. For each host now REACHABLE from ${zone}, write ${engagementDir}/hosts/<ip>/host.json (create or backfill) = {ip, live:true, reachable_from:"${zone}", ports:[...], notable:[...], scanned_profile:"geo-${zone}"} + its recon output under hosts/<ip>/recon/.\n` +
  697. `5. Tear the VM down explicitly at the end (the trap is the backstop); confirm \`tools/provision_vantage.sh --reap --engagement "$DIR"\` shows no remaining VM.\n\n` +
  698. `Return GEO_ESC_SCHEMA. newly_reachable = ONLY hosts that answered from ${zone} yet were dark from the primary vantage; interesting=true iff exploitable/admin/mgmt service or CVE>=7.`,
  699. { schema: GEO_ESC_SCHEMA, label: `geo-probe:${zone}`, phase: 'GeoProbe', agentType: 'general-purpose' }
  700. ).then(r => r || { zone, error: 'no result' }).catch(err => ({ zone, error: String(err) }))
  701. ))).filter(Boolean)
  702. }
  703. // --- Source-IP/geo-allowlist detection + 2nd-geography auto-probe ---------
  704. // A host that is existence-confirmed-but-dark from the primary vantage may be
  705. // reachable only from another geography (a source-IP/geo allowlist). Detect the
  706. // signature, and (unless dry-run / kill-switched) provision <=2 ephemeral 2nd-geo
  707. // VMs, re-probe ONLY the filtered hosts, and MERGE newly-reachable hosts into the
  708. // in-memory allLive BEFORE ranking (so they reach the deep-dive, not just disk).
  709. const { signature: allowlistDetected, filteredHosts } = detectAllowlist(sliceResults)
  710. const primaryGeo = setup.primary_geo || null
  711. const geosTried = [primaryGeo || 'primary-vantage']
  712. let escalationPlan = null
  713. if (allowlistDetected) {
  714. const geos = resolveGeoZones({ geoVantages, primaryGeo })
  715. escalationPlan = { detected: true, filtered: filteredHosts.map(h => h.ip), geos, auto_provision: autoProvision, reached: [] }
  716. const willProvision = autoProvision && !dryRun && geos.length > 0
  717. log(`Allowlist signature: ${filteredHosts.length} filtered host(s) dark from ${primaryGeo || 'the primary vantage'}; ${willProvision ? `auto-probing from ${JSON.stringify(geos)}` : 'detect+flag only (no provisioning)'}.`)
  718. if (willProvision) {
  719. phase('GeoProbe')
  720. const geoResults = await runGeoEscalation({ geos, filteredHosts })
  721. for (const z of geoResults) geosTried.push((z && z.zone) || 'unknown-zone')
  722. for (const gr of geoResults) for (const h of ((gr && gr.newly_reachable) || [])) {
  723. if (!h || !h.ip) continue
  724. const ex = allLive.find(x => x.ip === h.ip)
  725. if (ex) { ex.open_ports = [...new Set([...(ex.open_ports || []), ...(h.open_ports || [])])]; ex.interesting = true }
  726. else allLive.push({ ...h, interesting: h.interesting !== false })
  727. }
  728. escalationPlan.reached = geoResults.flatMap(z => ((z && z.newly_reachable) || []).map(h => h.ip))
  729. log(`Geo-probe reached ${escalationPlan.reached.length} previously-dark host(s): ${JSON.stringify(escalationPlan.reached)}.`)
  730. }
  731. }
  732. const liveCount = allLive.length
  733. // Filtered hosts STILL dark after any escalation -> no_surface_from (honest coverage caveat, never a bare 'dead').
  734. const reachedIps = new Set((escalationPlan && escalationPlan.reached) || [])
  735. const noSurfaceFrom = filteredHosts.filter(h => !reachedIps.has(h.ip)).map(h => ({ ip: h.ip, no_surface_from: geosTried.slice(), detected_via: h.signal }))
  736. // Inventory synthesis (single agent; reads per-host JSON + records no_surface_from).
  737. await agent(
  738. `ROLE: network inventory synthesis. cwd is repo root. Read every ${engagementDir}/hosts/*/host.json. Write ${engagementDir}/recon/inventory/hosts.json (array of all host.json) and ${engagementDir}/recon/inventory/scan-summary.md: live/dead counts, an open-port histogram, a service/product table, and a CVE rollup (id, cvss, affected-host count) sorted by CVSS desc. ALSO write ${engagementDir}/recon/inventory/filtered-hosts.json = ${JSON.stringify(noSurfaceFrom)} (hosts existence-confirmed but with NO reachable service from the tested vantage geographies — a coverage caveat, NOT 'zero exposure'); for each, ensure ${engagementDir}/hosts/<ip>/host.json exists with {ip, live:false, no_surface_from:[...], detected_via:...}. Bullets, no prose. Return one line: "<live> live, <distinctOpenPorts> open ports, <distinctCVEs> CVEs, <filtered> filtered".`,
  739. { label: 'inventory', phase: 'Scan', agentType: 'general-purpose' }
  740. ).catch(() => null)
  741. // Tiered depth (no arbitrary top-N): every host that exposes an enumerable app/
  742. // endpoint surface (an HTTP service) gets its OWN coverage-mode coordinator-loop
  743. // for the unit-scope attack classes; every bare-service host is covered for the
  744. // host/asset-scope classes by the deterministic network_coverage_map tail at report
  745. // time. Agents therefore scale with app-bearing host count, not raw IP count.
  746. const APP_PORTS = new Set([80, 443, 8080, 8443, 8000, 8888, 8081, 8008, 3000, 5000, 9000, 9200])
  747. const isAppBearing = (h) => (h.open_ports || []).some(p => APP_PORTS.has(Number(p))) ||
  748. /\b(http|https|nginx|apache|httpd|iis|tomcat|caddy|express|node)\b/i.test((h.top_services || []).join(' '))
  749. const ranked = allLive.filter(h => h && isAppBearing(h)).sort((a, b) => (Number(b.max_cvss) || 0) - (Number(a.max_cvss) || 0))
  750. const deepenHosts = deepenTop === 0 ? [] : (deepenTop > 0 ? ranked.slice(0, deepenTop) : ranked)
  751. log(`Deep-dive (tiered): ${ranked.length} app-bearing host(s); deep-diving ${deepenHosts.length}${deepenTop > 0 ? ` (deepen_top cap=${deepenTop})` : ' (all app-bearing)'}; bare hosts covered by the network_coverage_map tail.`)
  752. if (dryRun) {
  753. log('dryRun complete — returning scan inventory + deep-dive plan without deepening')
  754. return { status: 'DRY_RUN', engagement_kind: 'network', engagement_dir: engagementDir, date_tag: setup.date_tag, cpu_cores: cores, parallel_cap: cap, slices: indexedSlices.length, targets: netTargets.length, host_estimate: hostEstimate, live: liveCount, dead: deadCount, scan_profile: scanProfile, port_spec: portSpec, udp: udpScan, interesting: ranked.length, deepen_planned: deepenHosts.map(h => h.ip), allowlist_detected: allowlistDetected, escalation_plan: escalationPlan, no_surface_from: noSurfaceFrom, tool_limitations: scanLimitations }
  755. }
  756. // App-bearing deep-dives run to CONVERGENCE (coverage + dry_tail), agent-slice
  757. // backstopped, with honest cross-run resume: fully converge as many hosts as fit
  758. // their slice this run; hosts already 100% on disk are skipped; the rest defer.
  759. let results = []
  760. let netDeferredHosts = []
  761. let netResumeCompleted = []
  762. if (deepenHosts.length) {
  763. phase('Assess')
  764. const NET_RESUME_SCAN_SCHEMA = { type: 'object', additionalProperties: true, required: ['hosts'], properties: { hosts: { type: 'array', items: { type: 'object', additionalProperties: true, properties: { ip: { type: 'string' }, complete: { type: 'boolean' }, applicable: { type: 'number' }, findings_total: { type: 'number' } } } } } }
  765. const netScan = await agent(
  766. `ROLE: RESUME-SCAN (deterministic; run the gate, relay booleans — NO judgment). cwd is repo root. For EACH host below run \`python3 tools/coverage_gate.py --asset-dir <output_dir>\` and READ <output_dir>/reports/coverage-matrix.json; return {ip, complete:(the JSON's "complete"), applicable:(its "applicable"), findings_total:(count of *.json under <output_dir>/artifacts/validated/)}. A missing surface.json/coverage.json => complete:false, applicable:0.\nHOSTS: ${JSON.stringify(deepenHosts.map(h => ({ ip: h.ip, output_dir: `${engagementDir}/hosts/${h.ip}` })))}\nReturn NET_RESUME_SCAN_SCHEMA.`,
  767. { schema: NET_RESUME_SCAN_SCHEMA, agentType: 'general-purpose', label: 'resume-scan-net', phase: 'Assess' }
  768. ).catch(() => null)
  769. const netRows = (netScan && Array.isArray(netScan.hosts)) ? netScan.hosts : []
  770. const netCompleteIps = new Set(netRows.filter(r => r && r.complete === true && Number(r.applicable) > 0).map(r => r.ip))
  771. netResumeCompleted = deepenHosts.filter(h => netCompleteIps.has(h.ip)).map(h => { const row = netRows.find(r => r.ip === h.ip) || {}; return { ip: h.ip, tag: h.ip, output_dir: `${engagementDir}/hosts/${h.ip}`, coverage_status: 'COVERAGE_COMPLETE', status: 'COVERAGE_COMPLETE', findings_total: Number(row.findings_total) || 0, confirmed: 0, dropped: 0, rejected: 0 } })
  772. const netIncomplete = deepenHosts.filter(h => !netCompleteIps.has(h.ip)).sort((x, y) => (Number(y.max_cvss) || 0) - (Number(x.max_cvss) || 0))
  773. // Network overhead folds in the pre-deep-dive sweep spend (one agent per slice + inventory + geo/correlate).
  774. const netSweepReserve = indexedSlices.length + 4
  775. const netOverhead = RESUME_OVERHEAD + netSweepReserve
  776. const { assetsThisRun: hostsThisRunN } = resumeSchedule({ incompleteCount: netIncomplete.length, agentCap: 1000, deepSlice: deepAssetSlice, overhead: netOverhead })
  777. const runHosts = netIncomplete.slice(0, hostsThisRunN)
  778. netDeferredHosts = netIncomplete.slice(hostsThisRunN)
  779. const NH = runHosts.length
  780. results.push(...netResumeCompleted)
  781. log(`Deep-dive resume-scan: ${netResumeCompleted.length} host(s) pre-complete, ${netIncomplete.length} incomplete -> ${NH} converged this run (~${NH ? Math.floor((1000 - netOverhead) / NH) : 0} agents/host), ${netDeferredHosts.length} deferred.`)
  782. for (const grp of chunk(runHosts, cap)) {
  783. // Single-stage: the deep-dive loop validates each finding INLINE (strict
  784. // per-finding, drop-entirely) — no separate Stage-2 validate pass.
  785. const gr = await parallel(grp.map(h => () =>
  786. workflow('coordinator-loop', {
  787. target: h.ip,
  788. output_dir: `${engagementDir}/hosts/${h.ip}`,
  789. goal: `Deep-dive vuln assessment of host ${h.ip} (already scanned: open ports ${JSON.stringify(h.open_ports || [])}, services ${JSON.stringify(h.top_services || [])}). Confirm and PROVE every exploitable weakness across its open services (vulnerable version -> known CVE with a SAFE check, exposed admin/db/mgmt interface, dangerous misconfig). Authorized vuln-scan DEEP-DIVE, not a flag hunt: enumerate breadth, prove each issue with reproducible NON-DESTRUCTIVE evidence, score on root cause. This host exposes an HTTP surface: ENUMERATE its endpoints/pages/params into OUTPUT_DIR/recon/inventory/surface.json (schema surface/v2 — one unit per endpoint with the agent-set flags it warrants AND a conservative equiv_group: share an id ONLY across cells with the SAME route template / handler / param family, else null) so unit-scope attack-class coverage is measured PER ENDPOINT, and drive every applicable coverage cell to covered/covered_negative. NO brute force, NO DoS, NO destructive writes. Reversible own-tenant writes ${roe.reversible_writes ? 'authorized' : 'NOT authorized'}. Prohibitions: ${JSON.stringify(roe.prohibitions || [])}.`,
  790. scope: `network host deep-dive (coverage mode); open_ports=${JSON.stringify(h.open_ports || [])}`,
  791. skills_hint: 'infrastructure,system',
  792. platform: 'network',
  793. mode: 'coverage', // tiered: app-bearing hosts driven to attack-class coverage
  794. severity_rubric: 'root-cause',
  795. roe,
  796. output_base: 'projects/pentest',
  797. report_format: 'transilience',
  798. inline_validate: true, // strict per-finding validation inside the loop
  799. business_tier: tierDefault,
  800. assets: NH, // governor: partition the agent cap across the per-run deep-dive hosts
  801. dry_tail: dryTail, // convergence: full coverage + K empty batches
  802. agent_reserve: netOverhead, // folds in the pre-deep-dive sweep spend so perAsset*NH+reserve<=1000
  803. nvd_cache_dir: nvdCacheDir,
  804. kev_snapshot: kevSnapshot,
  805. validation_cache_dir: `${engagementDir}/artifacts/validation-cache`,
  806. replay_cache: !!setup.resumed, // E4: restore verdicts only on a resume run
  807. }).then(lo => ({ ip: h.ip, tag: h.ip, output_dir: `${engagementDir}/hosts/${h.ip}`, coverage_status: (lo && (lo.coverage_status || lo.status)) || 'DONE', status: (lo && (lo.engagement_status || lo.status)) || 'DONE', resumable: !!(lo && lo.resumable), findings_total: lo && (lo.findings_total != null ? lo.findings_total : (Array.isArray(lo.findings_confirmed) ? lo.findings_confirmed.length : 0)), confirmed: (lo && lo.confirmed) || 0, dropped: (lo && lo.dropped) || 0, rejected: (lo && lo.rejected) || 0 }))
  808. .catch(err => ({ ip: h.ip, tag: h.ip, output_dir: `${engagementDir}/hosts/${h.ip}`, coverage_status: 'FAILED', status: 'FAILED', degraded: true, blocked_reason: 'coordinator-loop error: ' + String(err) }))
  809. ))
  810. results.push(...gr.filter(Boolean))
  811. }
  812. }
  813. // Correlate across deepened-host validated findings (reuse stitcher + prioritiser).
  814. phase('Correlate')
  815. const netAssetDirs = results.map(r => r.output_dir).filter(Boolean)
  816. const correlateNet = await agent(
  817. `ROLE: cross-host correlation. cwd is repo root. Stitch validated findings across hosts into attack paths, then risk-rank. Mount skills/attack-path-stitcher/SKILL.md and skills/risk-prioritiser/SKILL.md.\n` +
  818. `ENGAGEMENT_DIR: ${engagementDir}\nHOST_DIRS: ${JSON.stringify(netAssetDirs)}\n\n` +
  819. `Do: build ${engagementDir}/artifacts/org-surface.json from ${engagementDir}/recon/inventory/hosts.json + each host's artifacts/validated/*.json (VALID/REPAIRED — every file in validated/ is a passing verdict); run the stitcher -> ${engagementDir}/artifacts/attack-paths.{json,md} (confirmed edges only — feasibility 1.0 with via_findings); derive ${engagementDir}/business-tier-map.csv then risk-prioritise (python3 tools/risk-prioritise.py --output-dir ${engagementDir}) -> ${engagementDir}/artifacts/attack-paths-ranked.{json,md}. Single-host validated findings not on a path are scored too. Return CORRELATE_SCHEMA.`,
  820. { schema: CORRELATE_SCHEMA, agentType: 'general-purpose', label: 'correlate', phase: 'Correlate' }
  821. ).catch(err => ({ ok: false, notes: ['correlate error: ' + String(err)] }))
  822. // Report — deterministic finalize (assembler -> PDF -> package); COMPLETE requires
  823. // BOTH scan completion AND deterministic 100% attack-class coverage (the gate runs
  824. // inside finalize over the swept + deep-dived hosts). Provisional until the gate returns.
  825. phase('Report')
  826. const netProvisionalStatus = scanComplete ? 'COMPLETE' : 'INCOMPLETE_scan'
  827. const netMeta = resolveEngagementMeta({ prior: input.prior || null, prompt: input.engagement || {}, currentScope: netTargets, dateTag: setup.date_tag, explicitVersion: input.version })
  828. const netEngagementBlock = {
  829. title_lines: netMeta.title_lines || [netMeta.title || setup.engagement_name || 'Network Vulnerability Assessment'],
  830. title: netMeta.title || setup.engagement_name || 'Network Vulnerability Assessment',
  831. subtitle: netMeta.subtitle || (netMeta.supersedes ? `Retest — supersedes ${netMeta.supersedes}` : `${liveCount} live host(s) of ~${hostEstimate}`),
  832. date: setup.date_tag, footer: netMeta.sector || 'Security Assessment',
  833. cover_meta: [
  834. ['REPORT DATE', setup.date_tag],
  835. ['DURATION', netMeta.duration],
  836. ['CLASSIFICATION', netMeta.classification || 'Confidential'],
  837. ['SECTOR', netMeta.sector],
  838. ['TARGET', netMeta.target || netTargets[0] || null],
  839. ['METHOD', netMeta.method || 'Network scan + deep-dive'],
  840. ['PREPARED BY', netMeta.prepared_by || 'Transilience'],
  841. ['REPORT ID', netMeta.report_id],
  842. ['VERSION', netMeta.version],
  843. ...(netMeta.supersedes ? [['SUPERSEDES', netMeta.supersedes]] : []),
  844. ],
  845. }
  846. let reportNet = { ok: false }
  847. if (wantReport) {
  848. reportNet = await finalizeEngagement({ engagementDir, engagement: netEngagementBlock, reportFormat: input.report_format, customReportCmd: input.custom_report_cmd, engagementStatus: netProvisionalStatus, agentCount: null, conclusion: input.conclusion || null, protect: input.protect !== false, certinExport: input.certin_export === true, certin: input.certin || null })
  849. if (reportNet.status === 'BLOCKED') log(`Report BLOCKED: ${reportNet.blocked_reason}`)
  850. }
  851. // COMPLETE requires scan completion AND the deterministic coverage gate (run inside
  852. // finalize) reporting 100% AND convergence with nothing left to resume. Fails closed.
  853. const netCoverageComplete = wantReport ? (reportNet.coverage_complete === true) : true
  854. const { engagement_status: netConvStatus, resume: netResumeBlock } = classifyEngagement(results, netDeferredHosts.map(h => h.ip))
  855. const netEngagementStatus = !scanComplete
  856. ? 'INCOMPLETE_scan'
  857. : ((netCoverageComplete && netConvStatus === 'COMPLETE') ? 'COMPLETE' : (netConvStatus === 'INCOMPLETE_resumable' ? 'INCOMPLETE_resumable' : 'INCOMPLETE_coverage'))
  858. const netRound = Number(setup.resume_round) || 0
  859. const netResume = netResumeBlock.remaining_assets.length
  860. ? { ...netResumeBlock, resume_round: netRound, rerun_hint: (netRound + 1) <= maxResumeRounds ? `resume_dir=${engagementDir}` : null, exhausted_rounds: (netRound + 1) > maxResumeRounds }
  861. : null
  862. log(`Network engagement ${netEngagementStatus}: ${liveCount} live host(s), ${results.length} deep-dive result(s), ${netDeferredHosts.length} deferred.${netResume && netResume.rerun_hint ? ` Resume: re-invoke with resume_dir=${engagementDir}.` : ''}`)
  863. return {
  864. status: 'DONE',
  865. engagement_kind: 'network',
  866. engagement_status: netEngagementStatus,
  867. resume: netResume,
  868. date_tag: setup.date_tag,
  869. engagement_dir: engagementDir,
  870. cpu_cores: cores,
  871. parallel_cap: cap,
  872. scan_profile: scanProfile,
  873. port_spec: portSpec,
  874. targets: netTargets.length,
  875. host_estimate: hostEstimate,
  876. slices: indexedSlices.length,
  877. live: liveCount,
  878. dead: deadCount,
  879. interesting: ranked.length,
  880. deepened: deepenHosts.map(h => h.ip),
  881. deep_results: results.map(r => ({ ip: r.ip, status: r.status, findings_total: r.findings_total, validation: r.validation && r.validation.counts ? r.validation.counts : null, output_dir: r.output_dir })),
  882. attack_paths_ranked: correlateNet && correlateNet.ranked_path ? correlateNet.ranked_path : `${engagementDir}/artifacts/attack-paths-ranked.md`,
  883. report_format: reportNet && reportNet.format ? reportNet.format : (input.report_format === 'custom' ? 'custom' : 'transilience'),
  884. report_status: reportNet && reportNet.status ? reportNet.status : (wantReport ? 'BLOCKED' : 'SKIPPED'),
  885. report_blocked_reason: reportNet && reportNet.blocked_reason ? reportNet.blocked_reason : null,
  886. report_path: reportNet && reportNet.report_path ? reportNet.report_path : `${engagementDir}/reports/Penetration-Test-Report.pdf`,
  887. severity_counts: reportNet && reportNet.severity_counts ? reportNet.severity_counts : null,
  888. deliverable_zip: reportNet && reportNet.deliverable_zip ? reportNet.deliverable_zip : null,
  889. protected_zip: reportNet && reportNet.protected_zip ? reportNet.protected_zip : null,
  890. deliverable_password: reportNet && reportNet.deliverable_password ? reportNet.deliverable_password : null,
  891. password_file: reportNet && reportNet.password_file ? reportNet.password_file : null,
  892. protection_limitations: reportNet && reportNet.protection_limitations ? reportNet.protection_limitations : [],
  893. summary: reportNet && reportNet.summary ? reportNet.summary : null,
  894. slack_offer: !!(reportNet && reportNet.slack_offer && wantReport),
  895. tool_limitations: scanLimitations,
  896. }
  897. }
  898. if (KIND === 'mobile') {
  899. // ==========================================================================
  900. // MOBILE MODE — a MAPT over TWO gated surfaces.
  901. // Acquire : hash + unpack + decompile the artifact, then emit BOTH surfaces —
  902. // the app bundle (mobile-surface/v1 -> the 15 MAS-* MASVS classes)
  903. // AND the backend recovered FROM the bundle (surface/v2 -> the
  904. // ordinary web/API classes). The second surface is the point: a MAPT
  905. // that stops at the bundle has tested the smaller half.
  906. // Expand : only when the scope ALSO names apexes (a hybrid WAPT+MAPT scope).
  907. // Device : mobile_device_check.py preflight. Only exit 0 is ready; anything
  908. // else routes to a machine-verified obstruction + client-input
  909. // request. There is NO flag that skips DAST.
  910. // Assess : one fan-out over app assets (platform:'mobile') and backend assets
  911. // (platform:'web'), both in coverage mode.
  912. // Self-contained and returns; WEB falls through below.
  913. // ==========================================================================
  914. phase('Acquire')
  915. const mobPlatform = mobilePlatformArg || setup.mobile_platform || 'android'
  916. const artifacts = (setup.mobile_artifacts || []).filter(a => a && (a.path || a.store_id))
  917. if (!artifacts.length) {
  918. log('Mobile engagement but the scope named no acquirable artifact')
  919. return { status: 'BLOCKED', reason: 'mobile engagement but no app artifact or store id is in scope', engagement_kind: 'mobile', engagement_dir: engagementDir, setup }
  920. }
  921. // the intake manifest already carries the stored path + sha256 for every artifact
  922. const storedFor = (p) => {
  923. const row = (intakeManifest || []).find(m => m && (m.original === p || m.stored === p))
  924. return row ? { stored: row.stored, sha256: row.sha256 } : { stored: p, sha256: null }
  925. }
  926. // scope allow-list for the recovered backends: what the SCOPE named, never what a
  927. // decompiled string happens to contain
  928. const mobAllow = [...new Set([...(setup.mobile_backend_hints || []), ...(setup.apex_domains || [])]
  929. .map(h => String(h || '').replace(/^https?:\/\//, '').split('/')[0].trim()).filter(Boolean))]
  930. const ACQUIRE_SCHEMA = {
  931. type: 'object', additionalProperties: true,
  932. required: ['ok', 'platform', 'app_dir'],
  933. properties: {
  934. ok: { type: 'boolean' },
  935. platform: { type: 'string' }, package_id: { type: ['string', 'null'] }, version_name: { type: ['string', 'null'] },
  936. artifact_path: { type: ['string', 'null'] }, artifact_sha256: { type: ['string', 'null'] },
  937. acquired: { type: 'boolean', description: 'a real artifact is on disk AND unpacked (false = store id only / nothing supplied)' },
  938. framework: { type: 'string', description: 'flutter | rn_hermes | unity_il2cpp | native_android | native_ios | webview | unknown' },
  939. tag: { type: 'string' }, app_dir: { type: 'string' },
  940. mobile_surface_path: { type: ['string', 'null'] },
  941. mobile_units: { type: 'number', description: "VERBATIM from mobile_surface_build.py's JSON summary — never your own count" },
  942. endpoints_recovered: { type: 'number' },
  943. api_surfaces: { type: 'array', items: { type: 'object', additionalProperties: true, properties: { tag: { type: 'string' }, apex: { type: 'string' }, output_dir: { type: 'string' }, surface_path: { type: 'string' }, units: { type: 'number' } } } },
  944. skipped_out_of_scope: { type: 'array', items: { type: 'string' } },
  945. control_wiring_path: { type: ['string', 'null'] }, wiring_gaps: { type: 'array', items: { type: 'string' } },
  946. tool_limitations: { type: 'array', items: { type: 'string' } },
  947. blocked_reason: { type: ['string', 'null'] },
  948. },
  949. }
  950. const acquireResults = (await parallel(artifacts.map((a, i) => () => {
  951. const plat = (a.platform || (String(a.path || '').endsWith('.ipa') ? 'ios' : 'android')).toLowerCase()
  952. const st = storedFor(a.path)
  953. const tag = `${(a.package_id || a.store_id || `app-${i + 1}`).replace(/[^A-Za-z0-9]+/g, '-').toLowerCase().replace(/^-+|-+$/g, '')}-${plat}-app`
  954. const appDir = `${engagementDir}/${tag}`
  955. return agent(
  956. `ROLE: MOBILE ACQUIRE + TRIAGE + SAST (deterministic tools own the bytes; you author FACTS only). cwd is repo root.\n` +
  957. `ARTIFACT: ${st.stored || '(not supplied)'} sha256=${st.sha256 || '(unknown)'} platform=${plat} APP_DIR=${appDir}\n` +
  958. `STORE_ID: ${a.store_id || '(none)'} PACKAGE: ${a.package_id || '(unknown)'}\n\n` +
  959. `1. mkdir -p ${appDir}/{recon/inventory,recon/dast,artifacts,reports}. If no artifact file is on disk and only a store id is known, acquire it ONLY if the scope authorises it; otherwise return ok:false with blocked_reason.\n` +
  960. `2. UNPACK + DECOMPILE (tools, not judgement). Android: \`unzip -o\` into artifacts/extracted/, \`apktool d -f -o artifacts/apktool\`, \`jadx -d artifacts/jadx\`, and for a React-Native bundle hermes-dec over assets/index.android.bundle. .aab/.xapk/.apks: \`bundletool build-apks --mode=universal\` first. iOS: unzip the .ipa, then plutil/otool/class-dump over Payload/*.app.\n` +
  961. `3. DETERMINISTIC FACTS — run these and do not hand-write their outputs:\n` +
  962. ` python3 tools/mobile_manifest_facts.py --platform ${plat} --decoded ${plat === 'ios' ? `${appDir}/artifacts/extracted` : `${appDir}/artifacts/apktool`} --app-dir ${appDir} --artifact ${JSON.stringify(st.stored || '')} --artifact-sha256 ${JSON.stringify(st.sha256 || '')} --framework <the framework you fingerprinted>\n` +
  963. (plat === 'android' ? ` python3 tools/apk_control_wiring.py ${appDir}/artifacts/apktool --json > ${appDir}/recon/control_wiring.json (its shipped-but-unwired / pinning-present-but-inert verdicts are AGENT-UNFABRICATABLE: never claim a control is enforced past a tool that saw it built and discarded)\n` : ` (control-wiring analysis is Android-only today — record that as a tool_limitation for this iOS artifact)\n`) +
  964. `4. YOUR FACTS — two files, facts only:\n` +
  965. ` (a) ${appDir}/recon/inventory/app-units.json {"schema":"app-units/v1","units":[{unit_id,type:webview|storage|crypto-use,address,flags:[webview|local_store|crypto_use],equiv_group,evidence_ref}]} — the CODE-level units only decompiled-source review finds. Exported components and deep links come from the manifest tool; do NOT duplicate them here.\n` +
  966. ` (b) ${appDir}/recon/inventory/endpoints.json [{origin,method,path_template,auth_scheme,params[],flags[<the web agent flags: object_by_id,json_body,role_verb_gated,sensitive_flow,server_fetched_url,input_sink,workflow,deser_or_ci,inbound_webhook,id_keyed_unauth,stored_field,auth_surface,consumes_upstream,static_js_or_repo>],equiv_group,evidence_ref,source_file,source_line}] — THE RECOVERED SERVER CONTRACT. This is the highest-value output of the whole phase: it becomes a separately-gated web asset. Recover EVERY endpoint the bundle references (route tables, RTK/retrofit/dio definitions, string constants, native .so strings) with its real route template. Set equiv_group ONLY when two endpoints genuinely share a handler family; when unsure leave it null — the gate CREDITS siblings from it, so an invented group erases cells.\n` +
  967. `5. EMIT BOTH SURFACES (tool-owned):\n` +
  968. ` python3 tools/mobile_surface_build.py --app-dir ${appDir} --engagement-dir ${engagementDir} --platform ${plat} --allow ${mobAllow.length ? mobAllow.map(h => JSON.stringify(h)).join(' ') : '(pass --allow with NO values only if the scope truly names no backend)'}\n` +
  969. ` Copy mobile_units / endpoints_recovered / api_surfaces / skipped_out_of_scope VERBATIM from its JSON summary line into your return. Do NOT recount them yourself.\n` +
  970. `Return ACQUIRE_SCHEMA with tag=${JSON.stringify(tag)} and app_dir=${JSON.stringify(appDir)}. Report real numbers; a small recovered surface is a fact to report, never one to pad.`,
  971. { schema: ACQUIRE_SCHEMA, agentType: 'general-purpose', label: `acquire:${tag}`, phase: 'Acquire' }
  972. ).catch(() => null)
  973. }))).filter(Boolean)
  974. const mobApps = acquireResults.filter(r => r && r.ok && r.app_dir)
  975. if (!mobApps.length) {
  976. log('Acquire produced no usable app bundle')
  977. return { status: 'BLOCKED', reason: 'no app artifact could be acquired or unpacked', engagement_kind: 'mobile', engagement_dir: engagementDir, setup, acquire: acquireResults }
  978. }
  979. const mobLimitations = mobApps.flatMap(r => r.tool_limitations || [])
  980. // Hybrid WAPT+MAPT: a scope naming apexes as well as an artifact keeps its web
  981. // half — expand those apexes and merge them into the backend work list.
  982. let expandedApiAssets = []
  983. const mobApexes = (setup.apex_domains || []).filter(Boolean)
  984. if (mobApexes.length) {
  985. phase('Expand')
  986. const EXPAND_MOB_SCHEMA = { type: 'object', additionalProperties: true, required: ['ok', 'work_list'], properties: { ok: { type: 'boolean' }, work_list: { type: 'array', items: { type: 'object', additionalProperties: true, properties: { tag: { type: 'string' }, base_url: { type: 'string' }, apex: { type: 'string' }, type: { type: 'string' }, output_dir: { type: 'string' }, notes: { type: 'string' } } } }, notes: { type: 'array', items: { type: 'string' } } } }
  987. const ex = await agent(
  988. `ROLE: SURFACE EXPANSION for the WEB half of a hybrid mobile engagement. cwd is repo root.\n` +
  989. `APEXES: ${JSON.stringify(mobApexes)}\nENGAGEMENT_DIR: ${engagementDir}\n\n` +
  990. `Run CT-log / passive-DNS / origin discovery across every apex and return work_list[] = the in-scope web assets, each {tag, base_url, apex, type, output_dir:"${engagementDir}/<tag>", notes}. These are assessed ALONGSIDE the backends recovered from the app bundle — do NOT duplicate a host that the bundle already produced an asset for: ${JSON.stringify(mobApps.flatMap(r => (r.api_surfaces || []).map(s => s.apex)))}. Stay strictly in scope.`,
  991. { schema: EXPAND_MOB_SCHEMA, agentType: 'general-purpose', label: 'expand-mobile-web', phase: 'Expand' }
  992. ).catch(() => null)
  993. if (ex && ex.ok && Array.isArray(ex.work_list)) {
  994. expandedApiAssets = ex.work_list.filter(a => a && a.tag).map(a => ({
  995. kind: 'api', tag: a.tag, apex: a.apex || '', base_url: a.base_url || a.apex,
  996. output_dir: String(a.output_dir || `${engagementDir}/${a.tag}`).replace(/\/+$/, ''),
  997. recovered_from: 'surface-expansion', units: 1, business_tier: tierDefault,
  998. }))
  999. log(`Hybrid scope: expansion added ${expandedApiAssets.length} web asset(s) beside the bundle-recovered backends.`)
  1000. }
  1001. }
  1002. // one backend asset per recovered apex, de-duplicated by tag
  1003. const apiByTag = new Map()
  1004. for (const r of mobApps) {
  1005. for (const s of r.api_surfaces || []) {
  1006. if (s && s.tag && !apiByTag.has(s.tag)) {
  1007. apiByTag.set(s.tag, { kind: 'api', tag: s.tag, apex: s.apex || '', base_url: s.apex ? `https://${s.apex}` : s.tag, output_dir: String(s.output_dir || `${engagementDir}/${s.tag}`).replace(/\/+$/, ''), recovered_from: r.tag, units: Number(s.units) || 0, business_tier: tierDefault })
  1008. }
  1009. }
  1010. }
  1011. for (const a of expandedApiAssets) if (!apiByTag.has(a.tag)) apiByTag.set(a.tag, a)
  1012. const apiAssets = [...apiByTag.values()]
  1013. // THE hard gate, and the direct fix for the failure that motivated this mode.
  1014. // mobApps.length is required because [].every() is vacuously true. A bundle that
  1015. // yields ZERO backend endpoints is a FAILED acquisition, not a small surface.
  1016. const mobSurfaceOk = mobApps.length > 0 && mobApps.every(r => Number(r.mobile_units) > 0)
  1017. && apiAssets.length > 0 && apiAssets.every(a => Number(a.units) > 0)
  1018. const totalEndpoints = mobApps.reduce((n, r) => n + (Number(r.endpoints_recovered) || 0), 0)
  1019. log(`Acquire: ${mobApps.length} app bundle(s), ${totalEndpoints} endpoint(s) recovered -> ${apiAssets.length} backend asset(s); surface_ok=${mobSurfaceOk}.`)
  1020. if (dryRun) {
  1021. return { status: 'DRY_RUN', engagement_kind: 'mobile', engagement_dir: engagementDir, date_tag: setup.date_tag, cpu_cores: cores, parallel_cap: cap, mobile_platform: mobPlatform, apps: mobApps.map(r => ({ tag: r.tag, platform: r.platform, package_id: r.package_id, framework: r.framework, mobile_units: r.mobile_units })), endpoints_recovered: totalEndpoints, api_assets: apiAssets.map(a => ({ tag: a.tag, apex: a.apex, units: a.units })), surface_ok: mobSurfaceOk, tool_limitations: mobLimitations }
  1022. }
  1023. // ---- Device preflight: the DAST gate -------------------------------------
  1024. phase('Device')
  1025. const DEVICE_SCHEMA = {
  1026. type: 'object', additionalProperties: true, required: ['platform', 'ready', 'exit_code'],
  1027. properties: {
  1028. platform: { type: 'string' }, ready: { type: 'boolean' }, exit_code: { type: 'number' },
  1029. backend: { type: ['string', 'null'] }, handle: { type: ['string', 'null'] },
  1030. api_level: { type: ['number', 'null'] }, os_version: { type: ['string', 'null'] },
  1031. root: { type: 'boolean' }, frida_ok: { type: 'boolean' }, mitm_ca: { type: 'boolean' },
  1032. blockers: { type: 'array', items: { type: 'string' } },
  1033. blocked_classes: { type: 'array', items: { type: 'string' } },
  1034. limitations: { type: 'array', items: { type: 'string' } },
  1035. verdict_path: { type: ['string', 'null'] },
  1036. },
  1037. }
  1038. const devPlatforms = mobPlatform === 'both' ? ['android', 'ios'] : [mobPlatform]
  1039. const deviceResults = (await parallel(devPlatforms.map(plat => () => agent(
  1040. `ROLE: DEVICE PREFLIGHT RUNNER (deterministic; run the command and report facts). cwd is repo root.\n` +
  1041. `Do NOT try to fix the device, do NOT judge whether DAST is "worth it", and NEVER edit anything to make the check pass.\n\n` +
  1042. `1. Run EXACTLY: python3 tools/mobile_device_check.py --platform ${plat}${deviceSerial ? ` --serial ${deviceSerial}` : ''}${emulatorAvd ? ` --avd ${emulatorAvd}` : ''} --engagement-dir ${mobApps[0].app_dir} --json\n` +
  1043. ` It writes recon/dast/device-check.json and prints the same JSON on its last stdout line. Copy every field VERBATIM into DEVICE_SCHEMA. ready = (exit code 0) and NOTHING ELSE — exit 20 (DEGRADED, which includes every iOS Simulator) is NOT ready.\n` +
  1044. `2. If and only if ready: bring the instrumented instance up ONCE so the assess executors attach instead of each re-doing bring-up — install the artifact, trust the interception CA, start frida-server, start the capturing proxy into recon/dast/traffic/. Then re-run the check and report the refreshed facts.\n` +
  1045. `Report what is true.`,
  1046. { schema: DEVICE_SCHEMA, agentType: 'general-purpose', label: `device:${plat}`, phase: 'Device' }
  1047. ).catch(() => null)))).filter(Boolean)
  1048. const deviceReady = deviceResults.length > 0 && deviceResults.every(d => d && d.ready === true)
  1049. const deviceHandles = deviceResults.map(d => `${d.platform}:${d.backend || '?'}${d.handle ? `/${d.handle}` : ''}`).join(', ')
  1050. const deviceLimitations = deviceResults.flatMap(d => d.limitations || [])
  1051. let dastDeferral = null
  1052. if (!deviceReady) {
  1053. // NOT a skip. One agent must attempt the documented bypasses, record MACHINE
  1054. // evidence, and file a client-input request. Only then is a deferral offered.
  1055. const OBSTRUCTION_SCHEMA = { type: 'object', additionalProperties: true, required: ['obstructed'], properties: { obstructed: { type: 'boolean' }, reason: { type: 'string' }, obstruction_path: { type: ['string', 'null'] }, cir_path: { type: ['string', 'null'] }, cir_rel: { type: ['string', 'null'] }, blocked_classes: { type: 'array', items: { type: 'string' } }, attempts: { type: 'array', items: { type: 'object', additionalProperties: true } } } }
  1056. const appDir = mobApps[0].app_dir
  1057. const obst = await agent(
  1058. `ROLE: DAST OBSTRUCTION RECORDER. cwd is repo root. The device preflight did not return READY:\n` +
  1059. `${JSON.stringify(deviceResults.map(d => ({ platform: d.platform, exit_code: d.exit_code, backend: d.backend, blockers: d.blockers, blocked_classes: d.blocked_classes })))}\n\n` +
  1060. `A missing device is NEVER a silent skip. Before any cell may be deferred you must:\n` +
  1061. `1. ATTEMPT the documented bring-up/bypass routes and record each one — Magisk Zygisk + DenyList, \`objection patchapk\` / frida-gadget repack, \`objection android sslpinning disable\`, an emulator-detection hook, and (iOS) the Simulator-vs-device capability delta. Read skills/mobile-security/reference/android-dynamic-analysis.md and ios-dynamic-analysis.md for the recipes.\n` +
  1062. `2. WRITE ${appDir}/recon/dast/obstruction.json = {attempts:[{technique,command,exit_code,stdout_excerpt,timestamp}],app_exit_signal,logcat_excerpt,conclusion}. Real commands and real output — this is the evidence that the shortfall is genuine.\n` +
  1063. `3. WRITE ${appDir}/reports/client-input-requests/CIR-001.md requesting exactly what unblocks it (a physical rooted/jailbroken device, a debug/no-pinning build, a test tenant).\n` +
  1064. ` CRITICAL: the gate resolves client_input_request RELATIVE TO THE ASSET DIR. Return cir_rel="reports/client-input-requests/CIR-001.md" — a path relative to ${appDir}, NOT an engagement-root or absolute path. Get this wrong and the deferral is an unsubstantiated hard miss and the engagement cannot complete.\n` +
  1065. `4. blocked_classes = the runtime-only MAS classes the shortfall actually costs (take them from the device-check verdict's blocked_classes). Do NOT list static classes — they are provable from the artifact and the gate refuses to defer them.\n` +
  1066. `Set obstructed=true ONLY if both files now exist on disk.`,
  1067. { schema: OBSTRUCTION_SCHEMA, agentType: 'general-purpose', label: 'dast-obstruction', phase: 'Device' }
  1068. ).catch(() => null)
  1069. if (obst && obst.obstructed === true && obst.obstruction_path && obst.cir_path) {
  1070. dastDeferral = { deferral_reason: obst.reason || 'no ready DAST device; documented bypasses attempted and recorded', client_input_request: obst.cir_rel || 'reports/client-input-requests/CIR-001.md', blocked_on: 'device', evidence: obst.obstruction_path, blocked_classes: obst.blocked_classes || [] }
  1071. log(`DAST obstructed — substantiated deferral recorded for ${(dastDeferral.blocked_classes || []).length} runtime class(es).`)
  1072. } else {
  1073. log('DAST device not ready AND no substantiated obstruction record — the engagement cannot complete.')
  1074. }
  1075. }
  1076. // ---- Assess: both surfaces, coverage mode --------------------------------
  1077. phase('Assess')
  1078. const appAssets = mobApps.map(r => ({ kind: 'app', tag: r.tag, output_dir: r.app_dir, platform: r.platform, package_id: r.package_id, framework: r.framework, artifact_sha256: r.artifact_sha256, business_tier: tierDefault }))
  1079. const mobWork = [...appAssets, ...apiAssets]
  1080. const mobOverhead = RESUME_OVERHEAD + mobApps.length * 4 + 8
  1081. const NM = mobWork.length
  1082. const mobResults = []
  1083. for (const grp of chunk(mobWork, cap)) {
  1084. const gr = await parallel(grp.map(a => () => (a.kind === 'app'
  1085. ? workflow('coordinator-loop', {
  1086. target: a.package_id || a.tag,
  1087. output_dir: a.output_dir,
  1088. goal: `MASVS/MASTG assessment of the ${a.platform} app bundle ${a.package_id || ''} (${a.framework}; sha256 ${a.artifact_sha256 || 'n/a'}). Drive EVERY applicable cell in OUTPUT_DIR/recon/inventory/mobile-surface.json to covered/covered_negative across STORAGE, CRYPTO, AUTH, NETWORK, PLATFORM/IPC, CODE, RESILIENCE and PRIVACY. Tag every finding with its MASVS control id AND its MASTG-TEST id. RESILIENCE and every "this control is enforced" claim is a RUNTIME claim: OUTPUT_DIR/recon/control_wiring.json already records which controls ship inert (pinning_present_but_inert, shipped_but_unwired) — raise those as POSITIVES, but never produce the corresponding NEGATIVE from static evidence, and never score a bypass you did not run. ${dastDeferral ? `DEVICE UNAVAILABLE: a machine-verified obstruction is recorded at ${dastDeferral.evidence}. For the runtime-only cells ${JSON.stringify(dastDeferral.blocked_classes || [])} ONLY, write the coverage.json ledger entry {"status":"deferred","deferral_reason":${JSON.stringify(dastDeferral.deferral_reason)},"client_input_request":"${dastDeferral.client_input_request}","blocked_on":"device"} — that path is RELATIVE TO THIS ASSET DIR and MUST resolve on disk. proof_mode:static cells are NOT deferrable; the gate rejects that outright.` : `DEVICE READY (${deviceHandles}): the dynamic cells are MANDATORY — run them.`} Reversible own-tenant writes ${roe.reversible_writes ? 'authorized' : 'NOT authorized'}. Prohibitions: ${JSON.stringify(roe.prohibitions || [])}.`,
  1089. scope: `mobile app bundle: platform=${a.platform}; package=${a.package_id}; framework=${a.framework}; device=${deviceReady ? deviceHandles : 'UNAVAILABLE (substantiated obstruction)'}`,
  1090. skills_hint: 'mobile-security,reverse-engineering,authentication',
  1091. platform: 'mobile',
  1092. mode: 'coverage',
  1093. surface_file: 'recon/inventory/mobile-surface.json',
  1094. severity_rubric: 'root-cause',
  1095. roe,
  1096. output_base: 'projects/pentest',
  1097. report_format: 'transilience',
  1098. inline_validate: true,
  1099. business_tier: a.business_tier,
  1100. assets: NM,
  1101. dry_tail: dryTail,
  1102. agent_reserve: mobOverhead,
  1103. nvd_cache_dir: nvdCacheDir,
  1104. kev_snapshot: kevSnapshot,
  1105. validation_cache_dir: `${engagementDir}/artifacts/validation-cache`,
  1106. replay_cache: !!setup.resumed,
  1107. })
  1108. : workflow('coordinator-loop', {
  1109. target: a.base_url,
  1110. output_dir: a.output_dir,
  1111. goal: `Achieve THOROUGH OWASP API+Web attack-class coverage of the backend this mobile client talks to (${a.base_url}). Its surface was RECOVERED FROM THE APP BUNDLE — OUTPUT_DIR/recon/inventory/surface.json (schema surface/v2) already lists every endpoint with its route template; PRESERVE it and do not re-enumerate from scratch, but DO add anything you discover live. This surface is not browser-reachable and is therefore SYSTEMATICALLY UNDER-TESTED: treat every client-side authorization check as a server-side HYPOTHESIS to confirm (a predictable id in a request proves intent, not vulnerability). Prioritise BOLA/BOPLA/BFLA on {id}/user_id routes, mass-assignment on fields the UI never exposes, and any encrypted request envelope whose key material was recovered from the bundle (replay it against the live API). You are DONE only when every applicable coverage-matrix cell is covered or genuinely negated. Reversible own-tenant writes ${roe.reversible_writes ? 'authorized' : 'NOT authorized'}. Prohibitions: ${JSON.stringify(roe.prohibitions || [])}.`,
  1112. scope: `mobile-recovered backend: apex=${a.apex}; recovered_from=${a.recovered_from}; tier=${a.business_tier}`,
  1113. skills_hint: 'api-security,authentication,server-side',
  1114. platform: 'web',
  1115. mode: 'coverage',
  1116. severity_rubric: 'root-cause',
  1117. roe,
  1118. output_base: 'projects/pentest',
  1119. report_format: 'transilience',
  1120. inline_validate: true,
  1121. business_tier: a.business_tier,
  1122. assets: NM,
  1123. dry_tail: dryTail,
  1124. agent_reserve: mobOverhead,
  1125. nvd_cache_dir: nvdCacheDir,
  1126. kev_snapshot: kevSnapshot,
  1127. validation_cache_dir: `${engagementDir}/artifacts/validation-cache`,
  1128. replay_cache: !!setup.resumed,
  1129. })
  1130. ).then(lo => ({ tag: a.tag, kind: a.kind, output_dir: a.output_dir, coverage_status: (lo && lo.engagement_status) || (lo && lo.status) || 'UNKNOWN', findings: (lo && lo.findings) || 0, coverage_complete: !!(lo && lo.coverage_complete) }))
  1131. .catch(err => ({ tag: a.tag, kind: a.kind, output_dir: a.output_dir, coverage_status: 'FAILED', degraded: true, blocked_reason: `coordinator-loop error: ${String(err)}` }))))
  1132. mobResults.push(...gr.filter(Boolean))
  1133. }
  1134. phase('Correlate')
  1135. const mobAssetDirs = mobWork.map(a => a.output_dir)
  1136. const mobPaths = await agent(
  1137. `ROLE: ATTACK-PATH STITCHER + RISK PRIORITISER across a mobile engagement. cwd is repo root.\n` +
  1138. `ENGAGEMENT_DIR: ${engagementDir}\nASSET_DIRS: ${JSON.stringify(mobAssetDirs)}\n\n` +
  1139. `Read every VALID/REPAIRED finding under <asset>/artifacts/validated/ and stitch multi-hop paths into ${engagementDir}/artifacts/attack-paths.json + .md, then rank them into attack-paths-ranked.json + .md.\n` +
  1140. `A client->API edge is FIRST-CLASS: a secret, endpoint, signing key, or auth scheme recovered from the app bundle that unlocks a backend finding IS a confirmed hop — cite the bundle finding as the via_finding. Do not report the two halves as unrelated single-asset findings.\n` +
  1141. `Return {ok, paths_ranked}.`,
  1142. { schema: { type: 'object', additionalProperties: true, properties: { ok: { type: 'boolean' }, paths_ranked: { type: 'number' } } }, agentType: 'general-purpose', label: 'correlate-mobile', phase: 'Correlate' }
  1143. ).catch(() => null)
  1144. phase('Report')
  1145. const mobProvisional = !mobSurfaceOk ? 'INCOMPLETE_sast' : (deviceReady || dastDeferral ? 'COMPLETE' : 'INCOMPLETE_dast')
  1146. const mobScope = [...mobApps.map(a => a.package_id || a.tag), ...apiAssets.map(a => a.apex).filter(Boolean)]
  1147. const mobMeta = resolveEngagementMeta({ prior: input.prior || null, prompt: input.engagement || {}, currentScope: mobScope, dateTag: setup.date_tag, explicitVersion: input.version })
  1148. const mobEngagementBlock = { ...(input.engagement || {}), ...(mobMeta.engagement || {}), method: (input.engagement && input.engagement.method) || 'MASVS/MASTG mobile application + API penetration test', target: (input.engagement && input.engagement.target) || mobApps[0].package_id || mobApps[0].tag, subtitle: (input.engagement && input.engagement.subtitle) || `${mobApps.length} app bundle(s) + ${apiAssets.length} backend(s)`, scope: mobScope }
  1149. let reportMob = { ok: false }
  1150. if (wantReport) {
  1151. reportMob = await finalizeEngagement({ engagementDir, engagement: mobEngagementBlock, reportFormat: input.report_format, customReportCmd: input.custom_report_cmd, engagementStatus: mobProvisional, agentCount: null, conclusion: input.conclusion || null, protect: input.protect !== false, certinExport: input.certin_export === true, certin: input.certin || null })
  1152. if (reportMob.status === 'BLOCKED') log(`Report BLOCKED: ${reportMob.blocked_reason}`)
  1153. }
  1154. const mobCoverageComplete = wantReport ? (reportMob.coverage_complete === true) : true
  1155. const { engagement_status: mobConvStatus, resume: mobResumeBlock } = classifyEngagement(mobResults, [])
  1156. // Two preconditions, and the order matters: you cannot DAST what you did not
  1157. // acquire. INCOMPLETE_sast is the analogue of network's INCOMPLETE_scan.
  1158. const mobEngagementStatus = !mobSurfaceOk
  1159. ? 'INCOMPLETE_sast'
  1160. : (!(deviceReady || dastDeferral)
  1161. ? 'INCOMPLETE_dast'
  1162. : ((mobCoverageComplete && mobConvStatus === 'COMPLETE') ? 'COMPLETE' : (mobConvStatus === 'INCOMPLETE_resumable' ? 'INCOMPLETE_resumable' : 'INCOMPLETE_coverage')))
  1163. return {
  1164. status: 'DONE',
  1165. engagement_kind: 'mobile',
  1166. engagement_status: mobEngagementStatus,
  1167. resume: mobResumeBlock,
  1168. date_tag: setup.date_tag,
  1169. engagement_dir: engagementDir,
  1170. cpu_cores: cores,
  1171. parallel_cap: cap,
  1172. mobile_platform: mobPlatform,
  1173. apps: mobApps.map(r => ({ tag: r.tag, platform: r.platform, package_id: r.package_id, version_name: r.version_name, framework: r.framework, artifact_sha256: r.artifact_sha256, mobile_units: r.mobile_units, wiring_gaps: r.wiring_gaps || [] })),
  1174. api_assets: apiAssets.map(a => ({ tag: a.tag, apex: a.apex, units: a.units, recovered_from: a.recovered_from })),
  1175. endpoints_recovered: totalEndpoints,
  1176. surface_ok: mobSurfaceOk,
  1177. device: { ready: deviceReady, backends: deviceResults.map(d => ({ platform: d.platform, backend: d.backend, exit_code: d.exit_code, blockers: d.blockers || [] })), limitations: deviceLimitations },
  1178. dast_deferral: dastDeferral,
  1179. skipped_out_of_scope: [...new Set(mobApps.flatMap(r => r.skipped_out_of_scope || []))],
  1180. assets: mobResults,
  1181. attack_paths_ranked: mobPaths && mobPaths.paths_ranked ? mobPaths.paths_ranked : 0,
  1182. report_format: input.report_format || 'transilience',
  1183. report_status: reportMob.status || (wantReport ? 'BLOCKED' : 'SKIPPED'),
  1184. report_blocked_reason: reportMob.blocked_reason || null,
  1185. report_path: reportMob.report_path || null,
  1186. severity_counts: reportMob.severity_counts || null,
  1187. deliverable_zip: reportMob.deliverable_zip || null,
  1188. protected_zip: reportMob.protected_zip || null,
  1189. deliverable_password: reportMob.deliverable_password || null,
  1190. password_file: reportMob.password_file || null,
  1191. protection_limitations: reportMob.protection_limitations || [],
  1192. summary: reportMob.summary || null,
  1193. slack_offer: !!(reportMob.slack_offer && wantReport),
  1194. tool_limitations: [...mobLimitations, ...deviceLimitations],
  1195. }
  1196. }
  1197. // ============================================================================
  1198. // WEB MODE (engagement_kind !== 'network') — existing behavior, unchanged.
  1199. // PHASE: Expand — MANDATORY surface expansion (closes the #1 gap: scope freeze)
  1200. // ============================================================================
  1201. phase('Expand')
  1202. const apexes = (setup.apex_domains || []).filter(Boolean)
  1203. // One expansion agent per apex (bounded by the concurrency cap), then a synthesis
  1204. // agent that merges handoff + discovered hosts into the per-asset work list.
  1205. const apexGroups = chunk(apexes, cap)
  1206. const apexResults = []
  1207. for (const grp of apexGroups) {
  1208. const r = await parallel(grp.map(apex => () =>
  1209. agent(
  1210. `ROLE: SURFACE-EXPANSION recon (apex: ${apex}). cwd is repo root. PASSIVE first; no exploitation. Mount skills/reconnaissance/reference/scenarios/subdomain-enumeration.md and skills/reconnaissance/reference/reconnaissance-principles.md.\n` +
  1211. `OUTPUT_DIR: ${engagementDir}\n\n` +
  1212. `Do, for apex ${apex}:\n` +
  1213. `1. CT-log / passive-DNS enum: crt.sh, certspotter, urlscan, hackertarget, and subfinder/amass if available. Record any unavailable tool-class as a limitation (NEVER skip silently).\n` +
  1214. `2. If the apex is CDN/WAF-fronted (Cloudflare/Akamai/Fastly detected): run an ORIGIN-DISCOVERY pass — direct cloud endpoints, archive.org CDX, historical A records — to surface origins/admin/management consoles that bypass the edge.\n` +
  1215. `3. Probe every discovered host with httpx (or curl -I with a browser UA) for liveness/title/tech.\n` +
  1216. `4. Write ${engagementDir}/recon/inventory/subdomains-${apex}.json (host, ip, tech, live, source). Return a terse bullet list of LIVE in-scope hosts you found and any tool limitations.`,
  1217. { label: `expand:${apex}`, phase: 'Expand', agentType: 'general-purpose' }
  1218. )
  1219. ))
  1220. apexResults.push(...r.filter(Boolean))
  1221. }
  1222. const expandDigest = apexResults.map((r, i) => `### apex ${i + 1}\n${r}`).join('\n\n')
  1223. const expand = await agent(
  1224. `ROLE: surface synthesis. cwd is repo root. Build the per-asset work list for the engagement. Read skills/coordination/reference/coverage-matrix.md (the canonical attack-class catalog).\n` +
  1225. `OUTPUT_DIR: ${engagementDir}\n` +
  1226. `HANDED-IN ASSETS: ${JSON.stringify(setup.assets || [])}\n` +
  1227. `BUSINESS_TIER_DEFAULT: ${tierDefault}\n` +
  1228. `DISCOVERED (from per-apex expansion):\n${expandDigest || '<none>'}\n\n` +
  1229. `SCOPE NOTE: the handed-in assets define the in-scope ENVIRONMENT (often a dev/test env on specific subdomains). Classify EVERY discovered/handed host into exactly one bucket:\n` +
  1230. ` (A) in_scope_app — a testable web/API application in the SAME environment as the handed-in assets (reachable real HTTP app/API/portal/docs). FULL coverage loop.\n` +
  1231. ` (B) scope_adjacent_infra — management/admin/infra consoles (Rancher, Retool, k8s, CI, monitoring) or bastions. LIGHT unauthenticated fingerprint ONLY (identity + exposure); never a full loop or auth/brute probing.\n` +
  1232. ` (C) out_of_scope — PRODUCTION hosts when the scope is a non-prod env (incl. regional prod APIs); CDN/static bundle hosts; npm/embeddable components with no testable URL; anything the scope marks out-of-scope. EXCLUDED (recorded with a reason).\n` +
  1233. `Be conservative: when the scope names a dev/test environment, prod hostnames are OUT OF SCOPE; do NOT turn an npm package or a static-bundle host into a coverage target. Keep the in_scope_app list focused — a handful of REAL apps, not every hostname.\n\n` +
  1234. `Do:\n` +
  1235. `1. Bucket every host (A/B/C) per the rule above, deduped.\n` +
  1236. `2. For each (A) in_scope_app emit a work_list row: tag (kebab host), identifier, type (api|portal|spa|docs), base_url, business_tier (per-asset from scope else default), output_dir = ${engagementDir}/<tag>/, skills_hint (api->api-security; portal/spa->client-side,authentication; docs->reconnaissance), and coverage_matrix: instantiate the catalog from coverage-matrix.md as rows {class_id, taxonomy, title, applicability ('applicable' iff the trigger matches THIS asset else 'not_applicable'+justification), status ('pending'|'NA'), evidence_ref: []}.\n` +
  1237. `3. For each (B) emit an infra_probes row {host, base_url, why}. For each (C) emit an excluded row {host, reason}.\n` +
  1238. `4. Write ${engagementDir}/recon/inventory/expanded-surface.md (full inventory + A/B/C classification) and work-list.json.\n\n` +
  1239. `Return EXPAND_SCHEMA: work_list[] = ONLY in_scope_app (with coverage_matrix); infra_probes[]; excluded[]; expanded_hosts[]; tool_limitations[].`,
  1240. { schema: EXPAND_SCHEMA, agentType: 'general-purpose', label: 'expand-synth', phase: 'Expand' }
  1241. )
  1242. if (!expand || !expand.ok || !Array.isArray(expand.work_list) || !expand.work_list.length) {
  1243. log('Expand produced no work list')
  1244. return { status: 'BLOCKED', reason: 'surface expansion produced no assessable assets', engagement_dir: engagementDir, expand }
  1245. }
  1246. const workList = expand.work_list.map(a => ({ ...a, output_dir: String(a.output_dir || `${engagementDir}/${a.tag}`).replace(/\/+$/, ''), business_tier: a.business_tier || tierDefault }))
  1247. const infraProbes = Array.isArray(expand.infra_probes) ? expand.infra_probes : []
  1248. const excluded = Array.isArray(expand.excluded) ? expand.excluded : []
  1249. log(`Expand complete: ${workList.length} in-scope app(s) — ${workList.map(a => a.tag).join(', ')}; ${infraProbes.length} infra probe(s); ${excluded.length} excluded. Tool limitations: ${JSON.stringify(expand.tool_limitations || [])}`)
  1250. if (dryRun) {
  1251. log('dryRun complete — returning work list + classification without assessment')
  1252. return { status: 'DRY_RUN', engagement_dir: engagementDir, date_tag: setup.date_tag, apex_domains: apexes, expanded_hosts: expand.expanded_hosts || [], work_list: workList, infra_probes: infraProbes, excluded, tool_limitations: expand.tool_limitations || [] }
  1253. }
  1254. // ============================================================================
  1255. // Prompt builders + budgeting for the per-asset pipeline
  1256. // ============================================================================
  1257. // ============================================================================
  1258. // RESUME-SCAN + agent-slice scheduling (WS2 M1). Each in-scope app runs to CONVERGENCE
  1259. // (no cost-style depth budget); the coordinator backstops on an honest per-asset agent
  1260. // slice. Because a run cannot exceed the runtime 1000-agent cap, we fully converge as
  1261. // many INCOMPLETE assets as fit their slice this run and DEFER the rest to a resume run
  1262. // (re-invoke with resume_dir=<engagement_dir>). An asset already at 100% coverage on
  1263. // disk (a prior run) is skipped — the deterministic coverage_gate.py boolean decides.
  1264. // ============================================================================
  1265. phase('Assess')
  1266. const RESUME_SCAN_SCHEMA = {
  1267. type: 'object', additionalProperties: true, required: ['assets'],
  1268. properties: { assets: { type: 'array', items: { type: 'object', additionalProperties: true, properties: { tag: { type: 'string' }, complete: { type: 'boolean' }, applicable: { type: 'number' }, findings_total: { type: 'number' } } } } },
  1269. }
  1270. const resumeScan = await agent(
  1271. `ROLE: RESUME-SCAN (deterministic; run the gate, relay its booleans — NO judgment). cwd is repo root.\n` +
  1272. `For EACH asset below run \`python3 tools/coverage_gate.py --asset-dir <output_dir>\` (it writes <output_dir>/reports/coverage-matrix.json; a non-zero exit is NOT a failure — READ that JSON). Return one row per asset {tag, complete:(the JSON's "complete" boolean), applicable:(its "applicable" count), findings_total:(count of *.json under <output_dir>/artifacts/validated/)}. A missing surface.json/coverage.json or unreadable matrix => complete:false, applicable:0.\n` +
  1273. `ASSETS: ${JSON.stringify(workList.map(a => ({ tag: a.tag, output_dir: a.output_dir })))}\n` +
  1274. `Return RESUME_SCAN_SCHEMA.`,
  1275. { schema: RESUME_SCAN_SCHEMA, agentType: 'general-purpose', label: 'resume-scan', phase: 'Assess' }
  1276. ).catch(() => null)
  1277. const scanRows = (resumeScan && Array.isArray(resumeScan.assets)) ? resumeScan.assets : []
  1278. // resume-COMPLETE iff the gate says complete AND there was real applicable work
  1279. // (guards the fresh-dir "0 cells => vacuously complete" trap).
  1280. const completeTags = new Set(scanRows.filter(r => r && r.complete === true && Number(r.applicable) > 0).map(r => r.tag))
  1281. const resumeCompleted = workList.filter(a => completeTags.has(a.tag)).map(a => {
  1282. const row = scanRows.find(r => r.tag === a.tag) || {}
  1283. return { tag: a.tag, type: a.type, base_url: a.base_url || a.identifier, output_dir: a.output_dir, business_tier: a.business_tier, coverage_status: 'COVERAGE_COMPLETE', coverage_ratio: 1, findings_total: Number(row.findings_total) || 0, validation: null, confirmed: 0, dropped: 0, rejected: 0, narrative: '', report_path: `${a.output_dir}/reports/pentest-report-source.md`, engagement_status: 'THOROUGH' }
  1284. })
  1285. // Selection order for the per-run slice: business_tier desc, then work-list order
  1286. // (deterministic across runs). Stuck assets are re-included (retry-each-run).
  1287. const TIER_RANK = { crown_jewel: 0, revenue: 1, support: 2, dev: 3, unknown: 4 }
  1288. const incompleteWork = workList.filter(a => !completeTags.has(a.tag))
  1289. .map((a, i) => ({ a, i })).sort((x, y) => ((TIER_RANK[x.a.business_tier] ?? 4) - (TIER_RANK[y.a.business_tier] ?? 4)) || (x.i - y.i)).map(o => o.a)
  1290. const { assetsThisRun, deferred } = resumeSchedule({ incompleteCount: incompleteWork.length, agentCap: 1000, deepSlice: deepAssetSlice, overhead: RESUME_OVERHEAD })
  1291. const runThisRun = incompleteWork.slice(0, assetsThisRun)
  1292. const deferredAssets = incompleteWork.slice(assetsThisRun)
  1293. const N = runThisRun.length
  1294. log(`Resume-scan: ${resumeCompleted.length} already complete, ${incompleteWork.length} incomplete -> ${N} converged this run (deep_asset_slice=${deepAssetSlice}, ~${N ? Math.floor((1000 - RESUME_OVERHEAD) / N) : 0} agents/asset), ${deferredAssets.length} deferred to a resume run.`)
  1295. function coverageGoalFor(a) {
  1296. return `Achieve THOROUGH OWASP API+Web attack-class coverage of this asset (${a.type || 'web'}: ${a.base_url || a.identifier}). The objective is to TEST EVERY applicable class in OUTPUT_DIR/coverage.json and report every confirmed weakness with reproducible proof — NOT to capture a flag. You are DONE only when every applicable coverage-matrix class is covered (>=1 experiment) or justified N/A. "I exhausted my hypotheses" is NOT done. ` +
  1297. `Reversible own-org/own-tenant writes are ${roe.reversible_writes ? 'AUTHORIZED' : 'NOT authorized'} (create-then-delete is non-destructive): if a finding can only be proven by a write (e.g. create a connector whose stored base_url the server fetches, to prove SSRF), do the minimal write and clean up. ` +
  1298. `Score findings on the confirmed ROOT CAUSE, not the demonstrated sub-impact; a transient/reversible data-state (deleted records, empty tables, IMDSv2) is NEVER a severity ceiling. Prohibitions: ${JSON.stringify(roe.prohibitions || [])}.`
  1299. }
  1300. function adaptSummary(a, loopOut) {
  1301. const lo = loopOut || {}
  1302. return {
  1303. tag: a.tag, type: a.type, base_url: a.base_url || a.identifier, output_dir: a.output_dir, business_tier: a.business_tier,
  1304. coverage_status: lo.coverage_status || lo.status || 'UNKNOWN',
  1305. coverage_pending: typeof lo.coverage_pending === 'number' ? lo.coverage_pending : null,
  1306. coverage_ratio: typeof lo.coverage_ratio === 'number' ? lo.coverage_ratio : null,
  1307. findings_total: lo.findings_total != null ? lo.findings_total : (Array.isArray(lo.findings_confirmed) ? lo.findings_confirmed.length : 0),
  1308. // Interleaved validation ran INSIDE the loop — carry its verdict counts so the
  1309. // summary never reads a silent null (no separate Stage-2 validate pass).
  1310. validation: lo.verdict_counts ? { status: 'INLINE', ...lo.verdict_counts } : null,
  1311. confirmed: lo.confirmed || 0, dropped: lo.dropped || 0, rejected: lo.rejected || 0,
  1312. narrative: lo.narrative || '', report_path: lo.report_path || `${a.output_dir}/reports/pentest-report-source.md`,
  1313. engagement_status: lo.engagement_status || null,
  1314. }
  1315. }
  1316. // ============================================================================
  1317. // PHASE: Assess — per-asset CONVERGENCE loop with STRICT PER-FINDING interleaved
  1318. // validation INSIDE the loop (inline_validate:true; no separate Stage-2 pass). Each
  1319. // loop runs to convergence (full coverage + dry_tail), agent-slice backstopped;
  1320. // assets:N (the per-run running count) lets the governor partition the 1000-agent cap.
  1321. // ============================================================================
  1322. const results = resumeCompleted.slice() // assets already 100% on disk are carried as done
  1323. for (const grp of chunk(runThisRun, cap)) {
  1324. const grpResults = await parallel(grp.map(a => () =>
  1325. workflow('coordinator-loop', {
  1326. target: a.base_url || a.identifier,
  1327. output_dir: a.output_dir,
  1328. goal: coverageGoalFor(a),
  1329. scope: `pentest asset: type=${a.type}; tier=${a.business_tier}; ${a.notes || ''}`,
  1330. skills_hint: a.skills_hint || a.type || '',
  1331. platform: 'web',
  1332. mode: 'coverage',
  1333. coverage_matrix: a.coverage_matrix || null,
  1334. severity_rubric: 'root-cause',
  1335. roe,
  1336. output_base: 'projects/pentest',
  1337. report_format: 'transilience',
  1338. inline_validate: true, // strict per-finding validation inside the loop
  1339. business_tier: a.business_tier || tierDefault,
  1340. assets: N, // governor: partition the 1000-agent cap across the per-run assets
  1341. dry_tail: dryTail, // convergence: full coverage + K empty batches
  1342. nvd_cache_dir: nvdCacheDir,
  1343. kev_snapshot: kevSnapshot,
  1344. validation_cache_dir: `${engagementDir}/artifacts/validation-cache`,
  1345. replay_cache: !!setup.resumed, // E4: restore verdicts only on a resume run
  1346. }).then(lo => adaptSummary(a, lo))
  1347. .catch(err => ({ tag: a.tag, coverage_status: 'FAILED', output_dir: a.output_dir, blocked_reason: 'coordinator-loop error: ' + String(err) }))
  1348. ))
  1349. results.push(...grpResults.filter(Boolean))
  1350. }
  1351. // ============================================================================
  1352. // PHASE: Infra — light UNAUTHENTICATED fingerprint of scope-adjacent consoles
  1353. // (identity + exposure only; never a full loop or auth/brute probing — the
  1354. // professional norm for scope-adjacent management planes, e.g. Rancher/Retool).
  1355. // ============================================================================
  1356. let infraFindings = []
  1357. if (infraProbes.length) {
  1358. phase('Infra')
  1359. const ir = await parallel(infraProbes.map(p => () =>
  1360. agent(
  1361. `ROLE: scope-adjacent infra fingerprint (UNAUTHENTICATED, read-only). cwd is repo root. Mount skills/infrastructure/SKILL.md. Do NOT brute-force, do NOT probe auth flows, do NOT run a coverage loop — single unauthenticated GETs to confirm identity + exposure only.\n` +
  1362. `HOST: ${p.host} BASE_URL: ${p.base_url || ('https://' + p.host)}\nWHY FLAGGED: ${p.why || 'management/admin console'}\nOUTPUT_DIR: ${engagementDir}/infra/${p.host}\n\n` +
  1363. `Do: confirm product + version (e.g. Rancher /rancherversion, Retool /api/checkLogin), whether it is reachable DIRECTLY (bypassing any CDN/WAF), and the auth posture (SSO vs local-password, MFA). If it is an internet-exposed management plane, write a finding to ${engagementDir}/infra/${p.host}/findings/finding-exposure/ (description.md with CVSS + CWE, evidence/raw-source.txt with the unauthenticated responses). Return a one-line verdict: exposed? product+version? severity?`,
  1364. { label: `infra:${p.host}`, phase: 'Infra', agentType: 'general-purpose' }
  1365. )
  1366. ))
  1367. infraFindings = ir.filter(Boolean)
  1368. log(`Infra probes complete: ${infraFindings.length}/${infraProbes.length} fingerprinted.`)
  1369. }
  1370. // ============================================================================
  1371. // PHASE: Correlate — multi-asset attack paths + risk prioritisation (REUSE skills)
  1372. // ============================================================================
  1373. phase('Correlate')
  1374. const assetDirs = results.map(r => r.output_dir).filter(Boolean)
  1375. const correlate = await agent(
  1376. `ROLE: cross-asset correlation. cwd is repo root. Stitch validated findings across all assets into attack paths, then risk-rank. Mount skills/attack-path-stitcher/SKILL.md and skills/risk-prioritiser/SKILL.md.\n` +
  1377. `ENGAGEMENT_DIR: ${engagementDir}\nASSET_DIRS: ${JSON.stringify(assetDirs)}\n\n` +
  1378. `Do:\n` +
  1379. `1. Build ${engagementDir}/artifacts/org-surface.json from the expanded surface (${engagementDir}/recon/inventory/) + every asset's artifacts/validated/*.json (validated findings ONLY — VALID/REPAIRED; every file in validated/ is a passing verdict).\n` +
  1380. `2. Run the attack-path-stitcher (its tool, e.g. python3 tools/chain-merger.py) -> ${engagementDir}/artifacts/attack-paths.json / .dot / .md. Confirmed paths only when every edge has feasibility 1.0 with via_findings citations.\n` +
  1381. `3. Derive ${engagementDir}/business-tier-map.csv from the per-asset business tiers, then run the risk-prioritiser (python3 tools/risk-prioritise.py --output-dir ${engagementDir}) -> ${engagementDir}/artifacts/attack-paths-ranked.json / .md. Single-asset validated findings not on a path are scored too.\n\n` +
  1382. `Return CORRELATE_SCHEMA.`,
  1383. { schema: CORRELATE_SCHEMA, agentType: 'general-purpose', label: 'correlate', phase: 'Correlate' }
  1384. ).catch(err => ({ ok: false, notes: ['correlate error: ' + String(err)] }))
  1385. // ============================================================================
  1386. // PHASE: Report — Transilience PDF + coverage-gated COMPLETE
  1387. // ============================================================================
  1388. phase('Report')
  1389. // Coverage gate: COMPLETE only if EVERY asset reached coverage-complete AND its
  1390. // engagement validator did not flag a coverage gap. "Ran out of hypotheses" cannot
  1391. // produce COMPLETE — an asset that ended INCOMPLETE_COVERAGE blocks engagement COMPLETE.
  1392. // Completeness by BACKFILL (never throw): every work-list asset must have a result.
  1393. // A missing/degraded asset is surfaced as a coverage gap, not silently dropped.
  1394. // Expected set = what we ATTEMPTED this run (runThisRun) + what was already complete
  1395. // on disk (resumeCompleted). DEFERRED assets are deliberately NOT expected — they are
  1396. // resumable work, not MISSING gaps, so a re-invocation picks them up.
  1397. const expectedThisRun = [...runThisRun, ...resumeCompleted].map(a => ({ tag: a.tag, key: a.tag, output_dir: a.output_dir, type: a.type, business_tier: a.business_tier }))
  1398. const assessedNorm = results.map(r => ({ ...r, key: r.tag }))
  1399. const rec = reconcileAssessed(expectedThisRun, assessedNorm, e => e.key)
  1400. const coverageGaps = rec.gaps.map(r => ({ asset: r.tag, coverage_status: r.coverage_status, coverage_pending: r.coverage_pending || null, coverage_ratio: r.coverage_ratio, degraded: !!r.degraded }))
  1401. // Tri-state: a slice-spent asset is RESUMABLE (carried forward), a stuck/degraded asset
  1402. // is a genuine gap. deferredAssets (not run this run) join the resume list.
  1403. const { engagement_status: convStatus, resume: resumeBlock } = classifyEngagement(rec.all, deferredAssets.map(a => a.tag))
  1404. // Provisional (per-asset relay); the deterministic coverage gate run inside
  1405. // finalizeEngagement is authoritative for COMPLETE (computed after it returns).
  1406. const provisionalStatus = convStatus
  1407. // Engagement metadata + version (req 10) — prompt > prior > default; fresh report_id.
  1408. const engagementMeta = resolveEngagementMeta({ prior: input.prior || null, prompt: input.engagement || {}, currentScope: apexes, dateTag: setup.date_tag, explicitVersion: input.version })
  1409. const engagementBlock = {
  1410. title_lines: engagementMeta.title_lines || [engagementMeta.title || setup.engagement_name || 'Penetration Test'],
  1411. title: engagementMeta.title || setup.engagement_name || 'Penetration Test',
  1412. subtitle: engagementMeta.subtitle || (engagementMeta.supersedes ? `Retest — supersedes ${engagementMeta.supersedes}` : `${apexes.length} asset(s)`),
  1413. date: setup.date_tag, footer: engagementMeta.sector || 'Security Assessment',
  1414. // Full cover metadata table (cover_meta overrides the auto table, so include every row).
  1415. cover_meta: [
  1416. ['REPORT DATE', setup.date_tag],
  1417. ['DURATION', engagementMeta.duration],
  1418. ['CLASSIFICATION', engagementMeta.classification || 'Confidential'],
  1419. ['SECTOR', engagementMeta.sector],
  1420. ['TARGET', engagementMeta.target || apexes[0] || null],
  1421. ['METHOD', engagementMeta.method || 'Grey-box'],
  1422. ['PREPARED BY', engagementMeta.prepared_by || 'Transilience'],
  1423. ['REPORT ID', engagementMeta.report_id],
  1424. ['VERSION', engagementMeta.version],
  1425. ...(engagementMeta.supersedes ? [['SUPERSEDES', engagementMeta.supersedes]] : []),
  1426. ],
  1427. }
  1428. let report = { ok: false }
  1429. if (wantReport) {
  1430. report = await finalizeEngagement({ engagementDir, engagement: engagementBlock, reportFormat: input.report_format, customReportCmd: input.custom_report_cmd, engagementStatus: provisionalStatus, agentCount: null, conclusion: input.conclusion || null, protect: input.protect !== false, certinExport: input.certin_export === true, certin: input.certin || null })
  1431. if (report.status === 'BLOCKED') log(`Report BLOCKED: ${report.blocked_reason}`)
  1432. }
  1433. // The deterministic (surface-unit × attack-class) coverage gate is authoritative
  1434. // for COMPLETE. Fails closed: if a report was wanted but the gate did not confirm
  1435. // 100% coverage, the engagement is INCOMPLETE_coverage (never a silent COMPLETE).
  1436. const coverageComplete = wantReport ? (report.coverage_complete === true) : true
  1437. // COMPLETE requires the deterministic gate AND convergence with nothing left to resume.
  1438. // Otherwise distinguish RESUMABLE (deferred/slice-spent — re-run) from a genuine gap.
  1439. const engagementStatus = (coverageComplete && convStatus === 'COMPLETE')
  1440. ? 'COMPLETE'
  1441. : (convStatus === 'INCOMPLETE_resumable' ? 'INCOMPLETE_resumable' : 'INCOMPLETE_coverage')
  1442. // ============================================================================
  1443. // Synthesis
  1444. // ============================================================================
  1445. log(`Engagement ${engagementStatus}: ${results.length} asset(s) assessed (${resumeCompleted.length} pre-complete, ${N} this run), ${coverageGaps.length} gap(s), ${deferredAssets.length} deferred. ${resumeBlock.remaining_assets.length ? `Resume: re-invoke with resume_dir=${engagementDir} (${resumeBlock.remaining_assets.length} asset(s) remaining).` : ''}`)
  1446. const webRound = Number(setup.resume_round) || 0
  1447. const webResume = resumeBlock.remaining_assets.length
  1448. ? { ...resumeBlock, resume_round: webRound, rerun_hint: (webRound + 1) <= maxResumeRounds ? `resume_dir=${engagementDir}` : null, exhausted_rounds: (webRound + 1) > maxResumeRounds }
  1449. : null
  1450. return {
  1451. status: 'DONE',
  1452. engagement_status: engagementStatus,
  1453. resume: webResume,
  1454. date_tag: setup.date_tag,
  1455. engagement_dir: engagementDir,
  1456. apex_domains: apexes,
  1457. expanded_host_count: (expand.expanded_hosts || []).length,
  1458. assets: results.map(r => ({ tag: r.tag, type: r.type, coverage_status: r.coverage_status, coverage_ratio: r.coverage_ratio, findings_total: r.findings_total, validation: r.validation && r.validation.counts ? r.validation.counts : null, output_dir: r.output_dir })),
  1459. infra_probes: infraProbes.map(p => p.host),
  1460. infra_findings: infraFindings.length,
  1461. excluded: excluded,
  1462. attack_paths_ranked: correlate && correlate.ranked_path ? correlate.ranked_path : `${engagementDir}/artifacts/attack-paths-ranked.md`,
  1463. report_format: report && report.format ? report.format : (input.report_format === 'custom' ? 'custom' : 'transilience'),
  1464. report_status: report && report.status ? report.status : (wantReport ? 'BLOCKED' : 'SKIPPED'),
  1465. report_blocked_reason: report && report.blocked_reason ? report.blocked_reason : null,
  1466. report_path: report && report.report_path ? report.report_path : `${engagementDir}/reports/Penetration-Test-Report.pdf`,
  1467. severity_counts: report && report.severity_counts ? report.severity_counts : null,
  1468. deliverable_zip: report && report.deliverable_zip ? report.deliverable_zip : null,
  1469. protected_zip: report && report.protected_zip ? report.protected_zip : null,
  1470. deliverable_password: report && report.deliverable_password ? report.deliverable_password : null,
  1471. password_file: report && report.password_file ? report.password_file : null,
  1472. protection_limitations: report && report.protection_limitations ? report.protection_limitations : [],
  1473. summary: report && report.summary ? report.summary : null,
  1474. slack_offer: !!(report && report.slack_offer && wantReport),
  1475. coverage_gaps: coverageGaps,
  1476. tool_limitations: expand.tool_limitations || [],
  1477. notes: setup.notes || [],
  1478. }
benchmarks/_shared/claude_runner.py · Bundled script · 247 lines · 2 findings marked
  1. """
  2. Spawn Claude Code as a subprocess against a prepared benchmark.
  3. Shared between XBOW and cybench runners. The caller builds the prompt and
  4. supplies suite-specific skill content; this module handles the invariants:
  5. - Strip CLAUDECODE from the environment (nested Claude sessions otherwise die).
  6. - Select cwd: VANILLA mode uses a fresh tmpdir outside the repo so Claude
  7. doesn't auto-load project CLAUDE.md or `.claude/skills/`; SKILLS mode uses
  8. `skills_cwd` (e.g. projects/pentest/) so slash commands are discoverable.
  9. - Inject skill content via `--append-system-prompt` in SKILLS mode.
  10. - Force `--setting-sources user` in VANILLA mode to suppress project/local
  11. configuration discovery.
  12. - Optional ANTHROPIC_API_KEY override.
  13. - Capture stdout/stderr, detect auth errors, return a typed result.
  14. """
  15. from __future__ import annotations
  16. import json
  17. import os
  18. import shutil
  19. import subprocess
  20. import tempfile
  21. import time
  22. from dataclasses import dataclass
  23. from pathlib import Path
  24. from typing import Literal, Optional
  25. from .agent_errors import classify_agent_error, extract_error_lines
  26. from .env_loader import resolve_anthropic_key
  27. _TOOL_INPUT_MAX = 4000
  28. _TOOL_RESULT_MAX = 4000
  29. def _truncate(text: str, limit: int) -> str:
  30. if len(text) <= limit:
  31. return text
  32. return text[:limit] + f"\n...[truncated {len(text) - limit} chars]"
  33. def _render_stream_json(raw: str) -> str:
  34. """Render Claude Code stream-json events into readable text.
  35. Falls back to returning the raw stdout if no JSON events parse, so callers
  36. that pass non-stream output (or partial buffers on timeout) still get
  37. something useful.
  38. """
  39. parts: list[str] = []
  40. parsed_any = False
  41. for line in raw.splitlines():
  42. s = line.strip()
  43. if not s:
  44. continue
  45. try:
  46. ev = json.loads(s)
  47. except json.JSONDecodeError:
  48. parts.append(line)
  49. continue
  50. parsed_any = True
  51. etype = ev.get("type")
  52. if etype == "assistant":
  53. for block in (ev.get("message") or {}).get("content") or []:
  54. bt = block.get("type")
  55. if bt == "text":
  56. parts.append(block.get("text", ""))
  57. elif bt == "thinking":
  58. parts.append(f"--- thinking ---\n{block.get('thinking', '')}")
  59. elif bt == "tool_use":
  60. name = block.get("name", "?")
  61. inp = json.dumps(block.get("input", {}), ensure_ascii=False)
  62. parts.append(f"--- tool_use: {name} ---\n{_truncate(inp, _TOOL_INPUT_MAX)}")
  63. elif etype == "user":
  64. for block in (ev.get("message") or {}).get("content") or []:
  65. if block.get("type") != "tool_result":
  66. continue
  67. content = block.get("content")
  68. if isinstance(content, list):
  69. content = "".join(
  70. b.get("text", "") for b in content if isinstance(b, dict)
  71. )
  72. content = content or ""
  73. parts.append(f"--- tool_result ---\n{_truncate(content, _TOOL_RESULT_MAX)}")
  74. elif etype == "result":
  75. final = ev.get("result")
  76. if final:
  77. parts.append(f"--- final result ---\n{final}")
  78. if not parsed_any:
  79. return raw
  80. return "\n\n".join(parts)
  81. @dataclass
  82. class AgentRunResult:
  83. """Narrow return type from `run_claude`. Suite runners wrap this into
  84. their own richer BenchmarkResult."""
  85. stdout: str
  86. stderr: str
  87. returncode: int
  88. duration_seconds: float
  89. status: str # "success" | "failed" | "timeout" | "error"
  90. error: Optional[str] = None
  91. fatal: bool = False # True → caller should abort the remaining run
  92. def run_claude(
  93. prompt: str,
  94. output_dir: Path,
  95. *,
  96. mode: Literal["skills", "vanilla"],
  97. model: Optional[str],
  98. api_key: Optional[str],
  99. timeout: int,
  100. skills_cwd: Optional[Path] = None,
  101. skills_content: str = "",
  102. task_id: str = "",
  103. base_url: Optional[str] = None,
  104. auth_token: Optional[str] = None,
  105. max_output_tokens: Optional[int] = None,
  106. ) -> AgentRunResult:
  107. """
  108. Invoke `claude --dangerously-skip-permissions -p <prompt>` and capture output.
  109. Writes:
  110. output_dir/prompt.txt
  111. output_dir/transcript.jsonl (raw stream-json events, one per line)
  112. output_dir/claude_output.txt (readable rendering of assistant turns,
  113. thinking blocks, tool calls, tool results)
  114. output_dir/claude_stderr.txt (only if stderr is non-empty)
  115. In VANILLA mode, `skills_cwd` and `skills_content` are ignored.
  116. In SKILLS mode, `skills_cwd` must be provided and typically be the pentest
  117. project root so Claude discovers project-level config (in addition to the
  118. skills explicitly injected via `skills_content`).
  119. """
  120. tag = f"[{task_id}] " if task_id else ""
  121. output_dir.mkdir(parents=True, exist_ok=True)
  122. (output_dir / "prompt.txt").write_text(prompt)
  123. vanilla_tmpdir: Optional[str] = None
  124. if mode == "vanilla":
  125. vanilla_tmpdir = tempfile.mkdtemp(prefix="bench_vanilla_")
  126. cwd = Path(vanilla_tmpdir)
  127. print(f" {tag}Mode: VANILLA (isolated tmpdir: {cwd})")
  128. else:
  129. if skills_cwd is None or not skills_cwd.exists():
  130. raise ValueError(
  131. "SKILLS mode requires skills_cwd pointing to an existing directory"
  132. )
  133. cwd = skills_cwd
  134. print(f" {tag}Mode: SKILLS (cwd: {skills_cwd})")
  135. cmd = [
  136. "claude", "--dangerously-skip-permissions",
  137. "--output-format", "stream-json", "--verbose",
  138. ]
  139. if model:
  140. cmd.extend(["--model", model])
  141. if mode == "vanilla":
  142. cmd.extend(["--setting-sources", "user"])
  143. elif skills_content:
  144. cmd.extend(["--append-system-prompt", skills_content])
  145. print(f" {tag}Injected {len(skills_content):,} bytes of skills content")
  146. cmd.extend(["-p", prompt])
  147. env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
  148. resolved_key = resolve_anthropic_key(api_key)
  149. if resolved_key:
  150. env["ANTHROPIC_API_KEY"] = resolved_key
  151. if base_url:
  152. env["ANTHROPIC_BASE_URL"] = base_url
  153. print(f" {tag}Routing Claude Code at custom endpoint: {base_url}")
  154. if auth_token:
  155. env["ANTHROPIC_AUTH_TOKEN"] = auth_token
  156. if max_output_tokens:
  157. env["CLAUDE_CODE_MAX_OUTPUT_TOKENS"] = str(max_output_tokens)
  158. start = time.time()
  159. try:
  160. result = subprocess.run(
  161. cmd,
  162. cwd=cwd,
  163. capture_output=True,
  164. text=True,
  165. timeout=timeout,
  166. env=env,
  167. )
  168. except subprocess.TimeoutExpired as e:
  169. duration = time.time() - start
  170. stdout = (e.stdout or "") if isinstance(e.stdout, str) else (e.stdout.decode(errors="replace") if e.stdout else "")
  171. stderr = (e.stderr or "") if isinstance(e.stderr, str) else (e.stderr.decode(errors="replace") if e.stderr else "")
  172. (output_dir / "transcript.jsonl").write_text(stdout)
  173. rendered = _render_stream_json(stdout)
  174. (output_dir / "claude_output.txt").write_text(rendered)
  175. if stderr:
  176. (output_dir / "claude_stderr.txt").write_text(stderr)
  177. if vanilla_tmpdir:
  178. shutil.rmtree(vanilla_tmpdir, ignore_errors=True)
  179. return AgentRunResult(
  180. stdout=rendered, stderr=stderr, returncode=-1,
  181. duration_seconds=duration, status="timeout",
  182. error=f"Timeout after {timeout}s",
  183. )
  184. except Exception as e:
  185. duration = time.time() - start
  186. if vanilla_tmpdir:
  187. shutil.rmtree(vanilla_tmpdir, ignore_errors=True)
  188. return AgentRunResult(
  189. stdout="", stderr="", returncode=-1,
  190. duration_seconds=duration, status="error", error=str(e),
  191. )
  192. duration = time.time() - start
  193. stdout = result.stdout or ""
  194. stderr = result.stderr or ""
  195. (output_dir / "transcript.jsonl").write_text(stdout)
  196. rendered = _render_stream_json(stdout)
  197. (output_dir / "claude_output.txt").write_text(rendered)
  198. if stderr:
  199. (output_dir / "claude_stderr.txt").write_text(stderr)
  200. if vanilla_tmpdir:
  201. shutil.rmtree(vanilla_tmpdir, ignore_errors=True)
  202. status = "success" if result.returncode == 0 else "failed"
  203. error: Optional[str] = None
  204. fatal = False
  205. if result.returncode != 0:
  206. classification = classify_agent_error(rendered, stderr, result.returncode)
  207. if classification:
  208. status = "error"
  209. fatal = classification.is_fatal
  210. error = f"[{classification.kind}] {classification.message}"
  211. else:
  212. clean = extract_error_lines(stderr) or extract_error_lines(rendered)
  213. error = f"rc={result.returncode} duration={duration:.1f}s" + (
  214. f" | {clean}" if clean else ""
  215. )
  216. print(f" {tag}Agent exited rc={result.returncode} after {duration:.1f}s")
  217. print(f" {tag}{error}")
  218. print(f" {tag}Full logs: {output_dir}/claude_output.txt, transcript.jsonl, claude_stderr.txt")
  219. return AgentRunResult(
  220. stdout=rendered, stderr=stderr, returncode=result.returncode,
  221. duration_seconds=duration, status=status, error=error, fatal=fatal,
  222. )
scripts/kali-claude-setup.sh · Bundled script · 187 lines · 2 findings marked
  1. #!/bin/bash
  2. # kali-claude-setup.sh
  3. # Sets up Claude Code on a Kali Linux Docker container with a project's .claude folder
  4. # (skills, agents, tools) embedded in the workspace.
  5. #
  6. # Usage:
  7. # bash scripts/kali-claude-setup.sh <project-folder>
  8. # bash scripts/kali-claude-setup.sh <project-folder> --rebuild
  9. #
  10. # Example:
  11. # bash scripts/kali-claude-setup.sh projects/pentest
  12. set -e
  13. # --- Require project folder argument ---
  14. if [ -z "$1" ]; then
  15. echo "Error: Please provide a project folder path."
  16. echo ""
  17. echo "Usage: bash scripts/kali-claude-setup.sh <project-folder>"
  18. echo ""
  19. echo "Available projects:"
  20. for dir in projects/*/; do
  21. if [ -d "${dir}.claude" ]; then
  22. echo " - ${dir%/}"
  23. fi
  24. done
  25. exit 1
  26. fi
  27. PROJECT_DIR="$1"
  28. if [ ! -d "$PROJECT_DIR" ]; then
  29. echo "Error: Project folder '$PROJECT_DIR' not found."
  30. exit 1
  31. fi
  32. if [ ! -d "$PROJECT_DIR/.claude" ]; then
  33. echo "Error: No .claude folder found in '$PROJECT_DIR'."
  34. echo "The project must contain a .claude/ directory with skills and agents."
  35. exit 1
  36. fi
  37. PROJECT_NAME=$(basename "$PROJECT_DIR")
  38. PROJECT_DIR_ABS=$(cd "$PROJECT_DIR" && pwd)
  39. CONTAINER_NAME="kali-claude-${PROJECT_NAME}"
  40. IMAGE_NAME="kali-claude:latest"
  41. WORKSPACE="/workspace"
  42. echo "[*] Project: $PROJECT_DIR"
  43. echo "[*] Container: $CONTAINER_NAME"
  44. echo ""
  45. # --- Always build/rebuild the image to ensure latest setup ---
  46. if true; then
  47. echo "[*] Building Kali + Claude Code image (one-time)..."
  48. docker build -t "$IMAGE_NAME" -f - . <<'DOCKERFILE'
  49. FROM kalilinux/kali-rolling
  50. # Layer 1: System deps + Node.js
  51. RUN apt update -qq && \
  52. apt install -y -qq curl git ca-certificates sudo > /dev/null && \
  53. curl -fsSL https://deb.nodesource.com/setup_20.x | bash - > /dev/null 2>&1 && \
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 62 on GitHub
  54. apt install -y -qq nodejs > /dev/null && \
  55. apt clean && rm -rf /var/lib/apt/lists/* /tmp/*
  56. # Layer 2: Playwright system dependencies + Xvfb
  57. RUN apt update -qq && \
  58. npx -y playwright install-deps chromium && \
  59. apt install -y -qq xvfb > /dev/null && \
  60. apt clean && rm -rf /var/lib/apt/lists/* /tmp/* /root/.npm
  61. # Layer 3: Claude Code + Playwright MCP
  62. RUN npm install -g @anthropic-ai/claude-code @playwright/mcp --silent && \
  63. npm cache clean --force && rm -rf /root/.npm /tmp/*
  64. # Layer 4: Install pip + playwright python as fallback
  65. RUN apt update -qq && apt install -y -qq python3-pip > /dev/null && \
  66. pip3 install playwright --break-system-packages --quiet && \
  67. apt clean && rm -rf /var/lib/apt/lists/* /tmp/*
  68. # Create non-root user BEFORE installing browser (so it goes to claude's home)
  69. RUN useradd -m -s /bin/bash -G sudo claude && \
  70. echo "claude ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
  71. # Layer 5: Install Chromium AS the claude user (browser cache goes to /home/claude/.cache/)
  72. USER claude
  73. RUN npx playwright install chromium
  74. # Set up minimal ~/.claude (no plugin system — using .mcp.json at project root instead)
  75. RUN mkdir -p /home/claude/.claude && \
  76. echo '{}' > /home/claude/.claude/settings.json
  77. USER root
  78. ENV TMPDIR=/workspace/.tmp
  79. WORKDIR /workspace
  80. RUN chown claude:claude /workspace
  81. USER claude
  82. DOCKERFILE
  83. echo "[+] Image built."
  84. else
  85. echo "[*] Using existing kali-claude image."
  86. fi
  87. # --- Prepare workspace in a temp dir (writable copy, not read-only mount) ---
  88. TEMP_DIR=$(mktemp -d)
  89. trap "rm -rf $TEMP_DIR" EXIT
  90. echo "[*] Preparing project workspace..."
  91. # Copy .claude folder (skills, agents, tools, settings) — writable so Claude Code can use it
  92. cp -r "$PROJECT_DIR_ABS/.claude" "$TEMP_DIR/.claude"
  93. # Add Playwright MCP config at PROJECT ROOT (must be .mcp.json at root, NOT inside .claude/)
  94. cat > "$TEMP_DIR/.mcp.json" <<'MCP_EOF'
  95. {
  96. "mcpServers": {
  97. "playwright": {
  98. "command": "npx",
  99. "args": ["@playwright/mcp@latest",
  100. "--launch-options", "{\"args\":[\"--disable-blink-features=AutomationControlled\",\"--no-sandbox\",\"--disable-setuid-sandbox\",\"--window-size=1920,1080\"]}"]
  101. }
  102. }
  103. }
  104. MCP_EOF
  105. # Copy AGENTS.md from repo root if it exists
  106. if [ -f "AGENTS.md" ]; then
  107. cp "AGENTS.md" "$TEMP_DIR/AGENTS.md"
  108. fi
  109. # Copy CLAUDE.md (project-level overrides repo-level)
  110. if [ -f "CLAUDE.md" ]; then
  111. cp "CLAUDE.md" "$TEMP_DIR/CLAUDE.md"
  112. fi
  113. if [ -f "$PROJECT_DIR_ABS/CLAUDE.md" ]; then
  114. cp "$PROJECT_DIR_ABS/CLAUDE.md" "$TEMP_DIR/CLAUDE.md"
  115. fi
  116. # Copy .env file into workspace (so it's readable as a file too)
  117. if [ -f "$PROJECT_DIR_ABS/.env" ]; then
  118. cp "$PROJECT_DIR_ABS/.env" "$TEMP_DIR/.env"
  119. echo "[*] .env file found — will be loaded as environment variables and available as file."
  120. else
  121. echo "[!] No .env file found in $PROJECT_DIR — skipping."
  122. fi
  123. # Initialize as a git repo so Claude Code recognizes it as a project
  124. git init -q "$TEMP_DIR"
  125. echo "[*] Starting container..."
  126. echo "[*] .claude/skills, .claude/agents, and .claude/tools will be available in $WORKSPACE"
  127. echo ""
  128. echo "-----------------------------------------------------------"
  129. echo " Inside the container, Claude will auto-launch with"
  130. echo " --dangerously-skip-permissions (no confirmation prompts)."
  131. echo " Playwright MCP (headed via Xvfb) is available."
  132. echo " It will show a URL — open it in your host browser to log in."
  133. echo "-----------------------------------------------------------"
  134. echo ""
  135. # Build docker run arguments
  136. DOCKER_ARGS=()
  137. # Mount the entire prepared workspace (writable — Claude Code needs to write state)
  138. DOCKER_ARGS+=(-v "$TEMP_DIR:${WORKSPACE}")
  139. # Mount scripts folder for debugging
  140. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  141. DOCKER_ARGS+=(-v "$SCRIPT_DIR:${WORKSPACE}/scripts:ro")
  142. # Pass .env variables as container environment variables
  143. if [ -f "$PROJECT_DIR_ABS/.env" ]; then
  144. DOCKER_ARGS+=(--env-file "$PROJECT_DIR_ABS/.env")
  145. fi
  146. # Remove any existing container with the same name
  147. docker rm -f "$CONTAINER_NAME" 2>/dev/null || true
  148. docker run -it --rm \
  149. --name "$CONTAINER_NAME" \
  150. --network host \
  151. --tmpfs /tmp:exec,size=2g \
  152. "${DOCKER_ARGS[@]}" \
  153. -w "$WORKSPACE" \
  154. -e TMPDIR=/tmp \
  155. "$IMAGE_NAME" \
  156. bash -c "Xvfb :99 -screen 0 1920x1080x24 &>/dev/null & export DISPLAY=:99 && sleep 1 && mkdir -p /workspace/.tmp && claude --dangerously-skip-permissions"
tools/test_passive_web_probe.py · Bundled script · 553 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. """Offline, deterministic tests for passive_web_probe.py.
  3. Stands up a REAL loopback HTTP server and a REAL loopback HTTPS server (embedded
  4. self-signed cert — no openssl/network at runtime), points a surface/v2 fixture at
  5. them, runs the probe, then runs enumerate_cells + coverage_gate and asserts the
  6. gate's own verdict. No traffic ever leaves 127.0.0.1.
  7. Variants covered:
  8. * happy path -> the 8 mechanical cells are covered_negative and the gate PASSES
  9. them (not in missing_cells), with ZERO artifacts/validated/.
  10. * --no-nmap -> WEB-A06-COMPONENTS becomes a limitation, cell left OPEN.
  11. * missing CSP -> XC-SECURITY-HEADERS emits a finding, cell left OPEN.
  12. """
  13. from __future__ import annotations
  14. import glob
  15. import json
  16. import os
  17. import shutil
  18. import ssl
  19. import subprocess
  20. import sys
  21. import tempfile
  22. import threading
  23. from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
  24. from urllib.parse import urlparse
  25. HERE = os.path.dirname(os.path.abspath(__file__))
  26. REPO = os.path.dirname(HERE)
  27. PROBE = os.path.join(HERE, "passive_web_probe.py")
  28. ENUM = os.path.join(HERE, "enumerate_cells.py")
  29. GATE = os.path.join(HERE, "coverage_gate.py")
  30. HAVE_NMAP = bool(shutil.which("nmap"))
  31. # Import the probe module directly so the block-page/soft-404 guards can be unit-
  32. # tested and driven against loopback servers without spawning a subprocess.
  33. sys.path.insert(0, HERE)
  34. import passive_web_probe as probe # noqa: E402
  35. # The canonical F5 BIG-IP ASM / F5 Distributed Cloud reject page (~269 bytes). A
  36. # rejected request comes back with HTTP 200 and THIS body — never a real file.
  37. F5_REJECT_PAGE = (
  38. "<html><head><title>Request Rejected</title></head><body>"
  39. "The requested URL was rejected. Please consult with your administrator.<br><br>"
  40. "Your support ID is: 7799990120182737622<br><br>"
  41. "<a href='javascript:history.back();'>[Go Back]</a></body></html>"
  42. )
  43. _FAKE_AWS_KEY = "AKIAIOSFODNN7EXAMPLE" # matches _SECRET_RE; forces a would-be positive
  44. # Long-lived self-signed cert (CN=127.0.0.1, SAN IP:127.0.0.1) embedded so the
  45. # test needs no openssl at runtime and never touches the network.
  46. _CERT_PEM = """-----BEGIN CERTIFICATE-----
  47. MIIDGjCCAgKgAwIBAgIUd379Ia/EwHxZNkiCyrtWdwUgKEkwDQYJKoZIhvcNAQEL
  48. BQAwFDESMBAGA1UEAwwJMTI3LjAuMC4xMB4XDTI2MDcxMzEwNTkxNloXDTQ2MDcw
  49. ODEwNTkxNlowFDESMBAGA1UEAwwJMTI3LjAuMC4xMIIBIjANBgkqhkiG9w0BAQEF
  50. AAOCAQ8AMIIBCgKCAQEAw35YXCd9jFN9vUyPffqcEG3MyHzxoHWjBI2cbDXFArzJ
  51. xO4EQHOqY6I2xTfNOmMncBs+Qpm/iKtFeAjUS1U+fgfZua2H1JdLbbiiNYJ2D4Ov
  52. XOv7woeosuZ3ydUNzF2MS+mtMXXCl0N+0pCXaStUlu82TF6GxNGB/2zDAymkKFV7
  53. iyy6aLCP7g0uW0v1SYFBsfX2sIw0IVDiXJ0W4ewKYfQkf2tvz3HfLFhgyIY3xaZD
  54. MgT3pL+UtquoU8iBI9pLYzdYcxnXE/eu47ahjC2iHI69ZCT+S84EUFXzgwZkk917
  55. 1Vcp9JpQiNoyUWExbg5fX3gNvuSen/cMT/matXZZbQIDAQABo2QwYjAdBgNVHQ4E
  56. FgQUGeXc4kWht+MaixCBglPjXMaobeowHwYDVR0jBBgwFoAUGeXc4kWht+MaixCB
  57. glPjXMaobeowDwYDVR0TAQH/BAUwAwEB/zAPBgNVHREECDAGhwR/AAABMA0GCSqG
  58. SIb3DQEBCwUAA4IBAQAfRki4KSq0QzaqhliL/wMdMuGTGiHJexT+Sxz1sszjXSn3
  59. kvrynbdk+G+ajPI7HmJtP+y/8SmPZmAwHtK6GyIxmc2llo5PDtFs4jJcoW0XOTAv
  60. PDvmLWJH8BXgIITsDfRKJK7p3VHIFvE3Ub2L+e0blgP3LcWEaIpokhjuIuF223F6
  61. Xv9/yOHo8mqMBDofnnURi76doOL5VWXJa/ChzQUvWSswV7afb5gF8JzyqY93YX8g
  62. nZmLl8AvMwzBTN39RvW6qaa9RBCOfIFdBs/VyCQb11NhGWe4fFHu8BRHLKhXxTuZ
  63. kUHe8NtDM/YST1I+YQsaIxqYWoDeBbmo/jjD3K2s
  64. -----END CERTIFICATE-----
  65. """
  66. _KEY_PEM = """-----BEGIN PRIVATE KEY-----
    • Dismissed after review: Contains what looks like a hardcoded PEM private key
    • Line 73 on GitHub
  67. MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDDflhcJ32MU329
  68. TI99+pwQbczIfPGgdaMEjZxsNcUCvMnE7gRAc6pjojbFN806YydwGz5Cmb+Iq0V4
  69. CNRLVT5+B9m5rYfUl0ttuKI1gnYPg69c6/vCh6iy5nfJ1Q3MXYxL6a0xdcKXQ37S
  70. kJdpK1SW7zZMXobE0YH/bMMDKaQoVXuLLLposI/uDS5bS/VJgUGx9fawjDQhUOJc
  71. nRbh7Aph9CR/a2/Pcd8sWGDIhjfFpkMyBPekv5S2q6hTyIEj2ktjN1hzGdcT967j
  72. tqGMLaIcjr1kJP5LzgRQVfODBmST3XvVVyn0mlCI2jJRYTFuDl9feA2+5J6f9wxP
  73. +Zq1dlltAgMBAAECggEADepH4Tz6xErLGyoNPeZHrPZ/Cmq0vkgXuikkUCJRq1y2
  74. lfrSBagJO4qEqh9LNe09FbWl7F99d5dAj7pwXHGTmN/3lC5kcHImfDrItqHAxC29
  75. uHg5ruj+GpUQdybgEqk6ZWSB0sPzMNYs+4SV3amoBA7AVC/kTIBgzizqAqce2E00
  76. h0BLfWODUrt44FP2QbLVYJD3EwBrH5rxly7W4VCBq+U+ROechQD2UZCr4H1fnMLj
  77. k9xAho30JtaukxvwaGDCdiEvBLqz7zRLIEqzGxroypa4ow96dKGuyvVLmSqatdsD
  78. zCs92m9lOwPvs7APCzuTmJFGIROQrpRXEH/JeNKWVwKBgQD61w7wxgFX6lYBrlrP
  79. gLZR6CiF2KmhsTGfeFRCXZF7v24nQBUsrxFKnvTmJUSY8MbZ4R+JuhKczljaQewj
  80. MsxhlA8hnlVx7QzL3OMyTh4Om7xMO1kA/zQvZvSs7gGWWAFvWLVdzchPVdAa5BVv
  81. YrCOF+BPdhw2eRPKZodYvl+bmwKBgQDHg9P4Fy3cJBJhkoby3YPhz5b9G4tgCAPY
  82. MlXxR/NJ5nCDEIhb4vV6tAuOjLART3my0n/wXHSGrw52+p/vOXexnsvTFvy35Bz0
  83. rRwuS01TM+6Qx/EkE05mkP0gOuMbOWke2vnadafAJYC7K5v12Bkw6yFuoyDwLOPh
  84. c2l9YYhDlwKBgEf+lcExc41CKvFMk6/e53VWxtqztuw7qVx18ukhZfI4nWsSj4FF
  85. thbOzMeJhsjGwqwiWyTyjQkIiKQMK7RmjharojQp96g9O2D/ww3bMfFLbZ4Lop4Q
  86. oW/BgxRnM3ltROwqb9O+jnGG1bYCJMzVbIs7+xuTcMGJus5q4wnrihFlAoGBAJ3O
  87. C05jJwbEETXTq6FUzAdDJm2z551hOYk65vccrbV56uv/m5rx/K+80JdDd895SQzD
  88. qiX3OsN8mrhIq0+P6Lg4nYas296nMq/kbDHBpbt1i/A/9N9P1ecSLuPbL95MnnSl
  89. RpIgFTrJbvScHZNqBSLIF31m0ZqmJugfXQSqrBipAoGAb4MgHQZwM0U+zn1ye/zu
  90. Kwx/fsJPgkN7j+PNLe0Fqflg1EF615ORTQbY2xgOeAPjM3vJ8Km76OKUu8QGP3oJ
  91. PyikmZ4sQK+fqdK2jxAhREk9cG/paVLC0REx6KeeRvMgju/13gqVlBZ1t/iEty/Q
  92. 5xTRLUFHZTLMqVNWa9VgZyE=
  93. -----END PRIVATE KEY-----
  94. """
  95. # --- controllable loopback servers -------------------------------------------
  96. def make_handler(omit_csp: bool):
  97. class Handler(BaseHTTPRequestHandler):
  98. def _headers(self, code, length, ctype):
  99. self.send_response(code)
  100. self.send_header("Content-Type", ctype)
  101. self.send_header("Content-Length", str(length))
  102. self.send_header("Server", "TestServer/1.0")
  103. self.send_header("Strict-Transport-Security", "max-age=63072000; includeSubDomains")
  104. self.send_header("X-Content-Type-Options", "nosniff")
  105. self.send_header("X-Frame-Options", "DENY")
  106. if not omit_csp:
  107. self.send_header("Content-Security-Policy", "default-src 'self'")
  108. self.end_headers()
  109. def _route(self):
  110. path = urlparse(self.path).path
  111. if path == "/app.js":
  112. return 200, b"console.log('hello world, nothing secret here');", "application/javascript"
  113. if path == "/" or path == "/api":
  114. return 200, b"<html><body>ok</body></html>", "text/html"
  115. return 404, b"Not Found", "text/plain" # plain 404, no stack trace
  116. def do_GET(self):
  117. code, body, ctype = self._route()
  118. self._headers(code, len(body), ctype)
  119. self.wfile.write(body)
  120. def do_HEAD(self):
  121. code, body, ctype = self._route()
  122. self._headers(code, len(body), ctype)
  123. def log_message(self, *a):
  124. pass
  125. return Handler
  126. class _QuietServer(ThreadingHTTPServer):
  127. daemon_threads = True
  128. def handle_error(self, request, client_address):
  129. pass # nmap's version probes reset connections on purpose — don't log
  130. def start_server(omit_csp=False, tls=False, certfile=None):
  131. httpd = _QuietServer(("127.0.0.1", 0), make_handler(omit_csp))
  132. if tls:
  133. ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
  134. ctx.load_cert_chain(certfile)
  135. httpd.socket = ctx.wrap_socket(httpd.socket, server_side=True)
  136. port = httpd.server_address[1]
  137. t = threading.Thread(target=httpd.serve_forever, daemon=True)
  138. t.start()
  139. return httpd, port
  140. def start_scripted_server(respond):
  141. """Loopback server whose every response is decided by respond(path) ->
  142. (status, headers_dict, body_bytes). Lets a test simulate a WAF reject page, an
  143. SPA soft-404 catch-all, or a server hosting one genuinely-distinct file."""
  144. class Handler(BaseHTTPRequestHandler):
  145. def _emit(self):
  146. status, headers, body = respond(urlparse(self.path).path)
  147. self.send_response(status)
  148. for k, v in headers.items():
  149. self.send_header(k, v)
  150. self.send_header("Content-Length", str(len(body)))
  151. self.end_headers()
  152. return body
  153. def do_GET(self):
  154. self.wfile.write(self._emit())
  155. def do_HEAD(self):
  156. self._emit()
  157. def log_message(self, *a):
  158. pass
  159. httpd = _QuietServer(("127.0.0.1", 0), Handler)
  160. port = httpd.server_address[1]
  161. threading.Thread(target=httpd.serve_forever, daemon=True).start()
  162. return httpd, port
  163. # --- fixture + tool runners --------------------------------------------------
  164. def write_surface(asset_dir, tag, http_port, https_port):
  165. units = [
  166. {"unit_id": "u1", "type": "endpoint", "address": f"http://127.0.0.1:{http_port}/api", "server": "TestServer/1.0"},
  167. {"unit_id": "u2", "type": "endpoint", "address": f"https://127.0.0.1:{https_port}/api", "server": "TestServer/1.0", "tls": True},
  168. {"unit_id": "u3", "type": "page", "address": f"http://127.0.0.1:{http_port}/app.js"},
  169. ]
  170. p = os.path.join(asset_dir, "recon", "inventory", "surface.json")
  171. os.makedirs(os.path.dirname(p), exist_ok=True)
  172. with open(p, "w") as f:
  173. json.dump({"schema": "surface/v2", "asset_tag": tag, "units": units}, f)
  174. def run_probe(asset_dir, no_nmap=False):
  175. cmd = [sys.executable, PROBE, "--asset-dir", asset_dir, "--allow", "127.0.0.1", "--timeout", "8"]
  176. if no_nmap:
  177. cmd.append("--no-nmap")
  178. p = subprocess.run(cmd, cwd=REPO, capture_output=True, text=True)
  179. assert p.returncode == 0, f"probe exited {p.returncode}: {p.stderr}\n{p.stdout}"
  180. line = [l for l in p.stdout.splitlines() if l.strip()][-1]
  181. return json.loads(line)
  182. def run_gate(asset_dir):
  183. subprocess.run([sys.executable, ENUM, "--asset-dir", asset_dir], cwd=REPO, capture_output=True, text=True, check=True)
  184. subprocess.run([sys.executable, GATE, "--asset-dir", asset_dir], cwd=REPO, capture_output=True, text=True)
  185. with open(os.path.join(asset_dir, "reports", "coverage-matrix.json")) as f:
  186. return json.load(f)
  187. def mechanical_cells(asset_dir):
  188. with open(os.path.join(asset_dir, "applicability", "cells.json")) as f:
  189. cells = json.load(f)["cells"]
  190. mech = {"XC-CORS", "XC-TRANSPORT-DOWNGRADE", "XC-VERBOSE-ERRORS", "XC-SECURITY-HEADERS",
  191. "XC-TLS-POSTURE", "WEB-A06-COMPONENTS", "API9-INVENTORY", "XC-SECRET-EXPOSURE"}
  192. return {(c["class_id"], c["scope_key"]) for c in cells if c["class_id"] in mech}
  193. def open_cells(matrix):
  194. return {(r["class_id"], r["scope_key"]) for r in matrix["missing_cells"]}
  195. # --- tests -------------------------------------------------------------------
  196. def _fixture(tmp, omit_csp=False):
  197. certfile = os.path.join(tmp, "cert.pem")
  198. with open(certfile, "w") as f:
  199. f.write(_CERT_PEM + _KEY_PEM)
  200. http_httpd, http_port = start_server(omit_csp=omit_csp)
  201. tls_httpd, tls_port = start_server(omit_csp=omit_csp, tls=True, certfile=certfile)
  202. asset_dir = os.path.join(tmp, "webA")
  203. write_surface(asset_dir, "webA", http_port, tls_port)
  204. return asset_dir, (http_httpd, tls_httpd)
  205. def test_happy_path_closes_mechanical_cells():
  206. with tempfile.TemporaryDirectory() as tmp:
  207. asset_dir, servers = _fixture(tmp)
  208. try:
  209. summary = run_probe(asset_dir)
  210. matrix = run_gate(asset_dir)
  211. finally:
  212. for s in servers:
  213. s.shutdown()
  214. mech = mechanical_cells(asset_dir)
  215. assert mech, "fixture must enumerate mechanical cells"
  216. opened = open_cells(matrix)
  217. # WEB-A06-COMPONENTS needs nmap; if nmap is absent it is (honestly) a limitation.
  218. expect_closed = {c for c in mech if HAVE_NMAP or c[0] != "WEB-A06-COMPONENTS"}
  219. still_open = expect_closed & opened
  220. assert not still_open, f"these mechanical cells should be PASSED, got open: {sorted(still_open)}"
  221. # Every closed mechanical cell shows up in the probe's covered_negative summary.
  222. cn = {(c["class_id"], c["scope_key"]) for c in summary["covered_negative"]}
  223. assert expect_closed <= cn, f"summary missing covered_negative for: {sorted(expect_closed - cn)}"
  224. # gate scored them as covered_negative via a real corroborator, with NO validated finding.
  225. assert not glob.glob(os.path.join(asset_dir, "artifacts", "validated", "*.json")), \
  226. "no validated findings must exist — these are code-corroborated negatives"
  227. for cid in {"XC-CORS", "XC-SECURITY-HEADERS", "XC-TLS-POSTURE", "API9-INVENTORY", "XC-SECRET-EXPOSURE"}:
  228. pc = matrix["per_class"].get(cid)
  229. if pc:
  230. assert pc["status"] == "covered_negative" and pc["passed"] == pc["applicable"], \
  231. f"{cid} should be fully covered_negative: {pc}"
  232. if not HAVE_NMAP:
  233. assert any(x["class_id"] == "WEB-A06-COMPONENTS" for x in summary["limitations"]), \
  234. "no nmap -> COMPONENTS must be a limitation"
  235. def test_no_nmap_leaves_components_open():
  236. with tempfile.TemporaryDirectory() as tmp:
  237. asset_dir, servers = _fixture(tmp)
  238. try:
  239. summary = run_probe(asset_dir, no_nmap=True)
  240. matrix = run_gate(asset_dir)
  241. finally:
  242. for s in servers:
  243. s.shutdown()
  244. opened = open_cells(matrix)
  245. comp = {c for c in mechanical_cells(asset_dir) if c[0] == "WEB-A06-COMPONENTS"}
  246. assert comp, "fixture must have COMPONENTS cells"
  247. assert comp <= opened, f"--no-nmap must leave COMPONENTS OPEN, got closed: {sorted(comp - opened)}"
  248. assert any(x["class_id"] == "WEB-A06-COMPONENTS" for x in summary["limitations"]), \
  249. f"COMPONENTS must be a limitation: {summary['limitations']}"
  250. assert not any(c["class_id"] == "WEB-A06-COMPONENTS" for c in summary["covered_negative"]), \
  251. "COMPONENTS must not be reported covered when nmap is unavailable"
  252. # The other (non-nmap) mechanical cells still close.
  253. others = {c for c in mechanical_cells(asset_dir) if c[0] != "WEB-A06-COMPONENTS"}
  254. assert not (others & opened), f"non-nmap mechanical cells should still pass: {sorted(others & opened)}"
  255. def test_missing_header_emits_finding_and_leaves_cell_open():
  256. with tempfile.TemporaryDirectory() as tmp:
  257. asset_dir, servers = _fixture(tmp, omit_csp=True)
  258. try:
  259. # --no-nmap keeps the run fast; the CSP omission is what we're testing.
  260. summary = run_probe(asset_dir, no_nmap=True)
  261. matrix = run_gate(asset_dir)
  262. finally:
  263. for s in servers:
  264. s.shutdown()
  265. opened = open_cells(matrix)
  266. hdr = {c for c in mechanical_cells(asset_dir) if c[0] == "XC-SECURITY-HEADERS"}
  267. assert hdr, "fixture must have SECURITY-HEADERS cells"
  268. assert hdr <= opened, f"missing CSP must leave SECURITY-HEADERS OPEN: {sorted(hdr - opened)}"
  269. findings = {(f["class_id"], f["scope_key"]) for f in summary["findings"]}
  270. assert hdr <= findings, f"a finding must be emitted per SECURITY-HEADERS cell: {summary['findings']}"
  271. assert not any(c["class_id"] == "XC-SECURITY-HEADERS" for c in summary["covered_negative"]), \
  272. "a positive must NOT be written as covered_negative"
  273. # The raw finding is on disk (routed to the validation lane), NOT pre-validated.
  274. fdirs = glob.glob(os.path.join(asset_dir, "findings", "finding-XC-SECURITY-HEADERS-*"))
  275. assert fdirs, "a raw finding directory must exist"
  276. assert os.path.isfile(os.path.join(fdirs[0], "description.md"))
  277. assert os.path.isfile(os.path.join(fdirs[0], "evidence", "raw-source.txt"))
  278. assert not glob.glob(os.path.join(asset_dir, "artifacts", "validated", "*.json")), \
  279. "positive findings are raw, never pre-validated by the probe"
  280. def test_out_of_scope_host_is_skipped_not_probed():
  281. with tempfile.TemporaryDirectory() as tmp:
  282. asset_dir, servers = _fixture(tmp)
  283. try:
  284. # No --allow -> 127.0.0.1 is not in {asset_tag}; every cell must be SKIPPED, never probed.
  285. cmd = [sys.executable, PROBE, "--asset-dir", asset_dir, "--timeout", "5", "--no-nmap"]
  286. p = subprocess.run(cmd, cwd=REPO, capture_output=True, text=True)
  287. assert p.returncode == 0, p.stderr
  288. summary = json.loads([l for l in p.stdout.splitlines() if l.strip()][-1])
  289. finally:
  290. for s in servers:
  291. s.shutdown()
  292. assert summary["covered_negative"] == [], "out-of-scope hosts must not be closed"
  293. assert summary["findings"] == [], "out-of-scope hosts must not be probed for findings"
  294. skipped_hosts = {s["host"] for s in summary["skipped_out_of_scope"]}
  295. assert "127.0.0.1" in skipped_hosts, f"127.0.0.1 must be skipped as out-of-scope: {summary['skipped_out_of_scope']}"
  296. def test_no_mechanical_cells_is_graceful():
  297. with tempfile.TemporaryDirectory() as tmp:
  298. # A surface with no listeners/units -> no mechanical cells -> clean no-op exit 0.
  299. asset_dir = os.path.join(tmp, "empty")
  300. p = os.path.join(asset_dir, "recon", "inventory", "surface.json")
  301. os.makedirs(os.path.dirname(p), exist_ok=True)
  302. with open(p, "w") as f:
  303. json.dump({"schema": "surface/v2", "asset_tag": "empty", "units": []}, f)
  304. summary = run_probe(asset_dir)
  305. assert summary["covered_negative"] == [] and summary["findings"] == [], \
  306. f"empty surface must be a graceful no-op: {summary}"
  307. # --- Addition #1: WAF/CDN block-page classifier -----------------------------
  308. def test_classify_block_vendor_signatures():
  309. cb = probe.classify_block
  310. # F5 XC ASM reject page (body markers, usually HTTP 200).
  311. r = cb(200, {}, F5_REJECT_PAGE)
  312. assert r == {"is_block": True, "vendor": "f5"}, r
  313. # Vercel — platform error header, and the NOT_FOUND shell with an x-vercel-* header.
  314. assert cb(404, {"x-vercel-error": "NOT_FOUND"}, "")["vendor"] == "vercel"
  315. assert cb(404, {"x-vercel-id": "abc"}, "This page could not be found")["vendor"] == "vercel"
  316. # AppTrana / Indusface — HTTP 406 with a vendor marker.
  317. assert cb(406, {"content-type": "text/html"}, "Blocked by AppTrana WAF")["vendor"] == "apptrana"
  318. # Akamai — Ghost reject markers / Reference # hex.
  319. assert cb(403, {"server": "AkamaiGHost"}, "Access Denied")["vendor"] == "akamai"
  320. assert cb(200, {}, "Reference #18.abcd1234.1700000000.deadbeef")["vendor"] == "akamai"
  321. # Cloudflare — cf-ray header + a challenge/block body.
  322. assert cb(403, {"cf-ray": "8a1b2c3d"}, "Attention Required! | Cloudflare")["vendor"] == "cloudflare"
  323. assert cb(429, {"cf-ray": "8a1b2c3d"}, "error 1015 rate limited")["vendor"] == "cloudflare"
  324. # Sucuri — block body / x-sucuri-block header.
  325. assert cb(403, {"x-sucuri-id": "1"}, "Sucuri WebSite Firewall - Access Denied")["vendor"] == "sucuri"
  326. # Imperva / Incapsula — deny body / cookie markers.
  327. assert cb(403, {}, "Powered by _Incapsula_Resource")["vendor"] == "imperva"
  328. assert cb(403, {"set-cookie": "incap_ses_123=abc; path=/"}, "denied")["vendor"] == "imperva"
  329. assert cb(403, {"x-iinfo": "9-12345-0"}, "Request unsuccessful. Incapsula incident ID: 1")["vendor"] == "imperva"
  330. # NEGATIVES — a plain page and, crucially, a real 200 asset merely fronted by a
  331. # CDN (bare vendor header, no deny status/body) must NOT be classified as a block.
  332. assert cb(200, {"server": "nginx"}, "<html><body>hello</body></html>")["is_block"] is False
  333. assert cb(200, {"x-akamai-transformed": "9 1234 0"}, "console.log(1)")["is_block"] is False
  334. assert cb(200, {"x-sucuri-id": "1"}, "legit body")["is_block"] is False
  335. assert cb(200, {"x-vercel-id": "abc"}, "real served asset")["is_block"] is False
  336. assert cb(200, {"x-iinfo": "9-12345-0"}, "real served asset")["is_block"] is False
  337. # --- Addition #2: soft-404 detector -----------------------------------------
  338. def test_is_soft_404_true_and_false():
  339. shell = "<html><body id='app'>loading…</body></html>"
  340. baseline = probe.baseline_fingerprint({"ok": True, "status": 200, "body": shell})
  341. # identical body-hash -> soft-404
  342. assert probe.is_soft_404({"ok": True, "status": 200, "body": shell}, baseline) is True
  343. # same status, different body but size within tolerance -> soft-404
  344. near = shell.replace("app", "App") # same length, different content
  345. assert probe.is_soft_404({"ok": True, "status": 200, "body": near}, baseline) is True
  346. # different status -> NOT soft-404 (a real 200 file vs a 404 baseline)
  347. assert probe.is_soft_404({"ok": True, "status": 404, "body": shell}, baseline) is False
  348. # same status but a genuinely distinct, much larger body -> NOT soft-404
  349. assert probe.is_soft_404({"ok": True, "status": 200, "body": "X" * 5000}, baseline) is False
  350. # missing baseline / unreachable candidate -> NOT soft-404
  351. assert probe.is_soft_404({"ok": True, "status": 200, "body": shell}, None) is False
  352. assert probe.is_soft_404({"ok": False, "error": "refused"}, baseline) is False
  353. # --- wiring: a WAF reject page is a block observation, never a secret exposure --
  354. def test_f5_reject_page_not_reported_as_secret():
  355. # /.env returns the F5 reject page WITH an embedded fake key: without the block
  356. # guard the secret regex would match; the guard must win and suppress it.
  357. body = (F5_REJECT_PAGE + f"<!-- api_key: {_FAKE_AWS_KEY} -->").encode()
  358. def respond(path):
  359. if path == "/.env":
  360. return 200, {"Content-Type": "text/html"}, body
  361. return 404, {"Content-Type": "text/plain"}, b"Not Found"
  362. httpd, port = start_scripted_server(respond)
  363. base = f"http://127.0.0.1:{port}"
  364. try:
  365. verdict, one_line, raw, obs = probe.check_secret_exposure([f"{base}/.env"], [base], timeout=8)
  366. finally:
  367. httpd.shutdown()
  368. assert verdict == "clean", f"F5 reject page must not be a secret finding: {verdict} / {one_line}"
  369. assert "[SECRET]" not in raw, raw
  370. assert any(o["kind"] == "waf_block" and o["vendor"] == "f5" for o in obs), \
  371. f"the /.env reject page must be recorded as an F5 block: {obs}"
  372. # --- wiring: an SPA/Blazor catch-all shell is a soft-404, never a hit ----------
  373. def test_soft404_shell_not_reported_as_secret():
  374. # Every path (incl. the nonsense baseline AND /.git/config) returns the SAME 200
  375. # shell that happens to contain a secret-looking token.
  376. shell = (f"<html><body><script>window.cfg={{api_key:'{_FAKE_AWS_KEY}'}}</script>"
  377. "<div id='app'>loading</div></body></html>").encode()
  378. def respond(path):
  379. return 200, {"Content-Type": "text/html"}, shell # true catch-all
  380. httpd, port = start_scripted_server(respond)
  381. base = f"http://127.0.0.1:{port}"
  382. try:
  383. verdict, one_line, raw, obs = probe.check_secret_exposure(
  384. [f"{base}/.git/config", f"{base}/app.js"], [base], timeout=8)
  385. finally:
  386. httpd.shutdown()
  387. assert verdict == "clean", f"catch-all shell must not be a secret finding: {verdict} / {one_line}"
  388. assert "[SECRET]" not in raw, raw
  389. assert any(o["kind"] == "soft_404" and o["url"].endswith("/.git/config") for o in obs), \
  390. f"/.git/config must be recorded as a soft-404, not an exposure: {obs}"
  391. # --- no regression: a genuinely distinct file IS still reported ----------------
  392. def test_distinct_file_still_reported():
  393. # /app.js is a real, distinct 200 body with a secret; the nonsense baseline is a
  394. # short 404 -> differs in status+body -> NOT soft-404 -> must still be reported.
  395. real = (f"'use strict';const AWS_KEY='{_FAKE_AWS_KEY}';export default AWS_KEY;").encode()
  396. def respond(path):
  397. if path == "/app.js":
  398. return 200, {"Content-Type": "application/javascript"}, real
  399. return 404, {"Content-Type": "text/plain"}, b"Not Found"
  400. httpd, port = start_scripted_server(respond)
  401. base = f"http://127.0.0.1:{port}"
  402. try:
  403. verdict, one_line, raw, obs = probe.check_secret_exposure([f"{base}/app.js"], [base], timeout=8)
  404. finally:
  405. httpd.shutdown()
  406. assert verdict == "positive", f"a real distinct secret must still be reported: {verdict} / {one_line}"
  407. assert "[SECRET]" in raw and _FAKE_AWS_KEY[:12] in one_line, (raw, one_line)
  408. assert not any(o["kind"] == "soft_404" for o in obs), f"a distinct file is not a soft-404: {obs}"
  409. # --- wiring: soft-404 also protects the API inventory check --------------------
  410. def test_soft404_shell_not_reported_as_openapi():
  411. # Every path returns an identical 200 shell that echoes 'openapi' — without the
  412. # soft-404 guard /openapi.json would be a false "exposed inventory" hit.
  413. shell = b'<html><body>{"openapi":"3.0.0"} single-page app shell</body></html>'
  414. def respond(path):
  415. return 200, {"Content-Type": "text/html"}, shell # true catch-all
  416. httpd, port = start_scripted_server(respond)
  417. base = f"http://127.0.0.1:{port}"
  418. try:
  419. verdict, one_line, raw, obs = probe.check_api_inventory([base], timeout=8)
  420. finally:
  421. httpd.shutdown()
  422. assert verdict == "clean", f"catch-all shell must not be exposed inventory: {verdict} / {one_line}"
  423. assert "[OPENAPI]" not in raw, raw
  424. assert any(o["kind"] == "soft_404" for o in obs), f"swagger paths must be recorded as soft-404: {obs}"
  425. def test_mobile_asset_is_never_probed():
  426. """Trap 4: a mobile app asset must never be sent an HTTP probe.
  427. XC-SECRET-EXPOSURE gates on static_js_or_repo, an AGENT flag a mobile app can
  428. legitimately carry (a bundled JS/AOT blob IS a static bundle). Filtering cells by
  429. class alone would enumerate that cell for the app and fabricate a covered_negative
  430. against a file on disk.
  431. """
  432. with tempfile.TemporaryDirectory() as tmp:
  433. d = os.path.join(tmp, "fieldapp-app")
  434. os.makedirs(os.path.join(d, "recon", "inventory"))
  435. with open(os.path.join(d, "recon", "inventory", "mobile-surface.json"), "w") as f:
  436. json.dump({"schema": "mobile-surface/v1", "asset_tag": "fieldapp-app",
  437. "platform": "android", "package": "com.example.fieldapp",
  438. "flags": ["static_js_or_repo"],
  439. "units": [{"unit_id": "st:prefs", "type": "storage",
  440. "address": "/data/data/com.example.fieldapp/shared_prefs/s.xml",
  441. "flags": ["local_store"]}]}, f)
  442. summary = run_probe(d, no_nmap=True)
  443. assert summary["covered_negative"] == [], \
  444. f"a mobile asset must yield no probed negatives: {summary['covered_negative']}"
  445. assert summary["findings"] == [], summary["findings"]
  446. assert not os.path.isfile(os.path.join(d, "coverage.json")), \
  447. "the probe must not write a coverage ledger for a mobile asset"
  448. def main():
  449. tests = [v for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
  450. failed = 0
  451. for t in tests:
  452. try:
  453. t()
  454. print(f" PASS {t.__name__}")
  455. except AssertionError as e:
  456. failed += 1
  457. print(f" FAIL {t.__name__}: {e}")
  458. except Exception as e: # noqa: BLE001
  459. failed += 1
  460. print(f" ERROR {t.__name__}: {type(e).__name__}: {e}")
  461. print(f"{len(tests) - failed}/{len(tests)} passed (nmap {'present' if HAVE_NMAP else 'absent'})")
  462. return 1 if failed else 0
  463. if __name__ == "__main__":
  464. sys.exit(main())
tools/test_protect_deliverable.py · Bundled script · 231 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. """Offline, deterministic tests for tools/protect_deliverable.py.
  3. Proves: a real AES-256 protected zip + encrypted PDF are produced alongside the
  4. plaintext ones; the correct password opens them and a wrong one is rejected; the
  5. archived PDF is itself encrypted; the password never rides inside the zip; the
  6. password is reused across runs; and when the AES tool is absent the artifact is
  7. SKIPPED (recorded as a limitation) rather than silently downgraded to weak crypto.
  8. Capability-aware (repo convention): branches on 7z / pypdf availability so it stays
  9. green in a runner that lacks them; skips clean if no AES-256 tool is present at all.
  10. Run: python3 tools/test_protect_deliverable.py
  11. """
  12. from __future__ import annotations
  13. import json
  14. import os
  15. import shutil
  16. import subprocess
  17. import sys
  18. import tempfile
  19. HERE = os.path.dirname(os.path.abspath(__file__))
  20. TOOL = os.path.join(HERE, "protect_deliverable.py")
  21. def sevenzip():
  22. return next((t for t in ("7z", "7za", "7zz") if shutil.which(t)), None)
  23. HAVE_7Z = sevenzip() is not None
  24. HAVE_QPDF = shutil.which("qpdf") is not None
  25. try:
  26. from pypdf import PdfReader # noqa: F401
  27. HAVE_PYPDF = True
  28. except ImportError:
  29. HAVE_PYPDF = False
  30. HAVE_PDF_ENC = HAVE_QPDF or HAVE_PYPDF
  31. if not (HAVE_7Z or HAVE_PDF_ENC):
  32. print("SKIP: no AES-256 tool (7z / qpdf / pypdf) available")
  33. sys.exit(0)
  34. _pass = 0
  35. _fail = 0
  36. def ok(cond, msg):
  37. global _pass, _fail
  38. if cond:
  39. _pass += 1
  40. else:
  41. _fail += 1
  42. print(" FAIL " + msg)
  43. def run_tool(eng, report_id="ACME-260713-v1.0", env=None, extra=None):
  44. cmd = [sys.executable, TOOL, "--engagement-dir", eng, "--report-id", report_id]
  45. if extra:
  46. cmd += extra
  47. p = subprocess.run(cmd, capture_output=True, text=True, env=env)
  48. try:
  49. return json.loads(p.stdout.strip().splitlines()[-1]), p
  50. except (json.JSONDecodeError, IndexError):
  51. print(" tool stdout:", p.stdout, "stderr:", p.stderr)
  52. return None, p
  53. # A valid 1-page PDF built with whatever is available (no hard reportlab dep).
  54. _MINIMAL_PDF = (
  55. b"%PDF-1.4\n"
  56. b"1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj\n"
  57. b"2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj\n"
  58. b"3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]/Resources<<>>>>endobj\n"
  59. b"trailer<</Size 4/Root 1 0 R>>\n%%EOF\n"
  60. )
  61. def write_fixture_pdf(path):
  62. try:
  63. from reportlab.pdfgen import canvas # noqa: PLC0415
  64. c = canvas.Canvas(path)
  65. c.drawString(72, 720, "CONFIDENTIAL — penetration test findings")
  66. c.save()
  67. return
  68. except ImportError:
  69. pass
  70. try:
  71. from pypdf import PdfWriter # noqa: PLC0415
  72. w = PdfWriter()
  73. w.add_blank_page(width=612, height=792)
  74. with open(path, "wb") as fh:
  75. w.write(fh)
  76. return
  77. except Exception: # noqa: BLE001
  78. pass
  79. with open(path, "wb") as fh:
  80. fh.write(_MINIMAL_PDF)
  81. def make_fixture(root, with_pdf=True):
  82. os.makedirs(os.path.join(root, "reports"))
  83. os.makedirs(os.path.join(root, "input"))
  84. os.makedirs(os.path.join(root, "logs", "activity"))
  85. os.makedirs(os.path.join(root, "artifacts"))
  86. if with_pdf:
  87. write_fixture_pdf(os.path.join(root, "reports", "Penetration-Test-Report.pdf"))
  88. open(os.path.join(root, "reports", "summary.md"), "w").write("# Summary\nfindings: 3\n")
  89. open(os.path.join(root, "input", "scope.txt"), "w").write("example.com\n")
  90. open(os.path.join(root, "artifacts", "org-surface.json"), "w").write("{}\n")
  91. # --------------------------------------------------------------------------- #
  92. def test_happy_path():
  93. root = tempfile.mkdtemp()
  94. try:
  95. make_fixture(root)
  96. res, _ = run_tool(root)
  97. ok(res and res["ok"], "tool reports ok (something was protected)")
  98. if not res:
  99. return
  100. ok(res["password"] and len(res["password"]) >= 20, "strong password generated")
  101. ok(os.path.isfile(os.path.join(root, "reports", "Penetration-Test-Report.pdf")),
  102. "plaintext PDF kept alongside the protected one")
  103. if HAVE_PDF_ENC:
  104. ok(res["protected_pdf"] and os.path.isfile(res["protected_pdf"]), "protected PDF exists")
  105. ok(res["protected_pdf_algo"] and "AES-256" in res["protected_pdf_algo"], "PDF algo is AES-256")
  106. if HAVE_PYPDF and res["protected_pdf"]:
  107. r = PdfReader(res["protected_pdf"])
  108. ok(r.is_encrypted, "protected PDF is_encrypted")
  109. ok(r.decrypt(res["password"]) != 0, "correct password decrypts the PDF")
  110. ok(PdfReader(res["protected_pdf"]).decrypt("wrong-password-xyz") == 0,
  111. "wrong password does NOT decrypt the PDF")
  112. else:
  113. ok(res["protected_pdf"] is None and any("PDF" in x for x in res["limitations"]),
  114. "no PDF tool -> protected_pdf skipped + limitation (no weak fallback)")
  115. if HAVE_7Z:
  116. ok(res["protected_zip"] and os.path.isfile(res["protected_zip"]), "protected zip exists")
  117. ok(res["protected_zip_algo"] and "AES-256" in res["protected_zip_algo"], "zip algo is AES-256")
  118. sz = sevenzip()
  119. good = subprocess.run([sz, "t", "-p" + res["password"], res["protected_zip"]], capture_output=True)
  120. ok(good.returncode == 0, "correct password opens the zip")
  121. bad = subprocess.run([sz, "t", "-pWRONGpw123", res["protected_zip"]], capture_output=True)
  122. ok(bad.returncode != 0, "wrong password is rejected by the zip")
    • Note: Quoted as data in code: Asks you to extract a password-protected archive, the usual way malware droppers get past scanners
    • Line 146 on GitHub
  123. listing = subprocess.run([sz, "l", "-p" + res["password"], res["protected_zip"]],
  124. capture_output=True, text=True)
  125. ok("DELIVERABLE-PASSWORD.txt" not in listing.stdout,
  126. "password file is NOT inside the protected zip")
  127. if HAVE_PYPDF:
  128. ext = tempfile.mkdtemp()
  129. subprocess.run([sz, "x", "-y", "-p" + res["password"], "-o" + ext, res["protected_zip"],
  130. "reports/Penetration-Test-Report.pdf"], capture_output=True)
  131. inner = os.path.join(ext, "reports", "Penetration-Test-Report.pdf")
  132. ok(os.path.isfile(inner) and PdfReader(inner).is_encrypted,
  133. "PDF inside the protected zip is itself encrypted")
  134. shutil.rmtree(ext, ignore_errors=True)
  135. else:
  136. ok(res["protected_zip"] is None and any("zip" in x for x in res["limitations"]),
  137. "no 7z -> protected_zip skipped + limitation (no weak ZipCrypto)")
  138. pf = os.path.join(root, "DELIVERABLE-PASSWORD.txt")
  139. ok(os.path.isfile(pf), "password file written at engagement root")
  140. ok(res["password"] in open(pf).read(), "password file contains the password")
  141. ok((os.stat(pf).st_mode & 0o777) == 0o600, "password file is chmod 600")
  142. finally:
  143. shutil.rmtree(root, ignore_errors=True)
  144. def test_password_reuse():
  145. root = tempfile.mkdtemp()
  146. try:
  147. make_fixture(root)
  148. r1, _ = run_tool(root)
  149. r2, _ = run_tool(root)
  150. ok(r1 and r2 and r1["password"] == r2["password"], "password is reused across runs (stable)")
  151. ok(r2 and r2["password_reused"] is True, "second run reports password_reused=True")
  152. r3, _ = run_tool(root, extra=["--no-reuse"])
  153. ok(r3 and r3["password"] != r1["password"], "--no-reuse mints a fresh password")
  154. finally:
  155. shutil.rmtree(root, ignore_errors=True)
  156. def test_no_7z_skips_zip_no_weak_fallback():
  157. """With every 7z binary stripped from PATH, the zip is SKIPPED + a limitation is
  158. recorded — never a weak-crypto zip. Only meaningful where pypdf can still protect
  159. the PDF without PATH tools; otherwise it just asserts the no-weak-fallback contract."""
  160. if not HAVE_7Z:
  161. return # can't demonstrate the strip if 7z was never there
  162. root = tempfile.mkdtemp()
  163. safe = tempfile.mkdtemp()
  164. try:
  165. make_fixture(root)
  166. env = dict(os.environ)
  167. env["PATH"] = safe # no 7z AND no qpdf on PATH -> pypdf (in-process) still protects the PDF
  168. res, _ = run_tool(root, env=env)
  169. ok(res is not None, "tool still runs with an empty PATH")
  170. if res:
  171. ok(res["protected_zip"] is None, "no protected zip when 7z is absent")
  172. ok(any("zip skipped" in x for x in res["limitations"]),
  173. "a limitation is recorded for the skipped zip (no silent weak fallback)")
  174. if HAVE_PYPDF:
  175. ok(res["protected_pdf"] is not None and "pypdf" in (res["protected_pdf_algo"] or ""),
  176. "PDF still protected via pypdf (AES-256) without external binaries")
  177. finally:
  178. shutil.rmtree(root, ignore_errors=True)
  179. shutil.rmtree(safe, ignore_errors=True)
  180. def test_missing_pdf_graceful():
  181. root = tempfile.mkdtemp()
  182. try:
  183. make_fixture(root, with_pdf=False)
  184. res, _ = run_tool(root)
  185. ok(res is not None and res["protected_pdf"] is None, "missing PDF -> protected_pdf None")
  186. ok(res and any("no plaintext PDF" in x for x in res["limitations"]),
  187. "missing PDF recorded as a limitation")
  188. if HAVE_7Z:
  189. ok(res and res["protected_zip"], "protected zip still produced without a PDF")
  190. finally:
  191. shutil.rmtree(root, ignore_errors=True)
  192. if __name__ == "__main__":
  193. for t in (test_happy_path, test_password_reuse, test_no_7z_skips_zip_no_weak_fallback,
  194. test_missing_pdf_graceful):
  195. t()
  196. print(" ran " + t.__name__)
  197. print("\n%d/%d passed (7z=%s qpdf=%s pypdf=%s)" % (_pass, _pass + _fail, HAVE_7Z, HAVE_QPDF, HAVE_PYPDF))
  198. sys.exit(1 if _fail else 0)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.