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

• ↑/↓ - Navegar por la lista de problemas (fila por fila)
• Tab / Shift+Tab - Cambiar el foco entre paneles
• Enter - Mostrar detalles del problema seleccionado
• / - Enfocar la caja de búsqueda (en el panel izquierdo)
• Esc - Limpiar la búsqueda y devolver el foco a la tabla de problemas
• r - Recargar los resultados desde el disco
• [ / ] - Redimensionar los paneles izquierdo/derecho (ajustar la posición de división)
• q - Salir de la aplicación

Características Interactivas

Ordenación de Columnas

• Haz clic en cualquier encabezado de columna para ordenar por esa columna
• Ordenación predeterminada: por Repo (ascendente) y luego por ID (ascendente)

Paneles Redimensionables

• Divisor arrastrable entre los paneles de Lista de Problemas y Detalles
• Ratón: Haz clic y arrastra el divisor para redimensionar
• Teclado: Usa [ para mover el divisor a la izquierda, ] para moverlo a la derecha
• La posición de división se recuerda durante la sesión

📊 Estructura de Salida

Después de ejecutar el pipeline, los resultados se organizan en output/results/<LANG>/<ISSUE_TYPE>/:

output/results/c/Copy_function_using_source_size/
├── 1_raw.json      # Original CodeQL issue data
├── 1_final.json    # LLM conversation and classification
├── 2_raw.json
├── 2_final.json
└── ...

Cada *_final.json contiene:

• Conversación completa del LLM (prompts del sistema, mensajes de usuario, respuestas del asistente, llamadas a herramientas)
• Código de estado final (1337 = vulnerable, 1007 = seguro, 7331/3713 = necesita más información)

Cada *_raw.json contiene:

• Datos originales del problema de CodeQL
• Contexto de la función
• Ruta de la base de datos (incluye información de org/repo: output/databases/<LANG>/<ORG>/<REPO>)
• Ubicación del problema

🛠 Solución de Problemas

• CodeQL CLI no encontrado:
  Establece CODEQL_PATH en tu archivo .env con la ruta completa de tu ejecutable de CodeQL. En Windows: La ruta debe terminar en .cmd (por ejemplo, C:\path\to\codeql\codeql.cmd).

• Límites de tasa de GitHub:
  Establece GITHUB_TOKEN en tu archivo .env (obtén un token desde https://github.com/settings/tokens).

• Problemas con el LLM:
  Verifica que las claves de API en el archivo .env coincidan con tu proveedor seleccionado.

• Errores de importación en la UI:
  Asegúrate de estar ejecutando desde el directorio raíz del proyecto, o usa python examples/ui_example.py, que maneja la configuración de rutas.

⚙️ Referencia de Configuración

Variables de Entorno

Toda la configuración se gestiona mediante variables de entorno en tu archivo .env. Esta es una referencia completa:

Variables Requeridas

Variables Requeridas Específicas por Proveedor

OpenAI:

Azure OpenAI:

Gemini (Google):

AWS Bedrock:

* Autenticación: Usa AWS_PROFILE o AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ AWS_SESSION_TOKEN opcional para STS).

Ejemplo de .env para Bedrock (SSO):

PROVIDER=bedrock
MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0
AWS_REGION_NAME=us-east-1
AWS_PROFILE=your-profile

⚠️ Requisitos previos:

• Las credenciales de AWS deben estar configuradas (SSO, perfil de IAM o claves de acceso) con permisos para invocar modelos de Bedrock
• Para usuarios de SSO: Ejecuta aws sso login --profile your-profile antes de usar Vulnhalla

🔧 Importante - Selección del Modelo: Al seleccionar un modelo de Bedrock, asegúrate de que soporte tool calling/function calling (no todos los modelos de Bedrock lo hacen). El tool calling es una parte clave del flujo de análisis de Vulnhalla, por lo que elegir un modelo compatible marca una gran diferencia en funcionalidad y resultados. Los modelos compatibles incluyen: Claude 3.x, Mistral, o Cohere Command R.

Variables Opcionales

