bg-szy/TOP-SKILLS

Análise CodeQL

Linguagens suportadas: Python, JavaScript/TypeScript, Go, Java/Kotlin, C/C++, C#, Ruby, Swift.

Recursos da skill: Arquivos de referência e modelos estão localizados em {baseDir}/references/ e {baseDir}/workflows/.

Princípios Essenciais

1. Qualidade do banco de dados não é negociável. Um banco de dados que compila não é automaticamente bom — uma compilação em cache não extrai nada, mas reporta sucesso.

2. Extensões de dados capturam o que o CodeQL perde. Projetos Django, Spring e Express ainda encapsulam chamadas de banco de dados, análise de requisições e execução de shell em APIs específicas do projeto que nenhum modelo embutido cobre.

3. Referências explícitas a suites evitam queda silenciosa de consultas. Nunca passe nomes de pacotes para codeql database analyze — cada pacote aplica um defaultSuiteFile com filtros ocultos que podem produzir zero resultados. Sempre gere um .qls.

4. Zero achados precisa de investigação, não de comemoração. Pode significar extração ruim, modelos faltando, os pacotes errados ou filtragem de suite. Execute {baseDir}/scripts/check_db_quality.py após a compilação, confirme que {baseDir}/scripts/verify_query_suite.py saiu com zero para a suite em uso — os scripts de geração o executam, então invoque-o manualmente apenas para uma suite reutilizada ou editada — e informe no relatório que ambos passaram.

5. macOS Apple Silicon requer soluções alternativas para linguagens compiladas. Código de saída 137 é uma incompatibilidade arm64e/arm64, não uma falha de compilação. Tente as ferramentas arm64 do Homebrew ou Rosetta antes de recorrer a build-mode=none.

6. Siga os workflows passo a passo. Cada fase condiciona a próxima; pular a avaliação de qualidade ou as extensões de dados deixa a lacuna invisível nos resultados.

Cada chamada Bash é um shell novo

Nada persiste entre chamadas Bash: nem variáveis, nem arrays, nem funções importadas de build_log.sh. Cada bloco abaixo que usa um valor deve reestabelecê-lo no mesmo bloco. Os workflows apontam de volta para cá em vez de repetir isso; o que eles afirmam é o dano específico naquele local, porque cada um falha de forma diferente e silenciosa:

• uma função perdida faz run_logged sair com 127, que a escada de compilação lê como um método falho e desce até --build-mode=none, nunca tendo invocado o CodeQL
• um array perdido se expande para nada, então todo --threat-model e --model-packs que o usuário escolheu é descartado enquanto o relatório final ainda os lista como usados
• um escalar perdido sob set -u aborta o bloco com unbound variable

Diretório de Saída

Todos os arquivos gerados (banco de dados, logs de compilação, diagnósticos, extensões, resultados) são armazenados em um único diretório de saída.

• Se o usuário especificar um diretório de saída em sua solicitação, use-o como OUTPUT_DIR.
• Se não for especificado, o padrão é ./static_analysis_codeql_1. Se já existir, incremente para _2, _3, etc.

Em ambos os casos, sempre crie o diretório com mkdir -p antes de escrever qualquer arquivo.

Defina USER_SPECIFIED_DIR para o caminho literal da solicitação do usuário antes de executar isso, ou deixe-o não definido para incrementar automaticamente. Nada mais o atribui.

# Resolver diretório de saída
USER_SPECIFIED_DIR="${USER_SPECIFIED_DIR:-}"   # substitua pelo caminho do usuário aqui, se houver
if [ -n "$USER_SPECIFIED_DIR" ]; then
  OUTPUT_DIR="$USER_SPECIFIED_DIR"
else
  BASE="static_analysis_codeql"
  N=1
  while [ -e "${BASE}_${N}" ]; do
    N=$((N + 1))
  done
  OUTPUT_DIR="${BASE}_${N}"
fi
mkdir -p "$OUTPUT_DIR"

O diretório de saída é resolvido uma vez no início, antes da execução de qualquer workflow. Todos os workflows recebem $OUTPUT_DIR e armazenam seus artefatos lá:

$OUTPUT_DIR/
├── rulesets.txt                 # Pacotes de consulta selecionados (registrados após o Passo 3)
├── codeql.db/                   # Banco de dados CodeQL (diretório contendo codeql-database.yml)
├── build.log                    # Log de compilação
├── codeql-config.yml            # Configuração de exclusão (linguagens interpretadas)
├── diagnostics/                 # Consultas e CSVs de diagnóstico
├── extensions/                  # YAMLs de extensão de dados
├── raw/                         # Saída de análise não filtrada
│   ├── results.sarif
│   └── run-all.qls | important-only.qls
└── results/                     # Resultados finais (filtrados para apenas importantes, copiados para executar tudo)
    └── results.sarif

