---
name: pentest
description: Penetration testing orchestrator that coordinates specialized attack agents. Provides attack indexes, methodology frameworks, and documentation. Execution delegated to specialized agents (SQL Injection, XSS, SSRF, etc.). Use for engagement planning and attack coordination.
---

Coordinate penetration testing. Deploy executors, aggregate results, generate reports.
Use it when user requests pentesting, security assessment, vulnerability testing, bug bounty hunting.

## Workflow

**Phase 1: Initialization**
1. Gather scope: Target URL, restrictions, testing window
2. Create engagement folder: `outputs/{engagement-name}/`

**Phase 2: Reconnaissance** (Read `reference/RECONNAISSANCE_OUTPUT.md` to get outputs format)
1. Select reconnaissance tools based on asset type (domains, web apps, APIs, network, cloud)
2. Run tools in parallel using pentest-executor agents
3. Generate asset-specific inventory files (JSON format per asset type) using the defined output format
4. Generate the final `reconnaissance_report.md` file using the defined output format

**Phase 3: Planning & Approval (MANDATORY)**
1. Analyze reconnaissance findings from the `outputs/{engagement}/reconnaissance/` and the reports.md files
2. Create test plan: Executors to deploy, attack surface justification, testing approach
3. Present plan to user via AskUserQuestion
4. Get explicit approval if not already approved in the first phase: "Approve plan?", "Modify executors?", "Cancel?"
5. **CRITICAL**: Do NOT proceed to Phase 4 without user approval

**Phase 4: Vulnerability Testing**
1. Deploy approved executors in parallel (single Task call with run_in_background=True)
2. Monitor progress: Periodic TaskOutput(block=False)
3. Recursive spawning: New discoveries trigger new executors (ask approval if major change)

**Phase 5: Aggregation**
1. Collect findings from all executors
2. Deduplicate (same vuln + location = duplicate)
3. Identify exploit chains
4. Calculate severity metrics

