vulnerability-db

name	vulnerability-db
description	SQLite 漏洞数据库 Schema、vuln-db Tool API 参考、各 Agent 交互模式。所有参与漏洞扫描的 Agent 应参考此 Skill 来读写漏洞数据。

Use this when

• 需要向数据库插入候选漏洞（Scanner）
• 需要查询或更新漏洞数据（Verification）
• 需要获取统计信息（Coordinator）
• 需要了解数据库表结构和字段含义
• 需要执行去重操作

概述

漏洞数据存储在 SQLite 数据库中（{CONTEXT_DIR}/scan.db）。所有漏洞的读写通过 vuln-db 工具进行，该工具以 command 参数区分操作类型。

数据库路径

DB_PATH = {CONTEXT_DIR}/scan.db = {SCAN_OUTPUT}/.context/scan.db

此路径由 Orchestrator 在调用每个子 Agent 时传递。

数据库 Schema

vulnerabilities 表

存储所有漏洞数据（候选阶段 + 验证阶段）。

字段	类型	默认值	说明
id	TEXT PK	-	漏洞唯一标识，如 VULN-DF-MEM-001
phase	TEXT	'candidate'	生命周期阶段：candidate（Scanner 写入）、verified（Verification 更新）
source_agent	TEXT	-	发现漏洞的 Scanner：dataflow-scanner 或 security-auditor
source_module	TEXT	NULL	所属扫描模块名称
type	TEXT	NULL	漏洞类型：buffer_overflow、use_after_free、command_injection 等
cwe	TEXT	NULL	CWE 编号，如 CWE-120
severity	TEXT	NULL	Scanner 评估的严重性：Critical/High/Medium/Low
description	TEXT	NULL	漏洞描述
file	TEXT	NULL	漏洞所在文件（相对于 PROJECT_ROOT）
line_start	INTEGER	NULL	起始行号
line_end	INTEGER	NULL	结束行号
function_name	TEXT	NULL	所在函数名
code_snippet	TEXT	NULL	漏洞代码片段
data_flow	TEXT	NULL	数据流路径（自由文本）
pre_validated	INTEGER	0	是否通过预验证
cross_module	INTEGER	0	是否为跨模块漏洞
modules_involved	TEXT	NULL	涉及的模块列表（JSON 数组字符串）
confidence	INTEGER	NULL	置信度评分 0-100（Verification 填写）
status	TEXT	NULL	验证状态：CONFIRMED/LIKELY/POSSIBLE/FALSE_POSITIVE（Verification 填写）
original_severity	TEXT	NULL	验证前的原始严重性（Verification 填写）
verified_severity	TEXT	NULL	验证后重评估的严重性（Verification 填写）
scoring_details	TEXT	NULL	评分明细（JSON 对象字符串，详见 @skill:confidence-scoring）
veto_applied	INTEGER	0	是否被一票否决
veto_reason	TEXT	NULL	否决原因：chain_broken/unreachable/test_code
verification_reason	TEXT	NULL	验证结论说明
control_flow	TEXT	NULL	控制流路径
mitigations_found	TEXT	NULL	发现的缓解措施（JSON 数组字符串）
source_agents	TEXT	NULL	来源 Agent 列表（JSON 数组，去重后可能有多个）
dedup_kept	INTEGER	1	去重后是否保留（0=已合并到其他条目）
merged_into	TEXT	NULL	合并到的目标漏洞 ID
created_at	TEXT	datetime('now')	创建时间
updated_at	TEXT	datetime('now')	更新时间

scan_metadata 表

字段	类型	说明
key	TEXT PK	元数据键
value	TEXT	元数据值

agent_log 表

字段	类型	说明
id	INTEGER PK	自增 ID
agent_name	TEXT	Agent 名称
module_name	TEXT	模块名称
phase	TEXT	所处阶段
status	TEXT	执行状态
message	TEXT	日志消息
item_count	INTEGER	处理条目数
created_at	TEXT	记录时间

漏洞生命周期

Scanner 发现 ──(insert)──→ phase='candidate'
                              │
Verification dedup ───────→ dedup_kept=0 (重复项)
                              │
Verification worker ──(update)──→ phase='verified'
                                    ├── status=CONFIRMED (confidence ≥ 80)
                                    ├── status=LIKELY (60 ≤ confidence < 80)
                                    ├── status=POSSIBLE (40 ≤ confidence < 60)
                                    └── status=FALSE_POSITIVE (confidence < 40 或 veto)

vuln-db 工具命令参考

init

初始化数据库，创建表和索引。Orchestrator 在扫描开始时调用一次。

vuln-db command=init db_path={CONTEXT_DIR}/scan.db

insert

批量插入候选漏洞。Scanner Worker 完成模块扫描后调用。

vulnerabilities 参数为 JSON 数组字符串，每个对象必须包含 id、source_agent、source_module。