Descoberta de Banco de Dados

Um banco de dados CodeQL é identificado pela presença de um arquivo marcador codeql-database.yml dentro de seu diretório. Ao pesquisar por bancos de dados existentes, sempre colete todas as correspondências — pode haver vários bancos de dados de execuções anteriores ou para diferentes linguagens.

Comando de descoberta. find_databases.sh imprime um caminho de banco de dados por linha, filtrando os arquivos marcadores que uma compilação falha deixa para trás. Construa o array no mesmo bloco que seleciona dele — cada chamada Bash é um shell novo, então um array construído aqui estará vazio na próxima chamada, e a execução conclui que não há banco de dados:

# Substituição de comando, não `done < <(...)`: uma substituição de processo descarta o status de saída
# do script, então "codeql não está no PATH deste shell" (saída 2) chegaria como uma lista vazia
# e direcionaria para "construir um novo banco de dados" com três bons no disco.
if ! DB_LIST=$("{baseDir}/scripts/find_databases.sh" "${OUTPUT_DIR:-.}" .); then
  echo "ERRO: descoberta de banco de dados falhou — veja a mensagem acima" >&2
  exit 1
fi

FOUND_DBS=()
while IFS= read -r db; do
  [ -n "$db" ] || continue
  FOUND_DBS+=("$db")
done <<<"$DB_LIST"

echo "Encontrado(s) ${#FOUND_DBS[@]} banco(s) de dados existente(s)"

# Os metadados que o prompt de seleção precisa, coletados aqui em vez de em um bloco próprio:
# FOUND_DBS desaparece na próxima chamada Bash, e um loop sobre um array que não existe mais
# não imprime nada e reporta sucesso.
for db in "${FOUND_DBS[@]}"; do
  CODEQL_LANG=$(codeql resolve database --format=json -- "$db" 2>/dev/null | jq -r '.languages[0]')
  CREATED=$(grep '^creationMetadata:' -A5 "$db/codeql-database.yml" 2>/dev/null | grep 'creationTime' | awk '{print $2}')
  echo "$db — language: $CODEQL_LANG, created: $CREATED"
done

Nunca presuma que um banco de dados se chama codeql.db — descubra-o pelo seu arquivo marcador.

Quando vários bancos de dados são encontrados: use AskUserQuestion para permitir que o usuário selecione qual banco de dados usar, ou construir um novo, a partir da linguagem e hora de criação impressas acima. AskUserQuestion aceita no máximo quatro opções, então, com mais bancos de dados do que isso, ofereça os três mais recentes mais "Construir um novo banco de dados" e liste o restante no texto do prompt. Pule AskUserQuestion se o usuário declarou explicitamente qual banco de dados usar ou construir um novo em sua solicitação.

Início Rápido

Para o caso comum ("escanear este código em busca de vulnerabilidades"):

# Verifique se o CodeQL está instalado. Pare aqui se não estiver — cada comando posterior falha com
# um erro menos informativo, e a execução desperdiça um ciclo de compilação antes de dizer por quê.
if ! command -v codeql >/dev/null 2>&1; then
  echo "ERRO: codeql não encontrado no PATH. Instale-o com um dos seguintes:" >&2
  echo "  gh extension install github/gh-codeql   # depois: gh codeql install-stub" >&2
  echo "  brew install --cask codeql" >&2
  echo "  https://github.com/github/codeql-action/releases  (codeql-bundle)" >&2
  exit 1
fi

# jq analisa `codeql resolve database --format=json` no próximo passo. Sem ele,
# CODEQL_LANG retorna vazio e a execução continua com a linguagem errada.
if ! command -v jq >/dev/null 2>&1; then
  echo "ERRO: jq não encontrado no PATH (brew install jq / apt install jq)" >&2
  exit 1
fi

# uv executa ambos os scripts de guarda e ambos os geradores de suite. Verifique-o aqui em vez de
# na geração da suite, que é após a compilação — caso contrário, uma máquina sem uv gasta
# toda a compilação antes de falhar.
if ! command -v uv >/dev/null 2>&1; then
  echo "ERRO: uv não encontrado no PATH (https://docs.astral.sh/uv/getting-started/)" >&2
  exit 1
