Transilience Community Security Tools
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.
Badge for your README
Markdown
[](/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)
- {
- "name": "Transilience Community Security Tools",
- "description": "Claude Code plugins for authorized security testing, bug bounty hunting, AI threat testing, and recon",
- "plugins": [
- {
- "name": "pentest",
- "path": "plugins/pentest",
- "description": "Full penetration testing framework — 100+ attack categories covering OWASP, injection, authentication, cloud, and more"
- },
- {
- "name": "hackerone",
- "path": "plugins/hackerone",
- "description": "HackerOne bug bounty integration — report generation, CSV parsing, and platform-ready submissions"
- },
- {
- "name": "ai-threat-testing",
- "path": "plugins/ai-threat-testing",
- "description": "AI security testing — OWASP LLM Top 10 with dedicated agents for prompt injection, model extraction, and more"
- },
- {
- "name": "techstack-identification",
- "path": "plugins/techstack-identification",
- "description": "Tech stack reconnaissance — 26 skills and 5 agents for DNS, cloud detection, subdomain enumeration, and more"
- },
- {
- "name": "skill-update",
- "path": "plugins/skill-update",
- "description": "Skill creation meta-tool — automates skill generation, validation, and PR submission for Claude Code plugins"
- }
- ]
- }
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)
- # Transilience AI Community Security Tools
- <div align="center">
- [](https://www.transilience.ai)
- [](https://choosealicense.com/licenses/mit/)
- [](https://github.com/transilienceai/communitytools/stargazers)
- [](https://claude.ai)
- **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)**
- [Quick Start](#-quick-start) | [Skills](#-skills) | [Architecture](#-architecture) | [Contributing](CONTRIBUTING.md) | [Website](https://www.transilience.ai)
- </div>
- ---
- ## Announcement
- **Practice Makes Perfect: Teaching an AI to Hack by Learning from Its Mistakes** (March 2026)
- 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.
- **[Read the paper](papers/practice-makes-perfect.pdf)**
- ---
- ## Overview
- **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=...)`.
- ### Why Choose Transilience Community Tools?
- - **AI-Powered Automation** — Claude coordinates intelligent security testing workflows
- - **Complete OWASP Coverage** — 100% OWASP Top 10 + OWASP LLM Top 10
- - **Professional Reporting** — CVSS 4.0 (primary; v3.1/v3.0/v2.0 fallback), CWE, MITRE ATT&CK, Transilience-branded PDF reports
- - **Playwright Integration** — Browser automation for client-side vulnerability testing
- - **Payload-Enriched References** — 160+ reference files with inline PayloadsAllTheThings techniques
- - **Open Source** — MIT licensed for commercial and personal use
- ---
- ## Prerequisites
- ### Local Setup
- - **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
- ### Docker Setup (Recommended)
- A single script spins up a Kali Linux container with Claude Code, Playwright (headed via Xvfb), and all Kali security tools pre-installed:
- ```bash
- bash scripts/kali-claude-setup.sh projects/pentest
- ```
- 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.
- ---
- ## Quick Start
- ### 1. Clone and enter the project
- ```bash
- git clone https://github.com/transilienceai/communitytools.git
- cd communitytools/projects/pentest
- ```
- ### 2. Open Claude Code and run skills
- ```bash
- claude # Launch Claude Code from the projects/pentest directory
- ```
- Then use slash commands inside the Claude session:
- ```
- Pentest https://target.com # Full penetration test (skills/coordination/)
- /hackthebox # HackTheBox challenge automation
- /hackerone # Bug bounty workflow
- /techstack-identification # Passive tech stack recon
- /reconnaissance target.com # Attack surface mapping
- /source-code-scanning ./app # Static code analysis
- ```
- ---
- ## Skills
- 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.
- Agent roles (coordinator, executor, validator) are defined in `skills/coordination/` with reference material in `skills/coordination/reference/`, spawned dynamically via `Agent(prompt=...)`.
- ### Skills by Category (26)
- #### Vulnerability Testing (10)
- | Skill | Coverage |
- |-------|----------|
- | `/injection` | SQL, NoSQL, OS Command, SSTI, XXE, LDAP/XPath |
- | `/client-side` | XSS (Reflected/Stored/DOM), CSRF, Clickjacking, CORS, Prototype Pollution |
- | `/server-side` | SSRF, HTTP Smuggling, Path Traversal, File Upload, Deserialization, Host Header |
- | `/authentication` | Auth Bypass, JWT, OAuth, Password Attacks, 2FA Bypass, CAPTCHA Bypass |
- | `/api-security` | GraphQL, REST API, WebSockets, Web LLM |
- | `/web-app-logic` | Business Logic, Race Conditions, Access Control, Cache Poisoning/Deception, IDOR |
- | `/cloud-containers` | AWS, Azure, GCP, Docker, Kubernetes |
- | `/system` | Active Directory, Privilege Escalation (Linux/Windows), Exploit Development |
- | `/infrastructure` | Port Scanning, DNS, MITM, VLAN Hopping, IPv6, SMB/NetBIOS |
- | `/social-engineering` | Phishing, Pretexting, Vishing, Physical Security |
- #### Reconnaissance (3)
- | Skill | Purpose |
- |-------|---------|
- | `/reconnaissance` | Subdomain discovery, port scanning, endpoint enumeration, API discovery, attack surface mapping |
- | `/osint` | Repository enumeration, secret scanning, git history analysis, employee footprint |
- | `/techstack-identification` | Passive tech stack inference across 17 intelligence domains |
- #### Specialized (5)
- | Skill | Purpose |
- |-------|---------|
- | `/ai-threat-testing` | OWASP LLM Top 10 — prompt injection, model extraction, data poisoning, supply chain |
- | `/blockchain-security` | Smart contract security, EVM storage, delegatecall, CREATE/CREATE2, DeFi exploits |
- | `/cve-poc-generator` | CVE research, NVD lookup, safe Python PoC generation, vulnerability reports |
- | `/dfir` | Digital forensics, incident response, Windows event logs, PCAP analysis, AD attack detection |
- | `/source-code-scanning` | SAST — OWASP Top 10, CWE Top 25, dependency CVEs, hardcoded secrets |
- #### Platform Integrations (2)
- | Skill | Purpose |
- |-------|---------|
- | `/hackerone` | Scope CSV parsing, parallel asset testing, PoC validation, platform-ready submissions |
- | `/hackthebox` | Playwright-based login, challenge browsing, VPN management, automated solving |
- #### Tooling (6)
- | Skill | Purpose |
- |-------|---------|
- | `/essential-tools` | Burp Suite, Playwright automation, methodology, reporting standards |
- | `/patt-fetcher` | On-demand payload extraction from PayloadsAllTheThings |
- | `/script-generator` | Optimized, syntax-validated script generation |
- | `formats/transilience-report-style` | Transilience-branded PDF report generation (ReportLab) |
- | `/github-workflow` | Git branching, commits, PRs, issues, code review |
- | `/skill-update` | Skill scaffolding, validation, GitHub workflow automation |
- ### Tool Integrations (3)
- | Tool | Purpose |
- |------|---------|
- | **Playwright** | Browser automation for client-side testing via MCP |
- | **Kali Linux Tools** | nmap, masscan, nikto, gobuster, ffuf, sqlmap, testssl, and more |
- | **NVD / CVE Risk Score** | Auto-invoked CVE lookup (`/cve-risk-score`) — CVSS score, severity, CWE from NVD |
- ### MCP Servers
- 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.
- | Server | Purpose |
- |--------|---------|
- | [`mcp/transilience-vuln`](./mcp/transilience-vuln) | Single-CVE and bulk CVE enrichment (CVSS, EPSS, KEV, impact taxonomy, vendor advisories) via the Transilience Vulnerability API. |
- ---
- ## Architecture
- The suite uses a **skills-only** architecture with canonical definitions at the repo root, symlinked into isolated project environments:
- - **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.
- - **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=...)`.
- - **Tools** (`tools/` at root, symlinked into each project's `.claude/tools/`) — Utility scripts for environment reading, integrations.
- ### Multi-Agent Execution Flow
- ```mermaid
- sequenceDiagram
- participant User
- participant Coord as Coordinator (inline)
- participant Roles as Role Definitions (skills/coordination/)
- participant Agents as Spawned Agents
- participant Output as Standardized Outputs
- User->>Coord: Pentest https://target.com
- Coord->>Roles: Read skills/coordination/SKILL.md
- Coord->>Coord: Execute coordinator workflow inline
- Coord->>Roles: Read skills/coordination/reference/executor-role.md
- Coord->>Agents: Agent(prompt=executor_role + chain + skills) × N
- Note over Agents: SQL/XSS/SSRF/JWT/OAuth/SSTI/XXE...
- Agents-->>Output: findings/*.json + evidence/*.png
- Coord->>Roles: Read skills/coordination/reference/validator-role.md
- Coord->>Agents: Agent(prompt=validator_role + evidence ONLY) × N
- Note over Agents: Blind review — no attack chain context
- Agents-->>Output: validated/*.json
- Coord->>Output: Phase 6: Generate reports
- Output-->>User: Executive + technical reports
- ```
- ### Repository Structure
- ```
- communitytools/
- ├── CLAUDE.md # Project instructions
- ├── marketplace.json # Machine-readable project manifest
- ├── papers/ # Research papers
- ├── benchmarks/ # XBOW benchmark runner
- │
- ├── skills/ # ← Canonical skill definitions (source of truth)
- │ ├── coordination/ # ← Agent roles + coordination reference
- │ │ ├── SKILL.md # Coordinator logic (entry point)
- │ │ └── reference/
- │ │ ├── executor-role.md # Executor role prompt
- │ │ ├── validator-role.md # Validator role prompt (blind review)
- │ │ ├── context-injection.md # What context each role receives
- │ │ ├── ATTACK_INDEX.md # 53 attack types mapped to skills
- │ │ ├── OUTPUT_STRUCTURE.md # Engagement output directory spec
- │ │ ├── VALIDATION.md # 5-check finding validation framework
- │ │ ├── GIT_CONVENTIONS.md # Branch/commit/PR standards
- │ │ └── PATT_STANDARD.md # PayloadsAllTheThings integration
- │ ├── injection/
- │ │ ├── SKILL.md
- │ │ └── reference/
- │ ├── reconnaissance/
- │ ├── server-side/
- │ └── ... # 27 skill directories total
- │
- ├── tools/ # ← Canonical tool integrations (source of truth)
- │ ├── env-reader.py
- │ └── slack-send.py
- │
- └── projects/ # ← Isolated project environments
- └── pentest/
- └── .claude/
- ├── skills/ # Real directory, contents are symlinks
- │ ├── injection/ → ../../../../skills/injection/
- │ └── ... # Each project picks what it needs
- └── tools/ # Real directory, contents are symlinks
- ├── env-reader.py → ../../../../tools/env-reader.py
- └── ...
- ```
- ### Why This Structure?
- **Canonical root directories** (`skills/`, `tools/`) hold the single source of truth for all definitions. No duplication, no drift.
- **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.
- This design gives you:
- - **Isolation** — Each project is a self-contained working directory. Run `claude` from `projects/pentest/` and it discovers only the skills that project has symlinked.
- - **Single source of truth** — Edit a skill once in `skills/`, and every project that symlinks it gets the update immediately.
- - **Selective inclusion** — A new project doesn't need all 23 skills. Symlink only what's relevant.
- - **Claude Code compatibility** — Claude Code resolves symlinks transparently via the OS.
- **Adding a new project:**
- ```bash
- mkdir -p projects/myproject/.claude/{skills,tools}
- cd projects/myproject/.claude/skills
- # Symlink only the skills this project needs
- ln -s ../../../../skills/injection injection
- # Coordination is a skill like any other — symlink if needed
- ln -s ../../../../skills/coordination coordination
- ln -s ../../../../skills/reconnaissance reconnaissance
- # ... add more as needed
- # Same for tools
- cd ../tools
- ln -s ../../../../tools/env-reader.py env-reader.py
- ```
- ---
- ## Contributing
- We welcome contributions from the security community!
- **Read the full guide:** [CONTRIBUTING.md](CONTRIBUTING.md)
- **Quick path using Skill Update:**
- ```bash
- /skill-update
- # Select: CREATE → provide details → automated GitHub workflow
- # Handles: issue creation, branch, skill generation, validation, commit, PR
- ```
- ---
- ## Security & Legal
- **IMPORTANT: These tools are designed for authorized security testing ONLY.**
- **Authorized & Legal Use:**
- - Penetration testing with written authorization
- - Bug bounty programs within scope
- - Security research on your own systems
- - CTF competitions and training environments
- - Educational purposes with proper permissions
- **Prohibited & Illegal Use:**
- - Unauthorized testing of any systems
- - Malicious exploitation of vulnerabilities
- - Data theft or system disruption
- - Any use that violates local or international laws
- **Users are solely responsible for compliance with all applicable laws and regulations.**
- ### Responsible Disclosure
- If you discover a vulnerability using these tools:
- 1. Do not exploit beyond proof-of-concept
- 2. Report immediately to the vendor/organization
- 3. Follow responsible disclosure timelines (typically 90 days)
- 4. Document thoroughly for remediation
- ---
- ## Community & Support
- - [GitHub Discussions](https://github.com/transilienceai/communitytools/discussions) — Ask questions, share ideas
- - [GitHub Issues](https://github.com/transilienceai/communitytools/issues) — Report bugs, request features
- - [Transilience.ai](https://www.transilience.ai) — See what else we're building
- - [LinkedIn](https://linkedin.com/company/transilienceai) — Follow our work
- - [Email](mailto:contact@transilience.ai) — Get in touch
- ---
- ## Project Stats
- | Category | Count |
- |----------|-------|
- | **Skills** | 27 |
- | **Role Prompts** | 3 (in coordination skill) |
- | **Tool Integrations** | 3 |
- | **Attack Types** | 53 |
- | **Reference Files** | 160+ |
- **Coverage:**
- - OWASP Top 10 (2021) — 100%
- - OWASP LLM Top 10 (2025) — 100%
- - SANS Top 25 CWE — 90%+
- - MITRE ATT&CK TTPs — mapped for all findings
- ---
- ## License
- MIT License — Copyright (c) 2026 Transilience AI. See [LICENSE](LICENSE) for details.
- ---
- ## Contributors
- <a href="https://github.com/transilienceai/communitytools/graphs/contributors">
- <img src="https://contrib.rocks/image?repo=transilienceai/communitytools" />
- </a>
- ---
- <div align="center">
- **Built by [Transilience AI](https://www.transilience.ai)**
- 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).
- [](https://github.com/transilienceai/communitytools)
- [Website](https://www.transilience.ai) | [Issues](https://github.com/transilienceai/communitytools/issues) | [Discussions](https://github.com/transilienceai/communitytools/discussions)
- `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`
- </div>
.claude/workflows/pentest-engagement.js · Bundled script · 1,547 lines · 1 finding marked
- export const meta = {
- name: 'pentest-engagement',
- 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.',
- 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.',
- phases: [
- { 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' },
- { 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' },
- { 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' },
- { 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)' },
- { 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' },
- { title: 'GeoProbe', detail: 'NETWORK: on a source-IP/geo-allowlist signature, auto-provision a 2nd-geography vantage and re-probe the filtered hosts' },
- { title: 'Infra', detail: 'WEB: bounded probes of scope-adjacent infrastructure surfaced during expansion' },
- { 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)' },
- { title: 'Correlate', detail: 'attack-path-stitcher across all validated findings -> risk-prioritiser -> ranked org roadmap' },
- { 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)' },
- ],
- }
- // ============================================================================
- // PENTEST-ENGAGEMENT — the general web/API/cloud analogue of htb-solve.
- //
- // Architecture (faithful to skills/coordination + the gap-analysis fixes):
- // ORCHESTRATOR = this workflow. Owns creds, scope parsing, OUTPUT_DIR, the
- // MANDATORY surface-expansion phase, cross-asset correlation,
- // the Transilience report, and the coverage-gated COMPLETE
- // decision. The only layer allowed to touch Slack.
- // COORDINATOR = the `coordinator-loop` workflow in COVERAGE mode, run once
- // per asset via workflow() (one level of nesting). It runs the
- // recon/think/execute/integrate loop driven by the attack-class
- // coverage matrix, with reversible-active-exploitation + root-
- // cause severity, and writes a Transilience per-asset source.
- // VALIDATOR = the `validate-findings` workflow (sibling, one level below),
- // reused VERBATIM as the authoritative per-asset validator.
- //
- // Pipeline (no barrier within Assess): each asset flows assess -> validate
- // independently; targets chunked by maxConcurrent. Correlate + Report run after
- // the Assess barrier (they need every asset's validated set).
- //
- // AGENT-CAP NOTE: child workflows SHARE this run's 1000-agent lifetime counter.
- // Each coordinator-loop runs to CONVERGENCE (full coverage + a dry tail), backstopped
- // by an honest per-asset agent slice (assessBudget.perAsset). Because a run cannot
- // exceed 1000 agents, resumeSchedule converges only as many assets as fit their slice
- // this run and DEFERS the rest to a resume run (resume_dir), reserving headroom for
- // Expand + Correlate + Report.
- //
- // Sandbox: no Date.now()/Math.random()/new Date() — agents shell out to `date`.
- // ============================================================================
- // ---- helpers ---------------------------------------------------------------
- function chunk(arr, n) {
- const out = []
- for (let i = 0; i < arr.length; i += n) out.push(arr.slice(i, i + n))
- return out
- }
- // ============================================================================
- // DETERMINISTIC HELPERS — inline copy of .claude/workflows/lib/wf-helpers.mjs
- // (sandbox has no import). Kept logic-identical; parity.test.mjs guards drift.
- // ============================================================================
- const SEVERITY = ['Critical', 'High', 'Medium', 'Low', 'Info']
- function severityBand(score) {
- const s = Number(score)
- if (!(s > 0)) return 'Info'
- if (s >= 9.0) return 'Critical'
- if (s >= 7.0) return 'High'
- if (s >= 4.0) return 'Medium'
- return 'Low'
- }
- function normalizeAssess(v, asset) {
- const lo = v || {}
- const degraded = !!(lo.blocked_reason || lo.status === 'FAILED' || lo.coverage_status === 'FAILED')
- return {
- tag: asset.tag, key: asset.key, output_dir: asset.output_dir || lo.output_dir || null, type: asset.type || null,
- business_tier: asset.business_tier || null,
- coverage_status: lo.coverage_status || lo.status || 'UNKNOWN',
- coverage_ratio: typeof lo.coverage_ratio === 'number' ? lo.coverage_ratio : null,
- findings_total: lo.findings_total != null ? lo.findings_total : (Array.isArray(lo.findings_confirmed) ? lo.findings_confirmed.length : 0),
- validation: lo.validation || null, degraded,
- blocked_reason: lo.blocked_reason || (degraded ? 'assessment degraded' : null),
- }
- }
- function reconcileAssessed(expected, assessed, keyOf) {
- const seen = new Set(assessed.map((a) => a.key))
- const backfilled = expected.filter((e) => !seen.has(keyOf(e))).map((e) => ({
- tag: e.tag, key: keyOf(e), output_dir: e.output_dir || null, type: e.type || null,
- business_tier: e.business_tier || null, coverage_status: 'MISSING', coverage_ratio: null,
- findings_total: 0, validation: null, degraded: true, blocked_reason: 'no result returned',
- }))
- const all = assessed.concat(backfilled)
- const gaps = all.filter((a) => a.degraded || a.coverage_status !== 'COVERAGE_COMPLETE')
- return { all, backfilled, gaps, complete: gaps.length === 0 }
- }
- function finalizeGate({ report_data_ok, report_data_lint_ok, renderGateOk, coverage_complete, coverage_untested, renderBlockedReason }) {
- const ok = !!(report_data_ok && report_data_lint_ok && renderGateOk && coverage_complete)
- const blocked_reason = ok ? null
- : !report_data_ok ? 'report_data_build failed'
- : !report_data_lint_ok ? 'report_data lint failed (schema/escaping)'
- : !renderGateOk ? (renderBlockedReason || 'render failed')
- : `attack-class coverage < 100% (${coverage_untested} cell(s) untested)`
- return { ok, status: ok ? 'COMPLETE' : 'BLOCKED', blocked_reason }
- }
- function bumpVersion(priorVersion) {
- if (!priorVersion) return 'v1.0'
- const m = String(priorVersion).match(/v?(\d+)(?:\.(\d+))?/i)
- if (!m) return 'v1.0'
- return `v${Number(m[1]) + 1}.0`
- }
- function scopeDiff(priorScope, currentScope) {
- const P = new Set((priorScope || []).map(String))
- const C = new Set((currentScope || []).map(String))
- const added = [...C].filter((x) => !P.has(x)).sort()
- const removed = [...P].filter((x) => !C.has(x)).sort()
- const unchanged = [...C].filter((x) => P.has(x)).sort()
- return { added, removed, unchanged, changed: added.length > 0 || removed.length > 0 }
- }
- // Prompt > prior > default. Prior SCOPE is METADATA-ONLY (display diff, never a work list).
- function resolveEngagementMeta({ prior, prompt, currentScope, dateTag, explicitVersion } = {}) {
- const p = prior || {}, pr = prompt || {}
- const pick = (k) => (pr[k] != null && pr[k] !== '' ? pr[k] : p[k]) || null
- const meta = {}
- for (const k of ['title', 'title_lines', 'subtitle', 'sector', 'target', 'classification', 'method', 'prepared_by', 'duration']) meta[k] = pick(k)
- meta.version = explicitVersion || bumpVersion(p.version || ((p.report_id || '').match(/v\d+(\.\d+)?/i) || [])[0])
- meta.supersedes = p.report_id || p.version || null
- const base = (meta.title || meta.sector || 'ENGAGEMENT').replace(/[^A-Za-z0-9]+/g, '-').slice(0, 24).toUpperCase().replace(/-+$/, '')
- meta.report_id = pr.report_id || `${base}-${dateTag || '000000'}-${meta.version}`
- meta.scope_changes = scopeDiff(p.scope, currentScope)
- return meta
- }
- // Source-IP/geo-allowlist SIGNATURE from per-slice scan results. The cost-bound
- // discriminator is the workers' filtered[] set (existence-confirmed-but-dark
- // hosts); genuinely-down hosts stay in dead_count and never fire it.
- function detectAllowlist(sliceResults) {
- const slices = Array.isArray(sliceResults) ? sliceResults : []
- const liveCount = slices.reduce((n, s) => n + ((s && Array.isArray(s.live)) ? s.live.length : 0), 0)
- const filteredHosts = []
- const seen = new Set()
- for (const s of slices) {
- for (const f of ((s && Array.isArray(s.filtered)) ? s.filtered : [])) {
- 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' }) }
- }
- }
- return { signature: liveCount >= 1 && filteredHosts.length >= 1, filteredHosts }
- }
- // Resolve the <=2 second-vantage gcp ZONES. Explicit geoVantages honored (dedup
- // + cap 2); else the default US+EU pair minus the primary's continent.
- function resolveGeoZones({ geoVantages, primaryGeo } = {}) {
- const DEFAULTS = ['us-central1-a', 'europe-west1-b']
- const dedupCap = (zs) => { const o = []; for (const z of zs) { if (!o.includes(z)) o.push(z); if (o.length === 2) break } return o }
- const override = (Array.isArray(geoVantages) ? geoVantages : []).map((s) => (s == null ? '' : String(s).trim())).filter(Boolean)
- if (override.length) return dedupCap(override)
- const primary = String(primaryGeo || '').toUpperCase()
- const US = ['US', 'CA', 'MX']
- const EU = ['DE', 'NL', 'ES', 'FR', 'IT', 'GB', 'UK', 'IE', 'BE', 'CH', 'AT', 'SE', 'NO', 'FI', 'DK', 'PL', 'PT', 'CZ', 'RO', 'HU', 'GR']
- const cont = US.includes(primary) ? 'us' : (EU.includes(primary) ? 'eu' : null)
- const regionOf = (z) => (z.startsWith('us-') || z.startsWith('northamerica-')) ? 'us' : (z.startsWith('europe-') ? 'eu' : 'other')
- const kept = cont ? DEFAULTS.filter((z) => regionOf(z) !== cont) : DEFAULTS.slice()
- return dedupCap(kept.length ? kept : DEFAULTS)
- }
- // How many INCOMPLETE assets to fully converge THIS run so each gets a real agent
- // slice and the worst-case total stays under the runtime cap; the rest defer to a
- // resume run. Always runs >=1 when any work remains (else the engagement stalls).
- function resumeSchedule({ incompleteCount, agentCap, deepSlice, overhead } = {}) {
- const cap = Math.max(0, Math.floor(Number(agentCap) || 0) - Math.max(0, Math.floor(Number(overhead) || 0)))
- const slice = Math.max(1, Math.floor(Number(deepSlice) || 1))
- const capacity = Math.floor(cap / slice)
- const inc = Math.max(0, Math.floor(Number(incompleteCount) || 0))
- const assetsThisRun = inc === 0 ? 0 : Math.max(1, Math.min(inc, capacity))
- return { assetsThisRun, deferred: inc - assetsThisRun }
- }
- // Tri-state engagement status from the per-asset rows + the deferred (not-run-this-
- // run) tags. A genuinely-stuck asset (INCOMPLETE_COVERAGE / degraded) blocks COMPLETE
- // and is surfaced for a human; resumable + deferred assets (and stuck ones, retried
- // each run) populate the resume list that drives the next run.
- function classifyEngagement(assetRows, deferredTags) {
- const rows = Array.isArray(assetRows) ? assetRows : []
- const stuck = rows.filter((r) => r && (r.coverage_status === 'INCOMPLETE_COVERAGE' || r.degraded)).map((r) => r.tag)
- const resumable = rows.filter((r) => r && r.coverage_status === 'INCOMPLETE_RESUMABLE').map((r) => r.tag)
- const remaining = [...new Set([...resumable, ...stuck, ...(Array.isArray(deferredTags) ? deferredTags : [])])]
- const engagement_status = stuck.length ? 'INCOMPLETE_coverage' : (remaining.length ? 'INCOMPLETE_resumable' : 'COMPLETE')
- const resume = remaining.length
- ? { remaining_assets: remaining, deferred_reason: stuck.length ? 'mixed: stuck + deferred' : 'agent-slice / per-run budget', rerun_hint: 'resume_dir=<engagement_dir>' }
- : { remaining_assets: [], deferred_reason: null, rerun_hint: null }
- return { engagement_status, resume }
- }
- // ============================================================================
- // finalizeEngagement — the deterministic Report -> Package -> Summarize lane,
- // shared by WEB and NETWORK. NO agent authors the report_data or the PDF: JS
- // hands the engagement block + exact commands to ONE tool-runner, which writes
- // engagement-meta.json verbatim, runs tools/report_data_build.py (the sole-owner
- // assembler), the format-dispatched renderer, and the packager — and reports the
- // real facts. JS then hard-gates on those facts.
- // ============================================================================
- const FINALIZE_SCHEMA = {
- type: 'object', additionalProperties: true,
- required: ['report_data_ok', 'findings', 'render_ok'],
- properties: {
- report_data_ok: { type: 'boolean' }, report_data_path: { type: 'string' }, report_data_sha: { type: 'string' },
- report_data_lint_ok: { type: 'boolean', description: 'tools/report_data_lint.py exited 0 (schema + RAW-field escaping/tag-allowlist gate before render)' },
- report_data_lint_errors: { type: 'array', items: { type: 'string' } },
- netscan_sound: { type: 'boolean', description: 'tools/netscan_guard.py found no host-timeout-truncation signature over the slice service XMLs' },
- netscan_rescan_hosts: { type: 'array', items: { type: 'string' }, description: '0-open up-hosts under --host-timeout to re-scan before calling dead' },
- netscan_notes: { type: 'array', items: { type: 'string' } },
- coverage_deferred: { type: 'number', description: 'count of client-input-deferred coverage cells (MFA/OTP/allowlist), disclosed in the report' },
- exports_ok: { type: 'boolean', description: 'tools/report_export.py produced both the CSV and XML machine-readable findings exports' },
- export_paths: { type: 'array', items: { type: 'string' }, description: 'the CSV/XML export paths that landed in the deliverable zip' },
- findings: { type: 'number' }, demoted: { type: 'number' }, severity_counts: { type: 'object', additionalProperties: true },
- render_ok: { type: 'boolean' }, report_path: { type: 'string' }, pdf_bytes: { type: 'number' },
- assets_provenance: { type: 'boolean', description: 'generate_report printed the [assets: .../formats/transilience-report-style] tag' },
- zip_ok: { type: 'boolean' }, deliverable_zip: { type: 'string' }, zip_entries: { type: 'number' },
- protect_ok: { type: 'boolean', description: 'an AES-256 password-protected deliverable was produced' },
- protected_zip: { type: ['string', 'null'] }, protected_pdf: { type: ['string', 'null'] },
- deliverable_password: { type: ['string', 'null'], description: 'the AES-256 passphrase (relay OUT-OF-BAND; also in <dir>/DELIVERABLE-PASSWORD.txt, excluded from the zip)' },
- protection_algos: { type: ['string', 'null'] }, protection_limitations: { type: 'array', items: { type: 'string' } },
- summary_path: { type: 'string' }, elapsed: { type: 'string' }, generator_stdout: { type: 'string' },
- tools_used_count: { type: 'number' }, source_ips_count: { type: 'number' }, reconciliation_gaps: { type: 'array', items: { type: 'string' } },
- coverage_complete: { type: 'boolean', description: 'the deterministic coverage gate reported reports/coverage-matrix.json "complete":true' },
- coverage_ratio: { type: ['number', 'null'] }, coverage_untested: { type: 'number', description: 'count of missing_cells from the gate' },
- // CERT-In Audit Metadata export (additional, non-blocking deliverable; only present when certin_export:true).
- certin_ok: { type: 'boolean', description: 'the CERT-In metadata build exited 0' },
- certin_json: { type: ['string', 'null'] }, certin_xlsx: { type: ['string', 'null'] },
- certin_needs_manual: { type: 'array', items: { type: 'string' }, description: 'CERT-In fields still needing a manual value' },
- },
- }
- async function finalizeEngagement(opts) {
- const { engagementDir, engagement, reportFormat, customReportCmd, engagementStatus, agentCount, conclusion } = opts
- const fmt = reportFormat === 'custom' ? 'custom' : 'transilience'
- // CERT-In Audit Metadata: an ADDITIONAL, NON-BLOCKING deliverable produced alongside the
- // report when the engagement declared certin_export:true. It never enters finalizeGate.
- const wantCertin = opts.certinExport === true
- const certinCfgJson = (wantCertin && opts.certin && typeof opts.certin === 'object') ? JSON.stringify(opts.certin) : null
- const certinInstr = wantCertin
- ? `\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`
- : ''
- const wantProtect = opts.protect !== false // default ON: also emit an AES-256 password-protected copy
- const engBlockJson = JSON.stringify(engagement, null, 2)
- const conclJson = conclusion ? JSON.stringify(conclusion, null, 2) : null
- const reportId = engagement.report_id || 'engagement'
- const zipName = `${reportId}_deliverable.zip`
- const pdfRel = fmt === 'custom' ? 'reports/report.md' : 'reports/Penetration-Test-Report.pdf'
- // Step 6: a deterministic AES-256 protected copy (qpdf/pypdf for the PDF, 7z for the zip),
- // ALONGSIDE the plaintext PDF+zip. AES-256 or nothing (no weak ZipCrypto). The password is
- // auto-generated, printed for OUT-OF-BAND relay, and written to a root file EXCLUDED from the zip.
- const protectInstr = wantProtect
- ? `\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
- : '\n6. (protection disabled) set protect_ok=false, protected_zip=null, protected_pdf=null, deliverable_password=null, protection_limitations=["protection disabled by caller"].\n'
- const genCmd = `python3 skills/transilience-report-style/reference/generate_report.py ${engagementDir}/reports/report_data.json -o ${engagementDir}/reports/Penetration-Test-Report.pdf`
- const renderInstr = fmt === 'custom' && customReportCmd
- ? `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.`
- : fmt === 'custom'
- ? `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.`
- : `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.`
- const runner = await agent(
- `ROLE: FINALIZE RUNNER (deterministic; run the given commands, report facts — do NOT compose or judge report content). cwd is repo root.\n` +
- `ENGAGEMENT_DIR: ${engagementDir}\nFORMAT: ${fmt}\n\n` +
- `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` +
- `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` +
- `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` +
- `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` +
- `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` +
- certinInstr +
- `3. Render. ${renderInstr}\n\n` +
- `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` +
- `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` +
- `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` +
- protectInstr +
- `\nReturn FINALIZE_SCHEMA with the real facts.`,
- { schema: FINALIZE_SCHEMA, agentType: 'general-purpose', label: 'finalize', phase: 'Report' }
- ).catch((err) => ({ report_data_ok: false, findings: 0, render_ok: false, _error: String(err) }))
- // JS HARD GATES on the runner's reported facts — including the deterministic
- // attack-class coverage gate (fails closed: a missing/false coverage_complete blocks).
- const r = runner || {}
- const renderGateOk = fmt === 'custom' ? !!r.render_ok : (r.render_ok && Number(r.pdf_bytes) > 0 && r.assets_provenance)
- const renderBlockedReason = !r.render_ok ? 'render failed' : Number(r.pdf_bytes) > 0 ? 'missing branded-assets provenance' : 'PDF is empty'
- const coverageUntested = Number(r.coverage_untested) || 0
- 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 })
- return {
- ok: gate.ok,
- status: gate.status,
- blocked_reason: gate.blocked_reason,
- format: fmt,
- report_data_path: r.report_data_path || `${engagementDir}/reports/report_data.json`,
- report_path: r.report_path || `${engagementDir}/reports/Penetration-Test-Report.pdf`,
- findings: Number(r.findings) || 0, demoted: Number(r.demoted) || 0, severity_counts: r.severity_counts || {},
- pdf_bytes: Number(r.pdf_bytes) || 0,
- coverage_complete: r.coverage_complete === true, coverage_ratio: r.coverage_ratio != null ? r.coverage_ratio : null, coverage_untested: coverageUntested,
- deliverable_zip: r.zip_ok ? (r.deliverable_zip || `${engagementDir}/${zipName}`) : null,
- protected_zip: wantProtect ? (r.protected_zip || null) : null,
- protected_pdf: wantProtect ? (r.protected_pdf || null) : null,
- deliverable_password: wantProtect ? (r.deliverable_password || null) : null,
- password_file: wantProtect && (r.protected_zip || r.protected_pdf) ? `${engagementDir}/DELIVERABLE-PASSWORD.txt` : null,
- protection_algos: wantProtect ? (r.protection_algos || null) : null,
- protection_limitations: r.protection_limitations || [],
- // CERT-In export facts (additional, non-blocking — never part of gate.ok/status/slack_offer).
- certin_ok: wantCertin ? (r.certin_ok === true) : false,
- certin_json: wantCertin ? (r.certin_json || null) : null,
- certin_xlsx: wantCertin ? (r.certin_xlsx || null) : null,
- certin_needs_manual: wantCertin ? (r.certin_needs_manual || []) : [],
- 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 },
- // Slack stays gated on a clean gate, deliberately: a completion ping must signal
- // a finished engagement, not a status update for a stalled one.
- slack_offer: gate.ok,
- // The blocked state was previously invisible in the RESULT too — a non-OK gate
- // returned no reason and no next step, so a stalled cycle looked like a quiet
- // one. These make it legible to the operator without turning it into a ping.
- status_signal: gate.ok ? 'GREEN' : (r.report_data_ok ? 'AMBER' : 'RED'),
- blocked_reason: gate.ok ? null : (gate.blocked_reason || engagementStatus),
- // What is still owed, so a blocked cycle names its own unblock instead of
- // leaving the operator to diff the coverage matrix by hand.
- outstanding_prerequisites: Array.isArray(r.client_input_requests) && r.client_input_requests.length
- ? r.client_input_requests
- : (coverageUntested > 0 ? [`${coverageUntested} attack-class cell(s) untested — see reports/coverage-matrix.json`] : []),
- }
- }
- // ---- structured-output schemas --------------------------------------------
- const SETUP_SCHEMA = {
- type: 'object', additionalProperties: true,
- required: ['ok', 'date_tag', 'engagement_dir'],
- properties: {
- ok: { type: 'boolean' },
- date_tag: { type: 'string', description: 'YYMMDD from `date +%y%m%d`' },
- engagement_name: { type: 'string' },
- engagement_dir: { type: 'string', description: 'projects/pentest/<date>_<engagement>/' },
- blocked_global: { type: ['string', 'null'], description: 'non-null ONLY for a true global block (never merely a missing credential — unauth surface is still tested)' },
- apex_domains: { type: 'array', items: { type: 'string' } },
- assets: {
- type: 'array',
- items: {
- type: 'object', additionalProperties: true,
- properties: {
- identifier: { type: 'string' }, type: { type: 'string' }, base_url: { type: 'string' },
- business_tier: { type: 'string' }, notes: { type: 'string' },
- },
- },
- },
- roe: {
- type: 'object', additionalProperties: true,
- properties: { reversible_writes: { type: 'boolean' }, prohibitions: { type: 'array', items: { type: 'string' } } },
- },
- creds: { type: 'object', additionalProperties: true, properties: { present: { type: 'array', items: { type: 'string' } }, slack: { type: 'boolean' } } },
- business_tier_default: { type: 'string' },
- cpu_cores: { type: ['number', 'null'], description: 'logical CPU cores on the runner (getconf _NPROCESSORS_ONLN / sysctl hw.ncpu / nproc)' },
- 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" },
- mobile_platform: { type: ['string', 'null'], description: 'MOBILE only: android | ios | both' },
- mobile_artifacts: {
- type: 'array', description: 'MOBILE only: one row per app artifact in scope (located, not yet acquired)',
- items: {
- type: 'object', additionalProperties: true,
- properties: {
- platform: { type: 'string', description: 'android | ios' },
- kind: { type: 'string', description: 'apk | aab | xapk | apks | ipa | store | unavailable' },
- path: { type: ['string', 'null'], description: 'on-disk path EXACTLY as given; null when only a store id is known' },
- store_id: { type: ['string', 'null'] },
- package_id: { type: ['string', 'null'], description: 'reverse-DNS package (Android) / bundle id (iOS)' },
- version_name: { type: ['string', 'null'] },
- notes: { type: 'string' },
- },
- },
- },
- mobile_test_accounts: {
- type: 'array', description: 'MOBILE only: in-app logins the scope supplies — env-var NAMES only, never values',
- 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' } } },
- },
- 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)' },
- network_targets: { type: 'array', items: { type: 'string' }, description: 'NETWORK only: IP / CIDR / range tokens to scan, EXACTLY as given (NOT expanded to individual IPs)' },
- host_estimate: { type: ['number', 'null'], description: 'NETWORK only: approximate total host count across network_targets (a /24 ~= 254)' },
- primary_ip: { type: ['string', 'null'], description: "the primary runner's egress IP (registered as the primary-runner vantage)" },
- 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' },
- notes: { type: 'array', items: { type: 'string' } },
- resumed: { type: 'boolean', description: 'true iff resume_dir was given and reused (continuing a prior engagement)' },
- resume_round: { type: ['number', 'null'], description: 'the prior engagement-meta.json resume_round (0 if fresh)' },
- },
- }
- const EXPAND_SCHEMA = {
- type: 'object', additionalProperties: true,
- required: ['ok', 'work_list'],
- properties: {
- ok: { type: 'boolean' },
- expanded_hosts: {
- type: 'array',
- 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' } } },
- },
- work_list: {
- type: 'array',
- items: {
- type: 'object', additionalProperties: true,
- required: ['tag', 'identifier', 'output_dir'],
- properties: {
- tag: { type: 'string' }, identifier: { type: 'string' }, type: { type: 'string' }, base_url: { type: 'string' },
- business_tier: { type: 'string' }, output_dir: { type: 'string' },
- coverage_matrix: { type: 'array', items: { type: 'object', additionalProperties: true } },
- skills_hint: { type: 'string' },
- },
- },
- },
- infra_probes: {
- type: 'array', description: 'scope-adjacent infra/admin consoles — LIGHT unauthenticated fingerprint only, NOT a full coverage loop',
- items: { type: 'object', additionalProperties: true, properties: { host: { type: 'string' }, base_url: { type: 'string' }, why: { type: 'string' } } },
- },
- excluded: {
- type: 'array', description: 'hosts deliberately NOT assessed (out-of-scope prod/env, CDN bundle hosts, non-host components) with a reason',
- items: { type: 'object', additionalProperties: true, properties: { host: { type: 'string' }, reason: { type: 'string' } } },
- },
- tool_limitations: { type: 'array', items: { type: 'string' }, description: 'tool-classes unavailable at runtime (recorded, never silently skipped)' },
- notes: { type: 'array', items: { type: 'string' } },
- },
- }
- const CORRELATE_SCHEMA = {
- type: 'object', additionalProperties: true,
- required: ['ok'],
- properties: {
- ok: { type: 'boolean' },
- attack_paths_path: { type: 'string' }, ranked_path: { type: 'string' },
- path_count: { type: 'number' }, notes: { type: 'array', items: { type: 'string' } },
- },
- }
- // (Report is now the deterministic finalizeEngagement lane — no agent REPORT_SCHEMA.)
- // ---- normalize inputs ------------------------------------------------------
- // args may arrive as an object, a JSON string (named-workflow invocations can
- // serialize it), or a bare scope-file path. Handle all three so flags like dryRun
- // are never silently lost.
- let __raw = args
- if (typeof __raw === 'string') {
- const s = __raw.trim()
- if (s.startsWith('{') || s.startsWith('[')) { try { __raw = JSON.parse(s) } catch (e) { __raw = { scope_file: __raw } } }
- else { __raw = { scope_file: __raw } }
- }
- const input = (__raw && typeof __raw === 'object' && !Array.isArray(__raw)) ? __raw : { scope_file: __raw }
- const explicitCap = Number(input.maxConcurrent) > 0 ? Math.floor(Number(input.maxConcurrent)) : 0
- let cap = explicitCap > 0 ? explicitCap : 3 // provisional; finalized from CPU cores after Setup (machine-prudent)
- const dryRun = !!input.dryRun
- const wantReport = input.report !== false
- // Convergence knobs (coverage mode). dry_tail = empty batches past 100% coverage
- // before an asset is done ("all techniques plus more"). deep_asset_slice = agents
- // per fully-converged asset; resumeSchedule fits ~floor((1000-overhead)/slice)
- // assets per run and defers the rest to a resume run (input.resume_dir).
- const dryTail = Number(input.dry_tail) > 0 ? Math.floor(Number(input.dry_tail)) : 2
- const deepAssetSlice = Number(input.deep_asset_slice) > 0 ? Math.floor(Number(input.deep_asset_slice)) : 200
- const RESUME_OVERHEAD = 40
- // Churn guard: cap how many resume rounds a self-driven /loop will keep re-attempting
- // remaining/stuck assets before it stops emitting a rerun hint (surfaces them for a human).
- const maxResumeRounds = Number(input.max_resume_rounds) > 0 ? Math.floor(Number(input.max_resume_rounds)) : 3
- // Network-mode tuning (used only when Setup classifies engagement_kind === 'network').
- // PROFILES: light = bounded 1-1024 + curated less-common; standard (DEFAULT) &
- // full = full-range -p- on every reachable host; full additionally forces UDP.
- const scanProfile = ['light', 'standard', 'full'].includes(String(input.scan_profile)) ? String(input.scan_profile) : 'standard'
- const fullPorts = !!input.full_ports || scanProfile === 'full'
- const fullRange = fullPorts || scanProfile === 'standard' // standard is now full-range too
- const udpScan = !!input.udp || scanProfile === 'full' // full auto-enables UDP
- const explicitSlice = Number(input.slice_size) > 0 ? Math.floor(Number(input.slice_size)) : 0
- // null (default) => deep-dive EVERY app-bearing host (tiered coverage); a positive
- // number caps the count as an explicit budget override; 0 disables deep-dives.
- const deepenTop = (input.deepen_top === 0 || Number(input.deepen_top) > 0) ? Math.floor(Number(input.deepen_top)) : null
- // Source-IP/geo-allowlist auto-probe: on a confirmed allowlist signature, provision
- // a 2nd-geography vantage and re-probe the filtered hosts. Kill-switch: auto_provision:false.
- const autoProvision = input.auto_provision !== false // default true
- const geoVantages = Array.isArray(input.geo_vantages) ? input.geo_vantages.map(String).filter(Boolean)
- : (typeof input.geo_vantages === 'string' ? input.geo_vantages.split(',').map((s) => s.trim()).filter(Boolean) : [])
- const geoProvider = ['gcp', 'aws', 'az'].includes(String(input.geo_provider)) ? String(input.geo_provider) : 'gcp'
- const FULL_RANGE_HOST_CAP = Number(input.full_range_host_cap) > 0 ? Math.floor(Number(input.full_range_host_cap)) : 32
- // Mobile-mode tuning. There is deliberately NO skip_dast / static_only knob: a run
- // that cannot reach a device must produce a MACHINE-VERIFIED obstruction record plus
- // a client-input request, never a flag that dodges the gate.
- const mobilePlatformArg = ['android', 'ios', 'both'].includes(String(input.mobile_platform)) ? String(input.mobile_platform) : null
- const deviceSerial = input.device_serial ? String(input.device_serial) : null
- const emulatorAvd = input.emulator ? String(input.emulator) : null
- const mobileArtifactsArg = (Array.isArray(input.mobile_artifacts) ? input.mobile_artifacts
- : [input.apk, input.ipa, input.app].filter(Boolean).map((p) => ({ path: String(p) }))).filter(Boolean)
- const scopeArg = input.scope_file
- ? JSON.stringify({ scope_file: input.scope_file })
- : 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)) })
- // ============================================================================
- // PHASE: Setup
- // ============================================================================
- phase('Setup')
- 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.
- SCOPE_INPUT: ${scopeArg}
- RESUME_DIR: ${input.resume_dir || '(none)'}
- DRY_RUN: ${dryRun}
- Do:
- 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:
- (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.
- (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.
- (w) else "web".
- 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.
- 1) PARSE SCOPE (web fields). If scope_file is given, READ it; else use the inline scope object. Normalize to:
- - engagement_name (kebab); apex_domains[] (the registrable domains in scope, e.g. example.com — derive from asset hostnames if not explicit);
- - assets[]: each {identifier, type (api|portal|spa|docs|admin|infra), base_url, business_tier, notes}. Include EVERY in-scope host/app named.
- - 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.
- - 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.
- - business_tier_default (from input.business_tier or "unknown").
- 2) DATE TAG: date_tag = $(date +%y%m%d).
- 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).
- 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.
- 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.
- 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.`
- const setup = await agent(setupPrompt, { schema: SETUP_SCHEMA, agentType: 'general-purpose', label: 'setup', phase: 'Setup' })
- if (!setup || !setup.ok || setup.blocked_global) {
- const reason = setup ? (setup.blocked_global || 'setup returned ok:false') : 'no setup result'
- log(`Setup blocked: ${reason}`)
- return { status: 'BLOCKED', reason, setup }
- }
- const engagementDir = (setup.engagement_dir || '').replace(/\/+$/, '')
- const roe = (setup.roe && typeof setup.roe === 'object') ? setup.roe : { reversible_writes: true, prohibitions: [] }
- const tierDefault = setup.business_tier_default || 'unknown'
- // Frozen-operand paths (C1) threaded into every coordinator-loop so its inline
- // validators read the SAME NVD/KEV snapshots (deterministic CVE reconciliation).
- const nvdCacheDir = `${engagementDir}/artifacts/nvd-cache`
- const kevSnapshot = `${nvdCacheDir}/kev-snapshot.json`
- log(`Setup ok. engagement_dir=${engagementDir}; apexes=${JSON.stringify(setup.apex_domains || [])}; assets=${(setup.assets || []).length}; reversible_writes=${roe.reversible_writes}`)
- // ============================================================================
- // Machine-prudent concurrency + engagement-kind routing
- // ============================================================================
- // Finalize the parallel-task cap from the machine's core count UNLESS the caller
- // set maxConcurrent explicitly. Prudent rule: ~half the cores, floored at 2,
- // hard-capped at 8 — we NEVER launch hundreds/thousands of parallel agents. The
- // runtime independently caps concurrency at min(16, cores-2); this is the lower,
- // safer app-level bound (and queued work still completes, just fewer at a time).
- const cores = Number(setup.cpu_cores) > 0 ? Math.floor(Number(setup.cpu_cores)) : 4
- const autoCap = Math.max(2, Math.min(8, Math.floor(cores / 2)))
- cap = explicitCap > 0 ? explicitCap : autoCap
- // Three-way WHITELIST, not a chain of ternaries: anything unknown or absent still
- // falls back to 'web', so a schema/model regression degrades to today's behaviour
- // rather than dropping out of every branch.
- const KIND = ['network', 'mobile'].includes(setup.engagement_kind) ? setup.engagement_kind : 'web'
- log(`Machine: ${cores} core(s) -> parallel-task cap=${cap}${explicitCap ? ' (explicit)' : ' (auto, prudent)'}; engagement_kind=${KIND}.`)
- // ============================================================================
- // Input-ingest (req 11) + Metadata-intake (req 10)
- // Capture every attached/referenced input into <dir>/input/ (idempotent by
- // sha256), then, if a prior report was given, extract its engagement metadata
- // from the STORED copy. resolveEngagementMeta later reconciles prompt>prior.
- // ============================================================================
- const INTAKE_SCHEMA = {
- type: 'object', additionalProperties: true,
- properties: {
- input_manifest: {
- type: 'array',
- items: { type: 'object', additionalProperties: true, properties: { original: { type: 'string' }, stored: { type: 'string' }, bytes: { type: 'number' }, sha256: { type: 'string' }, already_present: { type: 'boolean' } } },
- },
- prior_meta: {
- type: ['object', 'null'], additionalProperties: true,
- properties: {
- title: { type: ['string', 'null'] }, title_lines: { type: 'array', items: { type: 'string' } },
- subtitle: { type: ['string', 'null'] }, sector: { type: ['string', 'null'] }, target: { type: ['string', 'null'] },
- scope: { type: 'array', items: { type: 'string' } }, classification: { type: ['string', 'null'] },
- method: { type: ['string', 'null'] }, prepared_by: { type: ['string', 'null'] },
- report_id: { type: ['string', 'null'] }, version: { type: ['string', 'null'] },
- },
- },
- },
- }
- const priorReportPath = input.prior_report || null
- // Mobile artifacts ride the EXISTING intake path, which already sha256s every file
- // and copies it into <dir>/input/ — that satisfies the methodology's hash-before-touch
- // requirement for free rather than growing a second copy path.
- const extraInputs = [input.scope_file, ...(Array.isArray(input.input_files) ? input.input_files : []),
- ...((setup.mobile_artifacts || []).map((m) => m && m.path).filter(Boolean))].filter(Boolean)
- let intakeManifest = []
- if (priorReportPath || extraInputs.length) {
- const intake = await agent(
- `ROLE: INPUT-INGEST + METADATA-INTAKE (deterministic file ops + extraction only). cwd is repo root.\n` +
- `ENGAGEMENT_DIR: ${engagementDir}\nPRIOR_REPORT: ${priorReportPath || '(none)'}\nOTHER_INPUTS: ${JSON.stringify(extraInputs)}\n\n` +
- `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` +
- (priorReportPath
- ? `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`
- : `2. No prior report — return prior_meta: null.\n`) +
- `Return INTAKE_SCHEMA. Do NOT judge or assess anything.`,
- { schema: INTAKE_SCHEMA, agentType: 'general-purpose', label: 'input-intake', phase: 'Setup' }
- ).catch(() => null)
- if (intake) {
- const mani = intake.input_manifest || []
- intakeManifest = mani
- log(`Input-ingest: ${mani.length} file(s) -> input/ (${mani.filter(m => m.already_present).length} already present).`)
- if (intake.prior_meta) input.prior = { ...(input.prior || {}), ...intake.prior_meta }
- }
- }
- if (KIND === 'network') {
- // ==========================================================================
- // NETWORK MODE — tool-first, bounded, UNIFORM per-host scan of an IP/CIDR set.
- // Scan : slice targets into machine-prudent batches; ONE nmap worker per
- // slice runs the SAME pipeline over its slice, so agent count scales
- // with SLICES (~dozens), never with IP count. Per-IP output tree.
- // Deepen : bounded coordinator-loop deep-dives on ONLY the top-value hosts.
- // This block is fully self-contained and returns; WEB mode falls through to
- // the existing Expand/Assess/Correlate/Report code below.
- // ==========================================================================
- // Curated "less-common" service ports appended to the well-known 1-1024 range.
- // This is the LIGHT profile's bounded set (1-1024 + these) for large/fast
- // sweeps; standard/full run full-range -p- on every reachable host instead.
- 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'
- const SCAN_SLICE_SCHEMA = {
- type: 'object', additionalProperties: true, required: ['slice', 'live', 'dead_count'],
- properties: {
- slice: { type: 'number' },
- scanned_tokens: { type: 'array', items: { type: 'string' } },
- live: {
- type: 'array',
- items: {
- type: 'object', additionalProperties: true, required: ['ip'],
- properties: {
- ip: { type: 'string' }, open_ports: { type: 'array', items: { type: 'number' } },
- top_services: { type: 'array', items: { type: 'string' } },
- cve_count: { type: 'number' }, max_cvss: { type: 'number' }, interesting: { type: 'boolean' },
- cves: { type: 'array', description: 'per-CVE {id,cvss,severity,service} — feeds the network cve_register in-memory (M-7)', items: { type: 'object', additionalProperties: true } },
- },
- },
- },
- dead_count: { type: 'number' },
- filtered: {
- type: 'array',
- 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.',
- items: {
- type: 'object', additionalProperties: true, required: ['ip'],
- properties: {
- ip: { type: 'string' },
- 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' },
- },
- },
- },
- tool_limitations: { type: 'array', items: { type: 'string' } },
- },
- }
- phase('Scan')
- const netTargets = (setup.network_targets || []).filter(Boolean)
- if (!netTargets.length) {
- return { status: 'BLOCKED', reason: 'network engagement but Setup resolved no IP/CIDR targets', engagement_dir: engagementDir, setup }
- }
- const hostEstimate = Number(setup.host_estimate) > 0 ? Math.floor(Number(setup.host_estimate)) : netTargets.length
- const avgPerToken = netTargets.length ? hostEstimate / netTargets.length : 1
- // Keep each slice ~<= 64 hosts: many individual IPs -> 64 tokens/slice; CIDR-heavy -> 2 tokens/slice.
- const perSlice = explicitSlice > 0 ? explicitSlice : (avgPerToken > 8 ? 2 : 64)
- const portSpec = fullRange ? '-p-' : `-p 1-1024,${LESS_COMMON_PORTS}` // standard/full = -p-; light = bounded
- const indexedSlices = chunk(netTargets, perSlice).map((slice, idx) => ({ slice, idx }))
- log(`Network scan: ${netTargets.length} token(s) (~${hostEstimate} host(s)) -> ${indexedSlices.length} slice(s) of <=${perSlice} token(s); profile=${scanProfile}; udp=${udpScan}; concurrency=${cap}.`)
- // Port+service scan instruction — profile-conditional. FULL-RANGE (standard/full)
- // uses a host-count-guarded TWO-STAGE (SYN -p- then -sV on found-open ports) so a
- // per-port --host-timeout can never truncate high ports; LIGHT stays bounded.
- const nseTls = '--script ssl-cert,ssl-enum-ciphers' // fingerprints TLS on ANY port (catches non-443 listeners)
- const portScanInstr = fullRange
- ? `2. PORT+SERVICE SCAN — FULL-RANGE (-p-), host-count-guarded two-stage (live hosts only):\n` +
- ` 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` +
- ` 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` +
- ` 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`
- : `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`
- const sliceResults = []
- for (const grp of chunk(indexedSlices, cap)) {
- const r = await parallel(grp.map(({ slice, idx }) => () =>
- agent(
- `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` +
- `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` +
- `Reachability is UNKNOWN — discover first, then scan only what is alive:\n` +
- `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` +
- portScanInstr +
- `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` +
- `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` +
- `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` +
- `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` +
- `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.`,
- { schema: SCAN_SLICE_SCHEMA, label: `scan:slice-${idx}`, phase: 'Scan', agentType: 'general-purpose' }
- )
- ))
- sliceResults.push(...r.filter(Boolean))
- }
- let allLive = sliceResults.flatMap(s => (s.live || []))
- const deadCount = sliceResults.reduce((a, s) => a + (Number(s.dead_count) || 0), 0)
- const scanLimitations = [...new Set(sliceResults.flatMap(s => s.tool_limitations || []))]
- const scanComplete = sliceResults.length === indexedSlices.length
- log(`Scan complete: ${allLive.length} live / ~${deadCount} dead across ${sliceResults.length}/${indexedSlices.length} slice(s). Tool limits: ${JSON.stringify(scanLimitations)}`)
- // --- 2nd-geography escalation machinery ----------------------------------
- const GEO_ESC_SCHEMA = {
- type: 'object', additionalProperties: true, required: ['zone'],
- properties: {
- zone: { type: 'string' }, egress_ip: { type: 'string' },
- newly_reachable: {
- type: 'array',
- items: {
- type: 'object', additionalProperties: true, required: ['ip'],
- properties: {
- ip: { type: 'string' }, open_ports: { type: 'array', items: { type: 'number' } },
- top_services: { type: 'array', items: { type: 'string' } }, max_cvss: { type: 'number' },
- cves: { type: 'array', items: { type: 'object', additionalProperties: true } }, interesting: { type: 'boolean' },
- },
- },
- },
- error: { type: ['string', 'null'] },
- },
- }
- const engId = (engagementDir.split('/').pop() || 'eng').toLowerCase().replace(/[^a-z0-9-]/g, '-').slice(0, 40)
- async function runGeoEscalation({ geos, filteredHosts }) {
- const ips = filteredHosts.map(h => h.ip).join(' ')
- return (await parallel(geos.map(zone => () =>
- agent(
- `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` +
- `DIR="${engagementDir}"; handle=""\n` +
- `trap '[ -n "$handle" ] && tools/provision_vantage.sh --teardown "$handle" --engagement "$DIR" >/dev/null 2>&1 || true' EXIT\n` +
- `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` +
- `1. \`tools/provision_vantage.sh --reap --engagement "$DIR"\` — GC any orphan VM from a prior crash for this engagement.\n` +
- `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` +
- `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` +
- `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` +
- `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` +
- `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.`,
- { schema: GEO_ESC_SCHEMA, label: `geo-probe:${zone}`, phase: 'GeoProbe', agentType: 'general-purpose' }
- ).then(r => r || { zone, error: 'no result' }).catch(err => ({ zone, error: String(err) }))
- ))).filter(Boolean)
- }
- // --- Source-IP/geo-allowlist detection + 2nd-geography auto-probe ---------
- // A host that is existence-confirmed-but-dark from the primary vantage may be
- // reachable only from another geography (a source-IP/geo allowlist). Detect the
- // signature, and (unless dry-run / kill-switched) provision <=2 ephemeral 2nd-geo
- // VMs, re-probe ONLY the filtered hosts, and MERGE newly-reachable hosts into the
- // in-memory allLive BEFORE ranking (so they reach the deep-dive, not just disk).
- const { signature: allowlistDetected, filteredHosts } = detectAllowlist(sliceResults)
- const primaryGeo = setup.primary_geo || null
- const geosTried = [primaryGeo || 'primary-vantage']
- let escalationPlan = null
- if (allowlistDetected) {
- const geos = resolveGeoZones({ geoVantages, primaryGeo })
- escalationPlan = { detected: true, filtered: filteredHosts.map(h => h.ip), geos, auto_provision: autoProvision, reached: [] }
- const willProvision = autoProvision && !dryRun && geos.length > 0
- 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)'}.`)
- if (willProvision) {
- phase('GeoProbe')
- const geoResults = await runGeoEscalation({ geos, filteredHosts })
- for (const z of geoResults) geosTried.push((z && z.zone) || 'unknown-zone')
- for (const gr of geoResults) for (const h of ((gr && gr.newly_reachable) || [])) {
- if (!h || !h.ip) continue
- const ex = allLive.find(x => x.ip === h.ip)
- if (ex) { ex.open_ports = [...new Set([...(ex.open_ports || []), ...(h.open_ports || [])])]; ex.interesting = true }
- else allLive.push({ ...h, interesting: h.interesting !== false })
- }
- escalationPlan.reached = geoResults.flatMap(z => ((z && z.newly_reachable) || []).map(h => h.ip))
- log(`Geo-probe reached ${escalationPlan.reached.length} previously-dark host(s): ${JSON.stringify(escalationPlan.reached)}.`)
- }
- }
- const liveCount = allLive.length
- // Filtered hosts STILL dark after any escalation -> no_surface_from (honest coverage caveat, never a bare 'dead').
- const reachedIps = new Set((escalationPlan && escalationPlan.reached) || [])
- const noSurfaceFrom = filteredHosts.filter(h => !reachedIps.has(h.ip)).map(h => ({ ip: h.ip, no_surface_from: geosTried.slice(), detected_via: h.signal }))
- // Inventory synthesis (single agent; reads per-host JSON + records no_surface_from).
- await agent(
- `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".`,
- { label: 'inventory', phase: 'Scan', agentType: 'general-purpose' }
- ).catch(() => null)
- // Tiered depth (no arbitrary top-N): every host that exposes an enumerable app/
- // endpoint surface (an HTTP service) gets its OWN coverage-mode coordinator-loop
- // for the unit-scope attack classes; every bare-service host is covered for the
- // host/asset-scope classes by the deterministic network_coverage_map tail at report
- // time. Agents therefore scale with app-bearing host count, not raw IP count.
- const APP_PORTS = new Set([80, 443, 8080, 8443, 8000, 8888, 8081, 8008, 3000, 5000, 9000, 9200])
- const isAppBearing = (h) => (h.open_ports || []).some(p => APP_PORTS.has(Number(p))) ||
- /\b(http|https|nginx|apache|httpd|iis|tomcat|caddy|express|node)\b/i.test((h.top_services || []).join(' '))
- const ranked = allLive.filter(h => h && isAppBearing(h)).sort((a, b) => (Number(b.max_cvss) || 0) - (Number(a.max_cvss) || 0))
- const deepenHosts = deepenTop === 0 ? [] : (deepenTop > 0 ? ranked.slice(0, deepenTop) : ranked)
- 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.`)
- if (dryRun) {
- log('dryRun complete — returning scan inventory + deep-dive plan without deepening')
- 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 }
- }
- // App-bearing deep-dives run to CONVERGENCE (coverage + dry_tail), agent-slice
- // backstopped, with honest cross-run resume: fully converge as many hosts as fit
- // their slice this run; hosts already 100% on disk are skipped; the rest defer.
- let results = []
- let netDeferredHosts = []
- let netResumeCompleted = []
- if (deepenHosts.length) {
- phase('Assess')
- 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' } } } } } }
- const netScan = await agent(
- `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.`,
- { schema: NET_RESUME_SCAN_SCHEMA, agentType: 'general-purpose', label: 'resume-scan-net', phase: 'Assess' }
- ).catch(() => null)
- const netRows = (netScan && Array.isArray(netScan.hosts)) ? netScan.hosts : []
- const netCompleteIps = new Set(netRows.filter(r => r && r.complete === true && Number(r.applicable) > 0).map(r => r.ip))
- 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 } })
- const netIncomplete = deepenHosts.filter(h => !netCompleteIps.has(h.ip)).sort((x, y) => (Number(y.max_cvss) || 0) - (Number(x.max_cvss) || 0))
- // Network overhead folds in the pre-deep-dive sweep spend (one agent per slice + inventory + geo/correlate).
- const netSweepReserve = indexedSlices.length + 4
- const netOverhead = RESUME_OVERHEAD + netSweepReserve
- const { assetsThisRun: hostsThisRunN } = resumeSchedule({ incompleteCount: netIncomplete.length, agentCap: 1000, deepSlice: deepAssetSlice, overhead: netOverhead })
- const runHosts = netIncomplete.slice(0, hostsThisRunN)
- netDeferredHosts = netIncomplete.slice(hostsThisRunN)
- const NH = runHosts.length
- results.push(...netResumeCompleted)
- 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.`)
- for (const grp of chunk(runHosts, cap)) {
- // Single-stage: the deep-dive loop validates each finding INLINE (strict
- // per-finding, drop-entirely) — no separate Stage-2 validate pass.
- const gr = await parallel(grp.map(h => () =>
- workflow('coordinator-loop', {
- target: h.ip,
- output_dir: `${engagementDir}/hosts/${h.ip}`,
- 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 || [])}.`,
- scope: `network host deep-dive (coverage mode); open_ports=${JSON.stringify(h.open_ports || [])}`,
- skills_hint: 'infrastructure,system',
- platform: 'network',
- mode: 'coverage', // tiered: app-bearing hosts driven to attack-class coverage
- severity_rubric: 'root-cause',
- roe,
- output_base: 'projects/pentest',
- report_format: 'transilience',
- inline_validate: true, // strict per-finding validation inside the loop
- business_tier: tierDefault,
- assets: NH, // governor: partition the agent cap across the per-run deep-dive hosts
- dry_tail: dryTail, // convergence: full coverage + K empty batches
- agent_reserve: netOverhead, // folds in the pre-deep-dive sweep spend so perAsset*NH+reserve<=1000
- nvd_cache_dir: nvdCacheDir,
- kev_snapshot: kevSnapshot,
- validation_cache_dir: `${engagementDir}/artifacts/validation-cache`,
- replay_cache: !!setup.resumed, // E4: restore verdicts only on a resume run
- }).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 }))
- .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) }))
- ))
- results.push(...gr.filter(Boolean))
- }
- }
- // Correlate across deepened-host validated findings (reuse stitcher + prioritiser).
- phase('Correlate')
- const netAssetDirs = results.map(r => r.output_dir).filter(Boolean)
- const correlateNet = await agent(
- `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` +
- `ENGAGEMENT_DIR: ${engagementDir}\nHOST_DIRS: ${JSON.stringify(netAssetDirs)}\n\n` +
- `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.`,
- { schema: CORRELATE_SCHEMA, agentType: 'general-purpose', label: 'correlate', phase: 'Correlate' }
- ).catch(err => ({ ok: false, notes: ['correlate error: ' + String(err)] }))
- // Report — deterministic finalize (assembler -> PDF -> package); COMPLETE requires
- // BOTH scan completion AND deterministic 100% attack-class coverage (the gate runs
- // inside finalize over the swept + deep-dived hosts). Provisional until the gate returns.
- phase('Report')
- const netProvisionalStatus = scanComplete ? 'COMPLETE' : 'INCOMPLETE_scan'
- const netMeta = resolveEngagementMeta({ prior: input.prior || null, prompt: input.engagement || {}, currentScope: netTargets, dateTag: setup.date_tag, explicitVersion: input.version })
- const netEngagementBlock = {
- title_lines: netMeta.title_lines || [netMeta.title || setup.engagement_name || 'Network Vulnerability Assessment'],
- title: netMeta.title || setup.engagement_name || 'Network Vulnerability Assessment',
- subtitle: netMeta.subtitle || (netMeta.supersedes ? `Retest — supersedes ${netMeta.supersedes}` : `${liveCount} live host(s) of ~${hostEstimate}`),
- date: setup.date_tag, footer: netMeta.sector || 'Security Assessment',
- cover_meta: [
- ['REPORT DATE', setup.date_tag],
- ['DURATION', netMeta.duration],
- ['CLASSIFICATION', netMeta.classification || 'Confidential'],
- ['SECTOR', netMeta.sector],
- ['TARGET', netMeta.target || netTargets[0] || null],
- ['METHOD', netMeta.method || 'Network scan + deep-dive'],
- ['PREPARED BY', netMeta.prepared_by || 'Transilience'],
- ['REPORT ID', netMeta.report_id],
- ['VERSION', netMeta.version],
- ...(netMeta.supersedes ? [['SUPERSEDES', netMeta.supersedes]] : []),
- ],
- }
- let reportNet = { ok: false }
- if (wantReport) {
- 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 })
- if (reportNet.status === 'BLOCKED') log(`Report BLOCKED: ${reportNet.blocked_reason}`)
- }
- // COMPLETE requires scan completion AND the deterministic coverage gate (run inside
- // finalize) reporting 100% AND convergence with nothing left to resume. Fails closed.
- const netCoverageComplete = wantReport ? (reportNet.coverage_complete === true) : true
- const { engagement_status: netConvStatus, resume: netResumeBlock } = classifyEngagement(results, netDeferredHosts.map(h => h.ip))
- const netEngagementStatus = !scanComplete
- ? 'INCOMPLETE_scan'
- : ((netCoverageComplete && netConvStatus === 'COMPLETE') ? 'COMPLETE' : (netConvStatus === 'INCOMPLETE_resumable' ? 'INCOMPLETE_resumable' : 'INCOMPLETE_coverage'))
- const netRound = Number(setup.resume_round) || 0
- const netResume = netResumeBlock.remaining_assets.length
- ? { ...netResumeBlock, resume_round: netRound, rerun_hint: (netRound + 1) <= maxResumeRounds ? `resume_dir=${engagementDir}` : null, exhausted_rounds: (netRound + 1) > maxResumeRounds }
- : null
- 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}.` : ''}`)
- return {
- status: 'DONE',
- engagement_kind: 'network',
- engagement_status: netEngagementStatus,
- resume: netResume,
- date_tag: setup.date_tag,
- engagement_dir: engagementDir,
- cpu_cores: cores,
- parallel_cap: cap,
- scan_profile: scanProfile,
- port_spec: portSpec,
- targets: netTargets.length,
- host_estimate: hostEstimate,
- slices: indexedSlices.length,
- live: liveCount,
- dead: deadCount,
- interesting: ranked.length,
- deepened: deepenHosts.map(h => h.ip),
- 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 })),
- attack_paths_ranked: correlateNet && correlateNet.ranked_path ? correlateNet.ranked_path : `${engagementDir}/artifacts/attack-paths-ranked.md`,
- report_format: reportNet && reportNet.format ? reportNet.format : (input.report_format === 'custom' ? 'custom' : 'transilience'),
- report_status: reportNet && reportNet.status ? reportNet.status : (wantReport ? 'BLOCKED' : 'SKIPPED'),
- report_blocked_reason: reportNet && reportNet.blocked_reason ? reportNet.blocked_reason : null,
- report_path: reportNet && reportNet.report_path ? reportNet.report_path : `${engagementDir}/reports/Penetration-Test-Report.pdf`,
- severity_counts: reportNet && reportNet.severity_counts ? reportNet.severity_counts : null,
- deliverable_zip: reportNet && reportNet.deliverable_zip ? reportNet.deliverable_zip : null,
- protected_zip: reportNet && reportNet.protected_zip ? reportNet.protected_zip : null,
- deliverable_password: reportNet && reportNet.deliverable_password ? reportNet.deliverable_password : null,
- password_file: reportNet && reportNet.password_file ? reportNet.password_file : null,
- protection_limitations: reportNet && reportNet.protection_limitations ? reportNet.protection_limitations : [],
- summary: reportNet && reportNet.summary ? reportNet.summary : null,
- slack_offer: !!(reportNet && reportNet.slack_offer && wantReport),
- tool_limitations: scanLimitations,
- }
- }
- if (KIND === 'mobile') {
- // ==========================================================================
- // MOBILE MODE — a MAPT over TWO gated surfaces.
- // Acquire : hash + unpack + decompile the artifact, then emit BOTH surfaces —
- // the app bundle (mobile-surface/v1 -> the 15 MAS-* MASVS classes)
- // AND the backend recovered FROM the bundle (surface/v2 -> the
- // ordinary web/API classes). The second surface is the point: a MAPT
- // that stops at the bundle has tested the smaller half.
- // Expand : only when the scope ALSO names apexes (a hybrid WAPT+MAPT scope).
- // Device : mobile_device_check.py preflight. Only exit 0 is ready; anything
- // else routes to a machine-verified obstruction + client-input
- // request. There is NO flag that skips DAST.
- // Assess : one fan-out over app assets (platform:'mobile') and backend assets
- // (platform:'web'), both in coverage mode.
- // Self-contained and returns; WEB falls through below.
- // ==========================================================================
- phase('Acquire')
- const mobPlatform = mobilePlatformArg || setup.mobile_platform || 'android'
- const artifacts = (setup.mobile_artifacts || []).filter(a => a && (a.path || a.store_id))
- if (!artifacts.length) {
- log('Mobile engagement but the scope named no acquirable artifact')
- return { status: 'BLOCKED', reason: 'mobile engagement but no app artifact or store id is in scope', engagement_kind: 'mobile', engagement_dir: engagementDir, setup }
- }
- // the intake manifest already carries the stored path + sha256 for every artifact
- const storedFor = (p) => {
- const row = (intakeManifest || []).find(m => m && (m.original === p || m.stored === p))
- return row ? { stored: row.stored, sha256: row.sha256 } : { stored: p, sha256: null }
- }
- // scope allow-list for the recovered backends: what the SCOPE named, never what a
- // decompiled string happens to contain
- const mobAllow = [...new Set([...(setup.mobile_backend_hints || []), ...(setup.apex_domains || [])]
- .map(h => String(h || '').replace(/^https?:\/\//, '').split('/')[0].trim()).filter(Boolean))]
- const ACQUIRE_SCHEMA = {
- type: 'object', additionalProperties: true,
- required: ['ok', 'platform', 'app_dir'],
- properties: {
- ok: { type: 'boolean' },
- platform: { type: 'string' }, package_id: { type: ['string', 'null'] }, version_name: { type: ['string', 'null'] },
- artifact_path: { type: ['string', 'null'] }, artifact_sha256: { type: ['string', 'null'] },
- acquired: { type: 'boolean', description: 'a real artifact is on disk AND unpacked (false = store id only / nothing supplied)' },
- framework: { type: 'string', description: 'flutter | rn_hermes | unity_il2cpp | native_android | native_ios | webview | unknown' },
- tag: { type: 'string' }, app_dir: { type: 'string' },
- mobile_surface_path: { type: ['string', 'null'] },
- mobile_units: { type: 'number', description: "VERBATIM from mobile_surface_build.py's JSON summary — never your own count" },
- endpoints_recovered: { type: 'number' },
- 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' } } } },
- skipped_out_of_scope: { type: 'array', items: { type: 'string' } },
- control_wiring_path: { type: ['string', 'null'] }, wiring_gaps: { type: 'array', items: { type: 'string' } },
- tool_limitations: { type: 'array', items: { type: 'string' } },
- blocked_reason: { type: ['string', 'null'] },
- },
- }
- const acquireResults = (await parallel(artifacts.map((a, i) => () => {
- const plat = (a.platform || (String(a.path || '').endsWith('.ipa') ? 'ios' : 'android')).toLowerCase()
- const st = storedFor(a.path)
- const tag = `${(a.package_id || a.store_id || `app-${i + 1}`).replace(/[^A-Za-z0-9]+/g, '-').toLowerCase().replace(/^-+|-+$/g, '')}-${plat}-app`
- const appDir = `${engagementDir}/${tag}`
- return agent(
- `ROLE: MOBILE ACQUIRE + TRIAGE + SAST (deterministic tools own the bytes; you author FACTS only). cwd is repo root.\n` +
- `ARTIFACT: ${st.stored || '(not supplied)'} sha256=${st.sha256 || '(unknown)'} platform=${plat} APP_DIR=${appDir}\n` +
- `STORE_ID: ${a.store_id || '(none)'} PACKAGE: ${a.package_id || '(unknown)'}\n\n` +
- `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` +
- `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` +
- `3. DETERMINISTIC FACTS — run these and do not hand-write their outputs:\n` +
- ` 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` +
- (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`) +
- `4. YOUR FACTS — two files, facts only:\n` +
- ` (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` +
- ` (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` +
- `5. EMIT BOTH SURFACES (tool-owned):\n` +
- ` 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` +
- ` 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` +
- `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.`,
- { schema: ACQUIRE_SCHEMA, agentType: 'general-purpose', label: `acquire:${tag}`, phase: 'Acquire' }
- ).catch(() => null)
- }))).filter(Boolean)
- const mobApps = acquireResults.filter(r => r && r.ok && r.app_dir)
- if (!mobApps.length) {
- log('Acquire produced no usable app bundle')
- return { status: 'BLOCKED', reason: 'no app artifact could be acquired or unpacked', engagement_kind: 'mobile', engagement_dir: engagementDir, setup, acquire: acquireResults }
- }
- const mobLimitations = mobApps.flatMap(r => r.tool_limitations || [])
- // Hybrid WAPT+MAPT: a scope naming apexes as well as an artifact keeps its web
- // half — expand those apexes and merge them into the backend work list.
- let expandedApiAssets = []
- const mobApexes = (setup.apex_domains || []).filter(Boolean)
- if (mobApexes.length) {
- phase('Expand')
- 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' } } } }
- const ex = await agent(
- `ROLE: SURFACE EXPANSION for the WEB half of a hybrid mobile engagement. cwd is repo root.\n` +
- `APEXES: ${JSON.stringify(mobApexes)}\nENGAGEMENT_DIR: ${engagementDir}\n\n` +
- `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.`,
- { schema: EXPAND_MOB_SCHEMA, agentType: 'general-purpose', label: 'expand-mobile-web', phase: 'Expand' }
- ).catch(() => null)
- if (ex && ex.ok && Array.isArray(ex.work_list)) {
- expandedApiAssets = ex.work_list.filter(a => a && a.tag).map(a => ({
- kind: 'api', tag: a.tag, apex: a.apex || '', base_url: a.base_url || a.apex,
- output_dir: String(a.output_dir || `${engagementDir}/${a.tag}`).replace(/\/+$/, ''),
- recovered_from: 'surface-expansion', units: 1, business_tier: tierDefault,
- }))
- log(`Hybrid scope: expansion added ${expandedApiAssets.length} web asset(s) beside the bundle-recovered backends.`)
- }
- }
- // one backend asset per recovered apex, de-duplicated by tag
- const apiByTag = new Map()
- for (const r of mobApps) {
- for (const s of r.api_surfaces || []) {
- if (s && s.tag && !apiByTag.has(s.tag)) {
- 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 })
- }
- }
- }
- for (const a of expandedApiAssets) if (!apiByTag.has(a.tag)) apiByTag.set(a.tag, a)
- const apiAssets = [...apiByTag.values()]
- // THE hard gate, and the direct fix for the failure that motivated this mode.
- // mobApps.length is required because [].every() is vacuously true. A bundle that
- // yields ZERO backend endpoints is a FAILED acquisition, not a small surface.
- const mobSurfaceOk = mobApps.length > 0 && mobApps.every(r => Number(r.mobile_units) > 0)
- && apiAssets.length > 0 && apiAssets.every(a => Number(a.units) > 0)
- const totalEndpoints = mobApps.reduce((n, r) => n + (Number(r.endpoints_recovered) || 0), 0)
- log(`Acquire: ${mobApps.length} app bundle(s), ${totalEndpoints} endpoint(s) recovered -> ${apiAssets.length} backend asset(s); surface_ok=${mobSurfaceOk}.`)
- if (dryRun) {
- 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 }
- }
- // ---- Device preflight: the DAST gate -------------------------------------
- phase('Device')
- const DEVICE_SCHEMA = {
- type: 'object', additionalProperties: true, required: ['platform', 'ready', 'exit_code'],
- properties: {
- platform: { type: 'string' }, ready: { type: 'boolean' }, exit_code: { type: 'number' },
- backend: { type: ['string', 'null'] }, handle: { type: ['string', 'null'] },
- api_level: { type: ['number', 'null'] }, os_version: { type: ['string', 'null'] },
- root: { type: 'boolean' }, frida_ok: { type: 'boolean' }, mitm_ca: { type: 'boolean' },
- blockers: { type: 'array', items: { type: 'string' } },
- blocked_classes: { type: 'array', items: { type: 'string' } },
- limitations: { type: 'array', items: { type: 'string' } },
- verdict_path: { type: ['string', 'null'] },
- },
- }
- const devPlatforms = mobPlatform === 'both' ? ['android', 'ios'] : [mobPlatform]
- const deviceResults = (await parallel(devPlatforms.map(plat => () => agent(
- `ROLE: DEVICE PREFLIGHT RUNNER (deterministic; run the command and report facts). cwd is repo root.\n` +
- `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` +
- `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` +
- ` 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` +
- `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` +
- `Report what is true.`,
- { schema: DEVICE_SCHEMA, agentType: 'general-purpose', label: `device:${plat}`, phase: 'Device' }
- ).catch(() => null)))).filter(Boolean)
- const deviceReady = deviceResults.length > 0 && deviceResults.every(d => d && d.ready === true)
- const deviceHandles = deviceResults.map(d => `${d.platform}:${d.backend || '?'}${d.handle ? `/${d.handle}` : ''}`).join(', ')
- const deviceLimitations = deviceResults.flatMap(d => d.limitations || [])
- let dastDeferral = null
- if (!deviceReady) {
- // NOT a skip. One agent must attempt the documented bypasses, record MACHINE
- // evidence, and file a client-input request. Only then is a deferral offered.
- 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 } } } }
- const appDir = mobApps[0].app_dir
- const obst = await agent(
- `ROLE: DAST OBSTRUCTION RECORDER. cwd is repo root. The device preflight did not return READY:\n` +
- `${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` +
- `A missing device is NEVER a silent skip. Before any cell may be deferred you must:\n` +
- `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` +
- `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` +
- `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` +
- ` 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` +
- `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` +
- `Set obstructed=true ONLY if both files now exist on disk.`,
- { schema: OBSTRUCTION_SCHEMA, agentType: 'general-purpose', label: 'dast-obstruction', phase: 'Device' }
- ).catch(() => null)
- if (obst && obst.obstructed === true && obst.obstruction_path && obst.cir_path) {
- 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 || [] }
- log(`DAST obstructed — substantiated deferral recorded for ${(dastDeferral.blocked_classes || []).length} runtime class(es).`)
- } else {
- log('DAST device not ready AND no substantiated obstruction record — the engagement cannot complete.')
- }
- }
- // ---- Assess: both surfaces, coverage mode --------------------------------
- phase('Assess')
- 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 }))
- const mobWork = [...appAssets, ...apiAssets]
- const mobOverhead = RESUME_OVERHEAD + mobApps.length * 4 + 8
- const NM = mobWork.length
- const mobResults = []
- for (const grp of chunk(mobWork, cap)) {
- const gr = await parallel(grp.map(a => () => (a.kind === 'app'
- ? workflow('coordinator-loop', {
- target: a.package_id || a.tag,
- output_dir: a.output_dir,
- 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 || [])}.`,
- scope: `mobile app bundle: platform=${a.platform}; package=${a.package_id}; framework=${a.framework}; device=${deviceReady ? deviceHandles : 'UNAVAILABLE (substantiated obstruction)'}`,
- skills_hint: 'mobile-security,reverse-engineering,authentication',
- platform: 'mobile',
- mode: 'coverage',
- surface_file: 'recon/inventory/mobile-surface.json',
- severity_rubric: 'root-cause',
- roe,
- output_base: 'projects/pentest',
- report_format: 'transilience',
- inline_validate: true,
- business_tier: a.business_tier,
- assets: NM,
- dry_tail: dryTail,
- agent_reserve: mobOverhead,
- nvd_cache_dir: nvdCacheDir,
- kev_snapshot: kevSnapshot,
- validation_cache_dir: `${engagementDir}/artifacts/validation-cache`,
- replay_cache: !!setup.resumed,
- })
- : workflow('coordinator-loop', {
- target: a.base_url,
- output_dir: a.output_dir,
- 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 || [])}.`,
- scope: `mobile-recovered backend: apex=${a.apex}; recovered_from=${a.recovered_from}; tier=${a.business_tier}`,
- skills_hint: 'api-security,authentication,server-side',
- platform: 'web',
- mode: 'coverage',
- severity_rubric: 'root-cause',
- roe,
- output_base: 'projects/pentest',
- report_format: 'transilience',
- inline_validate: true,
- business_tier: a.business_tier,
- assets: NM,
- dry_tail: dryTail,
- agent_reserve: mobOverhead,
- nvd_cache_dir: nvdCacheDir,
- kev_snapshot: kevSnapshot,
- validation_cache_dir: `${engagementDir}/artifacts/validation-cache`,
- replay_cache: !!setup.resumed,
- })
- ).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) }))
- .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)}` }))))
- mobResults.push(...gr.filter(Boolean))
- }
- phase('Correlate')
- const mobAssetDirs = mobWork.map(a => a.output_dir)
- const mobPaths = await agent(
- `ROLE: ATTACK-PATH STITCHER + RISK PRIORITISER across a mobile engagement. cwd is repo root.\n` +
- `ENGAGEMENT_DIR: ${engagementDir}\nASSET_DIRS: ${JSON.stringify(mobAssetDirs)}\n\n` +
- `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` +
- `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` +
- `Return {ok, paths_ranked}.`,
- { schema: { type: 'object', additionalProperties: true, properties: { ok: { type: 'boolean' }, paths_ranked: { type: 'number' } } }, agentType: 'general-purpose', label: 'correlate-mobile', phase: 'Correlate' }
- ).catch(() => null)
- phase('Report')
- const mobProvisional = !mobSurfaceOk ? 'INCOMPLETE_sast' : (deviceReady || dastDeferral ? 'COMPLETE' : 'INCOMPLETE_dast')
- const mobScope = [...mobApps.map(a => a.package_id || a.tag), ...apiAssets.map(a => a.apex).filter(Boolean)]
- const mobMeta = resolveEngagementMeta({ prior: input.prior || null, prompt: input.engagement || {}, currentScope: mobScope, dateTag: setup.date_tag, explicitVersion: input.version })
- 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 }
- let reportMob = { ok: false }
- if (wantReport) {
- 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 })
- if (reportMob.status === 'BLOCKED') log(`Report BLOCKED: ${reportMob.blocked_reason}`)
- }
- const mobCoverageComplete = wantReport ? (reportMob.coverage_complete === true) : true
- const { engagement_status: mobConvStatus, resume: mobResumeBlock } = classifyEngagement(mobResults, [])
- // Two preconditions, and the order matters: you cannot DAST what you did not
- // acquire. INCOMPLETE_sast is the analogue of network's INCOMPLETE_scan.
- const mobEngagementStatus = !mobSurfaceOk
- ? 'INCOMPLETE_sast'
- : (!(deviceReady || dastDeferral)
- ? 'INCOMPLETE_dast'
- : ((mobCoverageComplete && mobConvStatus === 'COMPLETE') ? 'COMPLETE' : (mobConvStatus === 'INCOMPLETE_resumable' ? 'INCOMPLETE_resumable' : 'INCOMPLETE_coverage')))
- return {
- status: 'DONE',
- engagement_kind: 'mobile',
- engagement_status: mobEngagementStatus,
- resume: mobResumeBlock,
- date_tag: setup.date_tag,
- engagement_dir: engagementDir,
- cpu_cores: cores,
- parallel_cap: cap,
- mobile_platform: mobPlatform,
- 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 || [] })),
- api_assets: apiAssets.map(a => ({ tag: a.tag, apex: a.apex, units: a.units, recovered_from: a.recovered_from })),
- endpoints_recovered: totalEndpoints,
- surface_ok: mobSurfaceOk,
- device: { ready: deviceReady, backends: deviceResults.map(d => ({ platform: d.platform, backend: d.backend, exit_code: d.exit_code, blockers: d.blockers || [] })), limitations: deviceLimitations },
- dast_deferral: dastDeferral,
- skipped_out_of_scope: [...new Set(mobApps.flatMap(r => r.skipped_out_of_scope || []))],
- assets: mobResults,
- attack_paths_ranked: mobPaths && mobPaths.paths_ranked ? mobPaths.paths_ranked : 0,
- report_format: input.report_format || 'transilience',
- report_status: reportMob.status || (wantReport ? 'BLOCKED' : 'SKIPPED'),
- report_blocked_reason: reportMob.blocked_reason || null,
- report_path: reportMob.report_path || null,
- severity_counts: reportMob.severity_counts || null,
- deliverable_zip: reportMob.deliverable_zip || null,
- protected_zip: reportMob.protected_zip || null,
- deliverable_password: reportMob.deliverable_password || null,
- password_file: reportMob.password_file || null,
- protection_limitations: reportMob.protection_limitations || [],
- summary: reportMob.summary || null,
- slack_offer: !!(reportMob.slack_offer && wantReport),
- tool_limitations: [...mobLimitations, ...deviceLimitations],
- }
- }
- // ============================================================================
- // WEB MODE (engagement_kind !== 'network') — existing behavior, unchanged.
- // PHASE: Expand — MANDATORY surface expansion (closes the #1 gap: scope freeze)
- // ============================================================================
- phase('Expand')
- const apexes = (setup.apex_domains || []).filter(Boolean)
- // One expansion agent per apex (bounded by the concurrency cap), then a synthesis
- // agent that merges handoff + discovered hosts into the per-asset work list.
- const apexGroups = chunk(apexes, cap)
- const apexResults = []
- for (const grp of apexGroups) {
- const r = await parallel(grp.map(apex => () =>
- agent(
- `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` +
- `OUTPUT_DIR: ${engagementDir}\n\n` +
- `Do, for apex ${apex}:\n` +
- `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` +
- `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` +
- `3. Probe every discovered host with httpx (or curl -I with a browser UA) for liveness/title/tech.\n` +
- `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.`,
- { label: `expand:${apex}`, phase: 'Expand', agentType: 'general-purpose' }
- )
- ))
- apexResults.push(...r.filter(Boolean))
- }
- const expandDigest = apexResults.map((r, i) => `### apex ${i + 1}\n${r}`).join('\n\n')
- const expand = await agent(
- `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` +
- `OUTPUT_DIR: ${engagementDir}\n` +
- `HANDED-IN ASSETS: ${JSON.stringify(setup.assets || [])}\n` +
- `BUSINESS_TIER_DEFAULT: ${tierDefault}\n` +
- `DISCOVERED (from per-apex expansion):\n${expandDigest || '<none>'}\n\n` +
- `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` +
- ` (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` +
- ` (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` +
- ` (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` +
- `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` +
- `Do:\n` +
- `1. Bucket every host (A/B/C) per the rule above, deduped.\n` +
- `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` +
- `3. For each (B) emit an infra_probes row {host, base_url, why}. For each (C) emit an excluded row {host, reason}.\n` +
- `4. Write ${engagementDir}/recon/inventory/expanded-surface.md (full inventory + A/B/C classification) and work-list.json.\n\n` +
- `Return EXPAND_SCHEMA: work_list[] = ONLY in_scope_app (with coverage_matrix); infra_probes[]; excluded[]; expanded_hosts[]; tool_limitations[].`,
- { schema: EXPAND_SCHEMA, agentType: 'general-purpose', label: 'expand-synth', phase: 'Expand' }
- )
- if (!expand || !expand.ok || !Array.isArray(expand.work_list) || !expand.work_list.length) {
- log('Expand produced no work list')
- return { status: 'BLOCKED', reason: 'surface expansion produced no assessable assets', engagement_dir: engagementDir, expand }
- }
- const workList = expand.work_list.map(a => ({ ...a, output_dir: String(a.output_dir || `${engagementDir}/${a.tag}`).replace(/\/+$/, ''), business_tier: a.business_tier || tierDefault }))
- const infraProbes = Array.isArray(expand.infra_probes) ? expand.infra_probes : []
- const excluded = Array.isArray(expand.excluded) ? expand.excluded : []
- 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 || [])}`)
- if (dryRun) {
- log('dryRun complete — returning work list + classification without assessment')
- 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 || [] }
- }
- // ============================================================================
- // Prompt builders + budgeting for the per-asset pipeline
- // ============================================================================
- // ============================================================================
- // RESUME-SCAN + agent-slice scheduling (WS2 M1). Each in-scope app runs to CONVERGENCE
- // (no cost-style depth budget); the coordinator backstops on an honest per-asset agent
- // slice. Because a run cannot exceed the runtime 1000-agent cap, we fully converge as
- // many INCOMPLETE assets as fit their slice this run and DEFER the rest to a resume run
- // (re-invoke with resume_dir=<engagement_dir>). An asset already at 100% coverage on
- // disk (a prior run) is skipped — the deterministic coverage_gate.py boolean decides.
- // ============================================================================
- phase('Assess')
- const RESUME_SCAN_SCHEMA = {
- type: 'object', additionalProperties: true, required: ['assets'],
- properties: { assets: { type: 'array', items: { type: 'object', additionalProperties: true, properties: { tag: { type: 'string' }, complete: { type: 'boolean' }, applicable: { type: 'number' }, findings_total: { type: 'number' } } } } },
- }
- const resumeScan = await agent(
- `ROLE: RESUME-SCAN (deterministic; run the gate, relay its booleans — NO judgment). cwd is repo root.\n` +
- `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` +
- `ASSETS: ${JSON.stringify(workList.map(a => ({ tag: a.tag, output_dir: a.output_dir })))}\n` +
- `Return RESUME_SCAN_SCHEMA.`,
- { schema: RESUME_SCAN_SCHEMA, agentType: 'general-purpose', label: 'resume-scan', phase: 'Assess' }
- ).catch(() => null)
- const scanRows = (resumeScan && Array.isArray(resumeScan.assets)) ? resumeScan.assets : []
- // resume-COMPLETE iff the gate says complete AND there was real applicable work
- // (guards the fresh-dir "0 cells => vacuously complete" trap).
- const completeTags = new Set(scanRows.filter(r => r && r.complete === true && Number(r.applicable) > 0).map(r => r.tag))
- const resumeCompleted = workList.filter(a => completeTags.has(a.tag)).map(a => {
- const row = scanRows.find(r => r.tag === a.tag) || {}
- 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' }
- })
- // Selection order for the per-run slice: business_tier desc, then work-list order
- // (deterministic across runs). Stuck assets are re-included (retry-each-run).
- const TIER_RANK = { crown_jewel: 0, revenue: 1, support: 2, dev: 3, unknown: 4 }
- const incompleteWork = workList.filter(a => !completeTags.has(a.tag))
- .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)
- const { assetsThisRun, deferred } = resumeSchedule({ incompleteCount: incompleteWork.length, agentCap: 1000, deepSlice: deepAssetSlice, overhead: RESUME_OVERHEAD })
- const runThisRun = incompleteWork.slice(0, assetsThisRun)
- const deferredAssets = incompleteWork.slice(assetsThisRun)
- const N = runThisRun.length
- 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.`)
- function coverageGoalFor(a) {
- 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. ` +
- `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. ` +
- `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 || [])}.`
- }
- function adaptSummary(a, loopOut) {
- const lo = loopOut || {}
- 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: lo.coverage_status || lo.status || 'UNKNOWN',
- coverage_pending: typeof lo.coverage_pending === 'number' ? lo.coverage_pending : null,
- coverage_ratio: typeof lo.coverage_ratio === 'number' ? lo.coverage_ratio : null,
- findings_total: lo.findings_total != null ? lo.findings_total : (Array.isArray(lo.findings_confirmed) ? lo.findings_confirmed.length : 0),
- // Interleaved validation ran INSIDE the loop — carry its verdict counts so the
- // summary never reads a silent null (no separate Stage-2 validate pass).
- validation: lo.verdict_counts ? { status: 'INLINE', ...lo.verdict_counts } : null,
- confirmed: lo.confirmed || 0, dropped: lo.dropped || 0, rejected: lo.rejected || 0,
- narrative: lo.narrative || '', report_path: lo.report_path || `${a.output_dir}/reports/pentest-report-source.md`,
- engagement_status: lo.engagement_status || null,
- }
- }
- // ============================================================================
- // PHASE: Assess — per-asset CONVERGENCE loop with STRICT PER-FINDING interleaved
- // validation INSIDE the loop (inline_validate:true; no separate Stage-2 pass). Each
- // loop runs to convergence (full coverage + dry_tail), agent-slice backstopped;
- // assets:N (the per-run running count) lets the governor partition the 1000-agent cap.
- // ============================================================================
- const results = resumeCompleted.slice() // assets already 100% on disk are carried as done
- for (const grp of chunk(runThisRun, cap)) {
- const grpResults = await parallel(grp.map(a => () =>
- workflow('coordinator-loop', {
- target: a.base_url || a.identifier,
- output_dir: a.output_dir,
- goal: coverageGoalFor(a),
- scope: `pentest asset: type=${a.type}; tier=${a.business_tier}; ${a.notes || ''}`,
- skills_hint: a.skills_hint || a.type || '',
- platform: 'web',
- mode: 'coverage',
- coverage_matrix: a.coverage_matrix || null,
- severity_rubric: 'root-cause',
- roe,
- output_base: 'projects/pentest',
- report_format: 'transilience',
- inline_validate: true, // strict per-finding validation inside the loop
- business_tier: a.business_tier || tierDefault,
- assets: N, // governor: partition the 1000-agent cap across the per-run assets
- dry_tail: dryTail, // convergence: full coverage + K empty batches
- nvd_cache_dir: nvdCacheDir,
- kev_snapshot: kevSnapshot,
- validation_cache_dir: `${engagementDir}/artifacts/validation-cache`,
- replay_cache: !!setup.resumed, // E4: restore verdicts only on a resume run
- }).then(lo => adaptSummary(a, lo))
- .catch(err => ({ tag: a.tag, coverage_status: 'FAILED', output_dir: a.output_dir, blocked_reason: 'coordinator-loop error: ' + String(err) }))
- ))
- results.push(...grpResults.filter(Boolean))
- }
- // ============================================================================
- // PHASE: Infra — light UNAUTHENTICATED fingerprint of scope-adjacent consoles
- // (identity + exposure only; never a full loop or auth/brute probing — the
- // professional norm for scope-adjacent management planes, e.g. Rancher/Retool).
- // ============================================================================
- let infraFindings = []
- if (infraProbes.length) {
- phase('Infra')
- const ir = await parallel(infraProbes.map(p => () =>
- agent(
- `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` +
- `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` +
- `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?`,
- { label: `infra:${p.host}`, phase: 'Infra', agentType: 'general-purpose' }
- )
- ))
- infraFindings = ir.filter(Boolean)
- log(`Infra probes complete: ${infraFindings.length}/${infraProbes.length} fingerprinted.`)
- }
- // ============================================================================
- // PHASE: Correlate — multi-asset attack paths + risk prioritisation (REUSE skills)
- // ============================================================================
- phase('Correlate')
- const assetDirs = results.map(r => r.output_dir).filter(Boolean)
- const correlate = await agent(
- `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` +
- `ENGAGEMENT_DIR: ${engagementDir}\nASSET_DIRS: ${JSON.stringify(assetDirs)}\n\n` +
- `Do:\n` +
- `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` +
- `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` +
- `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` +
- `Return CORRELATE_SCHEMA.`,
- { schema: CORRELATE_SCHEMA, agentType: 'general-purpose', label: 'correlate', phase: 'Correlate' }
- ).catch(err => ({ ok: false, notes: ['correlate error: ' + String(err)] }))
- // ============================================================================
- // PHASE: Report — Transilience PDF + coverage-gated COMPLETE
- // ============================================================================
- phase('Report')
- // Coverage gate: COMPLETE only if EVERY asset reached coverage-complete AND its
- // engagement validator did not flag a coverage gap. "Ran out of hypotheses" cannot
- // produce COMPLETE — an asset that ended INCOMPLETE_COVERAGE blocks engagement COMPLETE.
- // Completeness by BACKFILL (never throw): every work-list asset must have a result.
- // A missing/degraded asset is surfaced as a coverage gap, not silently dropped.
- // Expected set = what we ATTEMPTED this run (runThisRun) + what was already complete
- // on disk (resumeCompleted). DEFERRED assets are deliberately NOT expected — they are
- // resumable work, not MISSING gaps, so a re-invocation picks them up.
- 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 }))
- const assessedNorm = results.map(r => ({ ...r, key: r.tag }))
- const rec = reconcileAssessed(expectedThisRun, assessedNorm, e => e.key)
- 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 }))
- // Tri-state: a slice-spent asset is RESUMABLE (carried forward), a stuck/degraded asset
- // is a genuine gap. deferredAssets (not run this run) join the resume list.
- const { engagement_status: convStatus, resume: resumeBlock } = classifyEngagement(rec.all, deferredAssets.map(a => a.tag))
- // Provisional (per-asset relay); the deterministic coverage gate run inside
- // finalizeEngagement is authoritative for COMPLETE (computed after it returns).
- const provisionalStatus = convStatus
- // Engagement metadata + version (req 10) — prompt > prior > default; fresh report_id.
- const engagementMeta = resolveEngagementMeta({ prior: input.prior || null, prompt: input.engagement || {}, currentScope: apexes, dateTag: setup.date_tag, explicitVersion: input.version })
- const engagementBlock = {
- title_lines: engagementMeta.title_lines || [engagementMeta.title || setup.engagement_name || 'Penetration Test'],
- title: engagementMeta.title || setup.engagement_name || 'Penetration Test',
- subtitle: engagementMeta.subtitle || (engagementMeta.supersedes ? `Retest — supersedes ${engagementMeta.supersedes}` : `${apexes.length} asset(s)`),
- date: setup.date_tag, footer: engagementMeta.sector || 'Security Assessment',
- // Full cover metadata table (cover_meta overrides the auto table, so include every row).
- cover_meta: [
- ['REPORT DATE', setup.date_tag],
- ['DURATION', engagementMeta.duration],
- ['CLASSIFICATION', engagementMeta.classification || 'Confidential'],
- ['SECTOR', engagementMeta.sector],
- ['TARGET', engagementMeta.target || apexes[0] || null],
- ['METHOD', engagementMeta.method || 'Grey-box'],
- ['PREPARED BY', engagementMeta.prepared_by || 'Transilience'],
- ['REPORT ID', engagementMeta.report_id],
- ['VERSION', engagementMeta.version],
- ...(engagementMeta.supersedes ? [['SUPERSEDES', engagementMeta.supersedes]] : []),
- ],
- }
- let report = { ok: false }
- if (wantReport) {
- 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 })
- if (report.status === 'BLOCKED') log(`Report BLOCKED: ${report.blocked_reason}`)
- }
- // The deterministic (surface-unit × attack-class) coverage gate is authoritative
- // for COMPLETE. Fails closed: if a report was wanted but the gate did not confirm
- // 100% coverage, the engagement is INCOMPLETE_coverage (never a silent COMPLETE).
- const coverageComplete = wantReport ? (report.coverage_complete === true) : true
- // COMPLETE requires the deterministic gate AND convergence with nothing left to resume.
- // Otherwise distinguish RESUMABLE (deferred/slice-spent — re-run) from a genuine gap.
- const engagementStatus = (coverageComplete && convStatus === 'COMPLETE')
- ? 'COMPLETE'
- : (convStatus === 'INCOMPLETE_resumable' ? 'INCOMPLETE_resumable' : 'INCOMPLETE_coverage')
- // ============================================================================
- // Synthesis
- // ============================================================================
- 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).` : ''}`)
- const webRound = Number(setup.resume_round) || 0
- const webResume = resumeBlock.remaining_assets.length
- ? { ...resumeBlock, resume_round: webRound, rerun_hint: (webRound + 1) <= maxResumeRounds ? `resume_dir=${engagementDir}` : null, exhausted_rounds: (webRound + 1) > maxResumeRounds }
- : null
- return {
- status: 'DONE',
- engagement_status: engagementStatus,
- resume: webResume,
- date_tag: setup.date_tag,
- engagement_dir: engagementDir,
- apex_domains: apexes,
- expanded_host_count: (expand.expanded_hosts || []).length,
- 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 })),
- infra_probes: infraProbes.map(p => p.host),
- infra_findings: infraFindings.length,
- excluded: excluded,
- attack_paths_ranked: correlate && correlate.ranked_path ? correlate.ranked_path : `${engagementDir}/artifacts/attack-paths-ranked.md`,
- report_format: report && report.format ? report.format : (input.report_format === 'custom' ? 'custom' : 'transilience'),
- report_status: report && report.status ? report.status : (wantReport ? 'BLOCKED' : 'SKIPPED'),
- report_blocked_reason: report && report.blocked_reason ? report.blocked_reason : null,
- report_path: report && report.report_path ? report.report_path : `${engagementDir}/reports/Penetration-Test-Report.pdf`,
- severity_counts: report && report.severity_counts ? report.severity_counts : null,
- deliverable_zip: report && report.deliverable_zip ? report.deliverable_zip : null,
- protected_zip: report && report.protected_zip ? report.protected_zip : null,
- deliverable_password: report && report.deliverable_password ? report.deliverable_password : null,
- password_file: report && report.password_file ? report.password_file : null,
- protection_limitations: report && report.protection_limitations ? report.protection_limitations : [],
- summary: report && report.summary ? report.summary : null,
- slack_offer: !!(report && report.slack_offer && wantReport),
- coverage_gaps: coverageGaps,
- tool_limitations: expand.tool_limitations || [],
- notes: setup.notes || [],
- }
benchmarks/_shared/claude_runner.py · Bundled script · 247 lines · 2 findings marked
- """
- Spawn Claude Code as a subprocess against a prepared benchmark.
- Shared between XBOW and cybench runners. The caller builds the prompt and
- supplies suite-specific skill content; this module handles the invariants:
- - Strip CLAUDECODE from the environment (nested Claude sessions otherwise die).
- - Select cwd: VANILLA mode uses a fresh tmpdir outside the repo so Claude
- doesn't auto-load project CLAUDE.md or `.claude/skills/`; SKILLS mode uses
- `skills_cwd` (e.g. projects/pentest/) so slash commands are discoverable.
- - Inject skill content via `--append-system-prompt` in SKILLS mode.
- - Force `--setting-sources user` in VANILLA mode to suppress project/local
- configuration discovery.
- - Optional ANTHROPIC_API_KEY override.
- - Capture stdout/stderr, detect auth errors, return a typed result.
- """
- from __future__ import annotations
- import json
- import os
- import shutil
- import subprocess
- import tempfile
- import time
- from dataclasses import dataclass
- from pathlib import Path
- from typing import Literal, Optional
- from .agent_errors import classify_agent_error, extract_error_lines
- from .env_loader import resolve_anthropic_key
- _TOOL_INPUT_MAX = 4000
- _TOOL_RESULT_MAX = 4000
- def _truncate(text: str, limit: int) -> str:
- if len(text) <= limit:
- return text
- return text[:limit] + f"\n...[truncated {len(text) - limit} chars]"
- def _render_stream_json(raw: str) -> str:
- """Render Claude Code stream-json events into readable text.
- Falls back to returning the raw stdout if no JSON events parse, so callers
- that pass non-stream output (or partial buffers on timeout) still get
- something useful.
- """
- parts: list[str] = []
- parsed_any = False
- for line in raw.splitlines():
- s = line.strip()
- if not s:
- continue
- try:
- ev = json.loads(s)
- except json.JSONDecodeError:
- parts.append(line)
- continue
- parsed_any = True
- etype = ev.get("type")
- if etype == "assistant":
- for block in (ev.get("message") or {}).get("content") or []:
- bt = block.get("type")
- if bt == "text":
- parts.append(block.get("text", ""))
- elif bt == "thinking":
- parts.append(f"--- thinking ---\n{block.get('thinking', '')}")
- elif bt == "tool_use":
- name = block.get("name", "?")
- inp = json.dumps(block.get("input", {}), ensure_ascii=False)
- parts.append(f"--- tool_use: {name} ---\n{_truncate(inp, _TOOL_INPUT_MAX)}")
- elif etype == "user":
- for block in (ev.get("message") or {}).get("content") or []:
- if block.get("type") != "tool_result":
- continue
- content = block.get("content")
- if isinstance(content, list):
- content = "".join(
- b.get("text", "") for b in content if isinstance(b, dict)
- )
- content = content or ""
- parts.append(f"--- tool_result ---\n{_truncate(content, _TOOL_RESULT_MAX)}")
- elif etype == "result":
- final = ev.get("result")
- if final:
- parts.append(f"--- final result ---\n{final}")
- if not parsed_any:
- return raw
- return "\n\n".join(parts)
- @dataclass
- class AgentRunResult:
- """Narrow return type from `run_claude`. Suite runners wrap this into
- their own richer BenchmarkResult."""
- stdout: str
- stderr: str
- returncode: int
- duration_seconds: float
- status: str # "success" | "failed" | "timeout" | "error"
- error: Optional[str] = None
- fatal: bool = False # True → caller should abort the remaining run
- def run_claude(
- prompt: str,
- output_dir: Path,
- *,
- mode: Literal["skills", "vanilla"],
- model: Optional[str],
- api_key: Optional[str],
- timeout: int,
- skills_cwd: Optional[Path] = None,
- skills_content: str = "",
- task_id: str = "",
- base_url: Optional[str] = None,
- auth_token: Optional[str] = None,
- max_output_tokens: Optional[int] = None,
- ) -> AgentRunResult:
- """
- Invoke `claude --dangerously-skip-permissions -p <prompt>` and capture output.
- Note: Starts a coding agent with its permission prompts off
- Line 122 on GitHub
- Writes:
- output_dir/prompt.txt
- output_dir/transcript.jsonl (raw stream-json events, one per line)
- output_dir/claude_output.txt (readable rendering of assistant turns,
- thinking blocks, tool calls, tool results)
- output_dir/claude_stderr.txt (only if stderr is non-empty)
- In VANILLA mode, `skills_cwd` and `skills_content` are ignored.
- In SKILLS mode, `skills_cwd` must be provided and typically be the pentest
- project root so Claude discovers project-level config (in addition to the
- skills explicitly injected via `skills_content`).
- """
- tag = f"[{task_id}] " if task_id else ""
- output_dir.mkdir(parents=True, exist_ok=True)
- (output_dir / "prompt.txt").write_text(prompt)
- vanilla_tmpdir: Optional[str] = None
- if mode == "vanilla":
- vanilla_tmpdir = tempfile.mkdtemp(prefix="bench_vanilla_")
- cwd = Path(vanilla_tmpdir)
- print(f" {tag}Mode: VANILLA (isolated tmpdir: {cwd})")
- else:
- if skills_cwd is None or not skills_cwd.exists():
- raise ValueError(
- "SKILLS mode requires skills_cwd pointing to an existing directory"
- )
- cwd = skills_cwd
- print(f" {tag}Mode: SKILLS (cwd: {skills_cwd})")
- cmd = [
- "claude", "--dangerously-skip-permissions",
- Note: Starts a coding agent with its permission prompts off
- Line 154 on GitHub
- "--output-format", "stream-json", "--verbose",
- ]
- if model:
- cmd.extend(["--model", model])
- if mode == "vanilla":
- cmd.extend(["--setting-sources", "user"])
- elif skills_content:
- cmd.extend(["--append-system-prompt", skills_content])
- print(f" {tag}Injected {len(skills_content):,} bytes of skills content")
- cmd.extend(["-p", prompt])
- env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
- resolved_key = resolve_anthropic_key(api_key)
- if resolved_key:
- env["ANTHROPIC_API_KEY"] = resolved_key
- if base_url:
- env["ANTHROPIC_BASE_URL"] = base_url
- print(f" {tag}Routing Claude Code at custom endpoint: {base_url}")
- if auth_token:
- env["ANTHROPIC_AUTH_TOKEN"] = auth_token
- if max_output_tokens:
- env["CLAUDE_CODE_MAX_OUTPUT_TOKENS"] = str(max_output_tokens)
- start = time.time()
- try:
- result = subprocess.run(
- cmd,
- cwd=cwd,
- capture_output=True,
- text=True,
- timeout=timeout,
- env=env,
- )
- except subprocess.TimeoutExpired as e:
- duration = time.time() - start
- stdout = (e.stdout or "") if isinstance(e.stdout, str) else (e.stdout.decode(errors="replace") if e.stdout else "")
- stderr = (e.stderr or "") if isinstance(e.stderr, str) else (e.stderr.decode(errors="replace") if e.stderr else "")
- (output_dir / "transcript.jsonl").write_text(stdout)
- rendered = _render_stream_json(stdout)
- (output_dir / "claude_output.txt").write_text(rendered)
- if stderr:
- (output_dir / "claude_stderr.txt").write_text(stderr)
- if vanilla_tmpdir:
- shutil.rmtree(vanilla_tmpdir, ignore_errors=True)
- return AgentRunResult(
- stdout=rendered, stderr=stderr, returncode=-1,
- duration_seconds=duration, status="timeout",
- error=f"Timeout after {timeout}s",
- )
- except Exception as e:
- duration = time.time() - start
- if vanilla_tmpdir:
- shutil.rmtree(vanilla_tmpdir, ignore_errors=True)
- return AgentRunResult(
- stdout="", stderr="", returncode=-1,
- duration_seconds=duration, status="error", error=str(e),
- )
- duration = time.time() - start
- stdout = result.stdout or ""
- stderr = result.stderr or ""
- (output_dir / "transcript.jsonl").write_text(stdout)
- rendered = _render_stream_json(stdout)
- (output_dir / "claude_output.txt").write_text(rendered)
- if stderr:
- (output_dir / "claude_stderr.txt").write_text(stderr)
- if vanilla_tmpdir:
- shutil.rmtree(vanilla_tmpdir, ignore_errors=True)
- status = "success" if result.returncode == 0 else "failed"
- error: Optional[str] = None
- fatal = False
- if result.returncode != 0:
- classification = classify_agent_error(rendered, stderr, result.returncode)
- if classification:
- status = "error"
- fatal = classification.is_fatal
- error = f"[{classification.kind}] {classification.message}"
- else:
- clean = extract_error_lines(stderr) or extract_error_lines(rendered)
- error = f"rc={result.returncode} duration={duration:.1f}s" + (
- f" | {clean}" if clean else ""
- )
- print(f" {tag}Agent exited rc={result.returncode} after {duration:.1f}s")
- print(f" {tag}{error}")
- print(f" {tag}Full logs: {output_dir}/claude_output.txt, transcript.jsonl, claude_stderr.txt")
- return AgentRunResult(
- stdout=rendered, stderr=stderr, returncode=result.returncode,
- duration_seconds=duration, status=status, error=error, fatal=fatal,
- )
scripts/kali-claude-setup.sh · Bundled script · 187 lines · 2 findings marked
- #!/bin/bash
- # kali-claude-setup.sh
- # Sets up Claude Code on a Kali Linux Docker container with a project's .claude folder
- # (skills, agents, tools) embedded in the workspace.
- #
- # Usage:
- # bash scripts/kali-claude-setup.sh <project-folder>
- # bash scripts/kali-claude-setup.sh <project-folder> --rebuild
- #
- # Example:
- # bash scripts/kali-claude-setup.sh projects/pentest
- set -e
- # --- Require project folder argument ---
- if [ -z "$1" ]; then
- echo "Error: Please provide a project folder path."
- echo ""
- echo "Usage: bash scripts/kali-claude-setup.sh <project-folder>"
- echo ""
- echo "Available projects:"
- for dir in projects/*/; do
- if [ -d "${dir}.claude" ]; then
- echo " - ${dir%/}"
- fi
- done
- exit 1
- fi
- PROJECT_DIR="$1"
- if [ ! -d "$PROJECT_DIR" ]; then
- echo "Error: Project folder '$PROJECT_DIR' not found."
- exit 1
- fi
- if [ ! -d "$PROJECT_DIR/.claude" ]; then
- echo "Error: No .claude folder found in '$PROJECT_DIR'."
- echo "The project must contain a .claude/ directory with skills and agents."
- exit 1
- fi
- PROJECT_NAME=$(basename "$PROJECT_DIR")
- PROJECT_DIR_ABS=$(cd "$PROJECT_DIR" && pwd)
- CONTAINER_NAME="kali-claude-${PROJECT_NAME}"
- IMAGE_NAME="kali-claude:latest"
- WORKSPACE="/workspace"
- echo "[*] Project: $PROJECT_DIR"
- echo "[*] Container: $CONTAINER_NAME"
- echo ""
- # --- Always build/rebuild the image to ensure latest setup ---
- if true; then
- echo "[*] Building Kali + Claude Code image (one-time)..."
- docker build -t "$IMAGE_NAME" -f - . <<'DOCKERFILE'
- FROM kalilinux/kali-rolling
- # Layer 1: System deps + Node.js
- RUN apt update -qq && \
- apt install -y -qq curl git ca-certificates sudo > /dev/null && \
- 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
- apt install -y -qq nodejs > /dev/null && \
- apt clean && rm -rf /var/lib/apt/lists/* /tmp/*
- # Layer 2: Playwright system dependencies + Xvfb
- RUN apt update -qq && \
- npx -y playwright install-deps chromium && \
- apt install -y -qq xvfb > /dev/null && \
- apt clean && rm -rf /var/lib/apt/lists/* /tmp/* /root/.npm
- # Layer 3: Claude Code + Playwright MCP
- RUN npm install -g @anthropic-ai/claude-code @playwright/mcp --silent && \
- npm cache clean --force && rm -rf /root/.npm /tmp/*
- # Layer 4: Install pip + playwright python as fallback
- RUN apt update -qq && apt install -y -qq python3-pip > /dev/null && \
- pip3 install playwright --break-system-packages --quiet && \
- apt clean && rm -rf /var/lib/apt/lists/* /tmp/*
- # Create non-root user BEFORE installing browser (so it goes to claude's home)
- RUN useradd -m -s /bin/bash -G sudo claude && \
- echo "claude ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
- # Layer 5: Install Chromium AS the claude user (browser cache goes to /home/claude/.cache/)
- USER claude
- RUN npx playwright install chromium
- # Set up minimal ~/.claude (no plugin system — using .mcp.json at project root instead)
- RUN mkdir -p /home/claude/.claude && \
- echo '{}' > /home/claude/.claude/settings.json
- USER root
- ENV TMPDIR=/workspace/.tmp
- WORKDIR /workspace
- RUN chown claude:claude /workspace
- USER claude
- DOCKERFILE
- echo "[+] Image built."
- else
- echo "[*] Using existing kali-claude image."
- fi
- # --- Prepare workspace in a temp dir (writable copy, not read-only mount) ---
- TEMP_DIR=$(mktemp -d)
- trap "rm -rf $TEMP_DIR" EXIT
- echo "[*] Preparing project workspace..."
- # Copy .claude folder (skills, agents, tools, settings) — writable so Claude Code can use it
- cp -r "$PROJECT_DIR_ABS/.claude" "$TEMP_DIR/.claude"
- # Add Playwright MCP config at PROJECT ROOT (must be .mcp.json at root, NOT inside .claude/)
- cat > "$TEMP_DIR/.mcp.json" <<'MCP_EOF'
- {
- "mcpServers": {
- "playwright": {
- "command": "npx",
- "args": ["@playwright/mcp@latest",
- "--launch-options", "{\"args\":[\"--disable-blink-features=AutomationControlled\",\"--no-sandbox\",\"--disable-setuid-sandbox\",\"--window-size=1920,1080\"]}"]
- }
- }
- }
- MCP_EOF
- # Copy AGENTS.md from repo root if it exists
- if [ -f "AGENTS.md" ]; then
- cp "AGENTS.md" "$TEMP_DIR/AGENTS.md"
- fi
- # Copy CLAUDE.md (project-level overrides repo-level)
- if [ -f "CLAUDE.md" ]; then
- cp "CLAUDE.md" "$TEMP_DIR/CLAUDE.md"
- fi
- if [ -f "$PROJECT_DIR_ABS/CLAUDE.md" ]; then
- cp "$PROJECT_DIR_ABS/CLAUDE.md" "$TEMP_DIR/CLAUDE.md"
- fi
- # Copy .env file into workspace (so it's readable as a file too)
- if [ -f "$PROJECT_DIR_ABS/.env" ]; then
- cp "$PROJECT_DIR_ABS/.env" "$TEMP_DIR/.env"
- echo "[*] .env file found — will be loaded as environment variables and available as file."
- else
- echo "[!] No .env file found in $PROJECT_DIR — skipping."
- fi
- # Initialize as a git repo so Claude Code recognizes it as a project
- git init -q "$TEMP_DIR"
- echo "[*] Starting container..."
- echo "[*] .claude/skills, .claude/agents, and .claude/tools will be available in $WORKSPACE"
- echo ""
- echo "-----------------------------------------------------------"
- echo " Inside the container, Claude will auto-launch with"
- echo " --dangerously-skip-permissions (no confirmation prompts)."
- echo " Playwright MCP (headed via Xvfb) is available."
- echo " It will show a URL — open it in your host browser to log in."
- echo "-----------------------------------------------------------"
- echo ""
- # Build docker run arguments
- DOCKER_ARGS=()
- # Mount the entire prepared workspace (writable — Claude Code needs to write state)
- DOCKER_ARGS+=(-v "$TEMP_DIR:${WORKSPACE}")
- # Mount scripts folder for debugging
- SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
- DOCKER_ARGS+=(-v "$SCRIPT_DIR:${WORKSPACE}/scripts:ro")
- # Pass .env variables as container environment variables
- if [ -f "$PROJECT_DIR_ABS/.env" ]; then
- DOCKER_ARGS+=(--env-file "$PROJECT_DIR_ABS/.env")
- fi
- # Remove any existing container with the same name
- docker rm -f "$CONTAINER_NAME" 2>/dev/null || true
- docker run -it --rm \
- --name "$CONTAINER_NAME" \
- --network host \
- --tmpfs /tmp:exec,size=2g \
- "${DOCKER_ARGS[@]}" \
- -w "$WORKSPACE" \
- -e TMPDIR=/tmp \
- "$IMAGE_NAME" \
- bash -c "Xvfb :99 -screen 0 1920x1080x24 &>/dev/null & export DISPLAY=:99 && sleep 1 && mkdir -p /workspace/.tmp && claude --dangerously-skip-permissions"
- Note: Starts a coding agent with its permission prompts off
- Line 187 on GitHub
tools/test_passive_web_probe.py · Bundled script · 553 lines · 1 finding marked
- #!/usr/bin/env python3
- """Offline, deterministic tests for passive_web_probe.py.
- Stands up a REAL loopback HTTP server and a REAL loopback HTTPS server (embedded
- self-signed cert — no openssl/network at runtime), points a surface/v2 fixture at
- them, runs the probe, then runs enumerate_cells + coverage_gate and asserts the
- gate's own verdict. No traffic ever leaves 127.0.0.1.
- Variants covered:
- * happy path -> the 8 mechanical cells are covered_negative and the gate PASSES
- them (not in missing_cells), with ZERO artifacts/validated/.
- * --no-nmap -> WEB-A06-COMPONENTS becomes a limitation, cell left OPEN.
- * missing CSP -> XC-SECURITY-HEADERS emits a finding, cell left OPEN.
- """
- from __future__ import annotations
- import glob
- import json
- import os
- import shutil
- import ssl
- import subprocess
- import sys
- import tempfile
- import threading
- from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
- from urllib.parse import urlparse
- HERE = os.path.dirname(os.path.abspath(__file__))
- REPO = os.path.dirname(HERE)
- PROBE = os.path.join(HERE, "passive_web_probe.py")
- ENUM = os.path.join(HERE, "enumerate_cells.py")
- GATE = os.path.join(HERE, "coverage_gate.py")
- HAVE_NMAP = bool(shutil.which("nmap"))
- # Import the probe module directly so the block-page/soft-404 guards can be unit-
- # tested and driven against loopback servers without spawning a subprocess.
- sys.path.insert(0, HERE)
- import passive_web_probe as probe # noqa: E402
- # The canonical F5 BIG-IP ASM / F5 Distributed Cloud reject page (~269 bytes). A
- # rejected request comes back with HTTP 200 and THIS body — never a real file.
- F5_REJECT_PAGE = (
- "<html><head><title>Request Rejected</title></head><body>"
- "The requested URL was rejected. Please consult with your administrator.<br><br>"
- "Your support ID is: 7799990120182737622<br><br>"
- "<a href='javascript:history.back();'>[Go Back]</a></body></html>"
- )
- _FAKE_AWS_KEY = "AKIAIOSFODNN7EXAMPLE" # matches _SECRET_RE; forces a would-be positive
- # Long-lived self-signed cert (CN=127.0.0.1, SAN IP:127.0.0.1) embedded so the
- # test needs no openssl at runtime and never touches the network.
- _CERT_PEM = """-----BEGIN CERTIFICATE-----
- MIIDGjCCAgKgAwIBAgIUd379Ia/EwHxZNkiCyrtWdwUgKEkwDQYJKoZIhvcNAQEL
- BQAwFDESMBAGA1UEAwwJMTI3LjAuMC4xMB4XDTI2MDcxMzEwNTkxNloXDTQ2MDcw
- ODEwNTkxNlowFDESMBAGA1UEAwwJMTI3LjAuMC4xMIIBIjANBgkqhkiG9w0BAQEF
- AAOCAQ8AMIIBCgKCAQEAw35YXCd9jFN9vUyPffqcEG3MyHzxoHWjBI2cbDXFArzJ
- xO4EQHOqY6I2xTfNOmMncBs+Qpm/iKtFeAjUS1U+fgfZua2H1JdLbbiiNYJ2D4Ov
- XOv7woeosuZ3ydUNzF2MS+mtMXXCl0N+0pCXaStUlu82TF6GxNGB/2zDAymkKFV7
- iyy6aLCP7g0uW0v1SYFBsfX2sIw0IVDiXJ0W4ewKYfQkf2tvz3HfLFhgyIY3xaZD
- MgT3pL+UtquoU8iBI9pLYzdYcxnXE/eu47ahjC2iHI69ZCT+S84EUFXzgwZkk917
- 1Vcp9JpQiNoyUWExbg5fX3gNvuSen/cMT/matXZZbQIDAQABo2QwYjAdBgNVHQ4E
- FgQUGeXc4kWht+MaixCBglPjXMaobeowHwYDVR0jBBgwFoAUGeXc4kWht+MaixCB
- glPjXMaobeowDwYDVR0TAQH/BAUwAwEB/zAPBgNVHREECDAGhwR/AAABMA0GCSqG
- SIb3DQEBCwUAA4IBAQAfRki4KSq0QzaqhliL/wMdMuGTGiHJexT+Sxz1sszjXSn3
- kvrynbdk+G+ajPI7HmJtP+y/8SmPZmAwHtK6GyIxmc2llo5PDtFs4jJcoW0XOTAv
- PDvmLWJH8BXgIITsDfRKJK7p3VHIFvE3Ub2L+e0blgP3LcWEaIpokhjuIuF223F6
- Xv9/yOHo8mqMBDofnnURi76doOL5VWXJa/ChzQUvWSswV7afb5gF8JzyqY93YX8g
- nZmLl8AvMwzBTN39RvW6qaa9RBCOfIFdBs/VyCQb11NhGWe4fFHu8BRHLKhXxTuZ
- kUHe8NtDM/YST1I+YQsaIxqYWoDeBbmo/jjD3K2s
- -----END CERTIFICATE-----
- """
- _KEY_PEM = """-----BEGIN PRIVATE KEY-----
- Dismissed after review: Contains what looks like a hardcoded PEM private key
- Line 73 on GitHub
- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDDflhcJ32MU329
- TI99+pwQbczIfPGgdaMEjZxsNcUCvMnE7gRAc6pjojbFN806YydwGz5Cmb+Iq0V4
- CNRLVT5+B9m5rYfUl0ttuKI1gnYPg69c6/vCh6iy5nfJ1Q3MXYxL6a0xdcKXQ37S
- kJdpK1SW7zZMXobE0YH/bMMDKaQoVXuLLLposI/uDS5bS/VJgUGx9fawjDQhUOJc
- nRbh7Aph9CR/a2/Pcd8sWGDIhjfFpkMyBPekv5S2q6hTyIEj2ktjN1hzGdcT967j
- tqGMLaIcjr1kJP5LzgRQVfODBmST3XvVVyn0mlCI2jJRYTFuDl9feA2+5J6f9wxP
- +Zq1dlltAgMBAAECggEADepH4Tz6xErLGyoNPeZHrPZ/Cmq0vkgXuikkUCJRq1y2
- lfrSBagJO4qEqh9LNe09FbWl7F99d5dAj7pwXHGTmN/3lC5kcHImfDrItqHAxC29
- uHg5ruj+GpUQdybgEqk6ZWSB0sPzMNYs+4SV3amoBA7AVC/kTIBgzizqAqce2E00
- h0BLfWODUrt44FP2QbLVYJD3EwBrH5rxly7W4VCBq+U+ROechQD2UZCr4H1fnMLj
- k9xAho30JtaukxvwaGDCdiEvBLqz7zRLIEqzGxroypa4ow96dKGuyvVLmSqatdsD
- zCs92m9lOwPvs7APCzuTmJFGIROQrpRXEH/JeNKWVwKBgQD61w7wxgFX6lYBrlrP
- gLZR6CiF2KmhsTGfeFRCXZF7v24nQBUsrxFKnvTmJUSY8MbZ4R+JuhKczljaQewj
- MsxhlA8hnlVx7QzL3OMyTh4Om7xMO1kA/zQvZvSs7gGWWAFvWLVdzchPVdAa5BVv
- YrCOF+BPdhw2eRPKZodYvl+bmwKBgQDHg9P4Fy3cJBJhkoby3YPhz5b9G4tgCAPY
- MlXxR/NJ5nCDEIhb4vV6tAuOjLART3my0n/wXHSGrw52+p/vOXexnsvTFvy35Bz0
- rRwuS01TM+6Qx/EkE05mkP0gOuMbOWke2vnadafAJYC7K5v12Bkw6yFuoyDwLOPh
- c2l9YYhDlwKBgEf+lcExc41CKvFMk6/e53VWxtqztuw7qVx18ukhZfI4nWsSj4FF
- thbOzMeJhsjGwqwiWyTyjQkIiKQMK7RmjharojQp96g9O2D/ww3bMfFLbZ4Lop4Q
- oW/BgxRnM3ltROwqb9O+jnGG1bYCJMzVbIs7+xuTcMGJus5q4wnrihFlAoGBAJ3O
- C05jJwbEETXTq6FUzAdDJm2z551hOYk65vccrbV56uv/m5rx/K+80JdDd895SQzD
- qiX3OsN8mrhIq0+P6Lg4nYas296nMq/kbDHBpbt1i/A/9N9P1ecSLuPbL95MnnSl
- RpIgFTrJbvScHZNqBSLIF31m0ZqmJugfXQSqrBipAoGAb4MgHQZwM0U+zn1ye/zu
- Kwx/fsJPgkN7j+PNLe0Fqflg1EF615ORTQbY2xgOeAPjM3vJ8Km76OKUu8QGP3oJ
- PyikmZ4sQK+fqdK2jxAhREk9cG/paVLC0REx6KeeRvMgju/13gqVlBZ1t/iEty/Q
- 5xTRLUFHZTLMqVNWa9VgZyE=
- -----END PRIVATE KEY-----
- """
- # --- controllable loopback servers -------------------------------------------
- def make_handler(omit_csp: bool):
- class Handler(BaseHTTPRequestHandler):
- def _headers(self, code, length, ctype):
- self.send_response(code)
- self.send_header("Content-Type", ctype)
- self.send_header("Content-Length", str(length))
- self.send_header("Server", "TestServer/1.0")
- self.send_header("Strict-Transport-Security", "max-age=63072000; includeSubDomains")
- self.send_header("X-Content-Type-Options", "nosniff")
- self.send_header("X-Frame-Options", "DENY")
- if not omit_csp:
- self.send_header("Content-Security-Policy", "default-src 'self'")
- self.end_headers()
- def _route(self):
- path = urlparse(self.path).path
- if path == "/app.js":
- return 200, b"console.log('hello world, nothing secret here');", "application/javascript"
- if path == "/" or path == "/api":
- return 200, b"<html><body>ok</body></html>", "text/html"
- return 404, b"Not Found", "text/plain" # plain 404, no stack trace
- def do_GET(self):
- code, body, ctype = self._route()
- self._headers(code, len(body), ctype)
- self.wfile.write(body)
- def do_HEAD(self):
- code, body, ctype = self._route()
- self._headers(code, len(body), ctype)
- def log_message(self, *a):
- pass
- return Handler
- class _QuietServer(ThreadingHTTPServer):
- daemon_threads = True
- def handle_error(self, request, client_address):
- pass # nmap's version probes reset connections on purpose — don't log
- def start_server(omit_csp=False, tls=False, certfile=None):
- httpd = _QuietServer(("127.0.0.1", 0), make_handler(omit_csp))
- if tls:
- ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
- ctx.load_cert_chain(certfile)
- httpd.socket = ctx.wrap_socket(httpd.socket, server_side=True)
- port = httpd.server_address[1]
- t = threading.Thread(target=httpd.serve_forever, daemon=True)
- t.start()
- return httpd, port
- def start_scripted_server(respond):
- """Loopback server whose every response is decided by respond(path) ->
- (status, headers_dict, body_bytes). Lets a test simulate a WAF reject page, an
- SPA soft-404 catch-all, or a server hosting one genuinely-distinct file."""
- class Handler(BaseHTTPRequestHandler):
- def _emit(self):
- status, headers, body = respond(urlparse(self.path).path)
- self.send_response(status)
- for k, v in headers.items():
- self.send_header(k, v)
- self.send_header("Content-Length", str(len(body)))
- self.end_headers()
- return body
- def do_GET(self):
- self.wfile.write(self._emit())
- def do_HEAD(self):
- self._emit()
- def log_message(self, *a):
- pass
- httpd = _QuietServer(("127.0.0.1", 0), Handler)
- port = httpd.server_address[1]
- threading.Thread(target=httpd.serve_forever, daemon=True).start()
- return httpd, port
- # --- fixture + tool runners --------------------------------------------------
- def write_surface(asset_dir, tag, http_port, https_port):
- units = [
- {"unit_id": "u1", "type": "endpoint", "address": f"http://127.0.0.1:{http_port}/api", "server": "TestServer/1.0"},
- {"unit_id": "u2", "type": "endpoint", "address": f"https://127.0.0.1:{https_port}/api", "server": "TestServer/1.0", "tls": True},
- {"unit_id": "u3", "type": "page", "address": f"http://127.0.0.1:{http_port}/app.js"},
- ]
- p = os.path.join(asset_dir, "recon", "inventory", "surface.json")
- os.makedirs(os.path.dirname(p), exist_ok=True)
- with open(p, "w") as f:
- json.dump({"schema": "surface/v2", "asset_tag": tag, "units": units}, f)
- def run_probe(asset_dir, no_nmap=False):
- cmd = [sys.executable, PROBE, "--asset-dir", asset_dir, "--allow", "127.0.0.1", "--timeout", "8"]
- if no_nmap:
- cmd.append("--no-nmap")
- p = subprocess.run(cmd, cwd=REPO, capture_output=True, text=True)
- assert p.returncode == 0, f"probe exited {p.returncode}: {p.stderr}\n{p.stdout}"
- line = [l for l in p.stdout.splitlines() if l.strip()][-1]
- return json.loads(line)
- def run_gate(asset_dir):
- subprocess.run([sys.executable, ENUM, "--asset-dir", asset_dir], cwd=REPO, capture_output=True, text=True, check=True)
- subprocess.run([sys.executable, GATE, "--asset-dir", asset_dir], cwd=REPO, capture_output=True, text=True)
- with open(os.path.join(asset_dir, "reports", "coverage-matrix.json")) as f:
- return json.load(f)
- def mechanical_cells(asset_dir):
- with open(os.path.join(asset_dir, "applicability", "cells.json")) as f:
- cells = json.load(f)["cells"]
- mech = {"XC-CORS", "XC-TRANSPORT-DOWNGRADE", "XC-VERBOSE-ERRORS", "XC-SECURITY-HEADERS",
- "XC-TLS-POSTURE", "WEB-A06-COMPONENTS", "API9-INVENTORY", "XC-SECRET-EXPOSURE"}
- return {(c["class_id"], c["scope_key"]) for c in cells if c["class_id"] in mech}
- def open_cells(matrix):
- return {(r["class_id"], r["scope_key"]) for r in matrix["missing_cells"]}
- # --- tests -------------------------------------------------------------------
- def _fixture(tmp, omit_csp=False):
- certfile = os.path.join(tmp, "cert.pem")
- with open(certfile, "w") as f:
- f.write(_CERT_PEM + _KEY_PEM)
- http_httpd, http_port = start_server(omit_csp=omit_csp)
- tls_httpd, tls_port = start_server(omit_csp=omit_csp, tls=True, certfile=certfile)
- asset_dir = os.path.join(tmp, "webA")
- write_surface(asset_dir, "webA", http_port, tls_port)
- return asset_dir, (http_httpd, tls_httpd)
- def test_happy_path_closes_mechanical_cells():
- with tempfile.TemporaryDirectory() as tmp:
- asset_dir, servers = _fixture(tmp)
- try:
- summary = run_probe(asset_dir)
- matrix = run_gate(asset_dir)
- finally:
- for s in servers:
- s.shutdown()
- mech = mechanical_cells(asset_dir)
- assert mech, "fixture must enumerate mechanical cells"
- opened = open_cells(matrix)
- # WEB-A06-COMPONENTS needs nmap; if nmap is absent it is (honestly) a limitation.
- expect_closed = {c for c in mech if HAVE_NMAP or c[0] != "WEB-A06-COMPONENTS"}
- still_open = expect_closed & opened
- assert not still_open, f"these mechanical cells should be PASSED, got open: {sorted(still_open)}"
- # Every closed mechanical cell shows up in the probe's covered_negative summary.
- cn = {(c["class_id"], c["scope_key"]) for c in summary["covered_negative"]}
- assert expect_closed <= cn, f"summary missing covered_negative for: {sorted(expect_closed - cn)}"
- # gate scored them as covered_negative via a real corroborator, with NO validated finding.
- assert not glob.glob(os.path.join(asset_dir, "artifacts", "validated", "*.json")), \
- "no validated findings must exist — these are code-corroborated negatives"
- for cid in {"XC-CORS", "XC-SECURITY-HEADERS", "XC-TLS-POSTURE", "API9-INVENTORY", "XC-SECRET-EXPOSURE"}:
- pc = matrix["per_class"].get(cid)
- if pc:
- assert pc["status"] == "covered_negative" and pc["passed"] == pc["applicable"], \
- f"{cid} should be fully covered_negative: {pc}"
- if not HAVE_NMAP:
- assert any(x["class_id"] == "WEB-A06-COMPONENTS" for x in summary["limitations"]), \
- "no nmap -> COMPONENTS must be a limitation"
- def test_no_nmap_leaves_components_open():
- with tempfile.TemporaryDirectory() as tmp:
- asset_dir, servers = _fixture(tmp)
- try:
- summary = run_probe(asset_dir, no_nmap=True)
- matrix = run_gate(asset_dir)
- finally:
- for s in servers:
- s.shutdown()
- opened = open_cells(matrix)
- comp = {c for c in mechanical_cells(asset_dir) if c[0] == "WEB-A06-COMPONENTS"}
- assert comp, "fixture must have COMPONENTS cells"
- assert comp <= opened, f"--no-nmap must leave COMPONENTS OPEN, got closed: {sorted(comp - opened)}"
- assert any(x["class_id"] == "WEB-A06-COMPONENTS" for x in summary["limitations"]), \
- f"COMPONENTS must be a limitation: {summary['limitations']}"
- assert not any(c["class_id"] == "WEB-A06-COMPONENTS" for c in summary["covered_negative"]), \
- "COMPONENTS must not be reported covered when nmap is unavailable"
- # The other (non-nmap) mechanical cells still close.
- others = {c for c in mechanical_cells(asset_dir) if c[0] != "WEB-A06-COMPONENTS"}
- assert not (others & opened), f"non-nmap mechanical cells should still pass: {sorted(others & opened)}"
- def test_missing_header_emits_finding_and_leaves_cell_open():
- with tempfile.TemporaryDirectory() as tmp:
- asset_dir, servers = _fixture(tmp, omit_csp=True)
- try:
- # --no-nmap keeps the run fast; the CSP omission is what we're testing.
- summary = run_probe(asset_dir, no_nmap=True)
- matrix = run_gate(asset_dir)
- finally:
- for s in servers:
- s.shutdown()
- opened = open_cells(matrix)
- hdr = {c for c in mechanical_cells(asset_dir) if c[0] == "XC-SECURITY-HEADERS"}
- assert hdr, "fixture must have SECURITY-HEADERS cells"
- assert hdr <= opened, f"missing CSP must leave SECURITY-HEADERS OPEN: {sorted(hdr - opened)}"
- findings = {(f["class_id"], f["scope_key"]) for f in summary["findings"]}
- assert hdr <= findings, f"a finding must be emitted per SECURITY-HEADERS cell: {summary['findings']}"
- assert not any(c["class_id"] == "XC-SECURITY-HEADERS" for c in summary["covered_negative"]), \
- "a positive must NOT be written as covered_negative"
- # The raw finding is on disk (routed to the validation lane), NOT pre-validated.
- fdirs = glob.glob(os.path.join(asset_dir, "findings", "finding-XC-SECURITY-HEADERS-*"))
- assert fdirs, "a raw finding directory must exist"
- assert os.path.isfile(os.path.join(fdirs[0], "description.md"))
- assert os.path.isfile(os.path.join(fdirs[0], "evidence", "raw-source.txt"))
- assert not glob.glob(os.path.join(asset_dir, "artifacts", "validated", "*.json")), \
- "positive findings are raw, never pre-validated by the probe"
- def test_out_of_scope_host_is_skipped_not_probed():
- with tempfile.TemporaryDirectory() as tmp:
- asset_dir, servers = _fixture(tmp)
- try:
- # No --allow -> 127.0.0.1 is not in {asset_tag}; every cell must be SKIPPED, never probed.
- cmd = [sys.executable, PROBE, "--asset-dir", asset_dir, "--timeout", "5", "--no-nmap"]
- p = subprocess.run(cmd, cwd=REPO, capture_output=True, text=True)
- assert p.returncode == 0, p.stderr
- summary = json.loads([l for l in p.stdout.splitlines() if l.strip()][-1])
- finally:
- for s in servers:
- s.shutdown()
- assert summary["covered_negative"] == [], "out-of-scope hosts must not be closed"
- assert summary["findings"] == [], "out-of-scope hosts must not be probed for findings"
- skipped_hosts = {s["host"] for s in summary["skipped_out_of_scope"]}
- 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']}"
- def test_no_mechanical_cells_is_graceful():
- with tempfile.TemporaryDirectory() as tmp:
- # A surface with no listeners/units -> no mechanical cells -> clean no-op exit 0.
- asset_dir = os.path.join(tmp, "empty")
- p = os.path.join(asset_dir, "recon", "inventory", "surface.json")
- os.makedirs(os.path.dirname(p), exist_ok=True)
- with open(p, "w") as f:
- json.dump({"schema": "surface/v2", "asset_tag": "empty", "units": []}, f)
- summary = run_probe(asset_dir)
- assert summary["covered_negative"] == [] and summary["findings"] == [], \
- f"empty surface must be a graceful no-op: {summary}"
- # --- Addition #1: WAF/CDN block-page classifier -----------------------------
- def test_classify_block_vendor_signatures():
- cb = probe.classify_block
- # F5 XC ASM reject page (body markers, usually HTTP 200).
- r = cb(200, {}, F5_REJECT_PAGE)
- assert r == {"is_block": True, "vendor": "f5"}, r
- # Vercel — platform error header, and the NOT_FOUND shell with an x-vercel-* header.
- assert cb(404, {"x-vercel-error": "NOT_FOUND"}, "")["vendor"] == "vercel"
- assert cb(404, {"x-vercel-id": "abc"}, "This page could not be found")["vendor"] == "vercel"
- # AppTrana / Indusface — HTTP 406 with a vendor marker.
- assert cb(406, {"content-type": "text/html"}, "Blocked by AppTrana WAF")["vendor"] == "apptrana"
- # Akamai — Ghost reject markers / Reference # hex.
- assert cb(403, {"server": "AkamaiGHost"}, "Access Denied")["vendor"] == "akamai"
- assert cb(200, {}, "Reference #18.abcd1234.1700000000.deadbeef")["vendor"] == "akamai"
- # Cloudflare — cf-ray header + a challenge/block body.
- assert cb(403, {"cf-ray": "8a1b2c3d"}, "Attention Required! | Cloudflare")["vendor"] == "cloudflare"
- assert cb(429, {"cf-ray": "8a1b2c3d"}, "error 1015 rate limited")["vendor"] == "cloudflare"
- # Sucuri — block body / x-sucuri-block header.
- assert cb(403, {"x-sucuri-id": "1"}, "Sucuri WebSite Firewall - Access Denied")["vendor"] == "sucuri"
- # Imperva / Incapsula — deny body / cookie markers.
- assert cb(403, {}, "Powered by _Incapsula_Resource")["vendor"] == "imperva"
- assert cb(403, {"set-cookie": "incap_ses_123=abc; path=/"}, "denied")["vendor"] == "imperva"
- assert cb(403, {"x-iinfo": "9-12345-0"}, "Request unsuccessful. Incapsula incident ID: 1")["vendor"] == "imperva"
- # NEGATIVES — a plain page and, crucially, a real 200 asset merely fronted by a
- # CDN (bare vendor header, no deny status/body) must NOT be classified as a block.
- assert cb(200, {"server": "nginx"}, "<html><body>hello</body></html>")["is_block"] is False
- assert cb(200, {"x-akamai-transformed": "9 1234 0"}, "console.log(1)")["is_block"] is False
- assert cb(200, {"x-sucuri-id": "1"}, "legit body")["is_block"] is False
- assert cb(200, {"x-vercel-id": "abc"}, "real served asset")["is_block"] is False
- assert cb(200, {"x-iinfo": "9-12345-0"}, "real served asset")["is_block"] is False
- # --- Addition #2: soft-404 detector -----------------------------------------
- def test_is_soft_404_true_and_false():
- shell = "<html><body id='app'>loading…</body></html>"
- baseline = probe.baseline_fingerprint({"ok": True, "status": 200, "body": shell})
- # identical body-hash -> soft-404
- assert probe.is_soft_404({"ok": True, "status": 200, "body": shell}, baseline) is True
- # same status, different body but size within tolerance -> soft-404
- near = shell.replace("app", "App") # same length, different content
- assert probe.is_soft_404({"ok": True, "status": 200, "body": near}, baseline) is True
- # different status -> NOT soft-404 (a real 200 file vs a 404 baseline)
- assert probe.is_soft_404({"ok": True, "status": 404, "body": shell}, baseline) is False
- # same status but a genuinely distinct, much larger body -> NOT soft-404
- assert probe.is_soft_404({"ok": True, "status": 200, "body": "X" * 5000}, baseline) is False
- # missing baseline / unreachable candidate -> NOT soft-404
- assert probe.is_soft_404({"ok": True, "status": 200, "body": shell}, None) is False
- assert probe.is_soft_404({"ok": False, "error": "refused"}, baseline) is False
- # --- wiring: a WAF reject page is a block observation, never a secret exposure --
- def test_f5_reject_page_not_reported_as_secret():
- # /.env returns the F5 reject page WITH an embedded fake key: without the block
- # guard the secret regex would match; the guard must win and suppress it.
- body = (F5_REJECT_PAGE + f"<!-- api_key: {_FAKE_AWS_KEY} -->").encode()
- def respond(path):
- if path == "/.env":
- return 200, {"Content-Type": "text/html"}, body
- return 404, {"Content-Type": "text/plain"}, b"Not Found"
- httpd, port = start_scripted_server(respond)
- base = f"http://127.0.0.1:{port}"
- try:
- verdict, one_line, raw, obs = probe.check_secret_exposure([f"{base}/.env"], [base], timeout=8)
- finally:
- httpd.shutdown()
- assert verdict == "clean", f"F5 reject page must not be a secret finding: {verdict} / {one_line}"
- assert "[SECRET]" not in raw, raw
- assert any(o["kind"] == "waf_block" and o["vendor"] == "f5" for o in obs), \
- f"the /.env reject page must be recorded as an F5 block: {obs}"
- # --- wiring: an SPA/Blazor catch-all shell is a soft-404, never a hit ----------
- def test_soft404_shell_not_reported_as_secret():
- # Every path (incl. the nonsense baseline AND /.git/config) returns the SAME 200
- # shell that happens to contain a secret-looking token.
- shell = (f"<html><body><script>window.cfg={{api_key:'{_FAKE_AWS_KEY}'}}</script>"
- "<div id='app'>loading</div></body></html>").encode()
- def respond(path):
- return 200, {"Content-Type": "text/html"}, shell # true catch-all
- httpd, port = start_scripted_server(respond)
- base = f"http://127.0.0.1:{port}"
- try:
- verdict, one_line, raw, obs = probe.check_secret_exposure(
- [f"{base}/.git/config", f"{base}/app.js"], [base], timeout=8)
- finally:
- httpd.shutdown()
- assert verdict == "clean", f"catch-all shell must not be a secret finding: {verdict} / {one_line}"
- assert "[SECRET]" not in raw, raw
- assert any(o["kind"] == "soft_404" and o["url"].endswith("/.git/config") for o in obs), \
- f"/.git/config must be recorded as a soft-404, not an exposure: {obs}"
- # --- no regression: a genuinely distinct file IS still reported ----------------
- def test_distinct_file_still_reported():
- # /app.js is a real, distinct 200 body with a secret; the nonsense baseline is a
- # short 404 -> differs in status+body -> NOT soft-404 -> must still be reported.
- real = (f"'use strict';const AWS_KEY='{_FAKE_AWS_KEY}';export default AWS_KEY;").encode()
- def respond(path):
- if path == "/app.js":
- return 200, {"Content-Type": "application/javascript"}, real
- return 404, {"Content-Type": "text/plain"}, b"Not Found"
- httpd, port = start_scripted_server(respond)
- base = f"http://127.0.0.1:{port}"
- try:
- verdict, one_line, raw, obs = probe.check_secret_exposure([f"{base}/app.js"], [base], timeout=8)
- finally:
- httpd.shutdown()
- assert verdict == "positive", f"a real distinct secret must still be reported: {verdict} / {one_line}"
- assert "[SECRET]" in raw and _FAKE_AWS_KEY[:12] in one_line, (raw, one_line)
- assert not any(o["kind"] == "soft_404" for o in obs), f"a distinct file is not a soft-404: {obs}"
- # --- wiring: soft-404 also protects the API inventory check --------------------
- def test_soft404_shell_not_reported_as_openapi():
- # Every path returns an identical 200 shell that echoes 'openapi' — without the
- # soft-404 guard /openapi.json would be a false "exposed inventory" hit.
- shell = b'<html><body>{"openapi":"3.0.0"} single-page app shell</body></html>'
- def respond(path):
- return 200, {"Content-Type": "text/html"}, shell # true catch-all
- httpd, port = start_scripted_server(respond)
- base = f"http://127.0.0.1:{port}"
- try:
- verdict, one_line, raw, obs = probe.check_api_inventory([base], timeout=8)
- finally:
- httpd.shutdown()
- assert verdict == "clean", f"catch-all shell must not be exposed inventory: {verdict} / {one_line}"
- assert "[OPENAPI]" not in raw, raw
- assert any(o["kind"] == "soft_404" for o in obs), f"swagger paths must be recorded as soft-404: {obs}"
- def test_mobile_asset_is_never_probed():
- """Trap 4: a mobile app asset must never be sent an HTTP probe.
- XC-SECRET-EXPOSURE gates on static_js_or_repo, an AGENT flag a mobile app can
- legitimately carry (a bundled JS/AOT blob IS a static bundle). Filtering cells by
- class alone would enumerate that cell for the app and fabricate a covered_negative
- against a file on disk.
- """
- with tempfile.TemporaryDirectory() as tmp:
- d = os.path.join(tmp, "fieldapp-app")
- os.makedirs(os.path.join(d, "recon", "inventory"))
- with open(os.path.join(d, "recon", "inventory", "mobile-surface.json"), "w") as f:
- json.dump({"schema": "mobile-surface/v1", "asset_tag": "fieldapp-app",
- "platform": "android", "package": "com.example.fieldapp",
- "flags": ["static_js_or_repo"],
- "units": [{"unit_id": "st:prefs", "type": "storage",
- "address": "/data/data/com.example.fieldapp/shared_prefs/s.xml",
- "flags": ["local_store"]}]}, f)
- summary = run_probe(d, no_nmap=True)
- assert summary["covered_negative"] == [], \
- f"a mobile asset must yield no probed negatives: {summary['covered_negative']}"
- assert summary["findings"] == [], summary["findings"]
- assert not os.path.isfile(os.path.join(d, "coverage.json")), \
- "the probe must not write a coverage ledger for a mobile asset"
- def main():
- tests = [v for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
- failed = 0
- for t in tests:
- try:
- t()
- print(f" PASS {t.__name__}")
- except AssertionError as e:
- failed += 1
- print(f" FAIL {t.__name__}: {e}")
- except Exception as e: # noqa: BLE001
- failed += 1
- print(f" ERROR {t.__name__}: {type(e).__name__}: {e}")
- print(f"{len(tests) - failed}/{len(tests)} passed (nmap {'present' if HAVE_NMAP else 'absent'})")
- return 1 if failed else 0
- if __name__ == "__main__":
- sys.exit(main())
tools/test_protect_deliverable.py · Bundled script · 231 lines · 1 finding marked
- #!/usr/bin/env python3
- """Offline, deterministic tests for tools/protect_deliverable.py.
- Proves: a real AES-256 protected zip + encrypted PDF are produced alongside the
- plaintext ones; the correct password opens them and a wrong one is rejected; the
- archived PDF is itself encrypted; the password never rides inside the zip; the
- password is reused across runs; and when the AES tool is absent the artifact is
- SKIPPED (recorded as a limitation) rather than silently downgraded to weak crypto.
- Capability-aware (repo convention): branches on 7z / pypdf availability so it stays
- green in a runner that lacks them; skips clean if no AES-256 tool is present at all.
- Run: python3 tools/test_protect_deliverable.py
- """
- from __future__ import annotations
- import json
- import os
- import shutil
- import subprocess
- import sys
- import tempfile
- HERE = os.path.dirname(os.path.abspath(__file__))
- TOOL = os.path.join(HERE, "protect_deliverable.py")
- def sevenzip():
- return next((t for t in ("7z", "7za", "7zz") if shutil.which(t)), None)
- HAVE_7Z = sevenzip() is not None
- HAVE_QPDF = shutil.which("qpdf") is not None
- try:
- from pypdf import PdfReader # noqa: F401
- HAVE_PYPDF = True
- except ImportError:
- HAVE_PYPDF = False
- HAVE_PDF_ENC = HAVE_QPDF or HAVE_PYPDF
- if not (HAVE_7Z or HAVE_PDF_ENC):
- print("SKIP: no AES-256 tool (7z / qpdf / pypdf) available")
- sys.exit(0)
- _pass = 0
- _fail = 0
- def ok(cond, msg):
- global _pass, _fail
- if cond:
- _pass += 1
- else:
- _fail += 1
- print(" FAIL " + msg)
- def run_tool(eng, report_id="ACME-260713-v1.0", env=None, extra=None):
- cmd = [sys.executable, TOOL, "--engagement-dir", eng, "--report-id", report_id]
- if extra:
- cmd += extra
- p = subprocess.run(cmd, capture_output=True, text=True, env=env)
- try:
- return json.loads(p.stdout.strip().splitlines()[-1]), p
- except (json.JSONDecodeError, IndexError):
- print(" tool stdout:", p.stdout, "stderr:", p.stderr)
- return None, p
- # A valid 1-page PDF built with whatever is available (no hard reportlab dep).
- _MINIMAL_PDF = (
- b"%PDF-1.4\n"
- b"1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj\n"
- b"2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj\n"
- b"3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]/Resources<<>>>>endobj\n"
- b"trailer<</Size 4/Root 1 0 R>>\n%%EOF\n"
- )
- def write_fixture_pdf(path):
- try:
- from reportlab.pdfgen import canvas # noqa: PLC0415
- c = canvas.Canvas(path)
- c.drawString(72, 720, "CONFIDENTIAL — penetration test findings")
- c.save()
- return
- except ImportError:
- pass
- try:
- from pypdf import PdfWriter # noqa: PLC0415
- w = PdfWriter()
- w.add_blank_page(width=612, height=792)
- with open(path, "wb") as fh:
- w.write(fh)
- return
- except Exception: # noqa: BLE001
- pass
- with open(path, "wb") as fh:
- fh.write(_MINIMAL_PDF)
- def make_fixture(root, with_pdf=True):
- os.makedirs(os.path.join(root, "reports"))
- os.makedirs(os.path.join(root, "input"))
- os.makedirs(os.path.join(root, "logs", "activity"))
- os.makedirs(os.path.join(root, "artifacts"))
- if with_pdf:
- write_fixture_pdf(os.path.join(root, "reports", "Penetration-Test-Report.pdf"))
- open(os.path.join(root, "reports", "summary.md"), "w").write("# Summary\nfindings: 3\n")
- open(os.path.join(root, "input", "scope.txt"), "w").write("example.com\n")
- open(os.path.join(root, "artifacts", "org-surface.json"), "w").write("{}\n")
- # --------------------------------------------------------------------------- #
- def test_happy_path():
- root = tempfile.mkdtemp()
- try:
- make_fixture(root)
- res, _ = run_tool(root)
- ok(res and res["ok"], "tool reports ok (something was protected)")
- if not res:
- return
- ok(res["password"] and len(res["password"]) >= 20, "strong password generated")
- ok(os.path.isfile(os.path.join(root, "reports", "Penetration-Test-Report.pdf")),
- "plaintext PDF kept alongside the protected one")
- if HAVE_PDF_ENC:
- ok(res["protected_pdf"] and os.path.isfile(res["protected_pdf"]), "protected PDF exists")
- ok(res["protected_pdf_algo"] and "AES-256" in res["protected_pdf_algo"], "PDF algo is AES-256")
- if HAVE_PYPDF and res["protected_pdf"]:
- r = PdfReader(res["protected_pdf"])
- ok(r.is_encrypted, "protected PDF is_encrypted")
- ok(r.decrypt(res["password"]) != 0, "correct password decrypts the PDF")
- ok(PdfReader(res["protected_pdf"]).decrypt("wrong-password-xyz") == 0,
- "wrong password does NOT decrypt the PDF")
- else:
- ok(res["protected_pdf"] is None and any("PDF" in x for x in res["limitations"]),
- "no PDF tool -> protected_pdf skipped + limitation (no weak fallback)")
- if HAVE_7Z:
- ok(res["protected_zip"] and os.path.isfile(res["protected_zip"]), "protected zip exists")
- ok(res["protected_zip_algo"] and "AES-256" in res["protected_zip_algo"], "zip algo is AES-256")
- sz = sevenzip()
- good = subprocess.run([sz, "t", "-p" + res["password"], res["protected_zip"]], capture_output=True)
- ok(good.returncode == 0, "correct password opens the zip")
- bad = subprocess.run([sz, "t", "-pWRONGpw123", res["protected_zip"]], capture_output=True)
- 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
- listing = subprocess.run([sz, "l", "-p" + res["password"], res["protected_zip"]],
- capture_output=True, text=True)
- ok("DELIVERABLE-PASSWORD.txt" not in listing.stdout,
- "password file is NOT inside the protected zip")
- if HAVE_PYPDF:
- ext = tempfile.mkdtemp()
- subprocess.run([sz, "x", "-y", "-p" + res["password"], "-o" + ext, res["protected_zip"],
- "reports/Penetration-Test-Report.pdf"], capture_output=True)
- inner = os.path.join(ext, "reports", "Penetration-Test-Report.pdf")
- ok(os.path.isfile(inner) and PdfReader(inner).is_encrypted,
- "PDF inside the protected zip is itself encrypted")
- shutil.rmtree(ext, ignore_errors=True)
- else:
- ok(res["protected_zip"] is None and any("zip" in x for x in res["limitations"]),
- "no 7z -> protected_zip skipped + limitation (no weak ZipCrypto)")
- pf = os.path.join(root, "DELIVERABLE-PASSWORD.txt")
- ok(os.path.isfile(pf), "password file written at engagement root")
- ok(res["password"] in open(pf).read(), "password file contains the password")
- ok((os.stat(pf).st_mode & 0o777) == 0o600, "password file is chmod 600")
- finally:
- shutil.rmtree(root, ignore_errors=True)
- def test_password_reuse():
- root = tempfile.mkdtemp()
- try:
- make_fixture(root)
- r1, _ = run_tool(root)
- r2, _ = run_tool(root)
- ok(r1 and r2 and r1["password"] == r2["password"], "password is reused across runs (stable)")
- ok(r2 and r2["password_reused"] is True, "second run reports password_reused=True")
- r3, _ = run_tool(root, extra=["--no-reuse"])
- ok(r3 and r3["password"] != r1["password"], "--no-reuse mints a fresh password")
- finally:
- shutil.rmtree(root, ignore_errors=True)
- def test_no_7z_skips_zip_no_weak_fallback():
- """With every 7z binary stripped from PATH, the zip is SKIPPED + a limitation is
- recorded — never a weak-crypto zip. Only meaningful where pypdf can still protect
- the PDF without PATH tools; otherwise it just asserts the no-weak-fallback contract."""
- if not HAVE_7Z:
- return # can't demonstrate the strip if 7z was never there
- root = tempfile.mkdtemp()
- safe = tempfile.mkdtemp()
- try:
- make_fixture(root)
- env = dict(os.environ)
- env["PATH"] = safe # no 7z AND no qpdf on PATH -> pypdf (in-process) still protects the PDF
- res, _ = run_tool(root, env=env)
- ok(res is not None, "tool still runs with an empty PATH")
- if res:
- ok(res["protected_zip"] is None, "no protected zip when 7z is absent")
- ok(any("zip skipped" in x for x in res["limitations"]),
- "a limitation is recorded for the skipped zip (no silent weak fallback)")
- if HAVE_PYPDF:
- ok(res["protected_pdf"] is not None and "pypdf" in (res["protected_pdf_algo"] or ""),
- "PDF still protected via pypdf (AES-256) without external binaries")
- finally:
- shutil.rmtree(root, ignore_errors=True)
- shutil.rmtree(safe, ignore_errors=True)
- def test_missing_pdf_graceful():
- root = tempfile.mkdtemp()
- try:
- make_fixture(root, with_pdf=False)
- res, _ = run_tool(root)
- ok(res is not None and res["protected_pdf"] is None, "missing PDF -> protected_pdf None")
- ok(res and any("no plaintext PDF" in x for x in res["limitations"]),
- "missing PDF recorded as a limitation")
- if HAVE_7Z:
- ok(res and res["protected_zip"], "protected zip still produced without a PDF")
- finally:
- shutil.rmtree(root, ignore_errors=True)
- if __name__ == "__main__":
- for t in (test_happy_path, test_password_reuse, test_no_7z_skips_zip_no_weak_fallback,
- test_missing_pdf_graceful):
- t()
- print(" ran " + t.__name__)
- print("\n%d/%d passed (7z=%s qpdf=%s pypdf=%s)" % (_pass, _pass + _fail, HAVE_7Z, HAVE_QPDF, HAVE_PYPDF))
- sys.exit(1 if _fail else 0)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.