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 - Выйти из приложения

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

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

• Нажмите на заголовок любого столбца для сортировки по этому столбцу
• Сортировка по умолчанию: по репозиторию (по возрастанию), затем по ID (по возрастанию)

Изменяемые панели

• Разделитель с возможностью перетаскивания между списком проблем и панелью деталей
• Мышь: нажмите и перетащите разделитель для изменения размера
• Клавиатура: используйте [ для перемещения разделителя влево, ] для перемещения вправо
• Позиция разделителя запоминается в течение сессии

📊 Структура вывода

После запуска конвейера результаты организованы в output/results/<LANG>/<ISSUE_TYPE>/:

output/results/c/Copy_function_using_source_size/
├── 1_raw.json      # Исходные данные проблемы CodeQL
├── 1_final.json    # Диалог и классификация LLM
├── 2_raw.json
├── 2_final.json
└── ...

Каждый файл *_final.json содержит:

• Полный диалог LLM (системные подсказки, сообщения пользователя, ответы ассистента, вызовы инструментов)
• Финальный код статуса (1337 = уязвимо, 1007 = безопасно, 7331/3713 = требуется больше информации)

Каждый файл *_raw.json содержит:

• Исходные данные проблемы CodeQL
• Контекст функции
• Путь к базе данных (включает информацию org/repo: output/databases/<LANG>/<ORG>/<REPO>)
• Местоположение проблемы

🛠 Устранение неполадок

• CodeQL CLI не найден:
  Укажите CODEQL_PATH в файле .env полный путь к исполняемому файлу CodeQL. В Windows: путь должен заканчиваться на .cmd (например, C:\path\to\codeql\codeql.cmd).

• Лимиты запросов GitHub:
  Укажите GITHUB_TOKEN в файле .env (получить токен можно на https://github.com/settings/tokens).

• Проблемы с LLM:
  Проверьте ключи API в файле .env — они должны соответствовать выбранному провайдеру.

• Ошибки импорта в UI:
  Убедитесь, что вы запускаете из корневого каталога проекта, или используйте python examples/ui_example.py, который настраивает пути.

⚙️ Справочник по конфигурации

Переменные окружения

Вся конфигурация управляется через переменные окружения в файле .env. Вот полный справочник:

Обязательные переменные

Обязательные переменные для конкретных провайдеров

OpenAI:

Azure OpenAI:

Gemini (Google):

AWS Bedrock:

* Аутентификация: Используйте AWS_PROFILE или AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ опционально AWS_SESSION_TOKEN для STS).

Пример .env для Bedrock (SSO):

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

⚠️ Предварительные требования:

• Учётные данные AWS должны быть настроены (SSO, профиль IAM или ключи доступа) с разрешениями на вызов моделей Bedrock
• Для пользователей SSO: Выполните aws sso login --profile your-profile перед использованием Vulnhalla

🔧 Важно — Выбор модели: При выборе модели Bedrock убедитесь, что она поддерживает вызов инструментов/функций (не все модели Bedrock это поддерживают). Вызов инструментов — ключевая часть рабочего процесса анализа Vulnhalla, поэтому выбор совместимой модели существенно влияет на функциональность и результаты. Совместимые модели включают: Claude 3.x, Mistral, Cohere Command R.

Опциональные переменные

⚠️ Важно: Не увеличивайте LLM_TEMPERATURE или LLM_TOP_P, если вы полностью не понимаете последствий. Меньшие значения сохраняют модель стабильной и детерминированной, что критично для анализа безопасности. Более высокие значения могут привести к непоследовательности, творческому подходу или галлюцинациям модели.

📝 Примечание: Дополнительные примеры конфигурации см. в файле .env.example в корне проекта.

Проверка конфигурации

Vulnhalla проверяет конфигурацию при запуске. Если обязательные переменные отсутствуют или некорректны, вы увидите понятные сообщения об ошибках, указывающие, что нужно исправить.

Типичные ошибки проверки:

• Отсутствует ключ API для выбранного провайдера
• Некорректное имя провайдера (см. PROVIDER — поддерживаемые значения)
• Отсутствует конечная точка Azure (требуется для провайдера Azure)
• Отсутствуют учётные данные или регион AWS (требуется для провайдера Bedrock)
• Некорректный путь к CodeQL (если CODEQL_PATH задан, но файл не существует)

📝 Коды статусов

LLM использует следующие коды статусов:

• 1337: Найдена уязвимость безопасности (True Positive)
• 1007: Код безопасен, уязвимости нет (False Positive)
• 7331: Требуется больше кода/информации для проверки безопасности
• 3713: Скорее всего не проблема безопасности, но нужна дополнительная информация (используется вместе с 7331)

Интерфейс сопоставляет их с:

• 1337 → "True Positive"
• 1007 → "False Positive"
• 7331 или 3713 → "Needs More Data"

🔧 Разработка

Запуск тестов

Проект включает базовую инфраструктуру тестирования с использованием pytest:

# Запустить все тесты
poetry run pytest

# Запустить с подробным выводом
poetry run pytest -v

Набор тестов включает дымовые тесты для проверки корректности настройки тестовой инфраструктуры.

Проверка типов

Проект использует mypy для статической проверки типов:

poetry run mypy src

Проверка типов настраивается в pyproject.toml в разделе [tool.mypy]. Конфигурация использует консервативный базовый уровень с переопределениями для отдельных модулей, что позволяет постепенно внедрять проверку.

Зависимости проекта

Управление зависимостями осуществляется через Poetry в pyproject.toml:

• requests - HTTP-запросы для API GitHub
• pySmartDL - Умный менеджер загрузок для баз данных CodeQL
• litellm - Унифицированный интерфейс LLM, поддерживающий несколько провайдеров
• python-dotenv - Управление переменными окружения
• PyYAML - Разбор YAML для файлов пакетов CodeQL
• textual - Фреймворк для терминального UI
• pytest - Фреймворк для тестирования (зависимость разработки)
• mypy - Статический анализатор типов (зависимость разработки)

Запросы CodeQL

Запросы CodeQL организованы в data/queries/<LANG>/:

• issues/ - Запросы на обнаружение проблем безопасности
• tools/ - Вспомогательные запросы (деревья функций, классы, глобальные переменные, макросы)

Каждый каталог содержит файл qlpack.yml, определяющий пакет CodeQL.

📄 Лицензия

Copyright (c) 2025 CyberArk Software Ltd. Все права защищены.

Этот репозиторий лицензирован под Apache License, Version 2.0 — подробности см. в LICENSE.txt.

🤝 Вклад в проект

Мы приветствуем любые формы вклада в этот репозиторий. Инструкции по началу работы и описание наших рабочих процессов разработки см. в руководстве по внесению вклада.

Кодекс поведения

Просим прочитать и соблюдать наш Кодекс поведения. Мы стремимся создать гостеприимную и инклюзивную среду для всех участников.

📧 Контакты

Свяжитесь с нами через GitHub Issues, если у вас есть предложения по функциям или вопросы по проекту.