fi

codeql --version

Em seguida, resolva OUTPUT_DIR usando o bloco em Diretório de Saída acima — ele honra um diretório especificado pelo usuário, o que um simples auto-incremento não faz.

Em seguida, execute o pipeline completo: construir banco de dados → criar extensões de dados → executar análise usando os workflows abaixo.

Racionalizações a Rejeitar

Esses atalhos levam a achados perdidos. Não os aceite:

• "security-extended é suficiente" - É a linha de base. Sempre verifique se os pacotes Trail of Bits e Community Packs estão disponíveis para a linguagem. Eles capturam categorias que security-extended perde completamente.
• "security-and-quality é a suite mais ampla" - security-and-quality exclui todos os caminhos de consulta experimental/. Para o modo executar tudo, importe ambos security-and-quality e security-experimental. O delta é de 1 a 52 consultas, dependendo da linguagem.
• "O banco de dados compilou, então está bom" - Um banco de dados que compila não significa que extraiu bem. Sempre execute a avaliação de qualidade e verifique as contagens de arquivos em relação aos arquivos de código-fonte esperados.
• "Extensões de dados não são necessárias para frameworks padrão" - Até aplicativos Django/Spring têm wrappers personalizados que o CodeQL não modela. Pular extensões significa perder vulnerabilidades.
• "build-mode=none é suficiente para linguagens compiladas" - Produz uma análise severamente incompleta. Use apenas como último recurso absoluto. No macOS, tente a solução alternativa da toolchain arm64 ou Rosetta primeiro.
• "A compilação falha no macOS, apenas use build-mode=none" - Código de saída 137 é causado por incompatibilidade arm64e/arm64, não uma falha fundamental de compilação. Veja macos-arm64e-workaround.md.
• "Nenhum achado significa que o código é seguro" - Execute check_db_quality.py e verify_query_suite.py e informe que passaram. Sem eles, zero achados e um banco de dados que não extraiu nada são a mesma saída.
• "Vou apenas executar a suite padrão" / "Vou apenas passar os nomes dos pacotes diretamente" - Cada pacote aplica filtros ocultos em seu defaultSuiteFile e pode produzir zero resultados. Sempre use uma referência de suite explícita.
• "Vou colocar arquivos no diretório atual" - Todos os arquivos gerados devem ir para $OUTPUT_DIR. Espalhar arquivos no diretório de trabalho torna a limpeza impossível e corre o risco de sobrescrever execuções anteriores.
• "Apenas use o primeiro banco de dados que encontrar" - Vários bancos de dados podem existir para diferentes linguagens ou de execuções anteriores. Quando mais de um for encontrado, apresente todas as opções ao usuário. Apenas pule o prompt quando o usuário já especificou qual banco de dados usar.
• "O usuário disse 'escanear', isso significa que ele quer que eu escolha um banco de dados" - "Escanear" não é seleção de banco de dados. Se vários bancos de dados existirem e o usuário não nomeou um, pergunte.

---

Seleção de Workflow

Esta skill possui três workflows. Uma vez que um workflow é selecionado, execute-o passo a passo sem pular fases.

Essas execuções são longas. Uma compilação de banco de dados tem quatro métodos de fallback, então use as ferramentas de tarefa para acompanhar o progresso. Decida quais passos vale a pena acompanhar com base na execução.

Workflow	Propósito
build-database	Criar banco de dados CodeQL usando métodos de compilação em sequência
create-data-extensions	Detectar ou gerar modelos de extensão de dados para APIs do projeto
run-analysis	Selecionar conjuntos de regras, executar consultas, processar resultados

Construindo sem supervisão

Este plugin fornece /static-analysis:codeql-build, que executa as etapas de compilação do banco de dados de ponta a ponta: detectar a linguagem e a toolchain, percorrer a escada de métodos aplicando correções de build-fixes.md entre os degraus, e impor o portão de qualidade.

/static-analysis:codeql-build {"target": "/abs/path", "lang": "cpp"}

Ele não pergunta nada. Cada método falhando, e um banco de dados que compilou mas ficou abaixo do limite de qualidade, retornam como status — no-method-succeeded e built-below-threshold — para você agir aqui, porque se os erros restantes do extrator estão confinados a código que ninguém precisa analisar é um julgamento que a execução não pode fazer.

Use-o quando a compilação é a parte longa e incerta e você quer que ela seja levada a uma conclusão. Trabalhe build-database.md manualmente quando quiser ter uma palavra a dizer sobre qual método é tentado, ou quando uma falha de compilação precisar ser interpretada à medida que acontece.

