Vulnhalla

Análisis automatizado de CodeQL con clasificación mediante LLM

Para obtener una visión detallada de la investigación y la motivación detrás de Vulnhalla, consulta la entrada oficial del blog de CyberArk Threat Research:

Vulnhalla: Cómo extraer las verdaderas vulnerabilidades del pajar de CodeQL

Vulnhalla automatiza el pipeline completo de análisis de seguridad:

1. Obtención de repositorios de un lenguaje de programación determinado desde GitHub
2. Descarga de sus correspondientes bases de datos de CodeQL (si están disponibles)
3. Ejecución de consultas de CodeQL en esas bases de datos para detectar problemas de seguridad o de calidad de código
4. Posprocesamiento de los resultados con un LLM (ChatGPT, Gemini, etc.) para clasificar y filtrar problemas

---

🚀 Inicio Rápido

Paso 1: Requisitos Previos

Antes de comenzar, asegúrate de tener:

• Python 3.10 – 3.13 (se recomienda Python 3.11 o 3.12)

  • Python 3.14+ no es compatible (esta herramienta usa grpcio, que no es compatible con Python 3.14+)
  • Descárgalo desde python.org

• CodeQL CLI

  • Descárgalo desde CodeQL CLI releases
  • Asegúrate de que codeql esté en tu PATH, o establece la ruta en .env (ver Paso 2)

• (Opcional) Token de API de GitHub

  • Para límites de tasa más altos al descargar bases de datos
  • Obtén uno desde GitHub Settings > Tokens

• Clave de API del LLM

  • Credenciales de OpenAI, Azure, Gemini o Bedrock (según tu proveedor)

Paso 2: Configurar el Entorno

Toda la configuración está en un único archivo: .env

1. Clona el repositorio:

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

2. Copia .env.example a .env:

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

3. Edita .env y completa tus valores:

Ejemplo 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

# Optional: Logging Configuration
LOG_LEVEL=INFO                  # DEBUG, INFO, WARNING, ERROR
LOG_FILE=                       # Optional: path to log file (e.g., logs/vulnhalla.log)
LOG_FORMAT=default              # default or json
# LOG_VERBOSE_CONSOLE=false     # If true, WARNING/ERROR use full format (timestamp - logger - level - message)

📖 Para la referencia de configuración completa: consulta Referencia de Configuración más abajo para conocer todos los proveedores compatibles (OpenAI, Azure, Gemini, Bedrock), las variables requeridas/opcionales y ejemplos detallados.

Paso 3: Instalar Poetry (Recomendado: pipx)

Windows (PowerShell):

# List available Python versions
py -0p

# Pick any supported Python: 3.10 / 3.11 / 3.12 / 3.13
py -3.12 -m pip install --user -U pipx
py -3.12 -m pipx ensurepath
# Close and reopen terminal (required)
pipx install poetry
poetry --version

macOS / Linux:

# Check your Python version
python3 --version

# Use any supported Python: 3.10 / 3.11 / 3.12 / 3.13
python3 -m pip install --user -U pipx
python3 -m pipx ensurepath
# Restart terminal (required)
pipx install poetry
poetry --version

Paso 4: Instalar Dependencias y Configuración

Windows (PowerShell):

# Pick one supported version you have: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Force Poetry to use a supported Python version if you have multiple versions installed
poetry install
poetry run vulnhalla-setup

macOS / Linux:

# Pick one supported version you have: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Force Poetry to use a supported Python version if you have multiple versions installed
poetry install
poetry run vulnhalla-setup

Paso 5: Ejecutar el Pipeline

# Analyze a specific repository, for example:
poetry run vulnhalla redis/redis

# Re-download even if database already exists
poetry run vulnhalla redis/redis --force

# Show help
poetry run vulnhalla --help

Esto hará automáticamente:

1. Obtener las bases de datos de CodeQL
2. Ejecutar consultas de CodeQL en todas las bases de datos descargadas
3. Analizar los resultados con el LLM y guardarlos en output/results/
4. Abrir la UI para explorar los resultados

Uso de una Base de Datos de CodeQL Local

Si ya tienes una base de datos de CodeQL en disco (por ejemplo, creada manualmente o de una ejecución anterior), puedes omitir el paso de obtención de GitHub usando la bandera --local / -l:

Windows (PowerShell):

poetry run vulnhalla --local C:\path\to\my-codeql-db

macOS / Linux:

poetry run vulnhalla --local /path/to/my-codeql-db

Nota: La bandera --local espera un directorio de base de datos de CodeQL, no una carpeta de código fuente. Puedes verificarlo comprobando que la carpeta contenga un archivo codeql-database.yml.

Comandos Adicionales

# Open UI to view existing results (without running analysis)
poetry run vulnhalla-ui

# Validate configuration: CodeQL, LLM, Logging (without running analysis)
poetry run vulnhalla-validate

# List analyzed repositories and their issue counts
poetry run vulnhalla-list

# Run example pipeline (analyzes videolan/vlc and redis/redis)
poetry run vulnhalla-example

---

🖥️ Interfaz de Usuario (UI)

Vulnhalla incluye una Interfaz de Usuario completa para navegar y explorar los resultados de los análisis.

Ejecutar la UI

poetry run vulnhalla-ui

Diseño de la UI

La UI muestra un área superior de dos paneles con una barra de controles en la parte inferior:

Área Superior (lado a lado, redimensionable):

• Panel Izquierdo (Lista de Problemas):

  • DataTable que muestra: ID, Repo, Nombre del Problema, Archivo, Decisión del LLM, Decisión Manual
  • Contador de problemas e indicador de ordenación
  • Caja de búsqueda en la parte inferior; se actualiza mientras escribes (sin distinguir mayúsculas/minúsculas).

• Panel Derecho (Detalles):

  • Sección de Decisión del LLM: Muestra la clasificación del LLM (Verdadero Positivo, Falso Positivo o Necesita Más Datos)
  • Sección de Metadatos: Nombre del problema, Repo, Archivo, Línea, Tipo, Nombre de la función
  • Sección de Código:
    • 📌 Contexto de Código Inicial (el primer fragmento de código que vio el LLM)
    • 📥 Código Adicional (código que el LLM solicitó durante la conversación) - solo se muestra si existe código adicional
    • Línea vulnerable resaltada en rojo
  • Sección de Resumen: respuesta/decisión final del LLM
  • Selector de Decisión Manual: Desplegable en la parte inferior para establecer el veredicto manual (Verdadero Positivo, Falso Positivo, Incierto o No Establecido)

Barra de Controles Inferior:

• Lenguaje: C (único lenguaje compatible actualmente)
• Desplegable de filtro por decisión del LLM: Todos, Verdadero Positivo, Falso Positivo, Necesita más información para decidir
• Botones de acción: Actualizar, Ejecutar Análisis
• Texto de ayuda de atajos de teclado

Atajos de Teclado