OWASP DecodeBox

编码。解码。识别。 面向任意数据的智能解码。

---

项目状态

预发布阶段，且已可使用。 工作台可运行，检测引擎可逐层拆解分层载荷，分析报告已完整。

• 引擎： 涵盖数据格式、密码、公钥密码学、哈希、压缩、网络、取证、多媒体和提取器的 504 项操作。每一项都有往返测试或已发布的已知答案测试覆盖——共计 1,109 项测试。
• 界面： 三种模式——用于转换的工作区、用于理解的报告，以及用于推断下一步尝试什么的 CTF 模式，部署于 owasp.github.io/DecodeBox。

仍待完成：无障碍审计和国际化处理。反汇编器和 OCR 引擎被有意排除在范围之外——它们是独立项目，而非操作。

关于项目

此类工具的常见模型假定你已经知道自己的数据是什么：你挑选操作、串联操作、反复迭代。当你一眼就能认出格式时这没问题，但当你认不出时就毫无用处——而分析师面对新事物时，大多数情况正是如此。

DecodeBox 从另一端出发。你粘贴数据，它推断出自己手中拿的是什么：每一层都被拆解，每一个指标都被提取，每一项安全发现都被解释，且每项结论的证据都可见，而非仅凭断言。

一切都在你的浏览器中运行。任何输入、配方和文件都不会离开你的机器——根本没有可发送到的服务器。

核心目标

• 识别： 为未知数据命名，而非要求用户先为其命名。
• 解释： 展示每项结论背后的测量结果，使置信度分数可被核查。
• 分析： 报告载荷意味着什么——每一深度上的指标和安全发现——而不仅是其字节说了什么。
• 保证： 将处理完全保持在客户端，并在构建中强制执行，而非仅在文档中承诺。

实际效果

来自测试套件的一个真实载荷：Base64 套 Base64 套 gzip 套 JSON，其中一个字段内含 PowerShell 加载器。

Findings   4        Indicators 7        Layers 8        257 ms

CRITICAL  Cloud or service credential            CWE-798
          Input → Base64 → Base64 → gzip
          AKIAIOSFODNN7EXAMPLE

CRITICAL  PowerShell download-and-execute        CWE-94
          Input → Base64 → Base64 → gzip → JSON → Base64 → UTF-16LE
          IEX (New-Object Net.WebClient).DownloadString

第二个发现位于向下六层，而最后一跳来自某个 JSON 字段内的一个 Base64 数据块。任何对原始数据块进行 grep 的方法都看不到它，任何只解开单一线性链条的方法也无法到达它。

工作原理

1. 检测。 候选解释由多个独立信号评分——香农熵、字符集、长度规则、魔数字节，以及解码结果本身是否格式良好。每个信号都带有可读的理由说明，而最后一个信号权重最高：任何长十六进制字符串在形态上都像 Base64，但只有一种解读能解码出连贯的内容。
2. 解包。 最佳候选被解码，然后对结果再次运行检测，从而构建一棵树而非一条链——包括埋藏在结构内部的编码区域。递归在深度、节点数量与实际耗时上都有上限。
3. 终止，并说明原因。 一条链会因以下原因结束：遇到内容、遇到具名的单向值（Base64 → Base64 → MD5）、遇到无法解码的剩余部分（如 JWT 签名），或诚实承认已触及限制且下面可能还有更多内容。
4. 扫描。 从树的每个节点收集指标和安全发现，每项都附带 CWE 引用、证据以及揭示它的确切解码路径。

当没有任何已声明的解释能说明输入时，DecodeBox 会尝试每一个单字节 XOR 密钥和每一种旋转，并对每个结果的可读性评分——其置信度会明确表明这是一次搜索而非一次匹配。

安全与隐私

DecodeBox 按设计处理不可信的、故意畸形的输入。

• 无后端。 没有可被攻破的东西，没有可记录日志的东西，也没有可被传票调取的东西。
• 强制无网络。 构建产物附带内容安全策略，包含 connect-src 'none' 和 script-src 'self'，外加针对唯一内联脚本的哈希。字体是打包的而非远程获取的，如果输出中一旦出现 CDN 引用，构建就会失败。
• 无动态求值。 eval、new Function 以及任何将输入渲染为 HTML 的路径都被 lint 规则禁止，而非靠约定。

