0xb007ab1e/vivarium-mcp

# Vivarium Vivarium 是一个安全的 [MCP](https://modelcontextprotocol.io) 服务器，允许 AI 助手使用 [Ghidra](https://ghidra-sre.org/) 来分析程序二进制文件。它将 Ghidra 的逆向工程功能 （反编译、反汇编、交叉引用、字符串等）作为 MCP 工具公开，供 Claude 等客户端调用。 Vivarium 的核心在于安全。你分析的二进制文件会被视为恶意输入。Ghidra 永远不会 与服务器运行在同一个进程中。相反，每次分析都在一个锁定、一次性且 无法联网的容器中进行。从二进制文件返回的每一条数据在到达模型之前， 都会被封装并标记为不受信任。 这个名字非常契合其设计理念：“生态箱”（vivarium）是一个封闭的围栏， 你可以在其中安全地存放和观察活的样本。在这里，样本就是不受信任的二进制文件。 ## 功能说明 - **读取和探索二进制文件。** 反编译和反汇编函数，列出函数、导入、导出、 字符串、符号、数据类型和注释，追踪交叉引用，读取内存映射，以及搜索 字节或字符串。每个读取工具都设有大小和数量限制，因此响应不会无限增长。 - **汇总和度量。** 报告圈复杂度、代码和数据覆盖率、调用图摘要， 扫描入侵指标和常见的加密常数，并生成整个程序的摘要。 - **识别库代码。** 将函数与内置的 Function ID 数据库进行匹配（`identify_functions`） 以标记静态链接的库代码（libc、OpenSSL、zlib 等），这样你就可以专注于程序自身的 逻辑，而无需重新逆向标准库。 - **以深度换取速度。** `session_analyze` 接受一个分析 `profile`（`light`、`default`、`deep`）， 这样你可以先对大型二进制文件进行快速的初步扫描，并在需要时进行更全面的分析。 - **边生成边流式传输结果。** 将批量反编译作为作业启动，并在提取继续的同时 通过游标拉取部分结果——这样 LLM 就可以开始对早期的函数进行推理—— 并在获取足够数据时中途取消运行。 - **建议名称。** 辅助工具支持客户端驱动的工作流，用于从反编译代码中 提出人类可读的函数名称。 - **仅在获得许可时进行修改。** 重命名函数和符号、设置注释、应用或 定义数据类型以及类似的编辑默认是关闭的。会话必须显式启用写入权限， 然后才能进行任何更改，并且可以将编辑导出并重新导入为便携式注释文件。 总共有 56 个工具。完整的列表以及每个工具的输入和输出在 [`docs/contracts/tool-catalog.md`](./docs/contracts/tool-catalog.md) 中。 ## 工作原理 Vivarium 由两部分组成： 1. **服务器**是你的 MCP 客户端与之通信的进程。它不包含任何二进制解析代码，也从不 加载 Ghidra。它负责验证每个请求、执行限制并管理会话。 2. **工作进程**是一个独立的、经过强化的容器，实际运行 Ghidra。服务器为每个会话 启动一个工作进程，并通过私有本地 socket 与其通信。当会话结束或超时时， 服务器会终止工作进程并清除其临时存储。 你可以通过 **stdio**（默认）或 **HTTP** 连接客户端。HTTP 增加了 bearer、OAuth 或 反向代理 mTLS 身份验证，旨在将 Vivarium 作为共享服务运行。 ## 安装与运行 请参阅 **[`docs/getting-started.md`](./docs/getting-started.md)** 了解分步设置指南：前置条件、 构建两个容器镜像、安装软件包、运行服务器、连接客户端以及 进行首次分析。简短版本如下： ``` git clone https://github.com/0xb007ab1e/vivarium-mcp.git cd vivarium-mcp # 构建 worker 和 server 镜像（这会下载 Ghidra；有关固定值，请参见 getting-started） # 创建 Python 3.12+ 虚拟环境并安装该 package # 将 server 指向 worker 镜像和一个 import 目录，然后运行：python -m vivarium ``` Vivarium 运行在 Linux 上，并使用 rootless [podman](https://podman.io) 来启动工作进程容器。 ## 通俗易懂的安全模型 - **二进制文件是不受信任的。** Ghidra 报告的关于它的一切（反编译代码、字符串、名称、 字节）都被封装为不受信任的数据。不要执行它、评估它或将其渲染为代码。 - **分析器是被隔离的。** 工作进程以非 root 用户身份运行，具有只读的根文件系统、 无网络访问权限、被剥夺的 Linux capabilities、seccomp 配置文件以及内存和 CPU 限制。在生产环境中，它还运行在 gVisor 之下，以提供额外的隔离边界。 - **工作进程是一次性的。** 每个会话一个工作进程，在驱逐或超时时会被终止并清除。 - **写入受控。** 在会话所有者启用写入权限之前，任何工具都无法更改分析结果。 - **供应链锁定。** Ghidra、JDK 和基础镜像均通过摘要锁定。发布 镜像会经过扫描和签名，并附带软件物料清单（SBOM）和构建来源进行发布。 完整的设计原理位于 [`docs/adr/`](./docs/adr/) 下的决策记录和 [威胁模型](./docs/security/threat-model.md) 中。 ## 文档 - [`docs/getting-started.md`](./docs/getting-started.md)：从零开始设置和运行 Vivarium。 - [`docs/faq.md`](./docs/faq.md)：快速解答——它是什么、用于恶意软件是否安全、只读与 写入、持久化、准确性、限制。 - [`docs/architecture.md`](./docs/architecture.md)：各个组件是如何组合在一起的。 - [`docs/contracts/`](./docs/contracts/)：工具目录、RPC 协议和数据封装。 - [`docs/examples/`](./docs/examples/README.md)：分层的、实践性的逆向工程工作流，展示了实际的工具 调用——[初步查看](./docs/examples/simple-first-look.md)（简单）， [分流未知的 ELF 文件](./docs/examples/medium-triage.md)（中等）， [恢复并记录集群](./docs/examples/large-annotate-and-recover.md)（大型）——此外还有一个 针对剥离过的 SQLite 二进制文件的盲测分析](./docs/examples/blind-analysis-sqlite.md)，并已与 原始源代码进行了核对。 - [`docs/runbooks/`](./docs/runbooks/)：操作程序（部署、回滚、事件响应等）， 包括 [HTTP 暴露](./docs/runbooks/http-exposure.md)。 - [`docs/adr/`](./docs/adr/)：带编号的设计决策（ADR-001 至 ADR-044）；请参阅 [ADR 索引](./docs/adr/README.md) 获取路线图和建议的阅读顺序。 - [`SECURITY.md`](./SECURITY.md)：如何报告漏洞。 - [`CHANGELOG.md`](./CHANGELOG.md)：发布历史。 - [`PLAN.md`](./PLAN.md)：交付计划和锁定的决策。 ## 许可证 [Apache License 2.0](./LICENSE)，与 Ghidra 自身的许可证相匹配。请参阅 [`NOTICE`](./NOTICE)。

标签：DLL 劫持, Ghidra, MCP, 云安全监控, 云资产清单, 大语言模型, 操作系统探测, 沙箱隔离, 逆向工具, 逆向工程, 静态分析