astrolabe

astrolabe maps the private API behind a website you're authorized to test — the GraphQL and REST calls a page makes once you're logged in — and turns what it observes into a typed, versioned contract instead of a one-off scrape. Point it at a domain with a browser session, and it gives you back an executable inventory of every operation it saw, with proof of what actually worked.

Alpha safety boundary: default generation and execution expose only operations classified as queries from trusted evidence. Persisted/unknown operations are inventory-only; recipes are executable code and require explicit trust acknowledgement. Historical example artifacts are documentation, not fresh executable contracts.

What it does

A capture host drives a real, logged-in browser session against the target site (via a Playwright-style browser automation layer, proxied through Burp with a Cloudflare-challenge fallback), records every GraphQL/REST/WebSocket call it makes, and hands the traffic to a local analysis pipeline:

• capture — record real traffic from a real session (GraphQL, REST, WebSocket/socket.io), shape-only by default (no payload values persisted)

• analyze — turn a capture into a human-readable map (map.md) and a machine-readable endpoint inventory (endpoints.json)

• contract — build a durable, versioned, typed contract of every operation observed, merged across runs so completeness and drift are tracked over time, with optional active re-verification

• mcp-gen — generate a typed MCP toolpack from a capture, so an agent can call the site's own API directly instead of scraping HTML

• scan — a deterministic, evidence-grounded source scan (sitemap, DOM, service worker, bundle/chunk-manifest mining) that scaffolds a per-site recipe from what it actually found, not from guesses

• replay — browserless, TLS-fingerprint-matched, high-frequency re-execution of a single operation, for monitoring or parameter enumeration without a browser per request

Related MCP server: Hydra ACI

Bring your own cookies

astrolabe never reads or decrypts your browser's cookie store. Authentication is entirely bring-your-own: export your session as a Playwright-format cookie JSON file and pass it with --cookies-file. There is no --browser/ --profile flag and no code path that touches Chrome/Chromium/Vivaldi/Edge/ Brave's local cookie database. If you need cookies from a browser, export them yourself (e.g. with a Playwright storage_state() dump or a cookie-export extension) before running astrolabe.

Install

uv sync --extra dev
uv run playwright install chromium

Requires Python 3.11+. Plain Playwright is a core dependency, so astrolabe map --local example.com works clone-and-go on any machine right after the two commands above — no separate capture host and no stealth engine required. The capture tier can also run against a remote "capture host" (--host, or bare astrolabe map when the profile resolves to one) through the same browser layer; the analysis/contract/mcp-gen/replay tiers are pure Python and run anywhere.

Browser backend

astrolabe drives the browser through a small pluggable layer (astrolabe/browser.py) with two backends:

• playwright (default, always available) — plain Chromium via Playwright. This is what makes the local demo clone-and-go.

• cloakbrowser (optional) — a stealth, Cloudflare-hardened Playwright-compatible driver for bot-protected targets. Install it with:

  pip install astrolabe[stealth]

Selection is automatic: ASTROLABE_BROWSER=auto (the default) uses cloakbrowser when it's installed, otherwise falls back to plain Playwright. Set ASTROLABE_BROWSER=playwright or ASTROLABE_BROWSER=cloakbrowser to pin one explicitly; pinning to cloakbrowser without the extra installed fails fast with an install hint rather than silently falling back.

Usage

astrolabe preflight                          # health + egress-safety check

astrolabe scan https://example.com/catalog \
    [--operator-seed https://example.com/search] \
    [--max-total-requests 100 --max-static-resources 25] \
    [--account-risk sensitive --delay-ms 750] \
    [--working-hours-utc 9-17] \
    [--authorized-path /catalog --prohibited-path /account]
    # -> scan.json + scan.md + an evidence-grounded recipe scaffold

astrolabe map example.com \
    --cookies-file cookies.json \            # bring-your-own Playwright cookie export
    --recipe surfaces/example.com.recipe.py \  # per-site interactions (optional)
    [--schema]     # recover GraphQL schema if introspection is off + suggestions leak
    [--openapi]    # first-party REST OpenAPI (host-side; HAR never leaves the host)
    [--no-auth]    # anonymous target (skip cookies entirely)
    [--seeds URL,URL] [--crawl N] [--out DIR]
    # -> contract.md (contract of record) + map.md + endpoints.json

astrolabe contract <capture-dir> \        # versioned typed inventory + observation/proof history
    [--merge prior/contract.json]           # union across runs (completeness) + drift
    [--execute --cookies-file cookies.json --domain example.com]  # actively re-verify
    # -> contract.json (contract of record) + contract.md (coverage scorecard)

astrolabe mcp-gen <capture-dir> \         # generate a typed MCP toolpack from a capture
    --overrides surfaces                    # use curated minimal queries where available
    # -> toolpack.json: typed tools only for safely classified, runtime-compatible ops.
    # Serve with `astrolabe-mcp` (FastMCP; env: ASTROLABE_TOOLPACK/COOKIES/AUTH).

astrolabe replay example.com --op op.json \   # browserless, TLS-matched, high-frequency replay
    --cookies-file cookies.json --auth-file auth.map.json \  # both bring-your-own
    [--vary 'dotpath=a,b,c'] [--repeat N] [--interval S]

astrolabe scan fuses sitemap, DOM/navigation, service-worker, operator-seed, bundle, chunk manifest, dynamic-import, and source-map evidence without flattening provenance or confidence. It never invents an executable operation from a static candidate — it hands you evidence to review, not a guess.

Status

Alpha. This is the reusable core of a larger internal tool, extracted and made target-neutral for public reference; the remote orchestration pieces (SSH to a capture host, Burp/CF-challenge-fallback wiring) assume you already have that infrastructure or run everything with --local.

License

MIT — see LICENSE.