regras-de-confiança-de-cabeçalho-de-autenticação

Um pequeno pacote de regras Semgrep que sinaliza código que toma decisões de autenticação, autorização ou confiança com base em cabeçalhos de requisição HTTP que um atacante controla.

O exemplo canônico desta classe de vulnerabilidade é o CVE-2025-29927: Next.js confiava no cabeçalho x-middleware-subrequest para decidir se o middleware era executado, e qualquer requisição de entrada que fornecesse um valor manipulado poderia pular o middleware por completo. O mesmo padrão se repete em frameworks e ecossistemas.

Este pacote contém regras para duas famílias de linguagens e três subclasses do bug. Ele é destinado como um auxílio de revisão de código, não como um portão de CI totalmente ajustado. As regras priorizam a revocação sobre a precisão e são melhor executadas interativamente, com um humano tomando a decisão sobre cada descoberta.

Para um artigo mais longo sobre a classe de vulnerabilidade e as escolhas de design por trás deste pacote, veja bk-security.github.io.

Inventário de Regras

Início Rápido

Instale o Semgrep:

pip install semgrep

Execute o pacote contra um alvo:

semgrep --config /caminho/para/auth-header-trust-rules/rules /caminho/para/alvo

Ou execute uma única regra:

semgrep --config /caminho/para/auth-header-trust-rules/rules/nodejs/header-flag-auth-bypass.yaml /caminho/para/alvo

Valide as regras contra os fixtures incluídos:

semgrep --test --config rules/ tests/

Saída esperada:

6/6: ✓ Todos os testes passaram

O que as Regras Vão e Não Vão Capturar

As regras correspondem a uma lista curada de nomes de cabeçalhos conhecidos por serem perigosos quando confiados. Elas vão capturar os casos comuns. Elas não vão capturar:

• Frameworks onde a leitura do cabeçalho está oculta dentro de uma função auxiliar cujo nome não contém a string do cabeçalho. Um auxiliar personalizado chamado getInternalFlag(req) que lê x-some-novel-name passará pelas regras.
• Nomes de cabeçalhos que não estão na lista curada. A classe CVE-2025-29927 pode em princípio usar qualquer nome de cabeçalho; erramos pelo lado da revocação incluindo padrões como x-internal-*, x-trust-*, e x-bypass-*, mas nomes novos passarão despercebidos.
• Decisões de autenticação baseadas em cookies, parâmetros de consulta ou campos do corpo da requisição. Essas são a mesma classe de vulnerabilidade, mas requerem suas próprias regras.
• Decisões de autenticação baseadas na ausência de um cabeçalho. Algumas aplicações pulam verificações de autenticação quando um cabeçalho não está presente (um padrão de lista de permissões mal configurado). As regras atuais são de leitura-e-uso, não baseadas em ausência.

Ao estender o pacote para uma base de código específica, as adições de maior valor são geralmente padrões de funções auxiliares específicas do framework. Se uma base de código tem um auxiliar isInternalRequest(req), a regra que o captura é uma linha de YAML.

Adicionando uma Regra

1. Crie a regra em rules/<lang>/<name>.yaml.
2. Crie um fixture de teste em tests/<lang>/<name>.<ext> com exemplos positivos anotados # ruleid: <rule-id> e exemplos negativos anotados # ok: <rule-id>.
3. Execute semgrep --test --config rules/ tests/. A nova regra e fixture serão detectados automaticamente; os testes devem passar antes de enviar uma alteração.

Licença

MIT.

Autor

Bruce Kang. O código-fonte do blog post complementar está em bk-security.github.io.