Vulnhalla

自动化 CodeQL 分析与 LLM 分类

有关 Vulnhalla 研究与动机的详细概述，请参阅官方 CyberArk 威胁研究博客文章：

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+ 不支持 grpcio）
  • 从 python.org 下载

• CodeQL CLI

  • 从 CodeQL CLI 发布版 下载
  • 确保 codeql 已加入 PATH，或者在 .env 中设置路径（见第 2 步）

• （可选）GitHub API 令牌

  • 用于提升数据库下载的速率限制
  • 从 GitHub 设置 > 令牌 获取

• LLM API 密钥

  • 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

# 选择任意支持的 Python：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

# 使用任意支持的 Python：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  # 若安装有多个 Python 版本，强制 Poetry 使用支持版本
poetry install
poetry run vulnhalla-setup

macOS / Linux：

# 选择一个您已安装的支持版本：3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # 若安装有多个 Python 版本，强制 Poetry 使用支持版本
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. 打开 UI 浏览结果

使用本地 CodeQL 数据库

如果您已有磁盘上的 CodeQL 数据库（例如手动创建或从之前的运行遗留），可以使用 --local / -l 标志跳过 GitHub 获取步骤：

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 文件来验证。

附加命令

# 打开 UI 查看现有结果（不运行分析）
poetry run vulnhalla-ui

# 验证配置：CodeQL、LLM、日志（不运行分析）
poetry run vulnhalla-validate

# 列出已分析的仓库及其问题数量
poetry run vulnhalla-list

# 运行示例流水线（分析 videolan/vlc 和 redis/redis）
poetry run vulnhalla-example

---

🖥️ 用户界面 (UI)

Vulnhalla 包含一个功能完整的用户界面，用于浏览和探索分析结果。

运行 UI

poetry run vulnhalla-ui

UI 布局

UI 显示一个双面板顶部区域，底部为控制栏：

顶部区域（左右并排，可调整大小）：

• 左面板（问题列表）：

  • DataTable 显示：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
• 操作按钮：刷新、运行分析
• 快捷键帮助文本

快捷键

• ↑/↓ - 导航问题列表（逐行）
• 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 问题数据
• 函数上下文
• 数据库路径（包含组织/仓库信息：output/databases/<LANG>/<ORG>/<REPO>）
• 问题定位

---

🛠 故障排除

• CodeQL CLI 未找到： 在 .env 文件中将 CODEQL_PATH 设置为 CodeQL 可执行文件的完整路径。 Windows 上：路径必须以 .cmd 结尾（例如 C:\path\to\codeql\codeql.cmd）。

• GitHub 速率限制： 在 .env 文件中设置 GITHUB_TOKEN（从 https://github.com/settings/tokens 获取令牌）。

• LLM 问题： 检查 .env 中的 API 密钥是否与所选提供商匹配。

• UI 中的导入错误： 确保从项目根目录运行，或使用 python examples/ui_example.py（它会处理路径设置）。

---

⚙️ 配置参考

环境变量

所有配置通过 .env 文件中的环境变量进行管理。以下是完整参考：

必需变量

变量	必需于	描述
CODEQL_PATH	所有环境	CodeQL 可执行文件路径。如果 CodeQL 已在 PATH 中，则默认值为 codeql。如果不在 PATH 中，请使用完整路径（例如 Windows 上为 C:\path\to\codeql\codeql.cmd）
PROVIDER	所有环境	LLM 提供商：openai、azure、gemini、bedrock、anthropic、mistral、groq、openrouter、ollama 等
MODEL	所有环境	模型名称（例如 gpt-4o、gpt-4-turbo、gemini-2.5-flash）

提供商特定必需变量

OpenAI：

变量	描述
OPENAI_API_KEY	您的 OpenAI API 密钥，来自 platform.openai.com

Azure OpenAI：

变量	描述
AZURE_OPENAI_API_KEY 或 AZURE_API_KEY	您的 Azure OpenAI API 密钥
AZURE_OPENAI_ENDPOINT 或 AZURE_API_BASE	您的 Azure OpenAI 端点 URL（例如 https://your-resource.openai.azure.com）
AZURE_OPENAI_API_VERSION 或 AZURE_API_VERSION	API 版本（默认：2024-08-01-preview）

Gemini (Google)：

变量	描述
GOOGLE_API_KEY	您的 Google API 密钥，来自 Google AI Studio

AWS Bedrock：

变量	必需	描述
AWS_REGION_NAME	是	AWS 区域（例如 us-east-1、us-west-2）
AWS_PROFILE	否*	AWS 配置文件名称（用于 SSO/凭证文件认证）
AWS_ACCESS_KEY_ID	否*	AWS 访问密钥（如果不使用配置文件）
AWS_SECRET_ACCESS_KEY	否*	AWS 秘密密钥（如果不使用配置文件）
AWS_SESSION_TOKEN	否	临时 STS 凭证的会话令牌

* 认证：使用 AWS_PROFILE 或 AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY（+ 可选的 AWS_SESSION_TOKEN 用于 STS）。

Bedrock .env 示例（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 用户： 使用 Vulnhalla 前，请运行 aws sso login --profile your-profile

🔧 重要 - 模型选择： 选择 Bedrock 模型时，请确保它支持工具调用/函数调用（并非所有 Bedrock 模型都支持）。工具调用是 Vulnhalla 分析流程的关键部分，因此选择兼容的模型对功能和结果有重大影响。兼容的模型包括：Claude 3.x、Mistral 或 Cohere Command R。

可选变量