Vulnhalla

Análise Automatizada de CodeQL com Classificação por LLM

Para uma visão geral detalhada da pesquisa e motivação por trás do Vulnhalla, consulte o artigo oficial no blog de Pesquisa de Ameaças da CyberArk:

Vulnhalla: Selecionando as Vulnerabilidades Reais do Palheiro do CodeQL

O Vulnhalla automatiza todo o pipeline de análise de segurança:

1. Buscar repositórios de uma determinada linguagem de programação do GitHub
2. Baixar seus CodeQL databases correspondentes (se disponíveis)
3. Executar consultas CodeQL nesses databases para detectar problemas de segurança ou qualidade de código
4. Pós-processar os resultados com um LLM (ChatGPT, Gemini, etc.) para classificar e filtrar problemas

---

🚀 Início Rápido

Passo 1: Pré-requisitos

Antes de começar, certifique-se de ter:

• Python 3.10 – 3.13 (Python 3.11 ou 3.12 recomendado)

  • Python 3.14+ não é suportado (esta ferramenta usa grpcio, que não é suportado pelo Python 3.14+)
  • Baixe em python.org

• CodeQL CLI

  • Baixe em CodeQL CLI releases
  • Certifique-se de que codeql está no seu PATH, ou você definirá o caminho no .env (veja Passo 2)

• (Opcional) Token da API do GitHub

  • Para limites de taxa mais altos ao baixar databases
  • Obtenha em GitHub Settings > Tokens

• Chave da API do LLM

  • Credenciais OpenAI, Azure, Gemini ou Bedrock (dependendo do seu provedor)

Passo 2: Configurar Ambiente

Toda a configuração está em um único arquivo: .env

1. Clone o repositório:

git clone https://github.com/cyberark/Vulnhalla
cd Vulnhalla

2. Copie .env.example para .env:

cp .env.example .env # macOS / Linux
Copy-Item .env.example .env # Windows (PowerShell)

3. Edite .env e preencha seus valores:

Exemplo para OpenAI:

CODEQL_PATH=codeql
GITHUB_TOKEN=ghp_your_token_here
PROVIDER=openai
MODEL=gpt-4o
OPENAI_API_KEY=your-api-key-here
LLM_TEMPERATURE=0.2
LLM_TOP_P=0.2

# Opcional: Configuração de Logging
LOG_LEVEL=INFO                  # DEBUG, INFO, WARNING, ERROR
LOG_FILE=                       # Opcional: caminho para arquivo de log (ex: logs/vulnhalla.log)
LOG_FORMAT=default              # default ou json
# LOG_VERBOSE_CONSOLE=false     # Se true, WARNING/ERROR usam formato completo (timestamp - logger - level - message)

📖 Para referência completa de configuração: Veja Referência de Configuração abaixo para todos os provedores suportados (OpenAI, Azure, Gemini, Bedrock), variáveis obrigatórias/opcionais e exemplos detalhados.

Passo 3: Instalar Poetry (Recomendado: pipx)

Windows (PowerShell):

# Listar versões Python disponíveis
py -0p

# Escolha qualquer Python suportado: 3.10 / 3.11 / 3.12 / 3.13
py -3.12 -m pip install --user -U pipx
py -3.12 -m pipx ensurepath
# Feche e reabra o terminal (obrigatório)
pipx install poetry
poetry --version

macOS / Linux:

# Verifique sua versão do Python
python3 --version

# Use qualquer Python suportado: 3.10 / 3.11 / 3.12 / 3.13
python3 -m pip install --user -U pipx
python3 -m pipx ensurepath
# Reinicie o terminal (obrigatório)
pipx install poetry
poetry --version

Passo 4: Instalar Dependências e Configurar

Windows (PowerShell):

# Escolha uma versão suportada que você tenha: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Force o Poetry a usar uma versão Python suportada se você tiver várias versões instaladas
poetry install
poetry run vulnhalla-setup

macOS / Linux:

