Attack Surface Mapping
Discover and inventory every entry point where external data enters the application. Produces a ranked catalog of all routes, APIs, input handlers, and external interfaces organized by exposure level and trust boundary.
Supported Flags
Read ../../shared/schemas/flags.md for the full flag specification.
| Flag | Attack Surface Behavior |
|---|---|
--scope | Default full. Attack surface mapping benefits from whole-codebase visibility. Narrow scopes produce partial inventories with a warning. |
--depth quick | Framework route extraction only (Grep for route decorators and definitions). |
--depth standard | Route extraction + read handlers to classify input types and auth requirements. |
--depth deep | Standard + trace each entry point to internal sinks, map trust boundary crossings. |
--depth expert | Deep + rank by exploitability, identify shadow/undocumented endpoints, DREAD scoring. |
--severity | Not directly applicable. Used to filter the exposure ranking in output. |
--format | Default text. Use json for machine-readable inventory, md for wiki export. |
Workflow
Step 1: Determine Scope
- Parse
--scopeflag. Default tofullfor this skill (attack surface requires broad visibility). - Resolve to a concrete file list.
- Prioritize discovery in: route files, controller directories, API definitions, middleware, OpenAPI/Swagger specs, GraphQL schemas, gRPC proto files, CLI entry points, WebSocket handlers.
Step 2: Discover Framework and Language
Identify the application framework(s) to determine route registration patterns:
| Framework | Route Pattern |
|---|---|
| Express/Koa/Fastify | app.get(), router.post(), fastify.route() |
| Django | urlpatterns, path(), re_path(), @api_view |
| Flask | @app.route(), @blueprint.route() |
| Spring | @GetMapping, @PostMapping, @RequestMapping |
| Rails | routes.rb, resources:, get '/' |
| Next.js/Nuxt | pages/ and app/ directory conventions, route.ts |
| ASP.NET | [HttpGet], [Route], MapGet(), MapPost() |
| Go net/http | http.HandleFunc(), mux.Handle(), gorilla/chi patterns |
| FastAPI | @app.get(), @router.post() |
| gRPC | .proto service definitions, generated server stubs |
| GraphQL | Schema definitions, resolver registrations |
Step 3: Extract Entry Points
For each framework detected, systematically extract all entry points:
- HTTP Routes: Method, path, handler function, middleware chain.
- API Endpoints: REST, GraphQL queries/mutations, gRPC services.
- Form Handlers: HTML form action targets, multipart upload handlers.
- File Upload Endpoints: Endpoints accepting file data, storage destinations.
- WebSocket Handlers: Connection endpoints, message handlers.
- CLI Arguments: Argument parsers (
argparse,commander,cobra,clap). - Message Queue Consumers: Kafka/RabbitMQ/SQS message handlers.
- Scheduled Tasks: Cron jobs, scheduled functions that process external data.
- Webhook Receivers: Endpoints accepting callbacks from external services.
- Server-Sent Events: SSE endpoints, streaming responses.
Step 4: Classify Each Entry Point
For every discovered entry point, determine:
- Authentication: None, API key, session, JWT, OAuth, mTLS, or unknown.
- Authorization: None, role-based, attribute-based, or unknown.
- Input Types: Query params, path params, headers, body (JSON/XML/form), files, cookies.
- Validation: Present (with details) or absent.
- Rate Limiting: Present or absent.
- Network Exposure: Internet-facing, internal network, localhost only.
- Protocol: HTTP, HTTPS, WebSocket, gRPC, raw TCP, message queue.
Step 5: Rank by Exposure
Assign an exposure level to each entry point:
| Level | Criteria |
|---|---|
| CRITICAL | Internet-facing, no authentication, accepts user input, interacts with sensitive data or system resources |
| HIGH | Internet-facing with authentication but handling sensitive data, or unauthenticated endpoints with limited input validation |
| MEDIUM | Authenticated endpoints with proper validation, or internal endpoints with no authentication |
| LOW | Internal endpoints with authentication, limited input surface, or read-only operations on non-sensitive data |
At --depth deep and --depth expert, trace each HIGH/CRITICAL entry point inward to identify what sinks they reach (databases, file system, external services, system commands).
Step 6: Identify Shadow Endpoints
At --depth expert, look for:
- Debug/admin routes not behind auth middleware (e.g.,
/debug,/admin,/metrics,/healthexposing internals). - Routes registered dynamically or via reflection that don't appear in static route lists.
- Endpoints in test/staging configuration that may be active in production.
- API versions that are deprecated but still routed.
- OpenAPI/Swagger UI exposed without authentication.
Step 7: Report
Output the attack surface inventory.
Output Format
This skill produces an inventory, not vulnerability findings. However, when entry points have clearly missing security controls (no auth on sensitive endpoints), emit findings using the standard schema from ../../shared/schemas/findings.md.
Finding ID prefix: SURF (e.g., SURF-001).
Inventory Table
## Attack Surface Inventory
### Summary
- Total entry points: N
- Internet-facing: N (N unauthenticated)
- Internal: N
- Exposure: N CRITICAL, N HIGH, N MEDIUM, N LOW
### Entry Points by Exposure
| # | Method | Path | Auth | Input Types | Validation | Rate Limit | Exposure |
|---|--------|------|------|-------------|------------|------------|----------|
| 1 | POST | /api/v1/users | None | JSON body | None | No | CRITICAL |
| 2 | GET | /api/v1/users/:id | JWT | Path param | Partial | Yes | MEDIUM |
| ... |
### Trust Boundary Map (--depth deep)
[Mermaid diagram showing entry points grouped by trust boundary]
### Shadow Endpoints (--depth expert)
[Undocumented or debug endpoints discovered]
### Findings
[Standard findings for missing security controls on entry points]Findings follow ../../shared/schemas/findings.md with:
metadata.tool:"attack-surface"metadata.framework: depends on invoking context (ornullif standalone)references.cwe:CWE-16(Configuration),CWE-306(Missing Authentication)
Pragmatism Notes
- Health check endpoints (
/health,/ready) without auth are normal in container orchestration. Only flag if they expose sensitive internal state. - Internal APIs behind a service mesh or VPN still warrant inventory but at lower exposure.
- CLI tools that only run locally have minimal attack surface unless they parse untrusted files.
- Static file serving endpoints are low priority unless directory traversal is possible.