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 文件中的环境变量进行管理。以下是完整参考：

必需变量

提供商特定必需变量

OpenAI：

Azure OpenAI：

Gemini (Google)：

AWS Bedrock：

* 认证：使用 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。

可选变量

⚠️ 重要提示： 除非您完全理解其影响，否则不要提高 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 一起使用）

UI 将这些映射为：

• 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 - GitHub API 的 HTTP 请求
• pySmartDL - CodeQL 数据库的智能下载管理器
• litellm - 统一 LLM 接口，支持多个提供商
• python-dotenv - 环境变量管理
• PyYAML - CodeQL 包文件的 YAML 解析
• textual - 终端 UI 框架
• pytest - 测试框架（开发依赖）
• mypy - 静态类型检查器（开发依赖）

CodeQL 查询

CodeQL 查询组织在 data/queries/<LANG>/ 目录下：

• issues/ - 安全问题检测查询
• tools/ - 辅助查询（函数树、类、全局变量、宏）

每个目录包含一个 qlpack.yml 文件，用于定义 CodeQL 包。

📄 许可证

版权所有 (c) 2025 CyberArk Software Ltd. 保留所有权利。

本仓库根据 Apache 许可证 2.0 版许可 - 有关详细信息，请参阅 LICENSE.txt。

🤝 贡献

我们欢迎各种形式的贡献。有关如何开始的说明以及开发工作流的描述，请参阅我们的 贡献指南。

行为准则

请阅读并遵守我们的 行为准则。我们致力于为所有贡献者提供一个友好和包容的环境。

📧 联系方式

如果您有任何功能请求或项目问题，请随时通过 GitHub Issues 联系我们。