CodeQL + LLM 自主漏洞审计 Agent

基于 CodeQL 静态分析与大语言模型（LLM）的自主漏洞审计系统。采用 ReAct 架构实现 Agent 自主决策、工具调用和多轮验证，对 C/C++ 开源项目进行自动化安全审计。

系统架构

┌────────────────────────────────────────────────────────────────┐
│                        输入层                                    │
│  CodeQL Database ──→ SARIF Report (133 alerts) ──→ 解析+上下文提取  │
└────────────────────────────────┬───────────────────────────────┘
                                 │
                                 ▼
┌────────────────────────────────────────────────────────────────┐
│              Autonomous Audit Agent (核心)                       │
│                                                                │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Tier 1: 规则预过滤 (无 LLM 调用)                           │  │
│  │   代码质量规则 → 自动判定 FALSE_POSITIVE (96 alerts)        │  │
│  └──────────────────────────┬───────────────────────────────┘  │
│                             │ 安全相关 (37 alerts)              │
│                             ▼                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Tier 2: ReAct 分析循环 (工具调用 LLM)                      │  │
│  │                                                          │  │
│  │   ┌─────────┐    ┌───────────┐    ┌──────────┐          │  │
│  │   │  Think  │───→│    Act    │───→│ Observe  │──┐       │  │
│  │   └─────────┘    └───────────┘    └──────────┘  │       │  │
│  │        ▲              │                          │       │  │
│  │        └──────────────┼──────────────────────────┘       │  │
│  │                       ▼ (max 3 rounds)                   │  │
│  │              ┌─────────────────┐                         │  │
│  │              │   Tool Box      │                         │  │
│  │              │  · read_file    │                         │  │
│  │              │  · grep_source  │                         │  │
│  │              │  · get_function │                         │  │
│  │              │  · get_callers  │                         │  │
│  │              │  · get_typedef  │                         │  │
│  │              └─────────────────┘                         │  │
│  └──────────────────────────┬───────────────────────────────┘  │
│                             │ TRUE_POSITIVE?                    │
│                             ▼                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Tier 3: Devil's Advocate 验证                              │  │
│  │   对抗性二次审查 → 确认或推翻判定                            │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────────┬───────────────────────────────┘
                                 │
                                 ▼
┌────────────────────────────────────────────────────────────────┐
│                        输出层                                    │
│  audit_results.json ──→ report_gen.py ──→ Vulnerability Report  │
└────────────────────────────────────────────────────────────────┘

核心功能运行截图

Docker 构建与 CodeQL 扫描

在 Docker 容器中自动完成 curl 源码编译、CodeQL 数据库构建和安全扫描。

SARIF 解析

解析 CodeQL 输出的 SARIF 报告，提取 133 条结构化告警并按规则分类统计。

代码上下文提取

从 curl 源码中自动提取每条告警对应的函数体，为 LLM 准备输入。

Agent 自主审计（Tier 1 预过滤 + Tier 2 ReAct 分析 + Summary）

Agent 启动后：Tier 1 预过滤自动跳过 96 条非安全告警；Tier 2 对 37 条安全告警执行 ReAct 循环，LLM 自主调用工具（read_file、grep_source、get_callers 等）获取额外上下文，多轮推理后给出判定。最终 Summary 显示 87 次工具调用。

线性流水线对比

线性流水线（无工具调用）产生 2 个幻觉性 TRUE_POSITIVE；Agent 方案通过工具验证消除了所有误判。

报告生成

最终生成结构化审计报告，包含统计数据、规则有效性分析和详细判定理由。

核心特性

特性	说明
自主决策	基于规则分类自动跳过非安全告警，节省 72% API 调用
工具调用	LLM 自主决定调用 5 个源码分析工具获取上下文
多轮推理	ReAct 循环最多 3 轮，逐步深入分析
对抗验证	Devil's Advocate 机制挑战 TRUE_POSITIVE 判定
幻觉缓解	低温度 + 怀疑性提示 + 结构化输出 + 工具验证

快速开始

环境要求

• Python 3.10+
• Docker Desktop（用于编译目标项目和 CodeQL 扫描）
• LLM API 访问（OpenAI 兼容接口）

安装

pip install openai

获取目标项目源码

