Web3 Vulnerability Database

一个经过策划和机器验证的Web3漏洞类别数据库，以及用于从公开安全发现中构建它的工具集。A curated and machine-validated database of Web3 vulnerability categories, along with the toolset for constructing it from public security disclosures.

原始信息汇总

Web3 漏洞数据库（Web3 Vulnerability Database）

本项目是一个经过机器验证的、精选的 Web3 漏洞类别数据库，专门面向安全研究人员和自动化审计工作流设计。它不是简单地复制原始漏洞报告，而是将多条安全发现作为证据，归纳提炼为通用的漏洞类别记录。

核心内容

数据库包含以下主要组成部分：

• Markdown 漏洞类别记录：带有经过验证的 YAML frontmatter 元数据
• 初始覆盖范围：涵盖清算（liquidation）、预言机（oracle）、会计（accounting）、借贷（lending）、治理（governance）、升级（upgrades）、外部回调（external callbacks）和跨链消息（cross-chain messaging）等漏洞类别
• 受控注册表：包括类别（category）和协议能力（protocol-capability）两类受控词汇表
• 数据摄入管线：基于 Bun/TypeScript 构建，支持从固定的 AuditVault 快照和 Solodit API 获取数据
• 确定性处理：提供确定性分类和重复候选报告功能
• 消费目录与摘要：包含顶层消费目录、逐记录和聚合的确定性摘要
• 查询与 API：提供可复用的加载器、适用性评估器、精确快照 API、确定性内存 SQLite 查询 API 以及 vulndb 命令行接口

需要说明的是，原始 API 响应和规范化处理记录不纳入 Git 版本管理，提交的内容仅包含原始安全指导文本和公开来源引用。

环境要求

• 运行时：需要 Bun，版本由 .bun-version 文件指定
• API 密钥：默认的 AuditVault 路径无需密钥；仅当使用 Solodit 查询包时才需要设置 SOLODIT_API_KEY
• 安装：执行 bun install --frozen-lockfile 安装依赖
• 检查命令：提供 bun run check、bun test、bun run schema:check 等一组完整的仓库检查命令

数据摄入

数据库支持两种数据源：

1. 默认路径（AuditVault）：使用 perpetuals-auditvault 查询包，从 AuditVault 的精确 Git 提交中选取衍生品（perpetuals）相关证据，无需 API 密钥。流程为 db probe → db fetch → db build --run <run-id>。
2. Solodit API 路径：显式使用 perpetuals 查询包，需要设置 SOLODIT_API_KEY 环境变量。

两个数据包均覆盖保证金（margin）、清算（liquidation）、定价（pricing）、资金费率（funding）、自动减仓（auto-deleveraging）、保险（insurance）、签名订单（signed orders）、结算（settlement）、恢复（recovery）和代币集成（token integration）等主题。

查询方式

提供 db search、db show、db select 和 db taxonomy 等命令，支持使用类型化分类选择器或受控简写别名进行查询。例如：

bash bun run db search --category derivatives.liquidation --capability trading.perpetuals bun run db show derivatives.liquidation-no-progress --format

机器可读输出包含目录聚合和选定记录摘要；Markdown 输出会验证并保留记录原始字节。

类别编写规范

类别记录存放在 classes/ 目录下，frontmatter 包含身份信息、适用性、路由和来源元数据，详细安全知识则在 Markdown 正文中阐述。项目提供 docs/authoring.md 作为记录契约的规范文档。

消费者 API

提供 TypeScript 导入接口：

ts import { evaluateApplicability, loadDatabase, selectApplicableClasses, snapshotSelectedClasses, } from "@aviggiano/web3-vulnerability-database";

重要设计原则：未知能力的证据绝不意味着“经证实的缺席”。消费者应默认同时包含 applicable 和 uncertain 的记录，仅排除有证据支持为 inapplicable 的记录。

不可变检出版本对外暴露 database.yml、capabilities.yml、catalog.json、manifest.json 以及 classes/ 下的精确 Markdown 字节。

数据政策与许可

• API 凭据仅从 SOLODIT_API_KEY 读取，且仅在 Solodit 的 probe 和 fetch 命令中使用
• .work/ 目录存放原始源数据、Git 对象、API 响应和规范化数据，必须保持不被跟踪
• 测试夹具为合成数据
• 类别正文为基于公开引用的原创摘要
• 重新分发原始源数据需另行进行许可审查

仓库编写的代码、模式、文档和类别文本采用 MIT 许可证；链接的源材料遵循其各自条款。

搜集汇总

数据集介绍

构建方式

Web3漏洞数据库旨在系统性地整合与组织去中心化金融生态中的安全缺陷类别，其构建过程遵循严格的数据溯源与验证原则。该数据库通过自动化的摄取与规范化管道，从公开的安全发现中提炼证据，涵盖清算、预言机、会计、借贷、治理、升级、外部回调及跨链消息等关键领域。原始证据均被锚定至特定版本的AuditVault快照或经由Solodit API获取，并利用Bun/TypeScript技术栈实现确定性的分类与去重候选报告。所有记录均以Markdown格式呈现，并带有经过验证的YAML前置元数据，确保每一条漏洞类别的归纳均源于多重证据支持，而非简单拷贝，从而保证了数据的权威性与可追溯性。

