api-attack-surface-mapper

name: api-attack-surface-mapper description: Build a full API inventory, trust-boundary map, and prioritized test matrix from specification and observed behavior.

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.