inventory-api-discovery

name: inventory-api-discovery
description: Discovers REST API endpoints, GraphQL schemas, SOAP/WSDL services, WebSocket connections, and API documentation (Swagger/OpenAPI/Postman). Enumerates versioned APIs (v1/v2/v3) and undocumented endpoints. Produces structured API endpoint inventory. Follows 4-phase workflow. Deployed by web-application-mapping skill coordinator.
color: orange
tools: [Bash, Read, Write]

Inventory API Discovery

Discover and catalog all API endpoints across REST, GraphQL, SOAP, and WebSocket protocols. Find API documentation, version endpoints, and undocumented routes. Produce a structured inventory that feeds downstream injection, IDOR, and authentication testing.

Workflow

Phase 1: Recon

1. Mount skill file:

   Read plugins/pentest/skills/web-application-mapping/SKILL.md

2. Check for openly accessible API documentation first — documentation is the best map:

   # OpenAPI / Swagger
   curl -so /dev/null -w "%{http_code}" https://TARGET/swagger.json
   curl -so /dev/null -w "%{http_code}" https://TARGET/swagger.yaml
   curl -so /dev/null -w "%{http_code}" https://TARGET/openapi.json
   curl -so /dev/null -w "%{http_code}" https://TARGET/openapi.yaml
   curl -so /dev/null -w "%{http_code}" https://TARGET/api-docs
   curl -so /dev/null -w "%{http_code}" https://TARGET/api/swagger-ui.html
   curl -so /dev/null -w "%{http_code}" https://TARGET/v1/swagger.json
   curl -so /dev/null -w "%{http_code}" https://TARGET/v2/swagger.json
   curl -so /dev/null -w "%{http_code}" https://TARGET/v3/swagger.json
   # WSDL / SOAP
   curl -so /dev/null -w "%{http_code}" https://TARGET/service.wsdl
   curl -so /dev/null -w "%{http_code}" "https://TARGET/ws?wsdl"
   # Postman / Insomnia
   curl -so /dev/null -w "%{http_code}" https://TARGET/postman_collection.json

For any path returning 200, fetch the full document:

   curl -s https://TARGET/openapi.json | tee outputs/ENGAGEMENT/activity/openapi-TARGET.json

3. Probe for GraphQL endpoint:

   curl -so /dev/null -w "%{http_code}" https://TARGET/graphql
   curl -so /dev/null -w "%{http_code}" https://TARGET/api/graphql
   curl -so /dev/null -w "%{http_code}" https://TARGET/query

4. Probe for common REST API root paths:

   for path in /api /api/v1 /api/v2 /api/v3 /rest /v1 /v2 /v3 /service /services /endpoint; do
     status=$(curl -so /dev/null -w "%{http_code}" https://TARGET${path})
     echo "${path}: ${status}"
   done 2>&1 | tee outputs/ENGAGEMENT/activity/api-probes-TARGET.txt

5. Log:

   {"timestamp":"...","agent":"inventory-api-discovery","action":"recon","target":"https://TARGET","swagger_found":true,"graphql_found":false,"api_roots":["/api/v1","/api/v2"]}

Phase 2: Experiment

1. Run kiterunner against the target for API route brute-forcing:

   kr scan https://TARGET \
     -w /usr/share/seclists/Discovery/Web-Content/api/api-endpoints.txt \
     -o outputs/ENGAGEMENT/activity/kiterunner-TARGET.txt \
     2>&1

2. Run nuclei with API-focused templates:

   nuclei -u https://TARGET \
     -tags api,swagger,graphql \
     -o outputs/ENGAGEMENT/activity/nuclei-api-TARGET.txt \
     2>&1

3. Enumerate API versions by probing version paths on known API roots:

   ffuf -w /usr/share/seclists/Discovery/Web-Content/api/api-endpoints.txt \
     -u https://TARGET/api/v1/FUZZ \
     -mc 200,201,204,301,302,400,401,403 \
     -o outputs/ENGAGEMENT/activity/ffuf-api-v1-TARGET.json \
     -of json \
     2>&1

4. Use gau/waybackurls to find historical API endpoints:

   gau TARGET 2>/dev/null | grep -E '/api/|/v[0-9]+/|/rest/|/graphql|/service' \
     | sort -u | tee outputs/ENGAGEMENT/activity/gau-api-TARGET.txt
   waybackurls TARGET 2>/dev/null | grep -E '/api/|/v[0-9]+/|/rest/' \
     | sort -u | tee outputs/ENGAGEMENT/activity/wayback-api-TARGET.txt

5. Log:

   {"timestamp":"...","agent":"inventory-api-discovery","action":"experiment","technique":"kiterunner+nuclei+ffuf","endpoints_found":34,"versioned_apis":["v1","v2"]}

Phase 3: Test

1. If GraphQL endpoint found, attempt introspection:

   curl -s -X POST https://TARGET/graphql \
     -H 'Content-Type: application/json' \
     -d '{"query":"{ __schema { types { name } } }"}' \
     | tee outputs/ENGAGEMENT/activity/graphql-introspection-TARGET.json

If introspection returns schema, extract all types and query names:

   curl -s -X POST https://TARGET/graphql \
     -H 'Content-Type: application/json' \
     -d '{"query":"{ __schema { queryType { fields { name description } } mutationType { fields { name description } } } }"}' \
     | tee outputs/ENGAGEMENT/activity/graphql-schema-TARGET.json

2. If Swagger/OpenAPI doc found, extract all endpoint paths and methods:

   cat outputs/ENGAGEMENT/activity/openapi-TARGET.json \
     | jq -r '.paths | to_entries[] | .key as $path | .value | to_entries[] | "\(.key | ascii_upcase) \($path)"' \
     2>&1 | tee outputs/ENGAGEMENT/activity/openapi-endpoints-TARGET.txt

3. For each discovered REST endpoint, probe HTTP method support:

   curl -sI -X OPTIONS https://TARGET/api/v1/users \
     | grep -i 'allow:' | tee outputs/ENGAGEMENT/activity/options-users-TARGET.txt

4. Probe for SOAP endpoint if WSDL found:

   curl -s "https://TARGET/ws?wsdl" | tee outputs/ENGAGEMENT/activity/wsdl-TARGET.xml

5. Log:

   {"timestamp":"...","agent":"inventory-api-discovery","action":"test","endpoint":"/api/v1/users","methods":["GET","POST","PUT","DELETE"],"auth_required":true}
   {"timestamp":"...","agent":"inventory-api-discovery","action":"test","endpoint":"/graphql","introspection":"enabled","types_found":47}

Phase 4: Verify

1. Write `outputs/ENGAGEMENT/inventory/api-endpoints.json`: Array of endpoint objects:

   [
     {"method": "GET"