从代码到 CVE — CyberAI 使用完全指南

01 · 快速开始

三步跑起第一次扫描

从零到开始扫描一个 C 库，需要大约 10 分钟。你需要一个智谱 AI 的 API Key。

1

安装

克隆仓库并安装依赖

          bash
          
        
# 克隆仓库
git clone https://github.com/fxp/cyberai.git && cd cyberai
# 配置 API Key（必填）
cp .env.example .env
echo "GLM_API_KEY=your_key_here" >> .env
# 安装（editable 模式，方便开发）
pip install -e ".[dev]"

2

目标

下载并解压目标源码

          bash
          
        
cd targets/
# 以 libtiff 为例
wget https://download.osgeo.org/libtiff/tiff-4.7.0.tar.gz
tar xf tiff-4.7.0.tar.gz
cd ..

已下载的 15 个目标已在 targets/ 目录，无需重新下载。

3

扫描

运行 Pipeline A 扫描

          bash
          
        
# 使用 CLI（推荐）
cyberai scan targets/tiff-4.7.0 --model glm-5.1 --max-parallel 4
# 或使用专用脚本（推荐用于已有扫描配置的库）
python scripts/scan_libtiff_t2.py
# 结果写入 research/libtiff/t2_glm5_results.json

预期耗时：扫描一个中型库（~40 个文件）约需 20-40 分钟，费用约 ¥5-15。使用 --max-parallel 8 可以加快速度，但注意 API 并发限制。

02 · 目录结构

项目文件树

了解每个目录和文件的职责，是高效使用本工具的前提。

📁 cyberai/

├── 📁src/cyberai/核心 Python 包

│ ├── 📁scanner/漏洞扫描引擎

│ │ ├── 🐍carlini.pyPipeline A 主引擎，4阶段扫描

│ │ ├── 🐍file_ranker.py文件攻击面评分与排序

│ │ ├── 🐍dedup.pyfindings 去重与聚合

│ │ └── 🐍verifier.pyLLM-as-Judge 二次验证

│ ├── 📁models/模型抽象层

│ │ ├── 🐍base.pySecurityAgent 抽象接口

│ │ ├── 🐍glm.pyGLM-5.1 / GLM-4-flash 适配器

│ │ └── 🐍registry.py模型注册表，--model 参数解析

│ ├── 📁api/FastAPI REST 接口（可选）

│ ├── 📁infra/阿里云 ECI 弹性容器（云端扫描）

│ ├── 📁storage/OSS 对象存储 + SQLite 本地 DB

│ ├── 📁tracker/API 成本追踪

│ └── 🐍cli.pyClick CLI 入口 (cyberai scan / verify / report)

├── 📁scripts/每个目标的扫描脚本

│ ├── 🐍scan_libtiff_t2.pylibtiff 专用脚本（含优先级配置）

│ ├── 🐍make_extracts.py函数级代码切片工具

│ ├── 🐍process_scan_results.py原始结果后处理

│ └── 🐍verify_candidates.py候选漏洞批量验证

├── 📁research/研究成果（按目标库分组）

│ ├── 📁libtiff/— CVE 候选 CAND-008, CAND-010

│ │ ├── 📄vulnerability_report.md人工分析报告

│ │ ├── 📊t2_glm5_results.json原始扫描结果

│ │ └── ⚙️poc_pixarlog_abgr.cPoC 代码

│ ├── 📁disclosures/CVE 披露草稿（向维护者发送前保密）

│ ├── 📁llm_security_report/AI 时代网络安全新范式报告

│ └── 📄technical_report_v1.md方法论技术报告

├── 📁targets/已下载的目标源码（15 个，git 忽略大文件）

├── 📁docs/文档网站 (index.html, architecture.html)

├── 📁terraform/阿里云基础设施即代码（ECI + OSS）

├── 🐳docker-compose.ymlAPI 服务 + Redis 容器编排

├── 📦pyproject.toml项目配置和依赖声明

└── 🔑.env.example环境变量模板（复制为 .env）

03 · Pipeline A 原理

四阶段漏洞发现流水线

Pipeline A 是 Carlini 方法的工程实现：将每个 C/C++ 源文件切片，逐段投给 LLM，通过多轮过滤将 97% 误报降到可人工复核的数量。

S1

文件发现 + 攻击面评分

scanner/file_ranker.py

遍历项目所有 .c/.cpp 文件，计算攻击面评分。评分因子包括：文件名关键词（decode、parse、read、write、handle 权重最高）、代码行数、函数数量、已知高危 API 使用情况（memcpy、malloc、sprintf 等）。评分决定扫描优先级，高风险文件优先送入 Stage 2。

文件名关键词代码复杂度危险 API 密度函数数量

S2

并行 LLM 扫描（核心阶段）

scanner/carlini.py · CarliniPipeline

