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:

2. Copie .env.example para .env:

3. Edite .env e preencha seus valores:

Exemplo para OpenAI:

📖 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):

macOS / Linux:

Passo 4: Instalar Dependências e Configurar

Windows (PowerShell):

macOS / Linux:

Passo 5: Executar o Pipeline

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):

macOS / Linux:

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

🖥️ 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

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

Funcionalidades Interativas

Ordenação de Colunas

• Clique em qualquer cabeçalho de coluna para ordenar por essa coluna
• Ordenação padrão: por Repositório (ascendente), depois por ID (ascendente)

Painéis Redimensionáveis

• Divisor arrastável entre os painéis Lista de Problemas e Detalhes
• Mouse: Clique e arraste o divisor para redimensionar
• Teclado: Use [ para mover o divisor para a esquerda, ] para mover para a direita
• A posição da divisória é lembrada durante a sessão

📊 Estrutura de Saída

Após executar o pipeline, os resultados são organizados em output/results/<LANG>/<ISSUE_TYPE>/:

Cada *_final.json contém:

• Conversa completa do LLM (prompts do sistema, mensagens do usuário, respostas do assistente, chamadas de ferramenta)
• Código de status final (1337 = vulnerável, 1007 = seguro, 7331/3713 = precisa de mais informações)

Cada *_raw.json contém:

• Dados originais do problema CodeQL
• Contexto da função
• Caminho do database (inclui informações org/repo: output/databases/<LANG>/<ORG>/<REPO>)
• Localização do problema

🛠 Solução de Problemas

• CodeQL CLI não encontrado:
  Defina CODEQL_PATH no seu arquivo .env com o caminho completo do executável CodeQL. No Windows: O caminho deve terminar com .cmd (ex: C:\caminho\para\codeql\codeql.cmd).

• Limites de taxa do GitHub:
  Defina GITHUB_TOKEN no seu arquivo .env (obtenha o token em https://github.com/settings/tokens).

• Problemas com LLM:
  Verifique suas chaves de API no arquivo .env correspondentes ao provedor selecionado.

• Erros de importação na UI:
  Certifique-se de estar executando a partir do diretório raiz do projeto, ou use python examples/ui_example.py que gerencia a configuração de caminho.

⚙️ Referência de Configuração

Variáveis de Ambiente

Toda a configuração é gerenciada através de variáveis de ambiente no seu arquivo .env. Aqui está uma referência completa:

Variáveis Obrigatórias

Variáveis Obrigatórias Específicas do Provedor

OpenAI:

Azure OpenAI:

Gemini (Google):

AWS Bedrock:

* Autenticação: Use AWS_PROFILE ou AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ opcional AWS_SESSION_TOKEN para STS).

Exemplo .env Bedrock (SSO):

⚠️ Pré-requisitos:

• As credenciais AWS devem estar configuradas (SSO, perfil IAM ou chaves de acesso) com permissões para invocar modelos Bedrock
• Para usuários SSO: Execute aws sso login --profile seu-perfil antes de usar o Vulnhalla

🔧 Importante - Seleção de Modelo: Ao selecionar um modelo Bedrock, certifique-se de que ele suporta tool calling/function calling (nem todos os modelos Bedrock suportam). Tool calling é uma parte fundamental do fluxo de análise do Vulnhalla, então escolher um modelo compatível faz uma grande diferença na funcionalidade e nos resultados. Modelos compatíveis incluem: Claude 3.x, Mistral ou Cohere Command R.

Variáveis Opcionais

⚠️ Importante: Não aumente LLM_TEMPERATURE ou LLM_TOP_P a menos que você entenda completamente o impacto. Valores mais baixos mantêm o modelo estável e determinístico, o que é crítico para análise de segurança. Valores mais altos podem fazer o modelo se tornar inconsistente, criativo ou alucinar resultados.

📝 Nota: Para exemplos adicionais de configuração, veja o arquivo .env.example na raiz do projeto.

Validação de Configuração

O Vulnhalla valida sua configuração na inicialização. Se variáveis obrigatórias estiverem ausentes ou inválidas, você verá mensagens de erro claras indicando o que precisa ser corrigido.

Erros comuns de validação:

• Chave de API ausente para o provedor selecionado
• Nome de provedor inválido (veja PROVIDER para valores suportados)
• Endpoint Azure ausente (obrigatório para provedor Azure)
• Credenciais AWS ou região ausentes (obrigatório para provedor Bedrock)
• Caminho CodeQL inválido (se CODEQL_PATH estiver definido mas o arquivo não existir)

📝 Códigos de Status

O LLM usa os seguintes códigos de status:

• 1337: Vulnerabilidade de segurança encontrada (Verdadeiro Positivo)
• 1007: Código seguro, sem vulnerabilidade (Falso Positivo)
• 7331: Mais código/informação necessária para validar segurança
• 3713: Provavelmente não é um problema de segurança, mas mais informação necessária (usado com 7331)

A UI mapeia estes para:

• 1337 → "Verdadeiro Positivo"
• 1007 → "Falso Positivo"
• 7331 ou 3713 → "Precisa de Mais Dados"

🔧 Desenvolvimento

Executando Testes

O projeto inclui infraestrutura básica de testes usando pytest:

A suíte de testes inclui testes smoke para verificar se a infraestrutura de testes está configurada corretamente.

Verificação de Tipos

O projeto usa mypy para verificação estática de tipos:

A verificação de tipos está configurada em pyproject.toml sob [tool.mypy]. A configuração usa uma linha de base conservadora com substituições por módulo para permitir adoção gradual.

Dependências do Projeto

As dependências são gerenciadas via Poetry em pyproject.toml:

• requests - Requisições HTTP para API do GitHub
• pySmartDL - Gerenciador de download inteligente para databases CodeQL
• litellm - Interface LLM unificada suportando múltiplos provedores
• python-dotenv - Gerenciamento de variáveis de ambiente
• PyYAML - Parsing YAML para arquivos de pacotes CodeQL
• textual - Framework de interface de terminal
• pytest - Framework de teste (dependência de desenvolvimento)
• mypy - Verificador de tipos estático (dependência de desenvolvimento)

Consultas CodeQL

As consultas CodeQL estão organizadas em data/queries/<LANG>/:

• issues/ - Consultas de detecção de problemas de segurança
• tools/ - Consultas auxiliares (árvores de função, classes, variáveis globais, macros)

Cada diretório contém um arquivo qlpack.yml definindo o pacote CodeQL.

📄 Licença

Copyright (c) 2025 CyberArk Software Ltd. Todos os direitos reservados.

Este repositório está licenciado sob a Licença Apache, Versão 2.0 - veja LICENSE.txt para mais detalhes.

🤝 Contribuindo

Aceitamos contribuições de todos os tipos para este repositório. Para instruções sobre como começar e descrições de nossos fluxos de trabalho de desenvolvimento, consulte nosso guia de contribuição.

Código de Conduta

Por favor, leia e siga nosso Código de Conduta. Estamos comprometidos em fornecer um ambiente acolhedor e inclusivo para todos os contribuidores.

📧 Contato

Sinta-se à vontade para nos contatar através de issues no GitHub se tiver alguma solicitação de funcionalidade ou problema com o projeto.