vuln-db command=insert db_path={DB_PATH} vulnerabilities='[
  {
    "id": "VULN-DF-MEM-001",
    "source_agent": "dataflow-scanner",
    "source_module": "内存管理模块",
    "type": "buffer_overflow",
    "cwe": "CWE-120",
    "severity": "Critical",
    "file": "src/memory/allocator.c",
    "line_start": 150,
    "line_end": 155,
    "function": "alloc_buffer",
    "description": "...",
    "code_snippet": "...",
    "data_flow": "src/input.c:50 read_input() [SOURCE]\nsrc/memory/allocator.c:120 process_data()\nsrc/memory/allocator.c:150 alloc_buffer() [SINK]",
    "pre_validated": true
  }
]'

query

按条件查询漏洞，返回 JSON 数组。

vuln-db command=query db_path={DB_PATH} phase=candidate source_module=内存管理模块
vuln-db command=query db_path={DB_PATH} phase=verified exclude_status=FALSE_POSITIVE min_confidence=40
vuln-db command=query db_path={DB_PATH} ids=VULN-DF-MEM-001,VULN-DF-MEM-002

返回值为 JSON 数组字符串，已自动解析 scoring_details 等 JSON 字段。data_flow 为纯文本，直接返回。

update

更新单个漏洞的验证结果，自动将 phase 设为 verified。

vuln-db command=update db_path={DB_PATH} id=VULN-DF-MEM-001 fields='{
  "confidence": 85,
  "status": "CONFIRMED",
  "original_severity": "Critical",
  "verified_severity": "Critical",
  "scoring_details": {"base": 30, "reachability": 25, "controllability": 15, "mitigations": -5, "context": 10, "cross_file": 10},
  "veto_applied": false,
  "verification_reason": "..."
}'

batch-update

批量更新多个漏洞。Verification Worker 完成批次验证后调用。

vuln-db command=batch-update db_path={DB_PATH} updates='[
  {"id": "VULN-DF-MEM-001", "fields": {"confidence": 85, "status": "CONFIRMED", ...}},
  {"id": "VULN-DF-MEM-002", "fields": {"confidence": 20, "status": "FALSE_POSITIVE", "veto_applied": true, "veto_reason": "test_code"}}
]'

dedup

对所有 phase=candidate 的漏洞按 (file, line_start, function_name, type) 去重。保留 severity 最高的条目，将其他条目标记为 dedup_kept=0 并合并 source_agents。

Verification Coordinator 在分批调度前调用一次。

vuln-db command=dedup db_path={DB_PATH}

stats

获取聚合统计信息，可选按 phase 过滤。

vuln-db command=stats db_path={DB_PATH} phase=verified

返回按 status、severity、module 分组的计数。

log

记录 Agent 执行事件。

vuln-db command=log db_path={DB_PATH} agent_name=dataflow-scanner module_name=内存管理模块 phase=scanning status=success item_count=8

export-json

将查询结果导出为 JSON 文件（调试/兼容用途）。

vuln-db command=export-json db_path={DB_PATH} phase=verified exclude_status=FALSE_POSITIVE output={CONTEXT_DIR}/verified_export.json

各 Agent 交互模式

Orchestrator

1. vuln-db init → 创建数据库
2. 调用 Architecture（输出 project_model.json、call_graph.json，不涉及 DB）
3. 并行调用 Scanner，传递 DB_PATH
4. 调用 Verification，传递 DB_PATH
5. 调用 Details Analyzer，传递 DB_PATH（无 CONFIRMED 漏洞时可跳过）
6. 调用 Reporter，传递 DB_PATH
7. vuln-db stats → 获取最终统计

Scanner Worker (dataflow-module-scanner / security-module-scanner)

1. 读取源代码 + project_model.json + call_graph.json
2. 扫描发现漏洞
3. vuln-db insert → 写入候选漏洞
4. vuln-db log → 记录完成状态

Scanner Coordinator (dataflow-scanner / security-auditor)

1. 读取 project_model.json 获取模块列表
2. 调度 module-scanner Worker（传递 DB_PATH）
3. 跨模块分析 → vuln-db insert（cross_module=true）
4. vuln-db stats phase=candidate → 验证结果完整性

Verification Coordinator

1. vuln-db dedup → 去重
2. vuln-db query phase=candidate → 获取待验证列表
3. 按 source_module 分组
4. 调度 verification-worker（传递 DB_PATH + 漏洞 ID 列表）
5. vuln-db stats phase=verified → 汇总验证结果

Verification Worker

1. vuln-db query ids=ID1,ID2,... → 获取分配的漏洞批次
2. 逐个验证（读取源代码、调用图、评分）
3. vuln-db batch-update → 写回验证结果
4. vuln-db log → 记录完成状态

Reporter

1. report-generator → 程序化生成两份报告（report_confirmed.md + report_unconfirmed.md）
2. 读取已确认报告骨架
3. 为已确认报告添加执行摘要、深度分析、修复建议

Details Analyzer (协调者)

1. vuln-db query status=CONFIRMED → 获取已确认漏洞列表
2. 读取 call_graph.json + project_model.json
3. 为每个漏洞调度 @details-worker
4. 不写入数据库（只读）

Details Worker

1. vuln-db query ids={VULN_ID} → 获取单个漏洞详情
2. 读取源代码进行深度利用分析
3. 判定为误报 → 跳过，不写文件
4. 判定为真实漏洞 → 写入 {SCAN_OUTPUT}/details/{VULN_ID}.md
5. 不写入数据库（只读）