CAPEsolo

用于在独立 VM 中运行 capemon 的 Python GUI。提供 CAPE（Configuration And Payload Extraction，配置与载荷提取）处理及结果的子集。

界面

• 顶部标签页：Start，然后每个结果视图各一个（Info、Behavior、Signatures、Payloads、 Yara、Configs、Strings、Debugger、JS Log、Network）。
• Start 标签页将目标选择、包选项、监控和日志标志分组到 卡片中；操作按钮（Launch、Kill、reports、Zip Results）固定在窗口底部， 因此不会随滚动而消失。
• 深色和浅色主题，可从右下角的状态栏或从 Settings 切换。 选择会写入 cfg.ini，并在下次运行时恢复。
• 在 Signatures 之前先处理 Payloads 和 Configs。签名在运行时只能看到 当时结果中已有的内容，而其中一些会读取 payload、config 和 yara 数据——先运行该阶段 会悄悄少报而不是失败。Signatures 按钮会保持禁用， 直到那些标签页已运行，其工具提示会说明还有哪些未完成。

开发 UI

• tools/uidev/ 在屏幕外构建真实面板并将其写入 PNG，因此布局 变更可以在不启动分析的情况下进行冒烟测试和截图。参见 tools/uidev/README.md。

• 相同的脚本会在每次拉取请求时于 CI 中运行，在 Windows runner 上，并将 渲染结果作为 artifact 上传。

• 创建一个适合运行恶意软件的 Windows 10 VM。

  • 使用 CAPEv2 客户机指南了解配置细节。
  • https://capev2.readthedocs.io/en/latest/installation/guest/index.html

• 在 VM 中安装 Python，已在 64 位 Python 版本 3.11、3.12 和 3.12 上测试。将 Python 添加到 path。

• 下载并安装两个 Microsoft Visual C++ Redistributable：

  • https://aka.ms/vs/17/release/vc_redist.x86.exe
  • https://aka.ms/vs/17/release/vc_redist.x64.exe

• 安装 CAPEsolo。

  • pip install CAPEsolo

• 为你的 VM 创建快照。

快速开始

• 打开管理员命令窗口。
• 输入 capesolo 运行。

或者，创建指向 CAPEsolo.exe 的快捷方式， 它位于与你的 python.exe 文件相同位置的 Scripts 子目录中。

• 在 Advanced 下，勾选 'Run as administrator'
• 图标文件位于 CAPEsolo 安装文件夹的 site-packages 下。

分析结果位于 C:\Users\Public\CAPEsolo\analysis。

• 可在 C:\Users\Public\CAPEsolo\cfg.ini 中配置
• 此处的设置会覆盖 python-path\site-packages\CAPEsolo\cfg.ini 中的打包默认值， 并且在 pip install --upgrade CAPEsolo 后仍然保留，而该命令会覆盖打包副本。
• 只包含你想更改的键；其余会回退到打包默认值。

社区签名

• CAPEsolo 仅附带自己的签名。CAPEv2 / CAPESandbox 社区签名放在 C:\Users\Public\CAPEsolo\signatures（与 cfg.ini 相邻），不做修改。Update（见下文）可以从 https://github.com/CAPESandbox/community 填充 其 community 子文件夹，或者你也可以自行将文件复制到那里。
• 会扫描子文件夹；deprecated 和 linux 会被跳过。添加或编辑的文件会在下一次签名阶段 被拾取，无需重启。
• 那里的签名会替换同名的随附签名。你自己放在 community 之外的签名 也会优先于其中的同名签名。
• 需要 CAPEsolo 没有的 CAPEv2 模块的签名会被跳过，分析日志 会指出缺失的模块。读取 CAPEsolo 不产生的结果部分（例如 Suricata）的签名 会加载但永远不会匹配。
• 这些签名在 CAPEv2 根目录下查找的可选数据文件（extra/msft-public-ips.csv、 data/dga.bloom）会从 C:\Users\Public\CAPEsolo 读取。

YARA 规则

• CAPEsolo 自带其 CAPE 规则。你自己的规则放在 C:\Users\Public\CAPEsolo\yara，社区规则放在其 community 子文件夹中。两者都会与 CAPE 规则一起被扫描。当两个文件同名时：Desktop\custom 优先，其次是你自己的文件夹，然后是 community，最后是打包的规则。
• pip install --upgrade CAPEsolo 会恢复打包的规则。

更新（Start 选项卡）

• 询问要下载什么：
  • YARA rules - CAPEsolo（默认勾选）和 CAPEv2 会根据勾选项重建打包的规则（CAPE 规则以及 capemon 在客户机中使用的监控规则）。当两者都有同名文件时，使用 CAPEsolo 的。
  • YARA rules - Community 用 CAPESandbox/community 的 data/yara/CAPE 替换 yara\community。
  • Signatures - Community 用 CAPESandbox/community 的 modules/signatures/windows 和 all 替换 signatures\community。
