Vulnhalla

Automatisierte CodeQL-Analyse mit LLM-Klassifizierung

Eine detaillierte Übersicht über die Forschung und Motivation hinter Vulnhalla finden Sie im offiziellen CyberArk Threat Research Blog-Beitrag:

Vulnhalla: Picking the True Vulnerabilities from the CodeQL Haystack

Vulnhalla automatisiert die gesamte Sicherheitsanalyse-Pipeline:

1. Abrufen von Repositorys einer bestimmten Programmiersprache von GitHub
2. Herunterladen der zugehörigen CodeQL-Datenbanken (sofern verfügbar)
3. Ausführen von CodeQL-Abfragen auf diesen Datenbanken, um Sicherheits- oder Codequalitätsprobleme zu erkennen
4. Nachbearbeitung der Ergebnisse mit einem LLM (ChatGPT, Gemini, usw.), um die Probleme zu klassifizieren und zu filtern

---

🚀 Schnellstart

Schritt 1: Voraussetzungen

Stellen Sie vor dem Start sicher, dass Sie Folgendes haben:

• Python 3.10 – 3.13 (Python 3.11 oder 3.12 empfohlen)

  • Python 3.14+ wird nicht unterstützt (dieses Tool verwendet grpcio, das von Python 3.14+ nicht unterstützt wird)
  • Herunterladen von python.org

• CodeQL CLI

  • Herunterladen von CodeQL CLI releases
  • Stellen Sie sicher, dass codeql in Ihrem PATH ist, oder Sie setzen den Pfad in .env (siehe Schritt 2)

• (Optional) GitHub-API-Token

  • Für höhere Ratenlimits beim Herunterladen von Datenbanken
  • Holen Sie sich einen Token von GitHub Settings > Tokens

• LLM-API-Schlüssel

  • OpenAI-, Azure-, Gemini- oder Bedrock-Anmeldedaten (je nach Anbieter)

Schritt 2: Umgebung konfigurieren

Die gesamte Konfiguration erfolgt in einer einzigen Datei: .env

1. Repository klonen:

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

2. Kopieren Sie .env.example nach .env:

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

3. Bearbeiten Sie .env und fügen Sie Ihre Werte ein:

Beispiel für 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-Konfiguration
LOG_LEVEL=INFO                  # DEBUG, INFO, WARNING, ERROR
LOG_FILE=                       # Optional: Pfad zur Logdatei (z. B. logs/vulnhalla.log)
LOG_FORMAT=default              # default oder json
# LOG_VERBOSE_CONSOLE=false     # Bei true: WARNING/ERROR im vollständigen Format (Timestamp - Logger - Level - Message)

📖 Für die vollständige Konfigurationsreferenz: Siehe Konfigurationsreferenz unten für alle unterstützten Anbieter (OpenAI, Azure, Gemini, Bedrock), erforderliche/optionale Variablen und detaillierte Beispiele.

Schritt 3: Poetry installieren (Empfohlen: pipx)

Windows (PowerShell):

# Verfügbare Python-Versionen auflisten
py -0p

# Beliebige unterstützte Python-Version auswählen: 3.10 / 3.11 / 3.12 / 3.13
py -3.12 -m pip install --user -U pipx
py -3.12 -m pipx ensurepath
# Terminal schließen und erneut öffnen (erforderlich)
pipx install poetry
poetry --version

macOS / Linux:

# Python-Version prüfen
python3 --version

# Beliebige unterstützte Python-Version verwenden: 3.10 / 3.11 / 3.12 / 3.13
python3 -m pip install --user -U pipx
python3 -m pipx ensurepath
# Terminal neu starten (erforderlich)
pipx install poetry
poetry --version

Schritt 4: Abhängigkeiten installieren und Setup

Windows (PowerShell):

# Eine unterstützte Version auswählen, die Sie installiert haben: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Poetry zwingen, eine unterstützte Python-Version zu verwenden, wenn mehrere Versionen installiert sind
poetry install
poetry run vulnhalla-setup