⚠️ Importante: No aumentes LLM_TEMPERATURE ni LLM_TOP_P a menos que entiendas completamente el impacto. Los valores más bajos mantienen el modelo estable y determinista, lo cual es crítico para el análisis de seguridad. Los valores más altos pueden hacer que el modelo se vuelva inconsistente, creativo o que alucine resultados.

📝 Nota: Para ejemplos de configuración adicionales, consulta el archivo .env.example en la raíz del proyecto.

Validación de la Configuración

Vulnhalla valida tu configuración al iniciar. Si faltan variables requeridas o son inválidas, verás mensajes de error claros que indican qué hay que corregir.

Errores de validación comunes:

• Falta la clave de API para el proveedor seleccionado
• Nombre de proveedor inválido (consulta PROVIDER para los valores compatibles)
• Falta el endpoint de Azure (requerido para el proveedor de Azure)
• Faltan credenciales o región de AWS (requerido para el proveedor de Bedrock)
• Ruta de CodeQL inválida (si CODEQL_PATH está establecido pero el archivo no existe)

📝 Códigos de Estado

El LLM utiliza los siguientes códigos de estado:

• 1337: Se encontró una vulnerabilidad de seguridad (Verdadero Positivo)
• 1007: El código es seguro, no hay vulnerabilidad (Falso Positivo)
• 7331: Se necesita más código/información para validar la seguridad
• 3713: Probablemente no sea un problema de seguridad, pero se necesita más información (se usa con 7331)

La UI los asigna de la siguiente manera:

• 1337 → "Verdadero Positivo"
• 1007 → "Falso Positivo"
• 7331 o 3713 → "Necesita Más Datos"

🔧 Desarrollo

Ejecutar Pruebas

El proyecto incluye una infraestructura básica de pruebas usando pytest:

# Run all tests
poetry run pytest

# Run with verbose output
poetry run pytest -v

La suite de pruebas incluye pruebas de humo para verificar que la infraestructura de pruebas esté correctamente configurada.

Comprobación de Tipos

El proyecto usa mypy para la comprobación estática de tipos:

poetry run mypy src

La comprobación de tipos está configurada en pyproject.toml bajo [tool.mypy]. La configuración usa una línea base conservadora con anulaciones por módulo para permitir una adopción gradual.

Dependencias del Proyecto

Las dependencias se gestionan mediante Poetry en pyproject.toml:

• requests - Solicitudes HTTP para la API de GitHub
• pySmartDL - Gestor de descargas inteligente para bases de datos de CodeQL
• litellm - Interfaz LLM unificada que soporta múltiples proveedores
• python-dotenv - Gestión de variables de entorno
• PyYAML - Análisis YAML para archivos de paquetes de CodeQL
• textual - Framework de UI de terminal
• pytest - Framework de pruebas (dependencia de desarrollo)
• mypy - Comprobador de tipos estático (dependencia de desarrollo)

Consultas de CodeQL

Las consultas de CodeQL están organizadas en data/queries/<LANG>/:

• issues/ - Consultas de detección de problemas de seguridad
• tools/ - Consultas auxiliares (árboles de funciones, clases, variables globales, macros)

Cada directorio contiene un archivo qlpack.yml que define el paquete de CodeQL.

📄 Licencia

Copyright (c) 2025 CyberArk Software Ltd. Todos los derechos reservados.

Este repositorio está licenciado bajo la Apache License, Versión 2.0 - consulta LICENSE.txt para más detalles.

🤝 Contribuciones

Damos la bienvenida a todo tipo de contribuciones a este repositorio. Para obtener instrucciones sobre cómo comenzar y descripciones de nuestros flujos de trabajo de desarrollo, consulta nuestra guía de contribución.

Código de Conducta

Por favor, lee y sigue nuestro Código de Conducta. Estamos comprometidos a proporcionar un entorno acogedor e inclusivo para todos los contribuyentes.

📧 Contacto

No dudes en contactarnos a través de los issues de GitHub si tienes solicitudes de funciones o problemas con el proyecto.