carlini.py 驱动 --max-parallel 个并发 Agent，每个 Agent 读取约 5,000 字符的代码段（PipelineConfig.token_budget 控制）。使用 CTF prompt 策略：要求 LLM 用攻击者视角寻找缓冲区溢出、整数溢出、UAF、逻辑错误。原始输出约含 97% 误报，直接写入 JSONL 文件。

CTF prompt asyncio 并发 ~97% 初始误报率 JSONL 输出

S3

去重 + 置信度过滤

scanner/dedup.py

将 Stage 2 的原始 findings 去重合并（同一代码位置的重复 finding 合并为一条）。按置信度阈值 ≥ 0.80 过滤，低于阈值的 finding 存档但不进入候选池。输出结构化的候选漏洞列表，每条记录包含文件路径、行号、漏洞类型、置信度。

置信度 ≥ 0.80 位置聚合结构化输出

S4

LLM-as-Judge 二次验证

scanner/verifier.py

用另一个独立 LLM 实例（默认同模型，可用 --verify-model 指定不同模型）对 Stage 3 候选进行交叉验证。验证器被告知这是一个"二次审核"，它不知道之前 LLM 的判断，这种盲审设计有效减少系统性误判。通过验证的 finding 标记 verified=true，进入人工复核队列。

盲审设计跨模型验证可选 verified 标记人工复核队列

04 · CLI 命令参考

命令行接口

安装后通过 cyberai 命令使用，也可以直接调用 scripts/ 下的专用脚本。

cyberai scan <project_dir> [OPTIONS]

对指定目录运行完整 Pipeline A 扫描，这是最常用的命令。

--model TEXT使用的 LLM，默认 glm-5.1

--max-files INT限制扫描文件数，调试时用

--max-parallel INT并发 Agent 数量，默认 4

--no-verify跳过 Stage 4 二次验证，加速但精度下降

--token-budget INT每文件 token 预算，默认 100000

--output-dir TEXT结果输出目录，默认 research/<name>/

cyberai verify <results.json>

对已有扫描结果跑 Stage 4 二次验证（当初次扫描用了 --no-verify 时补跑）。

cyberai report <results.json>

从 JSON 结果生成 Markdown 格式的漏洞报告，输出到 research/ 目录。

cyberai cost

查看所有扫描任务的累计 API Token 消耗和美元费用（从 SQLite 数据库读取）。

脚本工具

python scripts/make_extracts.py --target <dir> --output scripts/extracts/<name>

将源码切分为函数级代码段，存到 extracts/ 目录。专用脚本（如 scan_libtiff_t2.py）会引用这些切片。

--priority TEXT优先扫描的关键词，逗号分隔，如 "decode,parse,read"

--max-size INT每段最大字符数，默认 5000

python scripts/process_scan_results.py <results_dir>

后处理原始 JSONL 结果：统计 finding 分布、生成置信度直方图、输出 CSV 摘要。

python scripts/verify_candidates.py [--candidate-file CAND-XXX]

对候选漏洞列表进行批量深度验证。可指定单个候选 ID，也可批量验证全部候选。

05 · 添加新扫描目标

扫描一个新的 C/C++ 库

以 libwebp 1.4.0 为例，演示从零添加新扫描目标的完整流程。

下载并解压源码

将目标源码放入 targets/ 目录。源码目录必须包含 .c/.cpp 文件，可以是未编译的原始源码。

bash
cd targets/
wget https://storage.googleapis.com/downloads.webmproject.org/releases/webp/libwebp-1.4.0.tar.gz
tar xf libwebp-1.4.0.tar.gz

（可选）生成函数级代码切片

如果要使用专用扫描脚本（精确控制优先级），先用 make_extracts.py 将源码切分为函数级片段。直接用 cyberai scan 则跳过此步。

bash
python scripts/make_extracts.py \
  --target targets/libwebp-1.4.0 \
  --output scripts/extracts/libwebp \
  --priority "decode,read,vp8,huffman,lossless"

创建专用扫描脚本（推荐）

复制 scripts/scan_libtiff_t2.py 为模板，修改 SCANS 列表指定扫描顺序和优先注释，指定输出路径。

python
# scripts/scan_libwebp_t1.py — 在文件顶部说明扫描重点
EXTRACTS_DIR = Path("scripts/extracts/libwebp")
OUTPUT = Path("research/libwebp/t1_glm5_results.json")
# VP8L 无损解码——最高优先级
SCANS = [
  ("dec/vp8l_dec_A.c",    "src/dec/vp8l_dec.c [VP8LDecodeImage-A]"),
  ("dec/vp8l_dec_B.c",    "src/dec/vp8l_dec.c [VP8LDecodeImage-B]"),
  # ... 更多文件
]

运行扫描

bash
# 方式一：用专用脚本（推荐，精确控制优先级）
python scripts/scan_libwebp_t1.py
# 方式二：用 CLI（快速开始）
cyberai scan targets/libwebp-1.4.0 --model glm-5.1