• 你自己的文件以及 Debugger 选项卡保存的规则永远不会被改动。所有内容都会在替换任何东西之前先下载完成，因此更新失败时会保留原有内容。
• 同样的选项也可通过 capesolo --update_yara capesolo,capev2,community（不带值表示 capesolo）、capesolo --update_signatures 以及 MCP 工具 capesolo_update_yara 使用。

报告（Start 选项卡）

• Reports 通过对分析的一次遍历构建 JSON 和/或 HTML 报告（默认两者都勾选）。每个报告都会写入桌面和分析目录。

每次分析后还原虚拟机。

查看 JSON 报告（独立版）

• tools/report_viewer.py 是一个自包含的 CAPEsolo report.json 分诊查看器，可在任何仅装有 Python 的主机上运行——无需安装 CAPEsolo，也没有 pip 依赖（标准库 tkinter）。
  • python tools/report_viewer.py [path\to\report.json | path\to\bundle.zip]
  • 来自 Zip Results 的结果包可直接打开：报告会就地读取 zip 中的内容，因此完整包的有效载荷字节永远不会写入执行分诊的机器。
  • 不带参数时，它会打开 %USERPROFILE%\Desktop\report.json（CAPEsolo 写入该文件的位置）；使用 File > Open 选择其他报告或包。
  • 分诊选项卡：Overview（判定卡片——文件哈希、检测结果、主要签名、配置、计数，以及捕获过程中是否有任何内容丢失）、Capture（本次运行存储了什么、没有存储什么）、Signatures（按严重程度排序、带颜色、含每进程证据）、Processes（进程树及每进程元数据）、Network（DNS/HTTP/Hosts/Domains/Flows）、Payloads（含 yara 命中与字符串）、Yara（每个被扫描文件中命中的每条规则，含元数据、匹配字符串和偏移量）以及 IOCs（聚合，支持 Copy / Export CSV / Export text）。
  • 搜索框（顶部栏）可在签名、网络、有效载荷、配置、IOC 和字符串中查找某个值，并跳转到所属选项卡。
  • Raw JSON 选项卡保留完整树，用于查看分诊选项卡未展示的任何内容。
  • 可处理大型报告：文件读取时显示进度条，原始树延迟加载（展开时才加载子节点），详情窗格有大小限制，因此在数百 MB/GB 的报告上仍保持响应。（GB 级报告解析仍需数 GB 内存——这是 Python JSON 的固有特性。）
  • 深色和浅色主题，与 CAPEsolo GUI 的配色一致。默认跟随 Windows 的“应用模式”设置（其他情况下为深色）；右上角的按钮可在本次会话中切换，--theme dark|light 可强制指定。菜单栏和原生 Open/错误对话框由 Windows 绘制，保持浅色——tkinter 无法为它们设置主题。
  • 需要 tkinter——标准 Windows/macOS Python 已自带；在 Linux 上安装 python3-tk。

AI 分析（可选）

• 查看器可以对已加载的报告运行 Claude：每个证据标签页配备一名专家，Overview 上给出首席分析师的裁决，以及一个交互式问答循环。它是可选且非必需的——查看器仍然没有必需的依赖项，上述每个标签页在没有这些功能的情况下都能正常工作。
• 通过一个包和一个密钥即可启用：
  • pip install anthropic
  • set ANTHROPIC_API_KEY=sk-ant-...（或传入 --api-key，或在 AI > Settings 中输入）
  • 如果没有该包或密钥，AI 面板会说明这一点，其他一切保持不变。
• 三种使用方式：
  • GUI——AI 标签页为每个证据标签页配备一名专家（Signatures、Processes、 Behavior、Network、JS Log、Payloads、Configs、Yara、Static、IOCs、Capture），外加一个 Ask 面板。 “Analyze all”会运行所有专家，然后在 Overview 上写入一张裁决卡片。 顶部栏中的“Analyze tab”会针对你当前正在阅读的标签页运行相应的专家。
  • 一次性——python report_viewer.py bundle.zip --ask "is this a loader or the final stage?"
  • 交互式——python report_viewer.py bundle.zip --chat，或 --analyze all / --analyze Network 以无界面方式打印发现结果。
• 选项：--model（默认 $ANTHROPIC_MODEL 或 claude-opus-5）、--effort （low..max）、--yes 用于跳过数据外发确认。不会向磁盘写入任何内容—— 密钥和模型仅存在于环境变量或该会话中。
• 发送的内容：文件名和哈希、签名文本、进程/注册表活动、网络 端点、配置字段和载荷字符串——经过上限筛选的选取，任何被省略的内容都会 向模型声明并显示在面板中。样本和载荷字节永远不会被发送 （报告包本身就不包含这些内容）。每个会话会要求你确认一次。
• 成本：完整运行约 11 次调用。案件摘要只发送一次并缓存，因此后续 专家以约十分之一的输入价格重新读取它；“Analyze all”在开始前会显示 token 和 美元估算，状态行会在之后报告实际花费。
• 回答以报告为依据，并在证据不支持结论时明确说明。 恶意软件内容偶尔会触发模型的安全分类器；请求带有 服务器端回退，拒绝会显示为拒绝，而不是空白面板。

