API Attack Surface Mapper

Inventário determinístico de OpenAPI com sinais OWASP API Security e exportação para RedReport.

Visão geral

O API Attack Surface Mapper (asm) analisa contratos OpenAPI localmente, sem enviar requisições para a API. Ele normaliza operações, autenticação, parâmetros, schemas e respostas para produzir sinais de revisão reproduzíveis.

O MVP oferece:

• suporte a OpenAPI 3.0, 3.1 e 3.2 em YAML ou JSON;
• herança e override de Security Requirement Objects;
• inventário de método, rota, operationId, autenticação e parâmetros;
• 11 regras determinísticas mapeadas ao OWASP API Security Top 10 2023;
• severidade, confiança, evidência, CWE e orientação de correção;
• saída humana ou JSON e quality gate por severidade;
• projeto RedReport completo com a especificação preservada como evidência.

Fluxo

flowchart LR
    A[OpenAPI YAML / JSON] --> B[Parser]
    B --> C[Endpoint inventory]
    C --> D[Deterministic rules]
    D --> E[OWASP / CWE signals]
    E --> F[JSON / CI gate]
    E --> G[RedReport project]

Loading

Instalação

git clone https://github.com/guuszz/api-attack-surface.git
cd api-attack-surface
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"

Uso

Validar e interpretar o contrato:

asm validate examples/demo-api.yaml

Inventariar operações:

asm inventory examples/demo-api.yaml
asm inventory examples/demo-api.yaml --json

Executar análise:

asm scan examples/demo-api.yaml
asm scan examples/demo-api.yaml --json

Usar como quality gate:

asm scan openapi.yaml --fail-on high

O comando retorna exit code 3 quando encontra um sinal na severidade configurada ou acima.

Exportar para o RedReport:

asm export redreport examples/demo-api.yaml \
  --output reports/generated/demo-api \
  --client "Portfolio Lab"

redreport validate reports/generated/demo-api
redreport build reports/generated/demo-api

Regras

ID	Sinal	OWASP API Security
ASM001	Operação anônima com identificador de objeto	API1:2023
ASM002	Função sensível ou mutável anônima	API5:2023
ASM003	Fluxo de negócio sensível anônimo	API6:2023
ASM004	API key transportada na query string	API2:2023
ASM005	Operação protegida sem respostas 401/403	API5:2023
ASM006	Array de entrada sem maxItems	API4:2023
ASM007	Upload binário sem maxLength	API4:2023
ASM008	Servidor OpenAPI em HTTP	API8:2023
ASM009	Propriedade sensível gravável	API3:2023
ASM010	additionalProperties: true	API3:2023
ASM011	Operação sem ID ou depreciada	API9:2023

Esses resultados são sinais baseados no contrato, não confirmação automática de uma vulnerabilidade na implementação.

Integração do portfólio

flowchart LR
    SG[ScopeGuard] --> ASM[API Attack Surface Mapper]
    ASM --> RR[RedReport]
    ASM --> RTL[Red Team Lab]

Loading

• ScopeGuard: valida servidores e alvos antes de qualquer etapa ativa futura.
• API Attack Surface Mapper: transforma o contrato em inventário e hipóteses testáveis.
• Red Team Lab: organiza a validação controlada das hipóteses.
• RedReport: entrega os sinais confirmados em Markdown e HTML.

Qualidade

python -m ruff check .
python -m pytest
python -m build

Roadmap

• resolução completa de referências locais encadeadas;
• exportação SARIF;
• integração direta com ScopeGuard;
• comparação de superfície entre duas versões OpenAPI;
• dashboard HTML de rotas, autenticação e cobertura.

Referências

• OWASP API Security Top 10 — 2023
• OpenAPI Specification

Licença

MIT