feat:Resolving Call Chain Sequence Anomalies and Duplicate Nodes in VulnGym

[Xiu11111]

VulnGym Trace 调用链清理工具 — 工作介绍

完成者： Xiu1111

对应 Issue： Tencent/VulnGym #5 — 清理 VulnGym 调用链顺序异常和重复节点

---

一、项目概述

VulnGym 是腾讯悟空安全团队联合多所高校发布的项目级白盒漏洞挖掘基准数据集，用于评估 AI Agent 在真实工程环境中的漏洞检测能力。Issue #5 要求对其 entries.jsonl 中 408 条 entry 的 trace 调用链进行数据质量清理，识别并修复以下三类结构异常：

异常类型 | 说明 -- | -- 重复节点 | trace 数组中 {file, line, code} 三元组完全相同的节点 before-entry 异常 | trace 节点在 entry_file 中行号位于 entry_point 之前 after-critical 异常 | trace 节点在 critical_file 中行号位于 critical_operation 之后

# VulnGym Trace 调用链清理工具 — 工作介绍

完成者： Xiu11111

对应 Issue： [Tencent/VulnGym #5 — 清理 VulnGym 调用链顺序异常和重复节点](#5)

---

一、项目概述

VulnGym 是腾讯悟空安全团队联合多所高校发布的项目级白盒漏洞挖掘基准数据集，用于评估 AI Agent 在真实工程环境中的漏洞检测能力。Issue #5 要求对其 entries.jsonl 中 408 条 entry 的 trace 调用链进行数据质量清理，识别并修复以下三类结构异常：

异常类型	说明
重复节点	trace 数组中 {file, line, code} 三元组完全相同的节点
before-entry 异常	trace 节点在 entry_file 中行号位于 entry_point 之前
after-critical 异常	trace 节点在 critical_file 中行号位于 critical_operation 之后

核心设计原则：源码行号表示声明顺序，不等于运行时执行顺序，因此采用保守策略——仅对 verify=0 且明确越界的节点执行自动修复，verify=1 条目完全保护。

---

二、交付物清单

所有交付物位于 my_work/ 目录下：

2.1 核心输出文件

路径	说明	数据量
data/entries.trace_fixed.jsonl	修复后的 JSONL 数据文件	408 行，2069 个 trace 节点
reports/trace_fix_log.csv	修改日志（entry_id、字段、修改前后、原因）	4 条修改记录
reports/trace_findings.csv	每个 trace 节点的详细检测结果	完整检测明细
reports/trace_needs_human.csv	需要人工复核的条目清单	214 个条目
reports/trace_structure_report.json	汇总统计 JSON	完整统计摘要

2.2 工具源代码

路径	说明
tools/trace_cleanup/cleanup.py	主入口脚本，协调全流程
tools/trace_cleanup/line_parser.py	行号归一化模块（int / "start-end" 统一为元组）
tools/trace_cleanup/duplicate_detector.py	重复节点检测（基于 {file, line, code} 三元组）
tools/trace_cleanup/order_checker.py	顺序异常检测（before-entry / after-critical 分类）
tools/trace_cleanup/fixer.py	修复执行模块（conservative / fix 双模式）
tools/trace_cleanup/report_generator.py	报告生成模块
tools/trace_cleanup/README.md	使用说明文档

---

三、检测统计摘要

指标	数值
总 entries	408
人工已审核（verify=1）	393
未审核（verify=0）	15
原始 trace 节点总数	2073
重复节点	7（全部 desc 冲突，需人工复核）
before-entry 异常（明确）	88
before-entry 异常（模糊）	197
after-critical 异常（明确）	187
after-critical 异常（模糊）	208
跨文件节点（受保护不比较）	382
自动修复条目数	4
修复后 trace 节点数	2069（-4）
需人工复核条目数	214

---

四、优先样本验证结果

Issue #5 指定了 4 个优先检查样本，均已完成处理：

entry_id	异常类型	处理结果
entry-00103	trace 节点在 entry_point 之前	1 个明确越界节点已删除
entry-00320	trace 节点在 entry_point 之前	1 个明确越界节点已删除
entry-00511	双重异常（before-entry + after-critical）	1 个明确越界节点已删除
entry-00185	trace 节点在 critical_operation 之后	1 个明确越界节点已删除

所有 4 个样本均为 verify=0，修复操作严格限定于明确越界（strictly_before / strictly_after）场景，verify=1 条目零修改。

---

五、两种运行模式

保守模式（conservative，默认）

仅检测和报告所有异常，不做任何修改。适用于首次运行和人工审核前。

修复模式（fix）

对 verify=0 条目的明确异常执行自动删除：

• 删除完全位于 entry_point 之前的 trace 节点
• 删除完全位于 critical_operation 之后的 trace 节点
• verify=1 条目完全保护，不做任何修改
• 所有修改操作写入 trace_fix_log.csv

cd my_work

# 保守模式
python -m tools.trace_cleanup.cleanup --input ../VulnGym/data/entries.jsonl --output data/entries.trace_fixed.jsonl --reports-dir reports

# 修复模式
python -m tools.trace_cleanup.cleanup --input ../VulnGym/data/entries.jsonl --output data/entries.trace_fixed.jsonl --reports-dir reports --mode fix

---

六、设计决策

1. 源码行号 != 执行顺序 — 行号表示声明顺序，不等于运行时调用关系；这是所有判断的根本前提。
2. 保守优于激进 — 模糊区域（区间重叠）标记为 ambiguous，进入人工复核，不自动删除。
3. 跨文件是高压线 — 不同文件的行号之间不做任何比较或排序，严格按 file 分组独立检测。
4. verify=1 完全保护 — 已人工审核的数据不做任何自动修改，即使检测到异常也仅报告。
5. 可追溯性不可妥协 — 每条修改记录包含 entry_id、verify 状态、字段路径、action 类型、修改前后内容及修改原因。

---

七、验收标准对照

#	Issue #5 验收标准	达成情况
1	完整扫描 408 条 entries	全部 408 条完成扫描，零崩溃
2	正确处理 int 和 "start-end" 行号格式	int=392+368+1744，str=16+40+325，归一化为 (start, end) 元组
3	同文件越界稳定检测	before-entry / after-critical 双重检测，明确/模糊分类
4	跨文件不错误排序	382 个跨文件节点标记 skip，仅同文件内做行号比较
5	修改日志完整可追溯	CSV 含 entry_id、verify、field、action、before、after、reason、desc_merged 8 列
6	修复后仍满足 SCHEMA.md	JSONL 格式、字段完整性、类型约束全部通过验证