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
--scope flag. Default to full for 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, /health exposing 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 (or null if 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.
1---2name: attack-surface3description: This skill should be used when the user asks to "map attack surface", "list entry points", "inventory API endpoints", "find all inputs", "enumerate routes", "discover exposed endpoints", or "map external interfaces". Also triggers when the user asks about exposed APIs, form handlers, file upload endpoints, WebSocket handlers, CLI argument parsers, or wants to understand where external data enters the system.4---56# Attack Surface Mapping78Discover and inventory every entry point where external data enters the9application. Produces a ranked catalog of all routes, APIs, input handlers,10and external interfaces organized by exposure level and trust boundary.1112## Supported Flags1314Read `../../shared/schemas/flags.md` for the full flag specification.1516| Flag | Attack Surface Behavior |17|------|------------------------|18| `--scope` | Default `full`. Attack surface mapping benefits from whole-codebase visibility. Narrow scopes produce partial inventories with a warning. |19| `--depth quick` | Framework route extraction only (Grep for route decorators and definitions). |20| `--depth standard` | Route extraction + read handlers to classify input types and auth requirements. |21| `--depth deep` | Standard + trace each entry point to internal sinks, map trust boundary crossings. |22| `--depth expert` | Deep + rank by exploitability, identify shadow/undocumented endpoints, DREAD scoring. |23| `--severity` | Not directly applicable. Used to filter the exposure ranking in output. |24| `--format` | Default `text`. Use `json` for machine-readable inventory, `md` for wiki export. |2526## Workflow2728### Step 1: Determine Scope29301. Parse `--scope` flag. Default to `full` for this skill (attack surface requires broad visibility).312. Resolve to a concrete file list.323. Prioritize discovery in: route files, controller directories, API definitions, middleware,33 OpenAPI/Swagger specs, GraphQL schemas, gRPC proto files, CLI entry points, WebSocket handlers.3435### Step 2: Discover Framework and Language3637Identify the application framework(s) to determine route registration patterns:3839| Framework | Route Pattern |40|-----------|--------------|41| Express/Koa/Fastify | `app.get()`, `router.post()`, `fastify.route()` |42| Django | `urlpatterns`, `path()`, `re_path()`, `@api_view` |43| Flask | `@app.route()`, `@blueprint.route()` |44| Spring | `@GetMapping`, `@PostMapping`, `@RequestMapping` |45| Rails | `routes.rb`, `resources :`, `get '/'` |46| Next.js/Nuxt | `pages/` and `app/` directory conventions, `route.ts` |47| ASP.NET | `[HttpGet]`, `[Route]`, `MapGet()`, `MapPost()` |48| Go net/http | `http.HandleFunc()`, `mux.Handle()`, gorilla/chi patterns |49| FastAPI | `@app.get()`, `@router.post()` |50| gRPC | `.proto` service definitions, generated server stubs |51| GraphQL | Schema definitions, resolver registrations |5253### Step 3: Extract Entry Points5455For each framework detected, systematically extract all entry points:56571. **HTTP Routes**: Method, path, handler function, middleware chain.582. **API Endpoints**: REST, GraphQL queries/mutations, gRPC services.593. **Form Handlers**: HTML form action targets, multipart upload handlers.604. **File Upload Endpoints**: Endpoints accepting file data, storage destinations.615. **WebSocket Handlers**: Connection endpoints, message handlers.626. **CLI Arguments**: Argument parsers (`argparse`, `commander`, `cobra`, `clap`).637. **Message Queue Consumers**: Kafka/RabbitMQ/SQS message handlers.648. **Scheduled Tasks**: Cron jobs, scheduled functions that process external data.659. **Webhook Receivers**: Endpoints accepting callbacks from external services.6610. **Server-Sent Events**: SSE endpoints, streaming responses.6768### Step 4: Classify Each Entry Point6970For every discovered entry point, determine:71721. **Authentication**: None, API key, session, JWT, OAuth, mTLS, or unknown.732. **Authorization**: None, role-based, attribute-based, or unknown.743. **Input Types**: Query params, path params, headers, body (JSON/XML/form), files, cookies.754. **Validation**: Present (with details) or absent.765. **Rate Limiting**: Present or absent.776. **Network Exposure**: Internet-facing, internal network, localhost only.787. **Protocol**: HTTP, HTTPS, WebSocket, gRPC, raw TCP, message queue.7980### Step 5: Rank by Exposure8182Assign an exposure level to each entry point:8384| Level | Criteria |85|-------|----------|86| **CRITICAL** | Internet-facing, no authentication, accepts user input, interacts with sensitive data or system resources |87| **HIGH** | Internet-facing with authentication but handling sensitive data, or unauthenticated endpoints with limited input validation |88| **MEDIUM** | Authenticated endpoints with proper validation, or internal endpoints with no authentication |89| **LOW** | Internal endpoints with authentication, limited input surface, or read-only operations on non-sensitive data |9091At `--depth deep` and `--depth expert`, trace each HIGH/CRITICAL entry point92inward to identify what sinks they reach (databases, file system, external93services, system commands).9495### Step 6: Identify Shadow Endpoints9697At `--depth expert`, look for:9899- Debug/admin routes not behind auth middleware (e.g., `/debug`, `/admin`, `/metrics`, `/health` exposing internals).100- Routes registered dynamically or via reflection that don't appear in static route lists.101- Endpoints in test/staging configuration that may be active in production.102- API versions that are deprecated but still routed.103- OpenAPI/Swagger UI exposed without authentication.104105### Step 7: Report106107Output the attack surface inventory.108109## Output Format110111This skill produces an **inventory**, not vulnerability findings. However, when112entry points have clearly missing security controls (no auth on sensitive113endpoints), emit findings using the standard schema from `../../shared/schemas/findings.md`.114115Finding ID prefix: **SURF** (e.g., `SURF-001`).116117### Inventory Table118119```120## Attack Surface Inventory121122### Summary123- Total entry points: N124- Internet-facing: N (N unauthenticated)125- Internal: N126- Exposure: N CRITICAL, N HIGH, N MEDIUM, N LOW127128### Entry Points by Exposure129130| # | Method | Path | Auth | Input Types | Validation | Rate Limit | Exposure |131|---|--------|------|------|-------------|------------|------------|----------|132| 1 | POST | /api/v1/users | None | JSON body | None | No | CRITICAL |133| 2 | GET | /api/v1/users/:id | JWT | Path param | Partial | Yes | MEDIUM |134| ... |135136### Trust Boundary Map (--depth deep)137[Mermaid diagram showing entry points grouped by trust boundary]138139### Shadow Endpoints (--depth expert)140[Undocumented or debug endpoints discovered]141142### Findings143[Standard findings for missing security controls on entry points]144```145146Findings follow `../../shared/schemas/findings.md` with:147- `metadata.tool`: `"attack-surface"`148- `metadata.framework`: depends on invoking context (or `null` if standalone)149- `references.cwe`: `CWE-16` (Configuration), `CWE-306` (Missing Authentication)150151## Pragmatism Notes152153- Health check endpoints (`/health`, `/ready`) without auth are normal in container orchestration.154 Only flag if they expose sensitive internal state.155- Internal APIs behind a service mesh or VPN still warrant inventory but at lower exposure.156- CLI tools that only run locally have minimal attack surface unless they parse untrusted files.157- Static file serving endpoints are low priority unless directory traversal is possible.
florianbuetow