A OpenAPI Specification (OAS) (anteriormente conhecida como Swagger Specification) é uma forma de descrever e criar documentação para APIs REST, juntamente com seus componentes, como detalhes sobre endpoints, suas operações, parâmetros necessários para as operações, respostas esperadas para cada operação, métodos de autenticação e anotações. A OAS é um formato fácil de aprender e ler, e tanto humanos quanto máquinas podem consumir seus dados, tornando-a aplicável a diversos casos de uso. Neste artigo, abordaremos algumas das maneiras como as equipes de desenvolvimento e segurança utilizam a OAS e por que ela deixa a desejar quando o assunto é proteger suas APIs.
Como o Desenvolvimento utiliza a OAS
Os desenvolvedores utilizam a OAS para gerar documentação para APIs, como arquivos de especificação OpenAPI e arquivos de definição OpenAPI. Essa documentação ajuda outros a entenderem a estrutura e a funcionalidade da API, o que é útil quando outro desenvolvedor deseja integrar uma API para adicionar funcionalidades à sua aplicação.
Muitos desenvolvedores têm uma relação de amor e ódio com a OAS, já que qualquer tempo gasto com documentação é tempo perdido com o desenvolvimento. A OAS é fácil de aprender, mas a documentação é inerentemente tediosa — é manual, demorada e uma das partes menos glamorosas do trabalho de um desenvolvedor. Como resultado, os desenvolvedores geralmente fazem o mínimo possível, deixando a documentação incompleta, imprecisa ou, no pior dos casos, inexistente.
Como a Segurança utiliza a OAS
A documentação OAS ajuda as equipes de segurança a descobrir a existência de uma API e a entender o que ela deve fazer. Com a documentação, as equipes de segurança podem determinar se a API está em conformidade ou viola as políticas. Por exemplo, a segurança pode usar a documentação da API para garantir que a equipe de desenvolvimento tenha implementado a autenticação e a autorização corretamente e não tenha exposto desnecessariamente dados confidenciais, como PII.
As equipes de segurança também podem usar ferramentas de segurança baseadas em OAS para alinhar-se ao que os desenvolvedores pretendiam que a API fizesse, validando a entrada da API com base no que está definido em um arquivo de definição OpenAPI e aplicando políticas.
Utilizando a OAS para Descoberta de API e Validação de Políticas
Em um mundo perfeito, toda API é bem documentada como parte do processo de desenvolvimento. A segurança é informada sobre a documentação e a API antes que ela entre em produção, para que possam avaliar os detalhes, validar se a API está de acordo com a política e aprová-la para lançamento. Como nenhum de nós vive em um mundo perfeito, considere as seguintes perguntas:
A documentação OAS existe? Nos casos mais extremos, a documentação não existe, portanto, não pode ser usada para nenhum tipo de conscientização. A empresa fica com Shadow APIs e riscos não percebidos.
A documentação OAS está completa? Em todos os ambientes que já vimos? Não. Nossos clientes produzem suas documentações com confiança, nossa plataforma analisa o mesmo ambiente e a documentação não corresponde à realidade. As lacunas variam desde documentação incompleta até a falta de detalhes críticos, como destaca o exemplo a seguir, onde a documentação OAS (Swagger) indicava 2 parâmetros e encontramos 27:
Além de faltarem 25 parâmetros, a documentação OAS também carecia de informações importantes sobre onde PII estava sendo exposta, deixando a empresa vulnerável.
A documentação OAS está sendo mantida atualizada? As práticas de desenvolvimento rápido significam que as APIs estão em constante mudança, e a atualização da documentação sempre fica para trás.
Utilizando Ferramentas de Segurança baseadas em OAS para Proteger APIs
As empresas também podem usar a documentação OAS como um esquema para validar a entrada da API, aplicando uma ferramenta de segurança baseada em OAS para garantir que a entrada esteja em conformidade com o que está definido no arquivo de definição OpenAPI. Por exemplo, o arquivo de definição OpenAPI pode especificar que se espera uma string para um parâmetro específico, que essa string não deve exceder um comprimento determinado e que deve conter apenas letras e números, sem caracteres especiais. Qualquer coisa que esteja fora dessa definição será bloqueada.
Uma documentação OAS inexistente, imprecisa e desatualizada torna o inventário e a descoberta de APIs um desafio, além de representar um risco significativo quando se trata de aplicar a segurança.
Depender exclusivamente da documentação OAS para segurança, mesmo que ela seja precisa, cobrirá apenas uma pequena porcentagem do risco criado pelas APIs e, portanto, não impedirá violações de API ou perda de dados. Confiar na documentação OAS também pode impactar negativamente seus clientes, parceiros e operações comerciais, incluindo fluxos de receita, ao bloquear tráfego legítimo.
Abaixo estão os riscos ao depender da documentação OAS para proteger suas APIs:
As ferramentas de segurança baseadas em OAS não conseguem proteger contra as ameaças de API mais comuns e críticas. O OAS não compreende a lógica da API, por isso é impossível criar políticas em um arquivo de definição OpenAPI para prevenir ataques direcionados à lógica da API, como as principais ameaças definidas no OWASP API Security Top 10.
As ferramentas de segurança baseadas em OAS podem ser enganadas e contornadas. O OAS carece de contexto sobre a atividade geral do invasor e, portanto, só consegue bloquear uma chamada de API específica, não o invasor, permitindo que ele faça tentativas infinitas de contornar a validação de esquema baseada em OAS.
As ferramentas de segurança baseadas em OAS correm o risco de bloquear tráfego legítimo. A aplicação da técnica de Validação Estrita bloqueia qualquer chamada de API anormal, incluindo incompatibilidade de padrão de valor de parâmetro, parâmetros desconhecidos ou endpoints desconhecidos. Essa abordagem resultará no bloqueio de tráfego legítimo quando as APIs estiverem documentadas incorretamente.
As ferramentas de segurança baseadas em OAS correm o risco de deixar passar ataques. A aplicação da técnica de Validação Flexível com um contrato genérico e muito amplo, como não ter definições de padrão ou usar tipos de dados genéricos como "string", permitirá que muitas chamadas de API maliciosas passem pela validação.
Conclusão
A documentação baseada em OAS é útil tanto para equipes de desenvolvimento quanto de segurança se for precisa, mas o OAS e as ferramentas de segurança baseadas em OAS possuem deficiências inerentes que limitam a proteção a apenas uma pequena porcentagem do risco das APIs. Depender da documentação OAS e de ferramentas de segurança baseadas em OAS para proteger suas APIs não impedirá violações de API ou perda de dados.
Saiba como a Salt Security pode ajudar a aprimorar seus esforços de documentação de API baseada em OAS e fornecer cobertura total contra ameaças a APIs.