API Attack Surface Mapper

API Attack Surface Mapper

When To Use

Use this skill when you need high coverage before exploitation.

When Not To Use

Do not use this as a replacement for exploit confirmation. It is a discovery and planning skill.

Required Inputs

• target_base_url
• api_spec_source (OpenAPI URL/file, Postman collection, or captured traffic)
• auth_context (token types, role accounts, session rules)
• scope_rules (in-scope services, forbidden actions)

Optional Inputs

• known_business_flows
• environment_limits (rate limits, test windows)
• seed_ids (known object identifiers)

Preflight Checklist

• Spec is reachable and parseable.
• Base URL and version path are confirmed.
• Auth mechanism is known per endpoint family.
• Scope exclusions are explicit.

Execution Workflow

Phase 1: Normalize Inputs

1. Parse spec and resolve path templates, tags, and schema references.
2. Deduplicate routes by method + canonical path.
3. Flag undocumented endpoints observed in traffic.

Phase 2: Build Trust-Boundary Map

1. Label endpoints as public, user, admin, internal, or unknown.
2. Map auth styles: cookie session, bearer token, API key, mTLS.
3. Capture identity source and role enforcement points.

Phase 3: Parameter Risk Profiling

1. Classify parameters by risk type:

• object references
• filter/sort/query operators
• file/blob inputs
• callback URLs
• rich text/template fields

2. Mark whether each parameter is attacker-controlled and persisted.

Phase 4: Test Matrix Generation

1. Generate baseline tests for each endpoint (auth, method, content type).
2. Generate abuse tests by class:

• BOLA/BFLA
• mass assignment
• injection
• SSRF-style URL handling
• workflow/state abuse

3. Prioritize by business impact and reachable privilege.

Phase 5: Low-Noise Validation

1. Confirm route liveness and auth expectations.
2. Record response fingerprint per endpoint:

• status bands
• auth error shape
• validation error shape

3. Mark unstable endpoints as low-confidence until retested.

Coverage Matrix (Minimum)

Evidence Requirements

• Endpoint inventory with method/path/auth labels.
• Request templates for each high-priority case.
• Response fingerprints for baseline and negative controls.
• Explicit unknowns and blockers.

Output Contract

Return JSON:

{
  "endpoint_inventory": [],
  "trust_boundaries": [],
  "parameter_risk_profile": [],
  "prioritized_test_matrix": [],
  "baseline_observations": [],
  "coverage_gaps": []
}

Failure Modes

• Treating spec as truth while ignoring runtime drift.
• Assuming role checks from docs instead of testing.
• Ignoring undocumented routes from front-end telemetry.

Exit Criteria

• Inventory covers all observed and documented routes.
• Each high-risk endpoint has at least one concrete test case.
• Unknowns are explicit and actionable.

Detailed Operator Notes

Endpoint Normalization Rules

• Normalize path params to {id} style for deduping.
• Split endpoints by functional domain before prioritization.
• Keep undocumented and documented routes as separate sources.

Prioritization Heuristics

• Highest priority: object-level operations with write capability.
• Next priority: admin-like routes exposed in user-auth context.
• Next priority: import/export and callback endpoints.
• Lower priority: purely informational static metadata routes.

Common Blind Spots

• Versioned paths that differ only by prefix behavior.
• Bulk endpoints with relaxed validation compared to single-item routes.
• Graph-like query parameters that reach data-layer operators.

Reporting Rules

• Include discovery_source per endpoint (spec, traffic, frontend).
• Include auth_assumption and auth_verified flags separately.
• Include priority_reason for every high-risk endpoint.

Conditional Decision Matrix

Advanced Coverage Extensions

1. Add negative-object tests for soft-deleted or archived resources.
2. Add replay-window tests for idempotency and duplicate processing.
3. Add bulk endpoint abuse tests for partial authorization failures.
4. Add asynchronous job handoff checks for stale permission snapshots.
5. Add pagination/filter abuse checks for hidden data exposure.