cd codes/
git clone --branch curl-7_88_0 --depth 1 https://github.com/curl/curl.git

配置 API

创建 config/config.json：

{
    "API_key": "your-api-key",
    "base_url": "https://api.example.com",
    "model": "claude-opus-4-6"
}

完整流程

# Step 1: 构建 Docker 镜像（编译 curl + CodeQL 扫描）
docker build -t codeql-curl .

# Step 2: 提取扫描结果
docker create --name codeql-tmp codeql-curl
docker cp codeql-tmp:/workspace/results.sarif output/results.sarif
docker rm codeql-tmp

# Step 3: 解析 SARIF 报告
python codes/parse_sarif.py output/results.sarif codes/curl -o output/alerts.json

# Step 4: 提取代码上下文
python codes/extract_context.py output/alerts.json codes/curl -o output/alerts_with_context.json

# Step 5: 运行 Agent 审计
python codes/agent.py --input output/alerts_with_context.json \
                      --config config/config.json \
                      --source codes/curl

# Step 6: 生成报告
python codes/report_gen.py output/audit_results.json

仅运行 Agent（已有扫描数据）

python codes/agent.py --input output/alerts_with_context.json \
                      --config config/config.json \
                      --source codes/curl \
                      --output output/audit_results.json

运行结果

============================================================
  AGENT AUDIT SUMMARY
============================================================
  Total alerts:       133
  TRUE_POSITIVE:      0
  FALSE_POSITIVE:     133
  UNCERTAIN:          0
  ERROR:              0
  ---
  Tier 1 (pre-filter):  96
  Tier 2 (ReAct):       37
  Tier 3 (verified):    0
  Total tool calls:     87
  Verified findings:    0
============================================================

项目结构

CodeQL_agent/
├── README.md                     # 本文件
├── .gitignore
├── Dockerfile                    # Docker 环境（编译 + CodeQL 扫描）
├── build_and_scan.sh             # 构建辅助脚本
├── config/
│   └── config.json               # LLM API 配置（不入库）
├── codes/
│   ├── agent.py                  # ★ 核心：自主审计 Agent（ReAct 循环）
│   ├── parse_sarif.py            # SARIF 报告解析
│   ├── extract_context.py        # 代码上下文提取
│   ├── llm_audit.py              # 线性流水线基线（对比用）
│   ├── report_gen.py             # Markdown 报告生成
│   └── curl/                     # curl 7.88.0 源码（不入库，需自行 clone）
├── output/
│   ├── results.sarif             # CodeQL 原始扫描结果
│   ├── alerts.json               # 解析后的结构化告警
│   ├── alerts_with_context.json  # 带代码上下文的告警
│   ├── audit_results.json        # Agent 审计结果
│   ├── report.md                 # 最终审计报告
│   └── report_summary.csv        # 摘要表格
└── docs/
    ├── 实验报告.md                # 完整实验报告
    ├── 操作手册.md                # 复现步骤
    ├── 任务分析与规划.md          # 任务拆解
    └── 目标项目选型调研.md        # 选型依据

Agent vs 线性流水线

维度	线性流水线 (llm_audit.py)	Agent (agent.py)
架构	逐条单次 LLM 调用	ReAct 循环 + 工具调用
API 调用	133 次	37 次 + 工具轮次
工具能力	无	5 个源码分析工具
上下文	固定（≤80 行函数体）	动态（LLM 自主扩展）
验证机制	无	Devil's Advocate 二次审查
误判	2 个幻觉性 TP	0（通过工具验证消除）

技术栈

• 静态分析： CodeQL CLI v2.21.4 + codeql/cpp-queries@1.4.2
• LLM： Claude Opus (via OpenAI-compatible API)
• Agent 框架： 自研 ReAct 循环 (Python)
• 工具调用： OpenAI function-calling API + 文本解析 fallback
• 容器化： Docker (ubuntu:22.04)
• 报告格式： SARIF v2.1.0 → JSON → Markdown

参考文献

• ReAct: Synergizing Reasoning and Acting in Language Models (Yao et al., ICLR 2023)
• CodeQL CLI Documentation
• curl Security Vulnerabilities
• SARIF v2.1.0 OASIS Standard
• OpenAI Function Calling