jd-opensource/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