macOS / Linux:

# Eine unterstützte Version auswählen, die Sie installiert haben: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Poetry zwingen, eine unterstützte Python-Version zu verwenden, wenn mehrere Versionen installiert sind
poetry install
poetry run vulnhalla-setup

Schritt 5: Pipeline ausführen

# Ein bestimmtes Repository analysieren, z. B.:
poetry run vulnhalla redis/redis

# Erneut herunterladen, auch wenn die Datenbank bereits existiert
poetry run vulnhalla redis/redis --force

# Hilfe anzeigen
poetry run vulnhalla --help

Dies wird automatisch:

1. CodeQL-Datenbanken abrufen
2. CodeQL-Abfragen auf allen heruntergeladenen Datenbanken ausführen
3. Ergebnisse mit dem LLM analysieren und in output/results/ speichern
4. Die UI zum Durchsuchen der Ergebnisse öffnen

Verwenden einer lokalen CodeQL-Datenbank

Wenn Sie bereits eine CodeQL-Datenbank auf der Festplatte haben (z. B. manuell erstellt oder von einem vorherigen Lauf), können Sie den GitHub-Abruf-Schritt mit dem --local / -l-Flag überspringen:

Windows (PowerShell):

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

macOS / Linux:

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

Hinweis: Das --local-Flag erwartet ein CodeQL-Datenbank-Verzeichnis, keinen Quellcode-Ordner. Sie können überprüfen, ob der Ordner eine codeql-database.yml-Datei enthält.

Zusätzliche Befehle

# UI öffnen, um vorhandene Ergebnisse anzuzeigen (ohne Analyse auszuführen)
poetry run vulnhalla-ui

# Konfiguration validieren: CodeQL, LLM, Logging (ohne Analyse)
poetry run vulnhalla-validate

# Analysierte Repositorys und deren Problemzahlen auflisten
poetry run vulnhalla-list

# Beispiel-Pipeline ausführen (analysiert videolan/vlc und redis/redis)
poetry run vulnhalla-example

---

🖥️ Benutzeroberfläche (UI)

Vulnhalla enthält eine voll ausgestattete Benutzeroberfläche zum Durchsuchen und Erkunden der Analyseergebnisse.

UI starten

poetry run vulnhalla-ui

UI-Layout

Die UI zeigt einen zweigeteilten oberen Bereich mit einer Steuerungsleiste unten an:

Oberer Bereich (nebeneinander, in der Größe veränderbar):

• Linkes Panel (Problemliste):

  • Datentabelle mit: ID, Repo, Problemname, Datei, LLM-Entscheidung, Manuelle Entscheidung
  • Problemanzahl und Sortierindikator
  • Suchfeld unten, aktualisiert während der Eingabe (Groß-/Kleinschreibung wird ignoriert).

• Rechtes Panel (Details):

  • LLM-Entscheidungsabschnitt: Zeigt die LLM-Klassifizierung (True Positive, False Positive oder Needs More Data)
  • Metadatenabschnitt: Problemname, Repo, Datei, Zeile, Typ, Funktionsname
  • Codeabschnitt:
    • 📌 Erster Code-Kontext (das erste Code-Snippet, das das LLM sah)
    • 📥 Zusätzlicher Code (Code, den das LLM während des Gesprächs anforderte) – nur angezeigt, wenn zusätzlicher Code vorhanden ist
    • Verwundbare Zeile rot markiert
  • Zusammenfassungsabschnitt: LLM-Endantwort/-Entscheidung
  • Manuelle Entscheidung auswählen: Dropdown unten, um das manuelle Urteil zu setzen (True Positive, False Positive, Uncertain oder Not Set)

Untere Steuerungsleiste:

• Sprache: C (derzeit einzige unterstützte Sprache)
• Filter nach LLM-Entscheidung: Alle, True Positive, False Positive, Needs more Info to decide
• Aktionsschaltflächen: Aktualisieren, Analyse ausführen
• Hilfetext zu Tastenkombinationen

Tastenkombinationen