Lógica de Auto-Detecção

Se o usuário especificar explicitamente o que fazer (por exemplo, "construir um banco de dados", "executar análise em ./my-db"), execute esse workflow diretamente. NÃO chame AskUserQuestion para seleção de banco de dados se a solicitação do usuário já tornar clara sua intenção — por exemplo, "construir um novo banco de dados", "analisar o banco de dados codeql em static_analysis_codeql_2", "executar uma varredura completa do zero".

Pipeline padrão para "teste", "escanear", "analisar" ou similar: Descubra bancos de dados existentes usando o comando em Descoberta de Banco de Dados acima, então decida.

Condição	Ação
Nenhum banco de dados encontrado	Resolver novo $OUTPUT_DIR, executar compilação → extensões → análise (pipeline completo)
Um banco de dados encontrado	Usar AskUserQuestion: reutilizá-lo ou construir novo?
Vários bancos de dados encontrados	Usar AskUserQuestion, limitado a quatro opções — veja Descoberta de Banco de Dados
Usuário declarou intenção explicitamente	Pular AskUserQuestion, agir diretamente de acordo com suas instruções

Prompt de Seleção de Banco de Dados

Quando bancos de dados existentes são encontrados e o usuário não especificou explicitamente qual usar, apresente-os via AskUserQuestion sob o cabeçalho "Bancos de Dados CodeQL Existentes". Rotule cada opção com o caminho, linguagem e hora de criação coletados acima — ./static_analysis_codeql_1/codeql.db (language: python, created: 2026-02-24) — e faça a última opção ser "Construir um novo banco de dados".

Após a seleção:

• Se o usuário escolher um banco de dados existente: Defina $OUTPUT_DIR como seu diretório pai (ou o diretório que o contém), defina $DB_NAME como o caminho selecionado, então prossiga para extensões → análise.
• Se o usuário escolher "Construir novo": Resolva um novo $OUTPUT_DIR, execute compilação → extensões → análise.

Prompt de Decisão Geral

Se nem o banco de dados nem o workflow estiverem claros a partir da solicitação, ofereça os quatro workflows via AskUserQuestion com o cabeçalho "O que você gostaria de fazer?":

1. Construir banco de dados - Criar um banco de dados CodeQL
2. Criar extensões de dados - Gerar modelos de extensão para APIs específicas do projeto
3. Executar análise - Executar consultas em um banco de dados existente
4. Pipeline completo - Construir banco de dados → extensões → análise

Prompt de Modo de Análise

Se a análise for executada e o usuário não especificar o modo, pergunte usando AskUserQuestion com o cabeçalho "Modo de Análise":

• Executar tudo - Executar conjuntos security-and-quality + security-experimental
• Apenas importantes - Executar apenas consultas de alta precisão

Nota: "Apenas importantes" é o padrão se a varredura for parte de um ciclo de feedback rápido. "Executar tudo" é o padrão para varreduras abrangentes.

---

Estrutura de Referência

Workflows

Workflow	Caminho do arquivo	Descrição
Construir Banco de Dados	workflows/build-database.md	Cria um banco de dados CodeQL a partir de código-fonte usando métodos de compilação em sequência até que um tenha sucesso
Criar Extensões de Dados	workflows/create-data-extensions.md	Detecta e gera modelos de extensão de dados YAML para APIs específicas do projeto que o CodeQL não modela
Executar Análise	workflows/run-analysis.md	Seleciona conjuntos de regras, executa consultas e processa resultados SARIF

Arquivos de Referência

Arquivo	Caminho	Descrição
Correções de Compilação	references/build-fixes.md	Correções comuns para falhas de compilação do CodeQL
Solução Alternativa macOS arm64	references/macos-arm64e-workaround.md	Contorno para incompatibilidade arm64e/arm64 em Apple Silicon
Formato de Extensão de Dados	references/data-extension-format.md	Especificação para arquivos de modelo de extensão de dados YAML

Scripts de Suporte

Script	Caminho	Descrição
Verificar Qualidade do BD	scripts/check_db_quality.py	Avalia a qualidade da extração do banco de dados CodeQL
Verificar Suite de Consultas	scripts/verify_query_suite.py	Verifica se a suite de consultas gerada contém consultas reais
Encontrar Bancos de Dados	scripts/find_databases.sh	Descobre bancos de dados CodeQL existentes no diretório de saída