attack-surface

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

1. Parse --scope flag. Default to full for this skill (attack surface requires broad visibility).
2. Resolve to a concrete file list.
3. 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:

1. HTTP Routes: Method, path, handler function, middleware chain.
2. API Endpoints: REST, GraphQL queries/mutations, gRPC services.
3. Form Handlers: HTML form action targets, multipart upload handlers.
4. File Upload Endpoints: Endpoints accepting file data, storage destinations.
5. WebSocket Handlers: Connection endpoints, message handlers.
6. CLI Arguments: Argument parsers (argparse, commander, cobra, clap).
7. Message Queue Consumers: Kafka/RabbitMQ/SQS message handlers.
8. Scheduled Tasks: Cron jobs, scheduled functions that process external data.
9. Webhook Receivers: Endpoints accepting callbacks from external services.
10. Server-Sent Events: SSE endpoints, streaming responses.

Step 4: Classify Each Entry Point

For every discovered entry point, determine:

1. Authentication: None, API key, session, JWT, OAuth, mTLS, or unknown.
2. Authorization: None, role-based, attribute-based, or unknown.
3. Input Types: Query params, path params, headers, body (JSON/XML/form), files, cookies.
4. Validation: Present (with details) or absent.
5. Rate Limiting: Present or absent.
6. Network Exposure: Internet-facing, internal network, localhost only.
7. 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.