/recon

Phase 1 — RECON

You are performing Phase 1 (Recon) of the API reverse engineering workflow. Your goal is to build a Page Context Document — a comprehensive profile of the target site derived entirely from captured HAR traffic.

Input

The user will provide:

1. Target page — the URL they want to reverse-engineer
2. Data of interest — what they want to extract (e.g., events, odds, products, prices)
3. HAR file(s) — path to a .har file or a directory containing them

If the user hasn't provided all three, ask for the missing pieces before proceeding.

Procedure

Step 1 — Load the capture

Use load_har to ingest the HAR file(s). Confirm how many entries and sessions were loaded.

Step 2 — Overview & domain classification

1. Call har_overview to get summary statistics.
2. Call har_domains to list every domain contacted.
3. Classify each domain into one of these categories:
   • Data API — serves JSON/XML responses, dynamic data the user cares about
   • Static assets — JS bundles, CSS, images, fonts
   • Analytics/Tracking — Google Analytics, Facebook Pixel, Hotjar, Sentry, etc.
   • CDN — content delivery, caching layers
   • Other — anything that doesn't fit above
4. Identify which domains are likely to serve the data the user asked about. Remember: the API domain may be completely different from the target page domain.

Step 3 — API surface analysis

For each domain classified as Data API:

1. Call har_endpoints filtered to that domain to list all unique endpoints.
2. Determine the API style: REST, GraphQL, RPC, or mixed.
   • Look for /graphql paths or query/mutation in request bodies.
   • Look for RESTful path patterns with resource names and IDs.
3. Identify base URL patterns (e.g., api.example.com/v2/...).

Step 4 — Auth & session detection

1. Call har_search_headers with name_pattern matching common auth headers: authorization, x-auth, x-api-key, x-csrf, x-xsrf, bearer.
2. Call har_cookies to find session/auth cookies (look for names containing: token, auth, session, csrf, jwt, sid).
3. Determine:
   • Auth mechanism: cookies, bearer tokens, API keys, or combination
   • Whether public data flows without authentication
   • Any tokens embedded in the initial page load

Step 5 — Protection layer detection

1. Call har_search_headers looking for CDN/WAF signatures:
   • Cloudflare: cf-ray, cf-cache-status
   • Akamai: x-akamai
   • Fastly: x-served-by, x-fastly
   • AWS CloudFront: x-amz-cf
   • Imperva: x-iinfo
2. Call har_search_bodies with pattern looking for CAPTCHA scripts: recaptcha, hcaptcha, turnstile, challenges.cloudflare.
3. Look for browser fingerprinting or request signing patterns in headers.

Step 6 — Real-time layer detection

1. Call har_search_headers with name_pattern="upgrade" and value_pattern="websocket" to find WebSocket connections.
2. Call har_search with mime_type="event-stream" to find SSE connections.
3. For any real-time connections found, note the domain, path, and protocol hints.

Step 7 — Frontend stack detection

1. Call har_search_bodies in response bodies looking for framework signatures:
   • React: __REACT, _reactRootContainer, react-dom
   • Angular: ng-version, ng-app, angular
   • Vue: __VUE, vue-router, vuex
   • Next.js: __NEXT_DATA__, _next/
   • Nuxt: __NUXT__
2. Look at the JS bundle URLs and content types for clues about the HTTP client library (axios, fetch wrappers).

Output

Produce a Page Context Document with these sections:

1. Site Overview

One-paragraph plain-language summary of what the site is, what stack it uses, and where data comes from.

2. Domain Map

Table of every domain contacted, classified by category, with request counts.

3. API Surface

• Data API domains and their base URL patterns
• API style (REST / GraphQL / RPC / mixed)
• Key endpoints that likely serve the user's data of interest

4. Auth & Session

• Auth mechanism identified
• Required tokens/cookies
• Whether public data is accessible without auth

5. Protection Layer

• CDN/WAF detected
• CAPTCHA presence
• Anti-bot measures
• Initial feasibility assessment

6. Real-time Layer

• WebSocket/SSE connections found
• Domains and protocols

7. Frontend Stack

• Framework, HTTP client, state management hints

8. Open Source Intelligence

Before finalizing, search the web and any available source code for additional context about the target's API:

1. Web search for the target domain + "API", "GraphQL", "websocket", "developer docs", "swagger", "openapi"
2. Web search for the target + "reverse engineer", "scraping", "bot", "unofficial API"
3. GitHub search for repositories mentioning the target domain or API
4. Check for official API documentation, developer portals, or partner APIs
5. Look for blog posts, forum threads, or open-source projects that have already reverse-engineered parts of this API

Document any findings:

• Official or unofficial API documentation
• Known rate limits or anti-bot measures reported by others
• Open-source clients or libraries for this API
• Developer community discussions about the API
• Any GraphQL schema dumps, introspection results, or Postman collections shared publicly

9. Recommended Next Steps

• Which endpoints to focus on in Phase 2 (Mapping)
• Whether additional captures are needed
• Which specialist agents are best suited for the detected API style and transport framework
• Any early warnings about feasibility

Format the document clearly with markdown headers and tables. Save the document to .apiregen/reports/page-context.md. This document will be referenced in all subsequent phases.

Auto-delegation to specialist agents

After the Page Context Document is written, dispatch the appropriate specialist(s) via the Agent tool based on detected signals. Multiple specialists may apply to the same target:

• rest-api-specialist — invoke when versioned REST paths (/api/v1/, /rest/), REST envelopes ({data, meta}), pagination params (offset/limit/cursor), Bearer/API-key auth, or REST client libraries (axios, fetch, Retrofit, OkHttp) are detected.
• graphql-specialist — invoke when a /graphql endpoint accepting {query, variables}, GraphQL operation strings (query/mutation/subscription), AST literals in JS bundles, persisted-query fields (documentId, sha256Hash), or Apollo/Relay/urql client signatures are detected.
• websocket-specialist — invoke when WebSocket upgrade handshakes, ws:///wss:// URLs, graphql-ws / socket.io / SignalR / STOMP / MQTT signatures, binary frame handling (Protobuf/MessagePack), or real-time data (live odds, live scores, chat, streams) are detected.
• grpc-transport-specialist — invoke when gRPC, gRPC-Web, Connect, Twirp, Protobuf-over-HTTP, service/method paths, grpc-status, grpc-timeout, connect-protocol-version, or generated Protobuf clients are detected.
• realtime-framework-specialist — invoke when Socket.IO, SignalR, STOMP, MQTT-over-WebSocket, Phoenix Channels, Pusher, Ably, Centrifugo, Mercure, SSE/EventSource, or long-polling fallback patterns are detected.
• rpc-transport-specialist — invoke when JSON-RPC, tRPC, XML-RPC, SOAP, OData actions/functions, batch endpoints, or custom command/action envelopes are detected.
• mobile-transport-specialist — invoke for APK/mobile app targets or when OkHttp, Retrofit, Volley, Ktor, URLSession, Alamofire, Moya, native interceptors, certificate pinning, attestation, or mobile-only headers are detected.

Pass each specialist the path to the saved Page Context Document and the relevant HAR path so it can continue from the recon findings without repeating discovery work.