site-endpoint-scan — inventário de endpoints via análise de network

Descobre a superfície de endpoints de um site observando o tráfego de rede real (você navega/loga, a skill registra cada XHR/fetch/WebSocket) e parseando os bundles JS atrás de rotas referenciadas no código. Saída = inventário read-only, não um pacote executável.

Guardrails (não negociáveis). Só rode contra sites onde o usuário tem conta e autorização, com as credenciais dele. Respeite ToS/robots.txt e não faça mass-scraping nem mire contas de terceiros. A sessão/cookies ficam locais em <out>/.session/ e nunca são commitados. Headers de credencial (Authorization/Cookie/API-key) nunca entram no inventário — só registramos que existem. Se o alvo proíbe automação no ToS, avise o usuário e pare.

Irmã da site-to-cli

Esta skill é a versão leve e read-only: para no catálogo/relatório. Se o usuário quiser gerar uma CLI/OpenAPI a partir do site, é a site-to-cli — não reimplemente aqui.

O fluxo (3 passos)

[Capturar network]  →  [Consolidar inventário]  →  [Relatório]
   (Playwright/HAR)        (endpoints.json)            (REPORT.md)

Tudo passa pelo orquestrador scripts/run.ps1 (resolve Node, garante o Playwright na 1ª captura reusando os browsers já instalados). Saídas vão para um run dir <out> (default ./<slug>-scan/).

Antes de tudo: pwsh -NoProfile -File scripts/run.ps1 doctor — confere Node/Playwright/browser.

Passo 1 — Capturar o tráfego

(a) Gravação dirigida por você [principal]. Abre um browser headed; você loga e usa as funções que quer mapear. Ao fechar a janela (ou esgotar --duration), salva o network + a sessão.

pwsh -NoProfile -File scripts/run.ps1 record --url "<URL>" --out "<run>" [--duration 0] [--filter "api|graphql"] [--no-js]

--duration 0 = grava até você fechar a janela. --no-js pula a coleta de bundles (sem JS-parsing). Quanto mais funções você exercitar, mais completo o inventário — clique nas áreas que importam.

(b) Import de HAR pronto. Você já exportou um .har (DevTools → Network → Export HAR, ou Burp):

pwsh -NoProfile -File scripts/run.ps1 import-har --har "<arquivo.har>" --out "<run>"

Passo 2 — Consolidar o inventário

pwsh -NoProfile -File scripts/run.ps1 analyze --out "<run>"

Deduplica os requests, infere path-templates (/orders/123 → /orders/{id}), classifica por protocolo (rest/graphql/websocket), extrai operações GraphQL, detecta o padrão de auth, e parseia os bundles JS atrás de endpoints referenciados mas não chamados. Resultado: <run>/endpoints.json. Contrato do arquivo: references/ENDPOINTS_SCHEMA.md.

Opcional (seu julgamento): antes do relatório, você (modelo) pode preencher o campo summary de cada endpoint em 1 linha e revisar a coluna source — confirmar se um referenced-js é rota real ou código morto. Não invente: marque como incerto o que não trafegou.

Passo 3 — Relatório legível

pwsh -NoProfile -File scripts/run.ps1 report --out "<run>"

Gera <run>/REPORT.md: cabeçalho (base URL, auth, contagens) + tabelas por protocolo (REST · GraphQL · WebSockets · Referenciados-em-JS), separando observado de referenciado.

Atalho

pwsh -NoProfile -File scripts/run.ps1 scan --url "<URL>" --out "<run>"   # record → analyze → report

Como ler a saída

• Observado = o site chamou de fato durante a sua sessão. Alta confiança.
• Referenciado (JS) = string de endpoint encontrada no código mas não disparada. Superfície potencial (rota atrás de um fluxo/role que você não exercitou, ou código morto) — confirme.
• auth: true/🔒 = o request carregava credencial (o valor nunca é gravado).
• GraphQL aparece como um endpoint com a lista de operações; um /graphql ≠ N rotas REST.

Fim

A skill fica inerte no ateliê. Para usá-la num projeto: /install-skill site-endpoint-scan lá dentro. Créditos de inspiração (MIT) nos cabeçalhos dos scripts: AUTO_REVERSE/web-api-analyzer (captura), claude-skill-registry/reverse-engineering-api (filtro de ruído), shuvonsec/claude-bug-bounty (parsing de endpoints em JS).