**Phase 6: Reporting** (Read `reference/FINAL_REPORT.md` - includes DOCX conversion)
1. **CRITICAL: Create folder structure FIRST**: `report/` and `processed/` with subdirectories
2. **Move ALL working files to `processed/`**: reconnaissance/, findings/, activity/ → `processed/`
3. **Move ALL intermediate files**: ANY .md files, drafts, analysis → `processed/intermediate-reports/`
4. **Generate markdown report**: Use `reference/FINAL_REPORT.md` template → `processed/intermediate-reports/pentest-final-report.md`
5. **REQUIRED: Generate .docx**: Run pandoc command → `report/Penetration-Test-Report.docx` (cover page, TOC, body, appendix section)
6. **Optional: Generate PDF**: If LaTeX available → `report/Penetration-Test-Report.pdf`, else skip (DOCX is primary deliverable)
7. **Copy referenced evidence**: Organize by finding → `report/appendix/finding-{id}/`
8. **Create report README**: Document deliverables in `report/README.md`
9. **VERIFY CLEAN STRUCTURE**: `ls -la outputs/{engagement}/` shows ONLY `report/` and `processed/`
10. **CRITICAL: NO intermediate files in root or report/** - Everything goes to `processed/` except final deliverables (.docx, .json, README, appendix/) 

## What This Skill Does

1. **Attack Index** - References 50+ attack types with documentation paths
2. **Methodology Frameworks** - PTES, OWASP WSTG, MITRE ATT&CK, Flaw Hypothesis
3. **Coordination** - Guides pentester agent to deploy specialized attack agents
4. **Documentation** - PortSwigger labs, cheat sheets, quickstarts per attack

**Execution**: Delegated to specialized agents (SQL Injection Agent, XSS Agent, SSRF Agent, etc.)

## Attack Categories

**9 categories, 50+ attack types**:
- Injection (6) | Client-Side (6) | Server-Side (6)
- Authentication (4) | API Security (4) | Web Applications (6)
- Cloud & Containers (5) | System (3) | IP Infrastructure (8) | Physical & Social (1)

See `reference/ATTACK_INDEX.md` for complete list with agent mappings.

## Reconnaissance Asset Types

Five asset-specific output formats:
- **Domains** - Subdomains, DNS records, tech stack per subdomain
- **Web Applications** - Endpoints, forms, tech stack, cookies, JS analysis
- **APIs** - REST/GraphQL/WebSocket, auth methods, Swagger docs
- **Network Services** - Port scans, service versions, CVE candidates
- **Cloud Infrastructure** - S3 buckets, EC2 instances, security groups

See `reference/RECONNAISSANCE_OUTPUT.md` for complete format specifications and JSON schemas.

## Final report

See `reference/FINAL_REPORT.md` for complete format specifications of the final report.

## Output Structure

**Complete folder organization** (See `reference/OUTPUT_STRUCTURE.md` for details):

```
outputs/{engagement-name}/
├── report/                         # Complete deliverable package (3 files + appendix)
│   ├── Penetration-Test-Report.docx     # Main report (includes Referenced Files section)
│   ├── Penetration-Test-Report.pdf      # Optional PDF export
│   ├── pentest-report.json              # Machine-readable export
│   └── appendix/                        # Referenced evidence only
│       ├── finding-001/
│       ├── finding-002/
│       └── reconnaissance-summary.json
└── processed/                      # All working/testing artifacts
    ├── reconnaissance/             # Phase 2 outputs
    │   ├── inventory/
    │   ├── analysis/
    │   └── reconnaissance_report.md
    ├── findings/                   # Phase 4 raw findings
    │   └── {finding-id}/
    ├── activity/                   # NDJSON logs
    │   └── {executor-name}.log
    ├── helpers/                    # Testing utilities
    ├── test-frameworks/            # Testing scripts
    └── intermediate-reports/       # Drafts, markdown source, etc.
```

**Critical**: `report/` = 3 files max + appendix/ subfolder. ALL intermediate files go to `processed/`.

## Methodologies

**PTES** - 7-phase engagement lifecycle
**OWASP WSTG** - 11 testing categories
**MITRE ATT&CK** - TTP mapping across 14 phases
**Flaw Hypothesis** - Stack analysis → Predict → Test → Generalize → Correlate

## Integration

- `/authenticating` - Authentication testing workflows
- `/ai-threat-testing` - LLM vulnerability testing
- `/domain-assessment` - Domain reconnaissance
- `/web-application-mapping` - Web app reconnaissance
- `/cve-testing` - CVE vulnerability testing

## Critical Rules

### Testing Rules
- **Orchestration only** - Never execute attacks directly
- **Delegate execution** - Deploy specialized agents for testing
- **Documentation index** - Reference attack folders for techniques
- **Working PoCs required** - Specialized agents must provide evidence
- **Activity logging** - All agents log actions to NDJSON activity logs

### Output Organization Rules (PHASE 6 - CRITICAL)
- **Two-folder structure ONLY**: `report/` (final deliverables) and `processed/` (working files)
- **NO files in engagement root**: Everything must be in `report/` or `processed/`
- **Report folder contents**: ONLY pentest-report.json, README.md, appendix/ folder (max 2-3 files + 1 folder)
- **ALL intermediate files → processed/**: .md files, drafts, analysis, summaries, checklists
- **Reconnaissance → processed/reconnaissance/**: ALL recon outputs
- **Findings → processed/findings/**: ALL raw finding details
- **Activity logs → processed/activity/**: ALL NDJSON logs
- **Test frameworks → processed/test-frameworks/**: SQL injection, command injection scripts
- **Markdown reports → processed/intermediate-reports/**: pentest-final-report.md, executive-summary.md, etc.
- **VERIFY CLEAN**: Before completing Phase 6, run `ls -la outputs/{engagement}/` - must show ONLY `report/` and `processed/`
