Vulnhalla

Автоматизированный анализ CodeQL с классификацией на основе LLM

Подробный обзор исследования и мотивации Vulnhalla — в официальном блоге CyberArk Threat Research:

Vulnhalla: Выбирая истинные уязвимости из стога сена CodeQL

Vulnhalla автоматизирует полный конвейер анализа безопасности:

1. Получение репозиториев заданного языка программирования из GitHub
2. Загрузка соответствующих баз данных CodeQL (если доступны)
3. Запуск запросов CodeQL на этих базах данных для выявления проблем безопасности или качества кода
4. Постобработка результатов с помощью LLM (ChatGPT, Gemini и т.д.) для классификации и фильтрации проблем

---

🚀 Быстрый старт

Шаг 1: Предварительные требования

Перед началом убедитесь, что у вас есть:

• Python 3.10 – 3.13 (рекомендуется Python 3.11 или 3.12)

  • Python 3.14+ не поддерживается (инструмент использует grpcio, который не поддерживается в Python 3.14+)
  • Скачайте с python.org

• CodeQL CLI

  • Скачайте с релизы CodeQL CLI
  • Убедитесь, что codeql находится в PATH, или укажите путь в .env (см. Шаг 2)

• (Необязательно) Токен GitHub API

  • Для более высоких лимитов запросов при загрузке баз данных
  • Получить: GitHub Settings > Tokens

• Ключ API LLM

  • Учётные данные OpenAI, Azure, Gemini или Bedrock (в зависимости от провайдера)

Шаг 2: Настройка окружения

Вся конфигурация находится в одном файле: .env

1. Клонируйте репозиторий:

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

2. Скопируйте .env.example в .env:

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

3. Отредактируйте .env и заполните свои значения:

Пример для 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

# Опционально: настройки журналирования
LOG_LEVEL=INFO                  # DEBUG, INFO, WARNING, ERROR
LOG_FILE=                       # Опционально: путь к файлу журнала (например, logs/vulnhalla.log)
LOG_FORMAT=default              # default или json
# LOG_VERBOSE_CONSOLE=false     # Если true, WARNING/ERROR используют полный формат (timestamp - logger - level - message)

📖 Полную справочную информацию по конфигурации: см. Справочник по конфигурации ниже — все поддерживаемые провайдеры (OpenAI, Azure, Gemini, Bedrock), обязательные/опциональные переменные и подробные примеры.

Шаг 3: Установка Poetry (рекомендуется: pipx)

Windows (PowerShell):

# Показать доступные версии Python
py -0p

# Выберите любую поддерживаемую версию: 3.10 / 3.11 / 3.12 / 3.13
py -3.12 -m pip install --user -U pipx
py -3.12 -m pipx ensurepath
# Закройте и снова откройте терминал (обязательно)
pipx install poetry
poetry --version

macOS / Linux:

# Проверьте версию Python
python3 --version

# Используйте любую поддерживаемую версию: 3.10 / 3.11 / 3.12 / 3.13
python3 -m pip install --user -U pipx
python3 -m pipx ensurepath
# Перезапустите терминал (обязательно)
pipx install poetry
poetry --version

Шаг 4: Установка зависимостей и настройка

Windows (PowerShell):

# Выберите одну поддерживаемую версию, которая у вас есть: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Принудительно укажите Poetry поддерживаемую версию Python, если у вас установлено несколько версий
poetry install
poetry run vulnhalla-setup

macOS / Linux:

# Выберите одну поддерживаемую версию, которая у вас есть: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Принудительно укажите Poetry поддерживаемую версию Python, если у вас установлено несколько версий
poetry install
poetry run vulnhalla-setup

Шаг 5: Запуск конвейера

# Анализ конкретного репозитория, например:
poetry run vulnhalla redis/redis

# Повторная загрузка, даже если база данных уже существует
poetry run vulnhalla redis/redis --force

# Показать справку
poetry run vulnhalla --help

Это автоматически:

1. Загрузит базы данных CodeQL
2. Запустит запросы CodeQL на всех загруженных базах данных
3. Проанализирует результаты с помощью LLM и сохранит в output/results/
4. Откроет интерфейс для просмотра результатов

Использование локальной базы данных CodeQL

Если у вас уже есть база данных CodeQL на диске (например, созданная вручную или из предыдущего запуска), вы можете пропустить этап получения с GitHub, используя флаг --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

Примечание: Флаг --local ожидает каталог базы данных CodeQL, а не папку с исходным кодом. Убедитесь, что в папке есть файл codeql-database.yml.

Дополнительные команды

# Открыть интерфейс для просмотра существующих результатов (без запуска анализа)
poetry run vulnhalla-ui

# Проверить конфигурацию: CodeQL, LLM, журналирование (без запуска анализа)
poetry run vulnhalla-validate

# Список проанализированных репозиториев и количество проблем в них
poetry run vulnhalla-list

# Запустить пример конвейера (анализирует videolan/vlc и redis/redis)
poetry run vulnhalla-example

---

🖥️ Пользовательский интерфейс (UI)

Vulnhalla включает полнофункциональный пользовательский интерфейс для просмотра и изучения результатов анализа.

Запуск интерфейса

poetry run vulnhalla-ui

Расположение элементов интерфейса

Интерфейс отображает две панели в верхней части и панель управления внизу:

Верхняя часть (рядом, с изменяемыми размерами):

• Левая панель (Список проблем):

  • Таблица данных, показывающая: ID, Репозиторий, Название проблемы, Файл, Решение LLM, Решение вручную
  • Счётчик проблем и индикатор сортировки
  • Поле поиска внизу, обновляется по мере ввода (без учёта регистра).

• Правая панель (Детали):

  • Раздел решения LLM: показывает классификацию LLM (True Positive, False Positive или Needs More Data)
  • Раздел метаданных: название проблемы, репозиторий, файл, строка, тип, имя функции
  • Раздел кода:
    • 📌 Исходный контекст кода (первый фрагмент кода, который увидела LLM)
    • 📥 Дополнительный код (код, запрошенный LLM в ходе диалога) — отображается только если существует
    • Уязвимая строка выделена красным
  • Раздел сводки: окончательный ответ/решение LLM
  • Выбор решения вручную: выпадающий список внизу для установки вердикта вручную (True Positive, False Positive, Uncertain или Not Set)

Нижняя панель управления:

• Язык: C (единственный поддерживаемый на данный момент язык)
• Фильтр по решению LLM: выпадающий список: Все, True Positive, False Positive, Needs more Info to decide
• Кнопки действий: Refresh (обновить), Run Analysis (запустить анализ)
• Текст справки по горячим клавишам

Горячие клавиши

• ↑/↓ - Навигация по списку проблем (построчно)
• Tab / Shift+Tab - Переключение фокуса между панелями
• Enter - Показать детали выбранной проблемы
• / - Фокус на поле поиска (в левой панели)
• Esc - Очистить поиск и вернуть фокус на таблицу проблем
• r - Перезагрузить результаты с диска
• [ / ] - Изменить размер левой/правой панели (настройка разделителя)
• q - Выйти из приложения

Интерактивные функции

Сортировка столбцов