RealVuln Benchmark

一个开放的基准测试，用于评估安全扫描器在真实世界代码中的漏洞检测能力。包含26个Python仓库、796个发现、676个漏洞和120个FP陷阱。所有目标都是Type 1（故意易受攻击的应用程序），具有`human_authored`作者身份。目前仅支持Python（Flask, Django, FastAPI, aiohttp, Tornado），计划支持JavaScript/TypeScript、Go和Java。

An open benchmark for evaluating the vulnerability detection capabilities of security scanners in real-world code. It contains 26 Python repositories, 796 findings, 676 vulnerabilities, and 120 FP traps. All target applications are Type 1 (intentionally vulnerable applications) with `human_authored` authorship. Currently, it only supports Python frameworks including Flask, Django, FastAPI, aiohttp, and Tornado, with plans to support JavaScript/TypeScript, Go, and Java.

原始信息汇总

RealVuln Benchmark 数据集概述

数据集基本信息

• 数据集名称：RealVuln Benchmark
• 主要目的：一个用于评估安全扫描器在真实代码中检测真实漏洞能力的开放基准。主要评估指标为F2分数（0-100，召回率加权）。
• 核心问题：解决现有安全扫描器基准的不足，如使用合成测试用例、样本量小、方法论由供应商控制、缺乏可重用基础设施或标签不一致等问题。
• 设计原则：开放、可扩展，使用真实世界代码，提供机器可读的基准事实（含CWE映射），包含自动化评分引擎，并支持社区贡献。

数据集内容与规模

• 目标仓库数量：27个Python代码仓库。
• 总发现数：823个。
• 漏洞数：698个。
• 误报陷阱数：125个。
• 目标类型：全部为类型1（故意编写的漏洞应用程序），且作者身份均为human_authored。
• 语言与框架：目前仅支持Python（涵盖Flask, Django, FastAPI, aiohttp, Tornado框架）。计划未来支持JavaScript/TypeScript、Go和Java。

数据结构与组织

目录结构

├── config/ │ └── cwe-families.json # 用于按类别度量的CWE分组 ├── ground-truth/{repo}/ground-truth.json # 标记漏洞的基准事实文件 ├── scan-results/{repo}/{scanner}/results.json # 扫描器输出文件（Semgrep JSON格式） ├── parsers/ # 将扫描器输出规范化为NormalisedFinding ├── scorer/ │ ├── matcher.py # 发现匹配逻辑（文件 + CWE + 行容差） │ └── metrics.py # 包含F2、精确率、召回率等度量的ScoreCard ├── score.py # 为单个仓库评分（CLI、JSON、Markdown输出） ├── dashboard.py # 多扫描器多仓库HTML仪表板（Plotly） ├── validate_gt.py # 基准事实模式验证器 └── reports/ # 生成的输出（每个仓库的记分卡被git忽略） ├── dashboard.html # 交互式跨扫描器比较（已提交） └── dashboard.json # 机器可读的分数（已提交）

基准事实模式

每个目标仓库都有一个基准事实清单，固定指向特定的提交SHA。

• 关键字段：
  • schema_version: 模式版本。
  • repo_id, repo_url: 仓库标识和URL。
  • commit_sha: 固定的提交SHA，防止基准事实漂移。
  • type: 目标类型（当前为1）。
  • language, framework: 语言和框架。
  • authorship: 作者身份（当前为human_authored）。
  • findings: 发现列表。
• 发现条目关键设计：
  • is_vulnerable: 标识是否为真实漏洞（true）或误报陷阱（false）。
  • acceptable_cwes: 可接受的CWE列表，用于处理CWE模糊性。
  • location: 漏洞位置（起始行、结束行、函数）。
  • severity: 严重性等级。
  • evidence: 证据来源（CVE ID、指南URL或手动审查）。

评估方法

发现匹配

扫描器的发现与基准事实条目匹配采用固定模式：文件路径 + CWE + 行容差。

1. 文件路径：规范化后的路径必须完全匹配。
2. CWE：扫描器报告的CWE必须在基准事实条目的acceptable_cwes列表中。
3. 行接近度：扫描器报告的行必须在[start_line - 10, end_line + 10]范围内。如果任一方缺少行信息，则跳过此检查。

