[
][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 --no-cache-dir binary-refinery[extended]
使用 -h 运行单元以了解其工作方式，在 [docs][] 中搜索，或使用 binref 命令查找它们。
如果你想看实际演示，请观看[最近的视频][VOD3]。
但也请阅读本 readme 的其余部分。
没有固定的发布计划，但发布非常频繁，建议定期更新。 Bug 修复不会在 GIT 之外记录，但所有其他更改（即新功能）都记录在变更日志中。 在 [Mastodon][] 上关注我，获取关于特别重要版本的更新。
使用 -h 或 --help 开关执行单元时显示的帮助文本是其主要文档。
[自动生成的文档][docs]在顶层包含每个单元该输出的汇编，
但也包含该工具包三个基本概念的规范：
[分帧][frame]、[多二进制参数][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] 我再次[与][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 --no-cache-dir binary-refinery
如果你想为所有单元选择一个前缀，可以通过环境变量 REFINERY_PREFIX 来指定。
例如，以下命令将在 Linux 上以 r. 为前缀将 refinery 安装到当前的 Python 环境中：
REFINERY_PREFIX=r. pip install -U --no-cache-dir binary-refinery
在 Windows 上，你需要运行以下命令：
set REFINERY_PREFIX=r.
pip install -U --no-cache-dir binary-refinery
指定特殊前缀 ! 将导致完全不创建任何 shell 命令，
并且 binary refinery 将仅作为库安装。
设置 REFINERY_NO_EXTENSIONS=1 可在不安装 Cython 扩展的情况下进行安装；
此时 refinery 将使用（慢得多的）纯 Python 实现来运行若干算法。
如果你想安装当前的 refinery HEAD，可以重复上述所有步骤，但改为指定此仓库而非 pip 包。
例如，以下命令将安装最新的 refinery 提交：
pip install -U --no-cache-dir 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]。
以下是 binary refinery 使用的一些环境变量：
| 名称 | 类型 | 作用 |
|---|---|---|
REFINERY_TERM_SIZE | Int | 所有终端输出的最大宽度。 |
REFINERY_COLORLESS | Bool | 从不在终端上显示颜色。 |
REFINERY_DISABLE_SIZE_FORMAT | Bool | 不在元变量中美化打印大小。 |
REFINERY_DISABLE_PS1_BANDAID | Bool | 禁用 PS1 [临时修补][psh1]。 |
REFINERY_SILENCE_PS1_WARNING | Bool | 静默 PS1 [临时修补][psh1] 警告。 |
REFINERY_NO_EXTENSIONS | Bool | 不编译 Cython 扩展。 |
REFINERY_PREFIX | Str | 单元 shell 命令前缀（在安装期间使用） |