# Escolha uma versão suportada que você tenha: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Force o Poetry a usar uma versão Python suportada se você tiver várias versões instaladas
poetry install
poetry run vulnhalla-setup

Passo 5: Executar o Pipeline

# Analisar um repositório específico, por exemplo:
poetry run vulnhalla redis/redis

# Baixar novamente mesmo se o database já existir
poetry run vulnhalla redis/redis --force

# Exibir ajuda
poetry run vulnhalla --help

Isso irá automaticamente:

1. Buscar databases do CodeQL
2. Executar consultas CodeQL em todos os databases baixados
3. Analisar resultados com LLM e salvar em output/results/
4. Abrir a interface para navegar pelos resultados

Usando um Database CodeQL Local

Se você já tem um database CodeQL em disco (ex: criado manualmente ou de uma execução anterior), pode pular a etapa de busca no GitHub usando a flag --local / -l:

Windows (PowerShell):

poetry run vulnhalla --local C:\caminho\para\meu-codeql-db

macOS / Linux:

poetry run vulnhalla --local /caminho/para/meu-codeql-db

Nota: A flag --local espera um diretório de database do CodeQL, não uma pasta de código fonte. Você pode verificar se a pasta contém um arquivo codeql-database.yml.

Comandos Adicionais

# Abrir interface para visualizar resultados existentes (sem executar análise)
poetry run vulnhalla-ui

# Validar configuração: CodeQL, LLM, Logging (sem executar análise)
poetry run vulnhalla-validate

# Listar repositórios analisados e suas contagens de problemas
poetry run vulnhalla-list

# Executar pipeline de exemplo (analisa videolan/vlc e redis/redis)
poetry run vulnhalla-example

---

🖥️ Interface do Usuário (UI)

O Vulnhalla inclui uma Interface do Usuário completa para navegar e explorar os resultados da análise.

Executando a UI

poetry run vulnhalla-ui

Layout da UI

A UI exibe uma área superior de dois painéis com uma barra de controles na parte inferior:

Área Superior (lado a lado, redimensionável):

• Painel Esquerdo (Lista de Problemas):

  • DataTable mostrando: ID, Repositório, Nome do Problema, Arquivo, Decisão do LLM, Decisão Manual
  • Contagem de problemas e indicador de ordenação
  • Caixa de busca na parte inferior, atualiza conforme você digita (case-insensitive).

• Painel Direito (Detalhes):

  • Seção Decisão do LLM: Mostra a classificação do LLM (Verdadeiro Positivo, Falso Positivo, ou Precisa de Mais Dados)
  • Seção Metadados: Nome do problema, Repositório, Arquivo, Linha, Tipo, Nome da função
  • Seção Código:
    • 📌 Contexto Inicial do Código (primeiro trecho de código que o LLM viu)
    • 📥 Código Adicional (código que o LLM solicitou durante a conversa) - mostrado apenas se existir código adicional
    • Linha vulnerável destacada em vermelho
  • Seção Resumo: Resposta/decisão final do LLM
  • Selecionar Decisão Manual: Dropdown na parte inferior para definir veredito manual (Verdadeiro Positivo, Falso Positivo, Incerto, ou Não Definido)

Barra de Controles Inferior:

• Linguagem: C (única linguagem atualmente suportada)
• Filtro por decisão do llm dropdown: Todos, Verdadeiro Positivo, Falso Positivo, Precisa de Mais Informação para decidir
• Botões de ação: Atualizar, Executar Análise
• Texto de ajuda sobre atalhos de teclado

Atalhos de Teclado

• ↑/↓ - Navegar na lista de problemas (linha por linha)
• Tab / Shift+Tab - Alternar foco entre painéis
• Enter - Mostrar detalhes do problema selecionado
• / - Focar caixa de busca (no painel esquerdo)
• Esc - Limpar busca e retornar foco para tabela de problemas
• r - Recarregar resultados do disco
• [ / ] - Redimensionar painéis esquerdo/direito (ajustar posição da divisória)
• q - Sair da aplicação