[
][docs]
[
][tests]
[
][codecov]
[
][pypi]
__ __ High Octane Triage Analysis __
|| _||______ __ __________ _____ ||
|| \||___ \__| ____/ ______/___ / ____\ ||
==||=====|| | __/ |/ \ /==| / __ \ __\===]|
'======|| | \ | | \_ _| \ ___/| | ||
||____ /__|___|__/ / | \____]| | ||
=========''====\/=========/ /==|__|=====|__|======'
\ /
\/
Binary Refinery™ 是一系列 Python 脚本的集合，用于实现二进制数据的转换，例如压缩和加密。
我们通常将其简称为 refinery，这也是对应软件包的名称。
这些脚本被设计为仅从 stdin 读取输入并将输出写入 stdout。
其核心理念是每个脚本都应是一个单元，即只完成 一项 工作，
而各个单元可以通过命令行上的管道操作符 | 组合成 管道，以执行更复杂的任务。
该项目的主要关注点是恶意软件分类分析，
并尝试在命令行上实现类似 CyberChef 的功能。
创建一个 Python 虚拟环境。你需要 Python 3.11 或更高版本。像这样安装 refinery：
python -m pip install -U pip
python -m pip install -U binary-refinery[extended]
使用 -h 运行单元以了解其工作原理，通过 [docs][] 进行 grep 搜索，或使用 binref 命令来查找它们。
如果你想观看实际演示，请观看[最近的视频][VOD3]。
但同时也请阅读本 readme 的其余部分。
没有固定的发布计划，但发布非常频繁，建议定期更新。 错误修复不会在 GIT 之外记录，但所有其他更改（即新功能）都记录在变更日志中。 在 [Mastodon][] 上关注我，以获取有关特别重要版本的更新。
使用 -h 或 --help 开关执行单元时显示的帮助文本是其主要文档。
[自动生成的文档][docs]在顶层包含了每个单元该输出的汇编，
但也包含了该工具包三个基本概念的规范：
[分帧][frame]、[multibin 参数][argformats]和[元变量][meta]。
每个单元的描述和帮助文本的全文搜索也可在命令行上通过提供的 binref 命令获得。鉴于参考文档可能有些枯燥，
我们正在努力制作一系列教程；我非常推荐你去看看。
除此之外，我还在下面收集了额外的资源（包括一些第三方制作的资源）。
[!NOTE]
Refinery 仍处于 alpha 阶段，接口有时会发生变化， 即单元和参数可能会被移除或重命名。 因此，旧视频和博客文章中的特定命令行可能不再有效。
2021/08] [OALabs][OA] 非常友好地让我[在专题视频中演示该工具包][VOD1]。
在视频中，我基本上按照
第一个教程的内容进行操作。2021/11] [Johannes Bader][JB] 写了一篇关于使用 binary refinery 分析恶意垃圾邮件的精彩[博客文章][BLOG]。2024/03] [Malware Analysis For Hedgehogs][MH] 制作了[一个关于使用 refinery 解包 XWorm 样本的视频][VOD2]。2024/11] [the CyberYeti][CY] 邀请我[在直播中展示 refinery][VOD3]。2025/06] 我再次[与][CY] [the CyberYeti][CY] [一起直播][VOD4]，这次的内容更加原始。
你在这里看到的所有 bug 都已修复。😉展示内容再次包括下面示例部分中的样本以及教程。
Binary Refinery 版权 (c) 2019 Jesko Hüttenhain，根据 [3-Clause BSD License][license] 发布。 此仓库还包含完整许可证文本的副本。 如果你想做本许可证未涵盖的事情，请随时联系作者。
Refinery 需要至少 Python 3.11。 建议将其安装到自己的[虚拟环境][venv]中： 该软件包可能会引入大量依赖项， 将其安装到全局 Python 中容易产生版本冲突。 此外，由于该工具包引入了大量新命令， 这些命令在某些系统上很可能会发生冲突， 将它们保存在单独的虚拟环境中是防止这种情况的一种方法。
如果你希望所有 refinery 命令始终在 shell 中可用（即无需切换到自定义虚拟环境），
你也可以选择为安装指定一个 前缀，
该前缀将被添加到所安装的每个命令 shim 的前面。
例如，如果你选择 r. 作为前缀，那么 [emit][] 单元将被安装为命令 r.emit。
额外的好处是，你可以输入 r. 并连按两次 Tab 来获取所有可用 refinery 命令的列表。
但请注意，文档中不假定任何前缀，并且 refinery 的开发目标是在大多数系统上_不_发生冲突。
作者不使用前缀，并提供此选项作为安全措施。
安装和更新 refinery 最直接的方法是通过 pip。 首先确保你运行的是最新版本：
python -m pip install -U pip
然后直接安装 refinery 包：
pip install -U binary-refinery
如果你想为所有单元选择前缀，可以通过环境变量 REFINERY_PREFIX 指定。
例如，以下命令将在 Linux 上将 refinery 安装到当前 Python 环境中，前缀为 r.：
REFINERY_PREFIX=r. pip install -U binary-refinery
在 Windows 上，你需要运行以下命令：
set REFINERY_PREFIX=r.
pip install -U binary-refinery
指定特殊前缀 ! 将导致完全不创建 shell 命令，
并且 binary refinery 将仅作为库安装。
如果你想安装当前的 refinery HEAD，可以重复上述所有步骤，指定此仓库而不是 pip 包。
例如，以下命令将安装最新的 refinery 提交：
pip install -U git+git://github.com/binref/refinery.git
最后，如果你使用的是 [REMnux][remnux-main]，你可以使用他们的 [refinery docker 容器][remnux]。
如果你想教你本地的恶意软件分析 [claude][] 使用 binary refinery，请查看 [Binary Refinery Skill][agent]。
以下是当前对各种 shell 环境支持情况的总结：
| Shell | 平台 | 状态 | 备注 |
|---|---|---|---|
| Bash | Posix | 🔵 良好 | 作者偶尔使用。 |
| CMD | Windows | 🔵 良好 | 作者广泛使用。 |
| PowerShell | Windows | 🟡 合理 | [只要 PowerShell 版本至少为 7.4，它就能正常工作。][psh1] |
| Zsh | Posix | 🟠 小问题 | 经过[讨论][zsh1]后，有一个[修复][zsh2]。 |
| Fish | Posix | 🟠 小问题 | 参见 issue [#55][fsh1] 和讨论 [#22][fsh2]。 |
如果你使用的是其他 shell 并有反馈要分享，请告诉我！
有一些非常情境化的单元带有（有时很大的）外部依赖。
例如，[stego][] 是一个需要图像解析库 Pillow 的单元。
为了将 refinery 的安装时间保持在首次用户的合理水平，某些库默认不安装。
当缺少依赖时，相应的单元会告诉你该怎么做：
$ emit config.png | stego RG
(13:37:00) failure in stego: dependency Pillow is missing; run pip install Pillow
然后你可以手动安装这些缺失的依赖。 如果你不想被缺失的依赖困扰，并且不介意较长的 refinery 安装时间，可以按如下方式安装软件包：
pip install -U binary-refinery[all]
这将在必需依赖的基础上安装_所有_依赖。 更准确地说，有以下额外的类别可用：
| 名称 | 包含的依赖 |
|---|---|
default | 合理依赖的推荐选择，作者的选择 |
extended | 扩展选择，仅排除最冷门的依赖 |
all | 所有 refinery 单元的所有依赖 |
这些按升序列出，即 extended 将安装 default 会安装的所有内容。
或者，你可以克隆此仓库并使用脚本 update.sh（在 Linux 上）或 update.ps1（在 Windows 上）将 refinery 包安装到本地虚拟环境中。 此方法的安装和更新过程就是简单地运行脚本：
binary-refinery，binary-refinery[all]。你也可以在本地生成所有文档。
为此，请执行 run-pdoc3.py 脚本。
除非你在已将 binary refinery 作为 Python 包安装的环境中运行它，否则这将失败。
要运行它，你必须将虚拟环境的路径指定为 run-pdoc3.py 的第一个命令行参数，
这将导致脚本使用该环境的解释器再次运行自身。
如果你确定要运行 run-pdoc3.py，
有一个命令行开关可以强制脚本使用当前默认的 Python 解释器运行。
该脚本安装 [pdoc3 包][pdoc3] 并使用它为 refinery 包生成 HTML 文档。
然后可以在本 readme 文件旁边的 html 子目录中找到文档。
教程是 Jupyter notebook，如果你的虚拟环境[安装了 Jupyter][jupyter]，你可以直接运行和执行它们。 值得指出的是，[Visual Studio Code 对 Jupyter 有非常舒适的支持][jupyter-vscode]。
单元 [emit][] 和 [dump][] 扮演特殊角色： 前者用于输出数据，后者用于将数据转储到剪贴板或磁盘。 例如，考虑以下管道：
emit M7EwMzVzBkI3IwNTczM3cyMg2wQA | b64 | zl | hex
这里，我们输出字符串 M7EwMzVzBkI3IwNTczM3cyMg2wQA，
使用 [b64][] 对其进行 base64 解码，
使用 [zl][] 对结果进行 zlib 解压缩，
最后对解压缩后的数据进行 [hex][] 解码。
默认情况下，每个单元执行某种转换的_“解码”_操作，但其中一些也实现了反向操作。
如果实现了，总是通过提供命令行开关 -R 或 --reverse 来完成。
你可以使用以下命令生成上述 base64 字符串，因为 [hex][]、[zl][] 和 [b64][] 都提供反向操作：
emit "Hello World" | hex -R | zl -R | b64 -R
给定一个包含 base64 编码有效载荷缓冲区的文件 packed.bin，以下管道将所述有效载荷提取到 payload.bin：
emit packed.bin | carve -l -t1 b64 | b64 | dump payload.bin
[carve][] 单元可用于从输入缓冲区中雕刻出数据块，
在这种情况下，它查找 base64 编码的数据，按长度排序（-l）并返回其中的第一个（-t1），
即从 packed.bin 中雕刻出最大的看起来像 base64 的数据块。
然后对数据进行 base64 解码并转储到文件 payload.bin。
单元 [pack][] 将从文本缓冲区中选取所有数字表达式并将其转换为二进制表示。 一个简单的例子是管道
emit "0xBA 0xAD 0xC0 0xFF 0xEE" | pack | hex -R
它将输出字符串 BAADC0FFEE。