发现分类与度量

• 分类：
  • 真正例：匹配is_vulnerable: true的基准事实条目。
  • 假正例：匹配is_vulnerable: false的基准事实条目，或标记了基准事实中不存在的内容。
  • 假反例：扫描器遗漏的is_vulnerable: true条目。
  • 真反例：扫描器正确忽略的is_vulnerable: false条目。
• 主要度量：F2分数（0-100标度）。F-beta（beta=2）给予召回率比精确率高4倍的权重。
• 完整度量：计算精确率、召回率、F1、F2、F2分数和假正例率。
• 细分报告：支持按CWE族和按严重性进行细分统计。
• 非确定性扫描器支持：通过--runs参数支持多轮运行模式，报告度量的平均值和标准差。

当前状态与功能

已实现功能

• 带验证的基准事实模式（validate_gt.py）。
• 带有F2、精确率、召回率、按CWE族和严重性细分报告的评分引擎。
• 基于文件路径、CWE和行容差的发现匹配。
• 用于测量假正例率的误报陷阱（is_vulnerable: false条目）。
• Semgrep格式解析器，对未知扫描器标识符自动回退。
• 带有Plotly热图的交互式HTML仪表板（dashboard.py）。
• 每个仓库的JSON和Markdown记分卡（score.py）。
• 用于非确定性扫描器平均值±标准差评分的多轮运行模式（--runs）。
• 每个基准事实文件中的固定提交SHA。

暂未实现的功能

• 真实的扫描器结果（目前只有sample-scanner占位数据）。
• 结果文件中的扫描器版本字符串或元数据清单。
• CI/CD流水线（无GitHub Actions，无pre-commit钩子）。
• CLI打包（pip install realvuln）。
• 多语言支持（目前仅Python）。
• 类型1之外的目标类型（无基于CVE的、库或基准汇总目标）。

路线图（计划中）

新增目标类型

目标将按两个独立的轴进行分类。

• 轴1：代码真实性（类型）：计划新增类型2（先前易受攻击的平台）、类型3（先前易受攻击的库）、类型4（基准汇总）和类型5（学术重现）。
• 轴2：代码作者身份：计划新增llm_assisted（LLM辅助编写）、llm_generated（主要或完全由LLM生成）和unknown（未知）等类别。

可重现性

计划为每次运行添加元数据：扫描器版本字符串、使用的确切命令、时间戳、目标仓库提交SHA和配置哈希。对于非确定性扫描器（如AI代理），计划通过多次运行来度量和报告稳定性。

研究问题：扫描器性能与代码作者身份

假设：基于LLM的扫描器在LLM生成的代码上可能比在人类编写的代码上表现得出奇地好。 方法：让每个扫描器在匹配的代码对上运行——相同的漏洞类别、相同的类型，但分别是human_authored与llm_generated。比较不同扫描器的性能差异。

其他计划工作

• 多语言支持（JavaScript/TypeScript, Go, Java）。
• CI/CD流水线（用于验证、测试、代码检查的GitHub Actions）。
• CLI打包（pip install realvuln）。
• 真实的扫描器集成（Semgrep, Bandit, SonarQube, AI-native扫描器等）。

搜集汇总

数据集介绍

构建方式

在应用安全领域，评估漏洞扫描工具的实际效能一直面临挑战。RealVuln Benchmark的构建采用了严谨的实证方法，其核心在于收集真实世界中的开源项目代码，并基于明确的漏洞证据进行人工标注。该数据集选取了27个Python仓库，涵盖Flask、Django等多种主流框架，每个仓库均被固定到特定的提交版本，以防止代码更新导致标注失效。标注过程中不仅识别了698个真实漏洞，还精心设置了125个虚假漏洞陷阱，用以精确衡量扫描工具的误报率。所有标注均遵循机器可读的JSON模式，并映射到通用的CWE漏洞分类，确保了数据的一致性与可扩展性。

特点

