Trail of Bits CodeQL

ANÁLISE EDITORIAL

Trail of Bits CodeQL é uma Skill para orientar análises estáticas de segurança com CodeQL sem tratar um banco criado ou um relatório vazio como prova de qualidade. Ela organiza a preparação do ambiente, a criação e a validação do banco, a modelagem de fontes e destinos próprios do projeto, a seleção explícita de consultas e a preservação dos resultados em SARIF.

A instrução foi publicada pela Trail of Bits dentro de seu marketplace de Skills de segurança. Ela cobre Python, JavaScript e TypeScript, Go, Java e Kotlin, C e C++, C#, Ruby e Swift. O foco não é substituir uma revisão humana nem certificar que um sistema está seguro. O foco é evitar atalhos que produzem uma análise incompleta com aparência de sucesso.

O ZIP local é estritamente documental. Ele contém o SKILL.md, a licença e o registro de origem. Não inclui CodeQL CLI, consultas, scripts auxiliares, dependências, banco de dados, código analisado, credenciais nem resultado SARIF.

Imagem editorial exclusiva do Bastidores da IA. Não é captura de tela, interface real nem evidência de análise executada.

O que esta Skill faz de verdade

A Skill descreve um pipeline com três partes: criar um banco CodeQL utilizável, avaliar se o projeto precisa de extensões de dados e executar consultas com uma suíte explícita. Essa ordem importa. Um banco pode terminar a criação sem extrair arquivos suficientes, e uma suíte padrão pode aplicar filtros que retiram consultas sem deixar essa perda clara no resumo.

O SKILL.md no commit auditado exige duas verificações antes de aceitar o resultado: qualidade do banco e resolução efetiva da suíte de consultas. Também orienta investigar uma execução com zero achados. Esse resultado pode significar código limpo, mas também pode indicar extração insuficiente, modelos ausentes, pacote errado ou consultas filtradas.

Outro ponto útil é a modelagem de APIs próprias do projeto. Frameworks conhecidos ainda podem esconder entrada de usuário, acesso a banco, chamadas de shell ou outros destinos sensíveis atrás de funções internas. As extensões de dados permitem declarar essas relações para que o rastreamento interprocedural não pare nos limites criados pela aplicação.

Para quem serve

Serve para equipes de segurança de aplicações, desenvolvedores que mantêm software sensível, revisores de código e profissionais que precisam transformar uma varredura CodeQL em um processo repetível. É especialmente útil quando a análise envolve mais de uma linguagem, compilação complexa ou APIs internas que não são reconhecidas pelos modelos prontos.

Também pode ajudar em uma revisão de pull request maior, em uma avaliação antes de liberar uma versão ou na investigação de uma classe de vulnerabilidade. A Skill distingue dois modos de consulta: um modo amplo, que inclui conjuntos de segurança, qualidade e consultas experimentais, e um modo de maior precisão, voltado aos achados considerados mais importantes.

Não é a melhor escolha para procurar rapidamente um padrão em um único arquivo. Nessa situação, uma ferramenta como Semgrep pode ser mais direta. Também não substitui modelagem de ameaça, teste dinâmico, revisão de autorização, análise de configuração ou entendimento do impacto de negócio.

Compatibilidade e pré-requisitos

A versão documental da Skill auditada trabalha com o CodeQL CLI e usa shell, jq e uv em seus fluxos auxiliares. O guia oficial de configuração do CodeQL CLI deve ser a referência para instalar a ferramenta e conferir a versão suportada. Para repositórios privados, verifique também as condições de licenciamento e o modelo de uso aplicável à sua organização.

A lista oficial de linguagens e recursos do CodeQL muda ao longo do tempo. A Skill declara suporte operacional para oito grupos de linguagem, mas o resultado real depende da versão do bundle, dos pacotes instalados, do sistema operacional e da capacidade de construir o projeto.

Em linguagens compiladas, o processo de criação do banco precisa observar a compilação. A Skill considera build-mode=none um último recurso porque a extração pode ficar severamente incompleta. No macOS com Apple Silicon, ela documenta ainda um caso de incompatibilidade entre arm64e e arm64 que pode terminar com código 137 e exige diagnóstico antes de reduzir a qualidade da coleta.

Instalação recomendada

Instale o marketplace pela fonte oficial e selecione apenas o plugin necessário. O README da Trail of Bits documenta a instalação no Codex com codex plugin marketplace add trailofbits/skills, seguida de codex plugin add static-analysis@trailofbits. Confirme o nome exibido pelo catálogo antes de concluir.

O download local desta página não instala o plugin. Ele serve para ler a instrução e comparar o conteúdo com o repositório fixado. Os scripts, workflows e referências adicionais citados no SKILL.md foram excluídos do ZIP para que nenhum código de terceiro seja oferecido como parte do pacote documental.

Instale o CodeQL CLI separadamente a partir da documentação oficial. Depois, confira codeql --version, a disponibilidade de jq e uv, o espaço em disco e a política para analisar código privado. Não execute uma varredura de produção apenas porque a Skill foi adicionada ao agente.

Configuração antes do primeiro uso

Defina o repositório autorizado, as linguagens, o diretório de saída e o modo de análise. A Skill usa um diretório único para banco, logs, extensões, suíte e resultados. Se nenhum destino for informado, ela propõe nomes incrementais como static_analysis_codeql_1, evitando sobrescrever uma execução anterior.

Escolha se o objetivo é criar um banco novo, reutilizar um banco existente ou executar o pipeline completo. Quando há vários bancos, a instrução exige apresentar as opções em vez de usar o primeiro caminho encontrado. O marcador codeql-database.yml ajuda a localizar candidatos, mas o banco ainda precisa passar pela validação de qualidade.

