# Explicador de paths de API do F5XC

> Cole a spec OpenAPI / Swagger que você importa para (ou baixa do) F5XC API Protection e ela lista cada path e operação com seu método, parâmetros, request body, respostas, e autenticação.

- Tool: https://ronutz.com/pt-BR/tools/f5xc-api-path-explainer
- Family: Redes

---

## O que faz

Esta ferramenta explica uma especificação OpenAPI ou Swagger - o artefato exato com o qual o F5 Distributed Cloud (XC) API Protection trabalha. O XC importa uma spec OpenAPI (versão 2.0 ou 3.0.x) para construir seu inventário de API e impor um modelo de segurança positivo, e o XC API Discovery gera um Swagger JSON baixável que você pode editar e reimportar. Cole essa spec e esta ferramenta lista cada path e operação com seu método, parâmetros, request body, respostas, e se ela exige autenticação. Roda inteiramente no seu navegador.

## O inventário que ela constrói

Para cada path, a ferramenta percorre cada operação - GET, POST, PUT, PATCH, DELETE, e as demais - e reporta os mesmos detalhes que o XC usa para definir comportamento válido: os parâmetros (nome, localização, e se são obrigatórios), os content types do request body, os response codes, e os security schemes que se aplicam. Ela resolve parâmetros $ref locais dentro do documento, então um parâmetro definido uma vez e referenciado em várias operações é mostrado por completo em cada uso. O resumo no topo conta os paths, as operações, e quantas são sem autenticação, de nível de objeto, ou deprecadas.

## Autenticação, resolvida corretamente

Se uma operação exige autenticação nem sempre está declarado na própria operação. O OpenAPI deixa você definir um requisito de segurança global e sobrescrevê-lo por operação - e uma operação com uma lista de security vazia é explicitamente pública, mesmo que a API tenha um requisito global. A ferramenta resolve isso da forma que a spec define: uma operação usa seu próprio security se presente, senão o global, e uma lista vazia significa nenhuma autenticação. É por isso que uma operação pode aparecer como sem autenticação mesmo em uma API que na maior parte exige um token.

## Os flags, e por que eles mapeiam para o OWASP

A ferramenta sinaliza duas coisas que importam para a segurança de API. Uma operação sem security efetivo é um risco de Broken Authentication - ela é alcançável sem credenciais. Um endpoint com um parâmetro de path, como /orders/{id}, é um ponto de acesso de nível de objeto e a superfície clássica para Broken Object Level Authorization, o item do topo do OWASP API Security Top 10: a API precisa verificar que o chamador tem permissão para tocar aquele objeto específico, não apenas que ele está logado. Esses são lembretes para verificar seu design de autorização, não prova de uma vulnerabilidade - mas são exatamente os endpoints que vale checar primeiro.

## Standards and references

- [F5 Distributed Cloud: Import OpenAPI Specification to Define API Definition (supported versions: OpenAPI 2.0 and 3.0.x)](https://docs.cloud.f5.com/docs-v2/web-app-and-api-protection/how-to/adv-security/import-openapi-spec) - XC imports OpenAPI 2.0 (Swagger) and 3.0.x specs to build the API inventory (endpoints + methods) and drive OpenAPI Validation as a positive security model
- [F5 Distributed Cloud: Enable API Endpoint Discovery and Schema Learning (downloaded Swagger file is JSON)](https://docs.cloud.f5.com/docs-v2/web-app-and-api-protection/how-to/app-security/apiep-discovery-control) - XC API Discovery learns schemas from traffic and generates a downloadable Swagger JSON that can be edited and re-imported - the same artifact this tool reads
- [OpenAPI Specification (paths, operations, parameters, requestBody, responses, security, components)](https://swagger.io/specification/) - the OpenAPI 2.0/3.x document structure this tool parses, including $ref resolution and security requirement semantics
- [OWASP API Security Top 10 (Broken Object Level Authorization, Broken Authentication, Improper Assets Management)](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) - the risk framing for the flags: unauthenticated operations (Broken Authentication) and object-level path-parameter endpoints (Broken Object Level Authorization)

## Related reading

- [A Spec OpenAPI como o Inventário de API do XC: Paths, Auth e a Sombra](https://ronutz.com/pt-BR/learn/f5xc-openapi-and-api-inventory.md): O XC API Protection é um modelo de segurança positivo construído a partir de uma spec OpenAPI (2.0 ou 3.0.x): os paths e métodos da spec viram o inventário de API que dirige a validação, e endpoints não documentados são Shadow APIs. Isto cobre por que a spec é a fonte da verdade, como o API Discovery gera uma a partir do tráfego, como resolver autenticação corretamente (global vs por operação, e o override público de lista vazia), e por que endpoints com parâmetro de path são a superfície de Broken Object Level Authorization.