unbox-anything

unbox-anything

适用于“盒状”文件的通用解包工具——这类文件看起来像单个文件，实际上却是由多个文件组成的容器（例如 .exe 安装程序、.docx 文档、.apk 应用、.asar Electron 包）。将任何此类文件交给它，它都会打开容器并将内容解包到一个整洁的目录中，然后生成一份清单，描述找到的内容。

专为 Agent 驱动的分析（崩溃调查、逆向工程、内容提取、构建检查）而设计，而非面向用户的 GUI 工作流。输出确定且结构化，便于后续步骤读取。

铁律（每次都要先读）

这些规则旨在防范解包未知文件带来的危险。今天解包的 .exe 可能是恶意软件；自动挂载到 Finder 的 .dmg 可能会触发预览处理程序。以下规则可以保护 Agent 和用户的设备安全。

1. 只提取，绝不执行。 绝不要运行、source、open 或双击提取目录中的任何内容。二进制文件（.exe、.dll、.so、.dylib、.app、脚本）仅作为字节数据供检查而提取，绝不启动。如果后续任务需要运行这些文件，那是需要人工批准的独立步骤。
2. 以只读且静默的方式挂载磁盘映像。 在 macOS 上处理 .dmg/.iso 时，始终为 hdiutil 传入 -nobrowse -readonly，以免 Finder 自动打开并触发预览处理程序。复制出文件后立即卸载。
3. 提取前检测加密情况。 先运行 7z l -slt <file>；如果输出显示 Encrypted = +，请停止并报告，不要让 7z 挂起等待密码提示。明确向用户索要密码，或跳过。
4. 始终提取到全新的目录。 输出到 <outname>-unboxed/（使用后缀，绝不覆盖）。绝不要提取到 . 或已有内容的目录中——7z/unar 可能会悄无声息地覆盖文件。
5. 每次运行只使用一个真实数据源。 不要同时使用两种不同工具处理同一来源；完成一次提取并验证后，再递归处理。

前置条件

主要工具：7z，支持约 80% 的格式（zip、7z、tar、gz、bz2、xz、zst、cab、iso、rpm、deb、nsis、msi、ar、cpio、chm 等）。安装一次，大多数格式即可正常处理。

平台	安装命令
macOS	brew install p7zip
Linux (Debian/Ubuntu)	sudo apt install p7zip-full
Linux (Fedora/RHEL)	sudo dnf install p7zip p7zip-plugins
Windows	winget install 7zip.7zip (或 choco install 7zip)

辅助工具（仅在格式需要时使用——按需安装）：

• unar — 用于 .rar（完整读取支持，包括 RAR5）。
• innoextract — 用于 Inno Setup .exe 安装程序（处理此格式时比 7z 更整洁）。
• hdiutil — macOS 预装，用于 .dmg。
• xar + cpio — 用于 macOS .pkg（链式步骤）。
• npx @electron/asar — 用于 .asar Electron 包（链式步骤；需要 Node.js）。

各平台的完整安装命令和版本说明见 reference.md。

工作流（所有文件都使用同一条处理流水线）

按顺序运行以下六个步骤。步骤 1–4 是常规流程；步骤 5 是递归处理环节，可在无需特殊处理的情况下支持链式格式（exe→asar、pkg→xar→cpio）；步骤 6 会生成清单，使输出可供后续分析审计。

步骤 1 — 检测实际类型

文件扩展名可能不可靠。.exe 可能是 NSIS、Inno Setup、MSI 封装，或自解压 zip。选择工具前，务必通过文件的魔数确认其实际类型。

file "<input>"
# Also useful when `file` is unsure:
7z l "<input>"        # lists contents if 7z recognizes the format

如果 file 和 7z 的判断不一致，请相信 7z l（它能识别更多容器格式）。如果两者都无法确定，请查看 reference.md 中的魔数表，并手动匹配起始字节。

步骤 2 — 按类别归类

在下方的分类表中查找检测到的格式。每种格式都恰好归入五个类别 A–E 之一。类别会告诉你要运行哪种工作流——直到步骤 5 前，无需再考虑具体格式。

步骤 3 — 确保所需工具可用（并检查是否加密）

使用 command -v 检查类别所需的工具。如果缺少该工具，请打印先决条件表中的安装命令，然后停止——除非该类别的工作流明确列出了备用工具链，否则不要悄悄改用其他工具（改用其他工具可能会产生不一致的输出，进而破坏下游分析）。