使用方法

使用者可通过多种途径高效利用该数据库。对于自动化消费场景，项目暴露了基于TypeScript的API，支持加载完整数据库、评估漏洞类别对特定协议的适用性、选择相关类别并生成快照，且明确建议在不确定时保留适用与存疑记录，仅排除有明确证据表明不相关的项。对于交互式查询，内置的命令行界面支持通过分类选择器或简写别名进行搜索，并可输出Markdown或机器可读的摘要格式。此外，数据库提供了严谨的完整性校验流程，包括模式检查、数据库验证、固定快照审计等命令，确保使用者获取的数据始终处于一致且可验证的状态。最终，不可变的发布物（如database.yml与catalog.json）为规划者提供了索引化的全景视图，便于将功能定义、适用性与公共源绑定。

背景与挑战

背景概述

Web3 Vulnerability Database诞生于区块链安全研究需求日益增长的背景下，由独立研究者aviggiano创建，旨在系统化整理和验证Web3领域的安全漏洞类别。该数据库以公开安全发现为证据，通过机器验证的流程构建，覆盖清算、预言机、会计、借贷、治理、升级、外部回调和跨链消息等关键领域。其核心研究问题在于如何从分散的安全报告中提炼出标准化、可复用的漏洞类别，以支持安全研究和自动化审计工作流。该数据库采用Bun/TypeScript管道进行数据摄入与规范化，提供确定性分类、重复候选报告以及可复用的查询API和命令行工具，显著提升了漏洞知识的结构化程度和可用性，对Web3安全社区具有重要参考价值。

当前挑战

该数据库面临的挑战主要体现在两个层面。在领域问题层面，Web3安全领域本身复杂多变，漏洞类型繁多且相互关联，如何准确界定和分类漏洞类别，避免类别交叉和遗漏，是一个持续挑战；同时，智能合约和跨链协议不断演化，新型漏洞层出不穷，要求数据库具备高扩展性和及时更新能力。在构建过程中，挑战尤为突出：从多个异构来源（如AuditVault和Solodit）获取证据时，需处理数据格式差异、API速率限制和断点续传问题；确保源发现证据的准确性与可追溯性，避免直接复制原始内容，而需提炼原创的安全指南；维护受控的分类法和协议能力注册表，并在类别记录中保持证据与推断的清晰界限，确保确定性分类和重复候选报告的可靠性。此外，数据策略要求严格管理API密钥和敏感工作区，不将原始响应提交至Git，这也增加了数据治理的复杂度。

常用场景

经典使用场景

Web3 Vulnerability Database 作为一套经机器验证的漏洞类目知识库，其核心应用场景聚焦于安全研究与自动化审计流水线。研究者可借助其类型化分类体系和确定性查询接口（如`search`、`show`、`select`），对清算、预言机、借贷、治理、升级、外部回调及跨链消息等关键领域进行系统化漏洞模式检索。该库通过受控类别与协议能力注册表，支持将具体安全事件映射至通用漏洞类，为安全团队提供可复用的漏洞知识基座，从而提升审计工作的效率与准确性。

解决学术问题

该数据集解决了Web3安全领域中漏洞描述碎片化、分类体系不统一以及知识难以迁移的学术难题。通过构建确定性分类框架和标准化记录结构，它实现了跨来源安全发现的有效归并，消除了原始报告中冗余与噪声。研究者得以依据统一schema进行漏洞模式比较与分析，促进了实证研究中的可复现性。其MIT许可与公开引用机制，为构建大规模漏洞基准测试集、训练安全检测模型以及设计智能审计工具提供了坚实数据基础，推动了该领域理论向工程实践的系统性转化。

实际应用

在现实世界中，该数据库直接服务于去中心化金融协议的审计流程与安全监控。安全团队可将其集成至自动化审计工具链，作为漏洞模式匹配的离线知识库，快速识别智能合约中的潜在风险点。其确定性快照API和内存SQLite查询接口，支持在持续集成环境中进行实时合规检查。同时，该数据库为内部安全培训、威胁建模及应急响应提供标准化案例素材，有助于机构构建组织级安全知识管理平台，显著提升对新型攻击手段的感知与防御能力。

数据集最近研究

最新研究方向

Web3安全领域正经历从零散漏洞披露向系统性、机器可验证的漏洞知识库构建的范式转变。该数据库以策展方式整合公开安全发现，通过标准化分类与协议能力注册表，为自动化审计工作流提供结构化支撑，其涵盖清算、预言机、会计、借贷、治理、升级、外部回调及跨链消息等前沿攻击面。结合智能合约安全事件频发的热点，此研究推动漏洞分类学、确定性去重与可复现查询机制的发展，强化了安全工具间的互操作性，并为监管与审计标准的确立奠定数据基础。