将结果带到另一台机器

• 开始面板上的 Zip Results 会询问要写入哪个归档：
  • 报告包（Desktop\capesolo_report_<timestamp>.zip）——report.json、capture.json、 analysis.log 和 files.json。不含样本，也不含载荷字节，因此可以安全地复制到你的 工作站。直接用 tools/report_viewer.py 打开它（见下文）；查看器会从 zip 中读取 报告，无需解压任何内容。
  • 完整包（Desktop\capesolo_analysis_<timestamp>.zip）——整个分析目录， 用于恢复到干净的虚拟机中。它包含实时恶意软件；请相应处理。
• 如果还没有 report.json，Zip Results 会提议先生成一个——报告和 HTML 报告现在会同时写入分析目录和桌面，这正是让 任一包自包含的原因。

了解捕获了什么

• 每次分析都会在结果旁边写入 capture.json：来自 ResultServer 的传输计数、 files.json 中哪些工件在磁盘上缺失、哪些仅部分到达或在 upload_max_size 处被截断、分析器从未上传哪些文件（过大或为空），以及 当时生效的上限。
• 任何丢失的内容都会被记录，并在运行结束时显示在状态栏中，同时携带在 report.json 的 capture 下，并渲染在 tools/report_viewer.py 的 Capture 标签页上。仅部分 存储的载荷会在 Payloads 列表中标记出来，而不是作为完整内容呈现。

从不可用 VM 中保留结果

• 如果样本在引爆后使 VM 无法使用，请点击 Zip Results 并选择完整 捆绑包，将整个分析目录归档到 Desktop\capesolo_analysis_<timestamp>.zip。
• 要恢复到干净/已还原的 VM，请将该 zip 复制到 C:\Users\Public\CAPEsolo\restore.zip， 然后启动 CAPEsolo。启动时它会将 zip 解压到分析目录（仅当该 目录尚无分析结果时），并将其重命名为 restore.zip.done，以便只恢复一次。
• 随后结果选项卡会读取已恢复的产物，无需重新运行——逐个处理各选项卡（Behavior、 Yara、Configs、Signatures），或使用 Reports 按钮。

按哈希下载样本

• Start 面板可以从 VirusTotal 或 MalwareBazaar 按 MD5/SHA1/SHA256 获取样本， 并将其用作分析目标。来源会自动选择（优先 VirusTotal，其次 MalwareBazaar；MalwareBazaar 需要 SHA256），具体取决于配置了哪些密钥。
• 在 cfg.ini 中（或通过 Settings 按钮）启用：在 [download] 下设置 enabled = true。 directory 设置样本保存位置（默认为用户的 Desktop）。
• API 密钥——获取途径：
  • VirusTotal：文件下载需要 VirusTotal Enterprise / Intelligence API 密钥。免费的 社区密钥可以查询报告，但无法下载文件。
  • MalwareBazaar：免费的 abuse.ch Auth-Key（在 auth.abuse.ch 创建账户）。
• API 密钥以加密形式存储，绝不以明文形式存放在 VM 上。你在 VM 之外使用 tools/encrypt_api_key.py 生成加密 blob，然后将其粘贴到 cfg.ini。
• tools/encrypt_api_key.py 随 CAPEsolo 源代码仓库提供，位于 tools/ 下。请在 受信任的主机（而非分析 VM）上运行它；它只需要 pip install cryptography。
  • python tools/encrypt_api_key.py
  • 它会（隐藏地）提示输入 API 密钥和密码，并打印一个加密 blob。
  • 使用相同的密码加密你使用的每个提供商，这样一次提示即可解锁两者。
• 通过以下任一方式在客户机中安装该 blob：
  • 将其作为 api_key_enc 粘贴到 cfg.ini 的 [virustotal] 和/或 [malwarebazaar] 下，或
  • 设置 CAPESOLO_VT_APIKEY_ENC / CAPESOLO_MB_APIKEY_ENC 环境变量 （环境变量会覆盖 cfg.ini）。
• 启用下载后，CAPEsolo 会在启动时提示一次输入密码，并仅在内存中解密 密钥；明文密钥绝不会写入 VM 的磁盘。输入密码后， 对 VM 创建快照，以便每次还原后都可用。

MCP 服务器

• CAPEsolo 包含一个 MCP 服务器入口点，用于程序化分析工作流。
• 使用 CAPEsolo-mcp 通过 stdio 启动它，或通过 HTTP 提供服务以便从主机访问。
• 有关传输方式、cfg.ini 配置、完整工具列表和示例，请参阅 mcp_server.md。