在此期间，运行加密预检查（铁律 3），以确保 7z x 不会卡在密码提示处：

7z l -slt "<input>" | grep -i "^Encrypted"
# "Encrypted = -"  → safe, proceed to Step 4
# "Encrypted = +"  → STOP. Report to the user; do not run `7z x`.

这项检查应放在步骤 3，而不应只写在铁律中，因为按顺序执行工作流的 Agent 必须在提取前完成此检查——否则，受密码保护的归档文件会导致流程永久阻塞。

仅适用于类别 A/B 的备用工具链（标准归档文件和 zip 容器）：如果缺少 7z，则尝试 bsdtar（macOS 上预装为 tar）→ unzip → 停止并询问。对于其他所有类别，必须使用列出的工具。

步骤 4 — 提取

提取到一个全新的 <outname>-unboxed/ 目录中。<outname> 是输入文件的完整名称，包含扩展名，并将其中的每个 . 替换为 -（连字符）。保留扩展名（如 -docx、-exe）可记录解包容器的类型；将点替换为连字符，则可避免目录名称中出现容易造成歧义的扩展名分隔符。

输入文件	<outname>	输出目录
report.docx	report-docx	report-docx-unboxed/
App-1.2.3-x64.exe	App-1-2-3-x64-exe	App-1-2-3-x64-exe-unboxed/

绝不要提取到 . 或已有内容的目录中。具体命令见下文各类别的工作流。始终传入 -y（默认回答是），避免 Agent 卡在提示处；路径可能包含空格或中日韩字符时，请使用引号括起来。

步骤 5 — 扫描嵌套容器并递归处理

这一步让 unbox-anything 能够处理“盒中盒”。每次提取后（类别 A–D），都要扫描输出目录，查找文件名或 magic bytes 与已知嵌套容器（.asar、.zip、.7z、.tar、.jar、.apk、.ipa、.whl、.egg、.deb、.rpm、.cab、.msi、.pkg、.dmg、.iso、NSIS/Inno .exe）匹配的文件。

找到后，递归处理：对该内部文件重新运行工作流，并在其旁边提取到 <innername>-unboxed/。停止条件（必须全部遵守）：

• 深度限制：3。 不要递归超过 3 层——深度嵌套的压缩包几乎总是恶意文件或打包错误，应由人工检查。
• 循环保护。 记录已提取文件的绝对路径集合；绝不要重复提取同一文件（防止压缩包中的符号链接指回自身）。
• 仅处理已知格式。 只对上述经 magic number 确认的格式递归处理。不要“以防万一”地递归处理任意二进制文件。

递归是将 Electron 安装程序变为源代码的关键：setup.exe（类别 D，NSIS）→ $\PLUGINSDIR/app-64.7z（类别 A）→ app/resources/app.asar（在步骤 5 中检测到）→ app-src/（asar 提取）。一条流水线，无需特殊处理。

步骤 6 — 编写清单

顶层提取及所有递归处理完成后，编写 <outname>-unboxed/README.md，记录：

• 源文件：名称、大小、检测到的类型（file 输出）、SHA-256。
• 提取链：列出所有调用的工具及其生成的目录，形成一棵树，方便读者手动重现整个过程。
• 工具版本：实际使用的 7z / unar / npx @electron/asar 版本。
• 文件树：以 tree 风格列出最终输出（深度限制为 3 层，避免日志过长）。
• 异常情况：跳过的加密条目、权限错误、截断文件及任何可疑内容。

清单能让下游 Agent 分析时信任这些输出——没有清单，提取结果就只是“相信我，这些文件都在这里”。

分类表

精简路由器。找到你的格式，运行对应类别的工作流。每种格式的完整详细信息（确切命令、魔数、边缘情况）请参阅 reference.md。