RealVuln Benchmark的显著特点在于其高度的真实性与设计的科学性。与使用合成测试用例的传统基准不同，该数据集完全基于现实世界的应用程序代码构建，从而能够更准确地反映扫描工具在复杂环境下的检测能力。数据集引入了虚假漏洞陷阱机制，为评估工具的误报率提供了直接依据。其标注体系支持CWE模糊匹配与行号容差，适应了不同扫描工具在漏洞分类和定位上的差异。此外，数据集架构是开放且可扩展的，提供了完整的自动化评分引擎与交互式仪表盘，旨在鼓励安全社区共同验证与贡献，推动行业评估标准的透明化发展。

使用方法

使用RealVuln Benchmark进行评估，需遵循其提供的标准化工作流程。研究人员或开发者首先需要将目标扫描工具的输出结果，转换为项目所支持的Semgrep兼容JSON格式，并将其放置于指定的目录结构中。随后，通过运行内置的评分脚本，系统将自动把扫描结果与基准真值进行匹配，依据文件路径、CWE分类及行号容差等规则计算各项性能指标。评估的核心输出是加权召回率的F2分数，同时生成精确率、召回率及按CWE家族和严重性划分的详细分析报告。项目还支持对非确定性工具进行多次运行取平均，以获取稳定的性能统计，所有结果均可通过交互式HTML仪表盘进行可视化对比与分析。

背景与挑战

背景概述

RealVuln Benchmark 是由独立安全研究人员于近期构建的一个开源基准测试框架，旨在解决应用安全扫描器在真实世界代码中检测漏洞时性能评估的缺失问题。该数据集聚焦于评估安全扫描器对实际漏洞的识别能力，其核心研究问题在于如何提供一个可信、可复现且基于真实代码的评估标准，以弥补现有基准如OWASP Benchmark的合成性缺陷以及学术数据集的工具链不完整等不足。通过整合27个Python仓库、涵盖698个真实漏洞与125个误报陷阱，该数据集为安全社区提供了一个机器可读的基准真值标注与自动化评分引擎，推动了漏洞检测工具评估的透明化与科学化进程。

当前挑战

RealVuln Benchmark 所针对的领域挑战在于安全扫描器在复杂真实代码环境中对基础漏洞（如身份验证缺失、访问控制缺陷）的检测失效问题，这要求基准测试必须克服以往合成数据集的过拟合风险与评估方法的不一致性。在构建过程中，该数据集面临多重挑战：一是确保基准真值的准确性与一致性，需对每个漏洞进行证据溯源与CWE映射，并设计误报陷阱以量化误报率；二是处理代码演化的影响，通过固定提交SHA来防止基准真值漂移；三是扩展多语言支持与多样化目标类型（如基于CVE的漏洞库），以提升基准的覆盖范围与实用性。

常用场景

经典使用场景

在软件安全评估领域，RealVuln Benchmark作为开放基准测试框架，其经典应用场景体现在对各类安全扫描工具进行系统性性能评估。该数据集通过整合27个真实Python代码仓库，涵盖698个真实漏洞与125个误报陷阱，为研究人员提供了标准化的测试环境。评估过程采用F2分数作为核心指标，重点考察扫描工具在真实代码环境中的漏洞召回能力，同时通过精确匹配算法确保评估结果的科学性与可重复性。

解决学术问题

该数据集有效解决了安全扫描工具评估领域长期存在的基准测试缺失问题。传统评估方法如OWASP Benchmark采用合成测试用例，导致扫描工具可能通过针对性优化获得虚高分数而无法反映真实检测能力。RealVuln通过构建包含真实漏洞模式的代码库，并引入误报陷阱机制，为学术界提供了衡量扫描工具泛化性能的可靠标准。其机器可读的基准真值标注体系与自动化评分引擎，显著提升了安全工具评估研究的可重复性与可比性。

衍生相关工作

基于该数据集的评估框架，衍生出多个重要的研究方向。在工具性能分析方面，研究者通过对比传统SAST工具与AI原生扫描器在不同代码创作模式下的检测差异，揭示了工具性能与代码生成方式的相关性。在基准测试方法论层面，该数据集推动了多维度评估体系的发展，包括按CWE家族分类的细粒度性能分析、按漏洞严重程度分层的召回率评估等。其开源可扩展的设计理念，也促进了安全社区在JavaScript、Go等多语言基准测试建设方面的协作创新。