pentest-recon-attack-surface

# Pentest Recon Attack Surface

## Purpose
Perform comprehensive attack surface mapping by correlating three data sources: external network scans, authenticated browser exploration, and source code analysis. Produces a structured endpoint inventory with authorization metadata, role/privilege architecture, and prioritized authorization vulnerability candidates for downstream code review and exploitation.

## Prerequisites

### Authorization Requirements
- **Written authorization** with explicit scope for reconnaissance and source code access
- **Source code access** to the target application (white-box engagement)
- **Test accounts** at every privilege level (anonymous, user, admin, service)
- **Network scan approval** — confirm acceptable scan intensity with target owner

### Environment Setup
- nmap, subfinder, httpx, whatweb for external reconnaissance
- Playwright with authenticated browser contexts
- katana or gospider for web crawling
- ffuf for content discovery
- semgrep and ripgrep for source code analysis
- Access to deployment configs (Dockerfile, docker-compose, k8s manifests)

## Core Workflow
1. **Technology Fingerprinting**: Run whatweb + httpx to identify frameworks, languages, server versions, WAF presence, and response header signatures.
2. **External Scan Correlation**: Execute nmap service scan + subfinder subdomain enumeration. Cross-reference discovered services against deployment configs (docker-compose ports, k8s service definitions) to identify exposed vs internal-only services.
3. **Interactive Browser Exploration**: Authenticated Playwright crawl at each privilege level. Capture all XHR/fetch requests, form submissions, WebSocket connections, and dynamic route transitions. Record request/response pairs with auth context.
4. **Route Mapper**: Parse all backend route definitions from source code with file:line pointers. Extract HTTP method, path pattern, middleware chain, and handler function for every endpoint.
5. **Authorization Checker**: For each route, trace the middleware chain to identify auth/authz enforcement. Flag endpoints missing authentication middleware or with inconsistent authorization patterns.
6. **Input Validator**: Analyze validation logic per parameter — identify parameters with no server-side validation, client-only validation, or incomplete validation (e.g., type check but no range check).
7. **Session Handler**: Trace token lifecycle from issuance through validation to expiry. Map session storage mechanism, token rotation policy, and logout invalidation behavior.
8. **Authorization Architecture**: Synthesize role definitions, permission assignments, and privilege lattice from source code. Identify horizontal/vertical/workflow authorization vulnerability candidates.

## Output Deliverables

| Deliverable | Description |
|-------------|-------------|
| API Endpoint Inventory | Table: method, path, auth_required, roles_allowed, validation_summary, file:line |
| Network Interaction Map | External services, internal services, exposed ports, subdomain inventory |
| Role & Privilege Architecture | Role hierarchy, permission matrix, privilege escalation paths |
| Authorization Vulnerability Candidates | Prioritized list of endpoints with suspected authz gaps |
| Session Architecture | Token type, storage, rotation, expiry, invalidation behavior |

## Tool Categories

| Category | Tools | Purpose |
|----------|-------|---------|
| Fingerprinting | whatweb, httpx, wappalyzer | Technology and framework identification |
| Network Recon | nmap, subfinder, amass | Service discovery and subdomain enumeration |
| Web Crawling | Playwright, katana, gospider | Authenticated crawling and dynamic exploration |
| Content Discovery | ffuf, feroxbuster | Hidden endpoint and directory discovery |
| Code Analysis | semgrep, ripgrep, ast-grep | Route extraction and middleware tracing |
| Config Analysis | manual review | Deployment config correlation |

## References
- `references/tools.md` - Tool function signatures and parameters
- `references/workflows.md` - Reconnaissance workflow definitions and correlation procedures