分析结果并创建研究目录

扫描完成后，在 research/ 目录下为新目标创建标准结构。

bash
# 后处理原始结果
python scripts/process_scan_results.py research/libwebp/
# 生成 Markdown 报告
cyberai report research/libwebp/t1_glm5_results.json

06 · 解读扫描结果

理解输出格式和置信度

扫描结果以 JSON 格式存储。理解每个字段的含义，是从"看到一堆输出"到"找到真实漏洞"的关键一步。

{

"file": "libtiff/tif_zip.c_extract_001.c", // 源文件路径（切片后的）

"severity": "HIGH", // CRITICAL / HIGH / MEDIUM / LOW / INFO

"confidence": 0.85, // 0.0-1.0，≥0.80 进入候选池

"vuln_type": "buffer_overflow", // buffer_overflow / integer_overflow / uaf / logic_error

"title": "ZIPDecode OOB write in strip buffer",

"description": "tsize_t newsize = ... multiplication overflow ...",

"line_start": 142, "line_end": 168, // 在切片文件中的行号

"verified": true, // 经过 Stage 4 二次验证

"false_positive_reason": null // null = 候选有效；有值 = 解释为何是误报

}

置信度阈值建议

0.90 – 1.00

立即人工复核

0.80 – 0.89

候选池，批量分析

0.70 – 0.79

存档，低优先

< 0.70

忽略（97% 误报区）

07 · CVE 披露工作流

从候选漏洞到 CVE 披露

确认真实漏洞后，遵循 Google Project Zero 的 90 天协调披露政策。当前 CAND-008 处于 Day 29，进入追踪阶段。

Day 0

漏洞确认

PoC 可重现崩溃 → ASAN 验证根因 → 评估攻击面和 CVSS 分数 → 创建 research/disclosures/CAND-XXX_draft.md

Day 1-3

联系维护者

发送加密邮件至 security@<project>.org，附上漏洞摘要、影响范围、PoC 步骤。90 天窗口从此刻开始计时。

Day 1-30

等待响应 & 协商

维护者确认漏洞 → 协商修复时间线 → CVE ID 申请（通过 MITRE 或项目自有流程）

Day 30-89

补丁开发期

维护者开发修复补丁 → 测试验证 → 准备发布版本。如需延期可协商最多 14 天宽限期。

Day 90

公开披露

无论补丁是否就绪，在 Day 90 公开漏洞详情、PoC、CVE 编号。补丁未就绪时协调发布缓解措施。

CAND-008 当前状态：Day 29 / 90 天，已联系 Eclipse Mosquitto 维护团队，等待确认响应。剩余 61 天窗口。相关披露草稿位于 research/disclosures/mosquitto_CAND-008_*.md

08 · 配置参考

环境变量与模型选择

所有配置通过 .env 文件控制。复制 .env.example 修改后生效。

变量名	必填	默认值	说明
GLM_API_KEY	必填	—	智谱 AI BigModel API Key，在 bigmodel.cn 申请
ANTHROPIC_API_KEY	可选	—	Claude API Key，使用 --model claude-* 时必填
OPENAI_API_KEY	可选	—	OpenAI API Key，使用 --model gpt-* 时必填
SCANNER_MAX_PARALLEL	可选	4	并发扫描 Agent 数，建议 4-8，受 API 并发限制约束
SCANNER_TOKEN_BUDGET	可选	100000	每文件 token 预算，越大越贵但更彻底
DATABASE_URL	可选	sqlite+aiosqlite:///./cyberai.db	结果存储数据库，默认本地 SQLite
ALIYUN_*	可选	—	阿里云凭证，使用 ECI 云端扫描时必填

支持的模型（--model 参数）

glm-5.1

默认推荐

GLM-5.1，性价比最高。适合大批量扫描，成本低，速度快。

已扫描目标与 CVE 候选状态

截至 2026-05，已扫描 10+ 开源 C/C++ 库，产出 7 个 CVE 候选。

目标库	版本	候选漏洞	状态
Eclipse Mosquitto	2.0.21	CAND-008	● 披露中 Day 29
libtiff	4.7.0	CAND-010	● PoC 构建中
libjpeg-turbo	3.x	CAND-LJT-003/004	● ASAN 分析中
libwebp	1.4.0	—	● 扫描进行中
ImageMagick	7.1.2-19	CAND-005	● 深度分析中
curl	8.11.0	0	✓ 已扫描
libpng / expat / freetype	latest	待审查	✓ 已扫描
libssh2 / libxml2 / nginx	latest	待审查	✓ 已扫描
openssl / zlib / sqlite	latest	待审查	✓ 已扫描

← 项目文档主页 AI 安全新范式报告 →

从代码到 CVE —CyberAI 使用完全指南