格式	类别	主要工具
.zip .7z .tar .tar.gz/.tgz .tar.bz2 .tar.xz .gz .bz2 .xz .zst .lz4	A. 标准归档	7z（rar→unar）
.rar	A	unar（7z 对 RAR5 仅支持读取）
.docx .xlsx .pptx .jar .war .ear .apk .aab .ipa .whl .egg	B. ZIP 容器	7z（底层都是 ZIP）
.deb .rpm .msi .cab	C. 系统软件包	7z（将其视为归档处理）
.iso	D（磁盘映像）	7z / bsdtar
.exe（NSIS 安装程序）	D. 安装程序 / 映像	7z
.exe（Inno Setup）	D	innoextract
.dmg	D	macOS：hdiutil；其他平台：7z（效果有限）
.pkg（macOS）	E. 链式处理	先用 xar，再用 cpio
.asar（Electron）	E（通常通过递归处理到达）	npx @electron/asar
.old .doc .xls .ppt（旧版 Office）	—	不在范围内。 这些是二进制 OLE 文件，并非 ZIP。请向用户推荐转换工具（LibreOffice/antiword），不要假装可以处理。

此处未列出的格式（.snap、.AppImage、经过加密/打包的恶意软件，如 UPX）明确不在范围内——请参阅下文的 范围外。

类别工作流

A. 标准归档（zip、7z、tar*、gz、rar 等）

7z x "<input>" -o"<outname>-unboxed" -y
# For .rar without unar installed, install it first:
#   brew install unar  /  sudo apt install unar
unar "<input>" -o "<outname>-unboxed"

当无法使用 7z 时，bsdtar（macOS 默认的 tar）是 Mac 上处理 tar/zip/zst 的零依赖替代方案：bsdtar -xf "<input>" -C "<outname>-unboxed"。

B. ZIP 容器（docx、xlsx、apk、jar、whl 等）

命令与 A 完全相同——它们都是 ZIP。解压后，请在清单中注明可供下游读取的结构化内容：OOXML 会提供 word/document.xml、xl/sharedStrings.xml 等；.apk/.jar 会提供 AndroidManifest.xml / META-INF/MANIFEST.MF；.whl 会提供 METADATA 和软件包源代码。

7z x "<input>" -o"<outname>-unboxed" -y

C. 系统软件包（deb、rpm、msi、cab）

7z 会将这四种格式都视为归档并提取其内容。在 Linux 上处理 .deb 时，原生工具是 dpkg-deb -x；处理 .rpm 时，使用 rpm2cpio <file> | cpio -idmv。在对应平台上优先使用原生工具，其他平台则回退到 7z。

7z x "<input>" -o"<outname>-unboxed" -y

D. 安装程序 / 磁盘映像（NSIS exe、Inno exe、dmg、iso）

这些格式需要按格式分别处理，因为它们的文件头各不相同。

NSIS 安装程序（最常见的 .exe 安装程序；file 报告 "Nullsoft Installation" 时可检测到）：

7z x "<input>" -o"<outname>-unboxed" -y
# The payload is usually in $PLUGINSDIR/app-*.7z — recurse on it in step 5.

Inno Setup 安装程序（file 输出中包含 "Inno Setup"，或通过魔数检测到）：

innoextract -d "<outname>-unboxed" "<input>"

macOS 上的 .dmg（始终使用 -nobrowse -readonly，依次挂载、复制、卸载）：