style-src 确实允许 'unsafe-inline'，因为 React 会写入内联 style 属性；而真正风险所在的 script-src 则保持严格。要报告漏洞，请参阅 SECURITY.md——请不要为安全报告开启公开 issue。

仓库结构

DecodeBox/
├── .github/workflows/   # CI, CodeQL, SBOM, markdown quality, Pages deployment
├── public/              # Bundled fonts, favicon, CNAME
├── src/
│   ├── engine/          # The analysis engine — the only half that knows about data
│   │   ├── index.ts     # THE SEAM — the only module the interface imports from
│   │   ├── operations/  # One self-contained module per transformation
│   │   ├── detection/   # Entropy, charset, magic bytes, structural validity
│   │   ├── analysis/    # Recursive exploration, indicators, security findings
│   │   ├── ctf/         # Flag search, cipher key recovery, ranked hints
│   │   ├── core/        # Recipe executor, byte handling, ciphers, codecs
│   │   └── worker/      # The engine off the main thread, past a size threshold
│   ├── components/      # The interface: workspace, report, CTF mode
│   ├── store/           # One zustand store
│   ├── hooks/           # Interaction logic shared across components
│   ├── lib/             # Share links, saved recipes, recipe text format
│   ├── i18n/            # Every user-facing string
│   └── styles/          # Design tokens and themes
├── SECURITY.md
└── LICENSE

界面通过一个窄门面访问引擎，该门面暴露七个函数—— listOperations、bake、detect、autoDecode、identify、analyse 和 hints。两半 可以独立开发、测试和替换；工作区曾从零重建 而引擎一行未改。添加一个操作绝不应需要改动 UI。

快速开始

需要 Node.js 22.12 或更高版本。CI 在 22 和 24 上构建；.nvmrc 将开发环境固定为 22。

npm install
npm run dev     # development server
npm run test    # 1,109 tests
npm run build   # static site in dist/

构建输出完全静态——没有运行时、没有服务器、没有环境变量。任何静态托管服务都能提供它。

单文件，无需安装

运行中的应用程序头部有一个 Download DecodeBox 按钮。它会给你 decodebox.html：整个东西都在一个 1.2 MB 的文件里——界面、全部 504 个操作、字体、样式。双击它就能运行。没有服务器、没有 npm、没有网络、无需安装任何东西，这正是气隙机器上的关键所在——在那样的机器上，引入一套构建工具链比引入一个文件要难得多。

npm run build 会将它连同站点一起生成，因此任何部署都会提供它：

dist/index.html       the site
dist/decodebox.html   the same build, in one file

它必须是一个文件而不是一个文件夹。浏览器拒绝从 file:// URL 加载 ES 模块——该来源是不透明的，因此请求无法通过其 CORS 检查——这意味着从磁盘打开的普通 dist/ 文件夹会显示为空白。将所有内容内联后就不会有请求失败。唯一放弃的是 Web Worker，它按定义需要第二个文件，因此独立构建在处理超大输入时仍运行在主线程上，除此之外完全相同。

如何贡献

该网站已上线，因此你现在能做的最有价值的事情就是使用它并尝试破坏它。欢迎贡献，尤其是在以下方面：

• 测试： 在 owasp.github.io/DecodeBox 粘贴真实载荷，并报告它出错的任何地方——尤其是它自信地出错的地方。
• 运维： 新的转换。一个自包含模块，一个测试文件，无需更改 UI。
• 检测： 能解释其证据的更好的启发式方法。一个自信的错误答案比没有答案更糟。
• 无障碍： WCAG 2.1 AA 审计尚未完成。

请从 OWASP 贡献指南 开始。所有参与者都应遵守 OWASP 行为准则。

项目负责人

• Mohammad Hossein Sadeghian

许可证

根据 Apache License 2.0 授权。这是一个 OWASP Foundation 孵化器项目，归类为工具。

---