PrinceOfPwn/Munin

# Munin
## 📖 什么是 Munin Munin 是一个建立在 **Model Context Protocol (MCP)** 之上的综合威胁情报、红队和 agent 评估编排平台。它始终由作为最终权威的 **人类操作员** 进行管控。 Munin 专为授权实验室、内部演习和明确授权的红队环境而设计，提供以下功能： - 🧠 **ReAct 协调器**：一个自主的核心 agent，具备多步推理循环、自我诊断和任务委派能力。 - 💾 **持久化存储**：使用本地 SQLite 或云端 Turso 进行实时状态同步，确保 agent 在不同会话之间永不丢失上下文。 - 📜 **语义和情景记忆**：保留关键事实（语义）以及每一步和决策的不可变账本（情景）。 - 🛠️ **原生工具和子 agent**：内置包含攻击性、被动和管理功能的目录。 - 🚀 **受控的自我扩展**：动态创建新的 Python 工具（`tool_forge`）和子 agent（`graph_forge`）（在安全沙箱内）。 - 🐦 **兄弟 Hugin**：与 Hugin（Odin 的另一只乌鸦，代表“思想”）的原生集成，作为基于网络安全知识图谱的 RAG 系统。 - 🖥️ **多接口**：现代化的 Next.js 图形用户界面 (GUI)、Discord 集成以及 GitHub Actions 基础设施。 - 🛑 **人类在环 (HITL)**：严格的安全电路，当 agent 面临歧义、未经授权的范围或破坏性操作时，会自动暂停并请求人工批准。
## ⚡ 核心能力 | 类别 | 描述 | 已实现的工具 / 模块 | | :--- | :--- | :--- | | **MCP 和 HTTP 传输** | 异步 FastMCP 服务器 (`/mcp`)，使用 Bearer token 和 HTTP 状态控制暴露所有工具。 | `munin/mcp/main.py`, FastMCP, `streamable-http`。 | | **ReAct Agent** | 推理循环（系统提示词、思考、行动、观察），与动态工具目录进行交互。 | `munin_chat`, `munin_self_diagnose`。 | | **Soul** | 基于 Markdown 的版本化 agent 身份（目标、身份、原则、技能）。控制其行为。 | `soul_propose_edit`, `soul_reject_proposal`。 | | **记忆** | 持久化存储语义知识（事实）和情景知识（事件/轨迹）。 | `memory_remember`, `memory_recall`, `episodic_query`。 | | **共享情报** | 在同一活动的 agent 之间异步共享调查结果。 | `publish_shared_intel`, `query_shared_intel`。 | | **Hugin (RAG 和图谱)** | 从作为知识库的兄弟系统中查询结构化的攻击计划和假设。 | `hugin_search`, `hugin_rag_search`, `hugin_plan_for`, `hugin_neighbors`, `hugin_node_detail`。 | | **侦察和安全** | 集成主流进攻性安全工具的原生目录。 | `nmap_scan`, `httpx_probe`, `nuclei_scan`, `ffuf_scan`, `feroxbuster_scan`, `sqlmap_scan`, `netexec_scan`, `hydra_attack`, `smbmap_scan`。 | | **被动情报** | 利用公开来源和漏洞字典 (NVD/EPSS) 进行情报充实。 | `cve_lookup`, `cve_search`, `cve_enrich`, `exploit_search`, `package_vuln_lookup`。 | | **Active Directory / LDAP** | 使用带有 `escape_filter_chars` 的过滤器对 AD/OpenLDAP 进行安全查询。 | `ldap_search`, `ldap_who_am_i`, `find_domain_admins`, `find_kerberoastable_users`, `find_asrep_roastable_users`, `get_user_groups`, `get_current_user_info`, `dump_domain_structure`。 | | **Tool Forge** | 按需编写、验证 (AST) 并执行新的 Python 工具 (`gen__*`)。 | `tool_forge`, `disable_generated_tool`, `describe_generated_tool`。 | | **Graph Forge** | 生成具有受限工具白名单的专用子 agent（ReAct 沙箱化）。 | `graph_forge`, `describe_generated_graph`。 | | **委派 (Wake Queue)** | 一种并发架构，编排器为锻造的任务唤醒隔离的子进程。 | `munin_wake`, `subagent_trace`, `claim_shared_task`, `list_shared_tasks`, `complete_shared_task`。 | | **诊断与基础设施** | 用于检查 agent 健康、VPN 状态和执行临时命令的内部工具。 | `health_check`, `vpn_status`, `execute_command`, `shared_state_overview`。 | | **操作员交互** | Discord 和 GUI 桥接、屏幕截图上传以及 agent 间的通知。 | `post_agent_message`, `fetch_agent_messages`, `ack_agent_message`, `web_evidence_screenshotter`。 | | **Turso 和持久化** | 统一的 SQLite/Turso 数据库，维护真实的跨会话和多 agent 状态。 | `munin/mcp/shared_state.py`, `turso`/`libsql`。 | | **扩展 (Git/PR)** | 为 agent 的演进创建 Pull Request（需要明确的 HITL 批准）。 | `extension_forge`, `extension_open_pr`, `wiki_git_syncer`。 |
## 🏗️ 架构 Munin 的工作流程围绕着一个 **集中式编排器** 进行组织，它负责接收指令、查询 LLM、向子 agent 委派任务、记录证据，并将其存储在 SQLite/Turso 中。 ``` flowchart TD Operator[Human Operator] --> |HTTP / WebSockets| GUI[Next.js GUI] Operator --> |Discord API| DiscordBridge[Discord] GUI --> MCP_Bus[MCP Server / FastMCP] DiscordBridge --> MCP_Bus subgraph Core ["Munin Core"] MCP_Bus --> Agent[Munin Agent] Agent <--> LLM[LLM Client / OpenAI-compat] Agent <--> Soul[SoulManager] Agent <--> Orchestrator[Orchestrator] end subgraph Registries ["Registries & Tools"] MCP_Bus --> NativeTools[Native Tools] MCP_Bus --> GenTools[Generated Tools / tool_forge] end subgraph WakeQueueSub ["Subagents (Wake Queue)"] Orchestrator --> |munin_wake| WakeQueue[(Wake Queue)] WakeQueue --> |spawn| Subagent1[Graph Forge Subagent] WakeQueue --> |spawn| Subagent2[Specialist Subagent] end subgraph Persistence ["Persistence (SQLite / Turso)"] Agent --> |memory_remember| Semantic[(Semantic DB)] Agent --> |episodic_log| Episodic[(Episodic Trace)] Agent --> |publish| SharedIntel[(Shared Intel)] end NativeTools --> |Queries| External(Targets / AD / Web) GenTools --> |Queries| External Subagent1 --> MCP_Bus Semantic -.-> GUI Episodic -.-> GUI SharedIntel -.-> GUI ```
### 🔄 `munin_chat` 请求的流程 1. **接收**：请求通过 Web 客户端或 Discord 到达 `/mcp` 端点。 2. **上下文加载**：agent 加载其身份 (`Soul`)、整合后的语义记忆、当前工具目录以及 Hugin 上下文。 3. **决策**：LLM 评估提示词并决定是直接回复、委派给子 agent，还是调用特定工具。 4. **执行**：运行操作（例如 `nmap_scan` 或 `ldap_search`）。 5. **持久化**：将调用、参数和输出记录到情景轨迹中。 6. **迭代**：LLM 接收观察结果（证据）并进行迭代，直到实现目标或需要*人类在环*。 7. **展示**：将情景轨迹流式传输到 GUI 以供审计。
## 🧩 ReAct 和协调 Munin 使用 **ReAct** (Reasoning + Acting) 范式。 工具可以是： - **原生**：在代码库中使用 Python 实现（例如 `ldap_search`）。 - **生成**：在运行时由 `tool_forge` 创建并存储在动态目录中 (`gen__*`)。 - **原生子 agent**：在 `munin/subagents/` 中预定义的 ReAct 逻辑。 - **锻造图谱**：由 `graph_forge` 创建的特定用途子 agent。 - **异步作业**：处理长时间运行的扫描（例如 Nuclei、Nmap）而不会阻塞主线程。 与 Munin 的对话是持久化的。与临时的脚本不同，Munin 会记住每一个发现，并通过其记忆在未来的迭代中将其牢记于心。
## ✨ Soul 和提示词 Munin 的行为和个性在 `soul/` 目录中定义，由 Markdown 文件组成： - `soul/identity.md`：Munin 是谁（agent 的角色）。 - `soul/goals.md`：它必须努力实现的目标以及需要保护的内容。 - `soul/principles.md`：关于 OPSEC、安全和格式的硬性规则。 - `soul/skills.md`：关于 agent 认知能力的摘要。 **语言策略 (`MUNIN_OPERATOR_LANGUAGE`)**： - 内部 LLM 协调、深度推理（隐藏的 *thinking*）和处理过程可以使用*高密度简体中文*或模型的母语，以实现最大效率。 - 所有生成的代码、工具名称、JSON 参数、schema、日志和源代码均**严格使用英文**。 - 发给操作员的**最终响应**将采用配置的首选语言（`auto`、`en`、`es`）。
## 💾 记忆和持久化 Munin 在重启之间维护状态。它的所有记忆都是持久的，并受到统一管理： - **语义记忆**：重要事实（`memory_remember`、`memory_recall`）。 - **情景记忆**：每一个操作、工具调用和结果都会被记录到 `episodic_query` 中，以构建不可变的轨迹。 - **共享情报**：团队范围内共享的发现（`publish_shared_intel`、`query_shared_intel`）。 - **Wake Queue**：用于子进程（子 agent）的队列系统。 **支持的后端：** - **SQLite (本地)**：默认选项，非常适合开发和测试。（位于 `data/shared_state.sqlite`）。 - **Turso (libsql / 云端)**：通过配置 `MUNIN_DB_URL`，Munin 将连接到一个分布式数据库。**强烈推荐用于真实演习、GitHub Actions 中的在线会话以及 Multi-Agent 架构。**
## 🧠 Hugin（知识兄弟） 如果说 Munin 代表记忆和执行，那么 **Hugin**（思想）就是提供 TTP、方法论和攻击向量的结构化静态仓库（知识图谱）。 原生集成的 Hugin 工具包括： - `hugin_search`：在整个图谱中进行简单的文本搜索。 - `hugin_rag_search`：针对攻击上下文的混合搜索。 - `hugin_plan_for`：请求针对特定目标的结构化攻击计划（步骤）。 - `hugin_neighbors`：探索关系（例如，哪些工具可以缓解哪些漏洞）。 - `hugin_node_detail`：获取某项技术的深度描述。 - `hugin_refresh`：使本地的 Hugin 缓存失效。 **典型的 Hugin 流程**： `目标 → hugin_search → 关系 → hugin_node_detail → 攻击假设 → 使用 Munin 工具进行验证 → 持久化的发现`
## 🗄️ LDAP 和 Active Directory Munin 提供了一套全面且安全的工具套件，用于枚举 Active Directory 或 OpenLDAP 环境。所有工具均使用来自 `ldap3` 的 `escape_filter_chars` 来防止 LDAP 注入，并实现了一个 Schema-Tolerant 层，以便在 AD 属性（例如 `sAMAccountName`）不存在时（例如在 OpenLDAP 中）进行动态适应。 实际已实现的工具（`munin/mcp/tools/ldap_tools.py`）： 1. `ldap_who_am_i`：验证目录连接的凭据。 2. `get_current_user_info`：返回已认证用户的属性。 3. `get_user_groups`：枚举用户的组（支持 uid、sAMAccountName、cn）。 4. `ldap_search`：使用安全过滤器模板（例如 `filter_template` 和 `params_json`）进行参数化搜索。 5. `find_kerberoastable_users`：发现带有 SPN 的账户（Kerberoasting 候选者）。 6. `find_asrep_roastable_users`：发现具有 `DONT_REQ_PREAUTH` 属性的账户（AS-REP Roasting 候选者）。 7. `find_domain_admins`：枚举特权组的成员（Domain Admins）。 8. `dump_domain_structure`：提取拓扑结构（OUs、Containers）。
## 🔭 侦察和安全工具 Munin 暴露了封装为 MCP 工具的标准进攻性安全二进制文件（参见 `munin/mcp/main.py`）。 - **网络发现**：`nmap_scan`、`nmap_advanced_scan`。 - **Web 枚举**：`httpx_probe`、`feroxbuster_scan`、`ffuf_scan`、`katana_crawl`。 - **漏洞与利用**：`nuclei_scan`、`sqlmap_scan`。 - **SMB 和 AD (主动)**：`netexec_scan`、`smbmap_scan`。 - **凭据**：`hydra_attack`。 - **图形证据**：`web_evidence_screenshotter`。 - **诊断与控制**：`execute_command`（需要极高的 OPSEC 权限）、`health_check`、`vpn_status`。
## 🛠️ Tool Forge (`tool_forge`) Munin 可以通过编写安全的 Python 代码来进行自我扩展。 1. **识别缺口**：Munin 发现自己缺少用于完成某项任务的工具。 2. **调用 `tool_forge`**：生成一个 Python 脚本。契约必须用**英文**编写。 3. **AST 验证**：系统检查生成的代码，阻止不允许的导入、`exec`、`eval` 和复杂的类。 4. **沙箱**：在受限制的环境中执行代码。 5. **注册**：如果通过检查，它将被动态注册为 `gen__>`。 6. **持久化**：存储在 SQLite/Turso 的 `procedural` 表中。 7. **检查 / 执行**：操作员可以使用 `describe_generated_tool` 进行检查，或者在正常流程中观看 Munin 调用它。 8. **停用**：如果工具有缺陷，操作员或 Munin 可以调用 `disable_generated_tool`。
## 🕸️ Graph 和子 Agent Forge (`graph_forge`) 当一项任务对于单个对话线程来说过于庞大时，Munin 会使用 `graph_forge` 来创建一个专用的子 agent“配置”。 - **生成**：调用 `graph_forge`，定义一个目的、一个专门的系统提示词和一个严格的工具白名单（如有必要，包括 Hugin 工具）。 - **持久化**：定义保存在 `generated_graphs` 表中。**这些不是新的 Python 文件**，而是 ReAct 运行器的受限实例。 - **唤醒 (`munin_wake`)**：Munin 将任务发送到 `Wake Queue`。编排器随后会启动一个隔离的子进程。 - **可追溯性 (`subagent_trace`)**：Munin（或操作员）可以异步监控子 agent 正在做什么。 - **交接**：子 agent 通过消息收件箱返回其结果（或请求人工干预）。
## ✋ 人类在环 (HITL) 操作员是**最终权威**。Munin 被编程为在以下条件下暂停并请求审查： - 模糊的范围或目标。 - 不可逆的破坏性操作或实验室之外的操作。 - 对其自身源代码的深度修改。 - 身份 (Soul) 的更改。 - 最终发布关键发现或发起 Pull Request (`extension_open_pr`)。 - 在活动环境中使用高权限的被攻陷凭据。 操作员可以在 GUI 或 Discord 中观察每一个思考、工具调用和轨迹。
## 💻 GUI (图形用户界面) 位于 `app/` 文件夹中，使用 Next.js 14+ 和 Tailwind CSS 构建。 使用以下命令启动 GUI： ``` cd app && npm ci && npm run dev ``` 该界面包含： - **聊天**：与 Munin 对话并查看证据的主要终端。 - **工具**：包含 70 多种工具（原生和 `gen__*`）目录的可视化浏览器。 - **记忆**：用于查看语义记忆、情景轨迹和 Turso 表的查看器。 - **Soul**：用于检查定义其个性的 Markdown 文件的检查器。 - **Agent**：实时监控 Wake Queue 中的子 agent 以及 `agent_presence` 状态。 - **MCP 状态 / 设置**：HTTP 传输连接、Bearer token、超时设置。 - **Artifacts**：用于查看生成的工件（Markdown、JSON、Python）的查看器。
## 👾 Discord Munin 可以在私有的 Discord 服务器中 24/7 运行。 - **配置**：变量 `MUNIN_DISCORD_TOKEN`、`MUNIN_DISCORD_CHANNEL_ID`、`MUNIN_DISCORD_ALLOWED_USER_IDS`。 - **操作**：监听 `munin,` 前缀。仅响应 `ALLOW_LIST` 中明确允许的 ID。 - **安全**：所有 OPSEC 规则、预检、迭代限制和授权机制均与在 CLI 或 GUI 中完全一样适用。绝不会在聊天中暴露配置机密。
## ☁️ GitHub Actions 和在线会话 对于临时部署或远程演习，Munin 可以在 Turso 的支持下完全在 GitHub Actions 中运行。 1. **仓库机密**：配置 `LLM_BASE_URL`、`LLM_API_KEY`、`MUNIN_MCP_AUTH_TOKEN`、`MUNIN_DB_URL` (Turso) 以及 `MUNIN_DB_AUTH_TOKEN`。（绝不要将这些内容提交到代码中）。 2. **执行**：Workflow > `Munin Live Session` > Run。 3. **参数**： - `open_web_gui`：启动 Next.js 界面，并通过 3 种可能的隧道提供商（`ngrok`、`cloudflared` 或 `localhost-run`）暴露 URL。如果配置了 token，`auto` 模式将优先使用 ngrok。 - `persist_state`：启用到 Turso 的持久化存储。 - `duration_minutes`：限制 Runner 的会话持续时间。 4. **连接**：Action 的“Job Summary”将显示公开的 GUI URL。访问它并使用 `MUNIN_MCP_AUTH_TOKEN` 进行身份验证。
## ⚙️ 配置 (`.env.example`) 快速变量文档： - **LLM**：`LLM_BASE_URL`、`LLM_API_KEY`、`LLM_MODEL`、`LLM_TIMEOUT_FLOOR/CEILING`。（必填）。 - **语言**：`MUNIN_OPERATOR_LANGUAGE` (`auto`、`en`、`es`)。 - **MCP 认证**：`MUNIN_MCP_AUTH_TOKEN`（必填，HTTP Bearer 认证）、主机/端口。 - **Turso/持久化**：`MUNIN_DB_URL`、`MUNIN_DB_AUTH_TOKEN`。（SQLite 可选，云 Turso 必填）。 - **LDAP**：`LDAP_URI`、`LDAP_BASE_DN`、`LDAP_BIND_DN`、`LDAP_PASSWORD`。（用于 Active Directory 实验室）。 - **Hugin**：`HUGIN_URL`（指向 `graph.json` 的 Raw URL）。 - **Discord**：`MUNIN_DISCORD_TOKEN`、`MUNIN_DISCORD_CHANNEL_ID`（可选）。 - **自我扩展 / Git**：`MUNIN_AUTO_COMMIT`、`MUNIN_AUTO_PR`。 - **安全**：`PREFLIGHT_POLICY`、`OFFX_EXPECTED_EGRESS_IP`。
## 🛡️ 安全和 OPSEC Munin 被设计为一把已经“打开保险栓”的武器： - **授权和预检**：具有攻击性的工具（nmap、nuclei、sqlmap）在触发前会查询网络 OPSEC 策略。 - **出口限制**：严禁扫描超出范围的 IP（`OFFX_FORBIDDEN_EGRESS_IP`）。 - **保密性**：Munin 不会在日志或 Discord 中“泄露”密码或内部 CoT（除非在安全模式下明确报告发现）。 - **沙箱化**：`tool_forge` 通过 AST 阻止执行不安全的调用（例如不受控制的 `os.system`）。
## 🚑 故障排除 - **GUI 出现 HTTP 403**：检查 *Settings* 中的 **Bearer Token** (`MUNIN_MCP_AUTH_TOKEN`) 是否与服务器匹配。 - **HTTP 404 / Turso 问题**：确保在 Turso URL 中使用 `libsql://` 或 `https://`，并确保 Auth Token 有效。 - **"stream not found" / "EOF"**：MCP 服务器已重启或超时。从 GUI 重新启动通信。 - **`tools/call` 超时**：调整 `LLM_TIMEOUT_CEILING` 或 `MUNIN_MAX_ITERATIONS`。长耗时的工具应在子 agent (Wake Queue) 或 `async` 模式下执行。 - **Hugin 缓存不可用**：验证对 `HUGIN_URL` 的网络访问。尝试使用 `hugin_refresh`。 - **锻造工具时出现 `ModuleNotFoundError`**：确保依赖项是条件导入的；Munin 仅允许其当前环境中的库。 - **生成的工具缺少源码 (`gen__*`)**：工具未能注册，或者 `procedural` 数据库未能保存。运行 `munin reset` 并重新锻造。 - **Soul 路径无效**：验证 `MUNIN_SOUL_PATH` 是否从根目录指向 `./soul`。 - **Discord 没有事件**：确保在 Discord Developer Portal 中启用了 Intents，并且您发送了 `munin,` 前缀。
## 🔬 开发和测试 - **安装**：`poetry install` (Python 3.11+)。 - **启动服务器**：`poetry run munin mcp --transport streamable-http`。 - **单元 / 集成测试**：`poetry run pytest tests/` - **Linting**：`poetry run ruff check .`
## 📁 仓库结构 ``` munin/ ├── app/ # Next.js GUI (Dashboard, control terminal) ├── data/ # Local SQLite persistent state (git-ignored) ├── docs/ # Guides, architecture manuals, and operator guide ├── munin/ # Platform Core (Python) │ ├── core/ # ReAct Loop, Orchestrator, Prompting │ ├── mcp/ # FastMCP Server, native tools, registry │ ├── rag/ # Hugin RAG Logic │ └── subagents/ # Wake Queue, AST sandbox, tool_forge, graph_forge ├── scripts/ # Utilities, LDAP mock ├── soul/ # Markdown Identity (goals, identity, principles) ├── tests/ # Platform tests ├── .env.example # Secrets template ├── Dockerfile # OpenLDAP lab container └── pyproject.toml # Poetry dependencies ```
## 📚 相关文档 - [操作员指南](docs/operator-guide.md) - [Munin 系统指南](docs/munin-system-guide.md) - [核心架构](docs/architecture.md) - [持久化架构](docs/architecture-persistence.md) - [工具清单](docs/tools_reference.md) - [提示词架构](docs/prompt-architecture.md) - [安全说明](docs/security-notes.md) - [GitHub Actions 教程](docs/github-actions-tutorial.md) - [24/7 服务器操作](docs/operator-24x7.md) - [GUI README](app/README.md) - [Hugin 知识库](https://github.com/PrinceOfPwn/Hugin)
## ⚖️ 许可证和免责声明 **许可证**：本项目基于 **专有 - 非商业性** 许可证提供。您可以出于个人、学术或内部授权实验室的目的使用、研究和修改 Munin，但**严禁将 Munin 商业化、转售或作为商业服务提供**。

标签：AI安全智能体, FastMCP, GitHub, MCP协议, ReAct框架, 威胁情报, 实时处理, 密码管理, 开发者工具, 逆向工具