hdiutil attach "<input>" -nobrowse -readonly -mountpoint /tmp/unbox-dmg-$$
cp -R /tmp/unbox-dmg-$$/* "<outname>-unboxed"/ 2>/dev/null
hdiutil detach /tmp/unbox-dmg-$$

在 Linux/Windows 上，7z 可以读取许多 DMG 文件，但并非全部都能读取（UDZO 与 UDIF）：尝试 7z x；如果失败，请告知用户，在其平台上提取此文件中的 DMG 内容并不可靠。

.iso：7z x "<input>" -o"<outname>-unboxed" -y（或在 macOS 上使用 bsdtar -xf）。

E. 链式 / 嵌套处理（.pkg、.asar 以及步骤 5 中发现的任何内容）

分为两种子类型：

.pkg（macOS 安装程序）——包含 Payload 文件的 xar 归档（该文件是一个 cpio 归档，可选择使用 gzip 压缩）：

7z x "<input>" -o"<outname>-unboxed" -y          # or: xar -xf "<input>" -C "<outname>-unboxed"
cd "<outname>-unboxed"
# Payload naming + compression both vary across pkgs — do not hardcode.
# 7z sometimes renames it "Payload~"; some pkgs gzip it, some ship raw cpio.
PAYLOAD=$(find . -maxdepth 1 -iname "Payload*" -type f | head -1)
case "$(file "$PAYLOAD")" in
  *gzip*) gunzip -c "$PAYLOAD" | cpio -idmv ;;   # common case: gzipped cpio
  *cpio*) cpio -idmv < "$PAYLOAD" ;;             # some pkgs ship raw cpio
  *) echo "Unrecognized Payload format: $PAYLOAD" ;;
esac

.asar（Electron 软件包）——几乎总是通过递归处理从 Electron 安装程序中找到（NSIS exe → app-*.7z → app.asar）：

npx @electron/asar extract "<input>" "<outname>-unboxed"

对于步骤 5 中发现的其他任何嵌套容器，只需对其重新运行整个工作流（步骤 1–6）。

不在范围内

以下内容刻意不作处理。如果用户提出相关请求，请解释原因并建议替代方案，而不是伪装成可以处理：

• .AppImage — 一种可就地运行的自解压 ELF。安全提取需要使用 --appimage-extract，这会执行二进制文件，违反铁律 1。建议在沙箱中运行。
• .snap — squashfs 镜像；需要使用 unsquashfs，而该工具很少预装。v1 不在处理范围内。
• 打包／加密的恶意软件（UPX、Themida、用户不愿解锁的密码保护压缩包）— 这些属于安全研究工具的范畴，而非通用解包工具。
• 旧版二进制 Office 文件（.doc/.xls/.ppt）— OLE 复合文档，并非 ZIP。请使用 LibreOffice 或 antiword 转换；不要假装 7z 能处理它们。
• 创建／编辑 Office 文档 — 这是 anthropics/skills@docx 等工具的用途。unbox-anything 只负责提取。

注意事项（容易忽略的部分）

以下陷阱可能会在毫无预警的情况下造成问题。仔细看一遍，就不会再中招。

• $PLUGINSDIR 的 shell 展开。 NSIS 安装程序会提取到一个名称字面上为 $PLUGINSDIR 的目录。在 bash 中，$PLUGINSDIR 会被当作变量展开——请加引号或转义 $：'\$PLUGINSDIR' 或 "\$PLUGINSDIR"。任何包含字面 $ 的路径也一样。
• 加密压缩包会让 7z 挂起。 在运行 7z x 之前，务必先运行 7z l -slt "<input>"，并搜索 Encrypted = +。如果已加密，不要运行 7z x——它会一直等待永远不会输入的密码。
• .dmg 会自动在 Finder 中打开。 如果不加 -nobrowse，macOS 会挂载 DMG，Finder 可能会渲染图标、运行预览处理程序，或再次触发 Quick Look。务必使用 -nobrowse -readonly，并务必卸载。
• 终端中的 Unicode 文件名。 7z 和 unar 能正确提取这些文件名，但非 UTF-8 终端会显示乱码。如果文件列表看起来有乱码，请在列出文件前设置 LANG=en_US.UTF-8（或用户的区域设置）。
• .exe 类型检测存在歧义。 file 有时只会报告“PE32 executable”，而不指出 NSIS/Inno。如果安装程序类型不明确，请先尝试 7z l——如果能列出内容，则它是 NSIS 安装程序或自解压文件；若无法确定，则使用 innoextract -l 检测 Inno。
• .pkg 中 Payload 的命名和压缩方式各不相同。 macOS .pkg 内的 Payload 通常名为 Payload，并使用 gzip 压缩，但 7z 可能会将其提取为 Payload~；某些 pkg（例如 Microsoft Office 安装程序）则会附带未使用 gzip 封装的原始 cpio。务必使用 find -iname "Payload*" 定位 payload，并根据 file 的输出分支处理（*gzip* → gunzip|cpio，*cpio* → 直接运行 cpio），不要假设格式只有一种。
• app.asar 与 app.asar.unpacked/。 Electron 应用会同时包含这两者。asar extract 只处理 .asar 文件；.unpacked/ 目录中已包含散装文件——请原样复制，不要尝试“提取”。
• 大型 .iso/.dmg（数 GB）。 提取会使磁盘占用翻倍。请在清单中注明大小；如果目标卷空间不足，请在提取前发出警告。

参考资料

关于详尽内容——完整的格式 × 平台工具矩阵、完整的安装命令（包括 innoextract、xar、Node.js）、用于类型检测的魔数序列，以及各格式的特殊情况——请参阅 reference.md。

该文件刻意单独存放，以便让此 SKILL.md 保持精简，专注于决策。若需要此文件未提供的命令，或第 1 步中的类型检测存在歧义，请阅读该文件。