Registre os pacotes de consultas que serão usados. A Skill orienta criar uma referência .qls explícita, em vez de entregar somente o nome de um pacote ao comando de análise. Essa escolha permite verificar quantas consultas foram resolvidas e reduz o risco de um filtro padrão ocultar parte da cobertura.

Primeiro uso seguro

1. Comece com um repositório de teste sem segredos e com build conhecido.
2. Confirme CodeQL CLI, jq e uv antes de iniciar uma compilação longa.
3. Defina um diretório de saída novo e mantenha todos os artefatos dentro dele.
4. Crie o banco seguindo o manual oficial de codeql database create.
5. Valide quantidade de arquivos extraídos e erros do extrator antes de avançar.
6. Avalie se funções internas precisam ser descritas como fontes, destinos ou etapas de fluxo.
7. Gere a suíte explícita, confirme que ela resolve consultas e só então execute a análise.
8. Preserve o SARIF bruto e gere uma cópia final separada para triagem.

O Bastidores da IA não executou CodeQL, scripts ou consultas desta Skill. A curadoria foi estática, sobre o SKILL.md completo, o histórico do repositório, a licença e a documentação oficial.

Resultado esperado

Uma execução completa deve entregar um banco identificado, um log de build, a avaliação de qualidade, a decisão sobre extensões, a lista de pacotes selecionados, a suíte usada e dois níveis de resultado SARIF. O arquivo bruto preserva a saída sem filtros. O arquivo final registra o conjunto levado para triagem.

O manual de codeql database analyze mostra as opções do comando. A documentação do suporte a SARIF explica o formato aceito pelo code scanning. Esses arquivos podem conter caminhos, nomes de símbolos e trechos relacionados a vulnerabilidades. Trate-os como dados técnicos sensíveis.

Se não houver achados, o resultado esperado inclui a evidência de que o banco tinha código analisável e de que a suíte resolveu um número não nulo de consultas. Sem essas verificações, a ausência de alertas não é conclusiva.

Permissões e riscos

O pipeline pode ler todo o repositório, executar a compilação do projeto, instalar ou consultar pacotes, gravar bancos grandes e produzir artefatos que revelam detalhes internos. Um build pode disparar geradores, testes, downloads ou scripts definidos pelo próprio projeto. Execute apenas em código autorizado e, quando possível, em ambiente isolado.

Pacotes de consulta de terceiros também são código. Fixe versões, revise a procedência e registre quais foram usados. A Skill recomenda considerar pacotes oficiais, da Trail of Bits e da comunidade, mas isso não autoriza instalar todos automaticamente. Cada inclusão deve ter justificativa e origem verificável.

Extensões de dados incorretas podem criar falsos positivos ou esconder fluxos relevantes. Resultados filtrados também podem remover informação necessária para uma investigação posterior. Por isso, o SARIF bruto e o log devem permanecer preservados, com acesso restrito e retenção definida.

Erros comuns

• Celebrar zero achados: primeiro confirme extração, modelos e consultas resolvidas.
• Usar o primeiro banco encontrado: apresente todos quando houver mais de um.
• Confiar em build-mode=none para código compilado: use apenas como último recurso documentado.
• Passar somente nomes de pacotes: gere uma suíte explícita e verifique a resolução.
• Espalhar artefatos no projeto: mantenha banco, logs e resultados dentro do diretório de saída.
• Perder variáveis entre shells: a Skill alerta que cada chamada Bash começa sem funções, arrays ou variáveis anteriores.
• Ignorar APIs internas: wrappers próprios podem interromper o rastreamento de fontes e destinos.
• Tratar SARIF como relatório público: ele pode expor estrutura e pontos frágeis do código.

Versão auditada e download local

A curadoria foi realizada em 15 de agosto de 2026 sobre o commit 4db88ee79db0a68bbe049fe827e272ee2bc19510 do repositório trailofbits/skills. O histórico registra a alteração relevante mais recente da Skill no commit 304c81a8cefb6e3c029ebd0d12940ccf0713eccb. O GitHub mostrava 6.601 estrelas no momento da consulta.

A licença do repositório é Creative Commons Attribution-ShareAlike 4.0 International. O ZIP local inclui SKILL.md, LICENSE e ORIGEM.md, totalizando três arquivos. SHA-256 do pacote: 00620f30139fe9ca9f5b2aacfc9065e98a8d46428cdd69f3b82d0ae09c510f6c.

Foram excluídos scripts, workflows, referências adicionais, plugins, dependências, consultas, bancos, código-fonte analisado, logs, SARIF, tokens e credenciais. O botão de download local oferece a cópia documental auditada. O botão do repositório oficial abre a fonte completa separadamente.

Resultado esperado e limite final

Trail of Bits CodeQL é útil quando a equipe precisa de disciplina em torno da qualidade da extração, da seleção de consultas e da rastreabilidade dos artefatos. Ela ajuda a transformar uma sequência de comandos em um processo com condições de entrada e saída.

O limite permanece claro: a Skill não prova ausência de vulnerabilidades, não corrige automaticamente o código e não decide risco de negócio. Use os achados como evidência para triagem, reprodução e revisão humana. Se o build não puder ser executado de forma segura ou se o banco não representar o código relevante, pare e registre a cobertura incompleta.

Fontes primárias

• Repositório Trail of Bits Skills no commit auditado.
• SKILL.md oficial da CodeQL.
• Commit com os gates mais recentes da Skill.
• README oficial com instalação para Codex.
• Licença CC BY-SA 4.0.
• Configuração oficial do CodeQL CLI.
• Manual oficial de criação de banco.
• Manual oficial de análise de banco.
• Suporte oficial a SARIF no code scanning.