Foreman

<p align="center"> <img src="docs/assets/foreman-social-preview.png" alt="Foreman 代理安全 - AI 编程代理的安全监督"> </p> <h1 align="center">Foreman 代理安全</h1> <p align="center"> 面向 AI 编程代理的 Windows 安全监控：监控风险命令、卡住的运行、MCP 更改，并使用一个 AI 审计另一个 AI。 </p> <p align="center"> <strong>构建以保持代理工作可见、可问责和可审查，在其消耗令牌、CPU 和电力之前。</strong> </p> <p align="center"> <a href="LICENSE"><img alt="许可证：GPL-3.0-or-later" src="https://img.shields.io/badge/许可证-GPL--3.0--or--later-blue.svg"></a> <a href="https://github.com/aXL333/Foreman/actions/workflows/ci.yml"><img alt="持续集成" src="https://github.com/aXL333/Foreman/actions/workflows/ci.yml/badge.svg"></a> <img alt="Windows 10/11" src="https://img.shields.io/badge/Windows-10%2F11-4A90D9"> <img alt="状态：alpha" src="https://img.shields.io/badge/状态-alpha-E8B23C"> </p> > **状态：** alpha. Foreman 代理安全目前针对 .NET 10 预览版 SDK，并在 Windows 10/11 x64 上运行。将它视为安全可见性工具，而不是沙盒或策略强制边界。 ## 为什么存在 Foreman 代理安全 AI 编程代理可以快速跨越 shell、文件、凭证、联网工具和 MCP 服务器。其中大部分工作是有用的。其中一些令人惊讶、昂贵、卡住或不安全。 Foreman 代理安全驻留在系统托盘中，并保持该工作可见。它引发可解释的警报，将子进程归因于启动它们的容器，并为您提供两条响应路径： - **询问容器：** 请求冒犯代理商为其行为辩护或纠正。 - **发送审计：** 将警报行为路由到不同的代理商或 API 以获取第二意见，使用 MCP 连接审阅容器时。 该安全循环也可以节省资金。尽早捕获失控的命令或废弃的代理商意味着更少的浪费令牌、更少的 CPU/GPU 占用和更低的能耗。 ## Foreman 代理安全的作用 - 监视代理商进程树、生成的 shell、挂起的子进程和孤立的进程。 - 标记风险命令模式：破坏性命令、凭证访问、特权提升、网络传播的代码执行和 Windows 防御逃避或持久性。 - 跟踪每个代理商的行为，并在风险累积时通过 **监视 -> 警报 -> 警告 -> 紧急** 逐步升级。 - 读取代理商 MCP 配置，并在出现新的或更改的 MCP 服务器时发出警报。 - 可选地扫描 HTTP/SSE MCP 工具描述中的提示注入或数据泄露措辞。此可选扫描是唯一连接到第三方 MCP 服务器的功能；stdio 服务器从不启动。 - 暴露一个本地 MCP 服务器，以便代理商可以检查 Foreman 代理安全状态、预检命令、检查最近的事件并获取集成说明。 - 保留可搜索/可导出的事件日志和仪表板，用于实时进程、容器和行为状态。 - 为租约、移交和 Git 冲突证据定义共享存储库容器解除冲突模型；参见 [docs/harness-deconfliction.md](docs/harness-deconfliction.md)。 - 为事件日志时间完整性保留追加顺序和单调时钟元数据；参见 [docs/temporal-truth.md](docs/temporal-truth.md)。 ## 截图 <p align="center"> <img src="docs/assets/tab-overview.png" width="92%" alt="概览指挥中心"> </p> <p align="center"><em>概览指挥中心 — 活动警报、正在运行的代理、MCP 客户端和一目了然的状态指示灯。</em></p> <p align="center"> <img src="docs/assets/tab-processes.png" width="44%" alt="彩色编码的进程资源管理器"> <img src="docs/assets/tab-harnesses.png" width="54%" alt="每个代理的容器监控"> </p> <p align="center"><em>彩色编码的进程资源管理器（孤立 = 红色 · 挂起 = 琥珀色 · 代理本身 = 蓝色）&nbsp;·&nbsp; 每个代理的监控，带有信任级别和唤醒锁定状态。</em></p> <p align="center"> <img src="docs/assets/tab-behavior.png" width="80%" alt="每个代理的行为和升级"> </p> <p align="center"><em>每个代理的行为和升级（监视 → 警报 → 警告 → 紧急）。</em></p> ## 代理支持 已在机器上测试： | ID | 代理 | 集成状态 | | --- | --- | --- | | `claude-code` | Claude Code | 一键式 MCP 设置、进程/配置文件检测 | | `codex` | Codex | 一键式 MCP 设置（CLI + 桌面；`bearer_token_env_var`）、进程/配置文件检测、Codex TOML MCP 清单 | | `cursor` | Cursor | 一键式 MCP 设置（~/.cursor/mcp.json）、已确认进程检测 | 已识别/配置，但需要更广泛的现场测试： | ID | 代理 | 备注 | | --- | --- | --- | | `opencode` | OpenCode | 一键式 MCP 设置（opencode.json）、配置文件 + 默认审计路由 | | `t3-code` | T3 Code | 控制平面配置文件 + 默认审计路由 — 参见下面的备注 | | `gemini-cli` | Gemini CLI | 一键式 MCP 设置（~/.gemini/settings.json — 注意 `httpUrl` 用于可流式 HTTP）、进程分类 | | `amazon-q` | Amazon Q Developer | 进程分类 | | `aider` | Aider | 进程分类 | | `github-copilot` | GitHub Copilot CLI | 一键式 MCP 设置（~/.copilot/mcp-config.json）、进程分类 | | `lm-studio` | LM Studio | 一键式 MCP 设置（~/.lmstudio/mcp.json）— **买家注意：** 标头身份验证支持未经验证，请在 LM Studio 的 MCP 面板中确认 | | `cline` | Cline / Continue / Roo | 进程分类 | > **T3 Code 是一个控制平面 — 没有要配置的“T3 auth”。** T3 Code 运行一个**底层**代理（Claude Code、Codex、OpenCode、…）；该底层代理拥有 MCP 连接和持有者令牌。因此，请将底层代理连接到 Foreman（其在“连接代理”中的独立卡），而不是直接连接到 T3 Code。Foreman 仍然监视 T3 Code 本身作为控制平面。T3 Code 的“自动连接”只是为您复制配置，以便您放入它驱动的任何代理中。 可以在“设置”中作为自定义容器可执行文件名添加其他内容。 ## 快速入门 ### 安装 二进制版本发布后会在 alpha 安装程序完成后从发布工作流中发布。在此之前，请从源代码构建： ```powershell dotnet build .\Foreman.slnx -c Release dotnet test .\Foreman.slnx -c Release dotnet run --project .\src\Foreman.App\Foreman.App.csproj ``` 先决条件： - Windows 10/11 x64 - .NET 10 SDK 预览版 要生成与发布工作流使用的相同独立安装程序有效负载： ```powershell dotnet publish .\src\Foreman.App\Foreman.App.csproj ` -c Release -r win-x64 --self-contained true ` -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true ` -o publish # 提升的 ETW 边车单独发布（单文件应用程序无法共享其运行时） # 进入 sidecar\ 子文件夹，应用程序从中启动： dotnet publish .\src\Foreman.EtwSidecar\Foreman.EtwSidecar.csproj ` -c Release -r win-x64 --self-contained true ` -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true ` -o publish\sidecar ``` ### 使用 Windows 启动 可选：在 **设置 → 常规** 中，勾选 **当您登录到 Windows 时启动 Foreman 代理安全**。这会在用户注册表（`HKCU`）中添加一个 Run 条目（无需管理员权限），以便在您的第一个代理会话之前启动托盘应用程序、监视和 MCP 服务器。Foreman 代理安全会自行修复该条目，如果您稍后移动安装。 ### 连接代理 Foreman 代理安全的 MCP 服务器在托盘应用程序运行时侦听 `http://localhost:54321/mcp`。`/mcp` 需要每个安装的持有者令牌。`/health` 对活动检查开放。 最简单的路径是在应用程序中： 1. 从托盘或仪表板打开 Foreman 代理安全。 2. 选择 **连接代理**。 3. 为 Claude Code 或 Codex 使用 **自动连接**。 4. 重启代理。 Foreman 代理安全仅写入其自己的用户范围 `foreman` MCP 条目，并在备份原始配置之前保存。对于 Codex，它还在 `~/.codex/AGENTS.md` 中添加/更新标记的 Foreman 代理安全部分，以便 Codex 知道如何接收和回答询问容器的提示。 手动 Claude Code 设置： ```bash claude mcp add --transport http foreman http://localhost:54321/mcp \ --header "Authorization: Bearer <粘贴-token-from-mcp.token>" \ --scope user ``` 手动 Codex 设置在 `~/.codex/config.toml` 中： ```toml [mcp_servers.foreman] url = "http://localhost:54321/mcp" http_headers = { Authorization = "Bearer <粘贴-token-from-mcp.token>" } enabled = true ``` 还将此标记部分添加到 `~/.codex/AGENTS.md`，然后重启 Codex： ```markdown <!-- foreman-mcp:begin --> ## Foreman 代理安全 MCP 监视器 当 `foreman` MCP 服务器可用时： - 将此代理标识为 `harnessId: "codex"`，当 Foreman 代理安全工具接受 harness id 时。 - 在启动新任务时，调用 `report_task_start(taskDescription, harnessId: "codex")`。 - 如果 `foreman_status` 或 `report_task_start` 报告 `pendingAskHarnessRequests`，请调用 `list_ask_harness_requests(harnessId: "codex")`。 - 对于地址为 Codex 的每个待处理请求（询问容器或排队审计提示），请使用 `reply_to_ask_harness_request(requestId, response, actionTaken, harnessId: "codex")` 作答。 - 将每个请求视为安全提示：解释发生了什么，是否是预期的，以及您采取或建议的任何纠正措施。 <!-- foreman-mcp:end --> ``` 令牌在首次运行时生成，并存储在 `%LocalAppData%\Foreman\mcp.token` 中，Windows 允许的情况下使用当前用户仅限 ACL。 ### 测试 MCP 循环（无需代理） `Foreman.TestHarness` 是一个小型控制台客户端，模拟一个容器并驱动询问容器的往返端到端，因此您可以在不附加真实代理的情况下练习循环。每个刻度它打印一个 **SITREP**（`foreman_status` + 此容器的行为指标）和 **ACK** 每个待处理的询问容器/审计请求。 它使用与应用程序生成令牌相同的方式连接真实的每个容器范围的令牌，因此它测试每个容器身份 + 调用者范围路径，而不仅仅是操作员令牌。 ```powershell dotnet run --project .\src\Foreman.TestHarness\Foreman.TestHarness.csproj -- --harness claude-code ``` 然后触发警报并单击 **询问容器**（或让自动响应触发） 在托盘中，然后观察容器响应。 有用的标志：`--harness <id>`（codex，cursor，opencode，…），`--once`（单次通过）， `--no-ack`（仅观察），`--interval <secs>`，`--token <tok>`（使用特定令牌）。`--help` 列出所有标志。 ## 隐私和信任边界 - Foreman 代理安全是本地的。没有托管服务、帐户系统或遥测。 - 进程命令行可以包含机密。Foreman 代理安全在本地显示和记录命令行，并在将警报提示复制到剪贴板之前屏蔽明显的机密。 - Foreman 代理安全不是沙盒。同一用户本地进程仍然可以执行您的用户帐户可以执行的任何操作。 - 可选的 ETW 网络边车仅在您启用 **为每个进程网络运行提升** 时才会以提升的权限运行。 - 可选的 **强化守护程序** 是唯一可以以提升的权限运行的另一个组件（LocalSystem 服务）。它是可选的，默认关闭，仅签名 Foreman 代理安全自己的完整性密封 — 它不沙盒或对代理强制执行策略。 - 可选的 MCP 工具描述扫描可以对已配置的第三方 MCP 服务器进行出站 HTTP/SSE 连接。它默认关闭。 ## 工作原理 Foreman 代理安全代码库分为以下主要部分： - **Foreman.App：** WPF 托盘应用程序、仪表板、设置、警报详细信息和连接界面。 - **Foreman.Monitor：** WMI 进程创建/终止监视器、进程树跟踪器、I/O 轮询、挂起/孤立检测、MCP 清单监视器。 - **Foreman.Core：** 平台无关模型、事件总线、启发式规则、设置、配置文件、升级逻辑。 - **Foreman.McpServer：** 本地 MCP 主机、工具注册表、持有者令牌身份验证、连接会话跟踪。 - **Foreman.Guardian（可选，默认关闭）：** 一个可选的 LocalSystem Windows 服务，持有 SYSTEM 范围的密钥，以签名 Foreman 代理安全自己的篡改证据事件日志/设置密封，这样同一个用户代理无法伪造它。启用/禁用“设置”→“强化守护程序”（一个 UAC 提示）；卸载 Foreman 提示删除它。这是 Foreman 的自我保护，而不是代理沙盒。 嵌入式 MCP 服务器公开了包括以下在内的工具： 工具在 snake_case 中注册（ModelContextProtocol SDK 从 C# 方法名称派生工具名称），因此请按原样调用它们： | 工具 | 目的 | | --- | --- | | `foreman_status` | 当前健康状态、活动警报、进程计数、正常运行时间、版本 | | `list_connected_mcp_clients` | 调试连接的客户端身份和采样支持 | | `list_monitored_processes` | Foreman 代理安全跟踪的代理和子进程 | | `query_process_detail` | 单个 PID 的详细信息 | | `report_suspicious_command` | 预检命令行 | | `list_recent_events` | 最近的事件日志条目 | | `list_ask_harness_requests` | 接收待处理的询问容器提示，包括排队的审计提示，用于一个容器 | | `reply_to_ask_harness_request` | 向待处理的询问容器或排队的审计提示发送回复 | | `request_harness_review` | 向另一个容器发送 Foreman 介导的邮件或移交包；操作调用可以设置审阅者上下文，容器调用被包装为归因的不受信任邮件 | | `acknowledge_alert` | 确认低/中警报；高/严重警报需要 UI | | `get_behavior_metrics` | 每个容器的升级状态 | | `reset_behavior_metrics` | 重置容器的升级指标以获得全新任务 | | `report_task_start` | 公告任务边界 | | `get_my_permissions` | 调用容器的已解析配置文件权限 | | `get_my_instructions` | 调用容器的自助服务规则（模式） | | `get_integration_instructions` | 容器特定的 MCP 设置说明 | | `validate_harness_integration` | 检查配置文件/进程/MCP 可见性 | | `list_audit_preferences` / `get_audit_route` | 跨容器审计路由 | | `list_mcp_servers` | 跨容器配置发现的 MCP 服务器 | | `list_mcp_tool_findings` | 缓存的 MCP 工具描述发现 | | `scan_repo_for_agent_config` | 检查存储库的代理配置供应链（`.claude`/`.gemini` 挂钩、`.cursor` 规则、`.vscode` `folderOpen` 任务、`.github/setup.js`、`CLAUDE.md`/`AGENTS.md`）以获取“规则文件后门”植入触发器类 — *在* 代理中打开它之前 | 参见 [docs/oversight-model.md](docs/oversight-model.md) 获取询问容器与发送审计模型和 MCP 供应链层的信息。 ## 配置 设置存储在 `%LocalAppData%\Foreman\settings.json` 并可从“设置”窗口编辑。 | 设置 | 默认值 | 目的 | | --- | --- | --- | | `McpPort` | `54321` | MCP 和健康服务器端口 | | `HangThresholdMinutes` | `30` | 子进程无 I/O 多久后被视为挂起 | | `HookJamThresholdMinutes` | `5` | 子进程无 I/O 多久后被视为卡住 | | `IoPollerIntervalSeconds` | `30` | I/O 采样间隔 | | `MonitorAllProcesses` | `false` | `false` 表示仅监控容器子进程 | | `CustomHarnessExes` | `[]` | 额外可视为容器的可执行文件名 | | `DisabledHarnesses` | `[]` | 检测但不提醒的容器 | | `RunElevated` | `false` | 为“网络”列启用提升的 ETW 边车 | | `ScanMcpTools` | `false` | 启用 MCP 工具描述注入扫描 | | `LlmTriage` | 已启用 | 跨容器审计路由的首选 | ## 发布信任 安装程序是每个用户安装的，不需要管理员提示。当发布工作流程为其配置时，`Foreman.exe`（及其 `Foreman.EtwSidecar.exe`）和安装程序都通过 **SignPath 基金会**（免费开放源码签名）进行 Authenticode 签名；签名是可选的，并由存储库变量控制，因此在配置完成之前，alpha 安装程序会附带 **未签名**，并且发布说明会说明这一点。无论哪种情况，发布都会附带 **SHA-256 校验和**。请注意，即使签名，新发布的构建仍可能在 Microsoft 的声誉系统赶上之前出现 SmartScreen“未知应用”提示 — 这是针对低容量工具的预期，因此校验和很重要。参见 [CODE_SIGNING.md](CODE_SIGNING.md) 了解签名的工作原理以及如何验证下载，参见 [docs/release-checklist.md](docs/release-checklist.md) 获取维护人员签名设置。 ## 路线图 - 尽快从 .NET 10 预览版迁移到稳定版 SDK。 - 为 LLM 三级分类偏好添加完整的设置界面。 - 在更多现场测试后为 OpenCode/T3 添加 MCP 配置适配器。 - 在托盘气泡通知中添加原生 Windows 通知。 - 继续优化来自真实代理工作流的误报。 - 浏览器扩展（alpha）：通过环回与其他 Foreman 代理安全配对以获取概览状态 — 通过 **连接代理 → 配对浏览器扩展** 连接。参见 [extension/README.md](extension/README.md) 和 [docs/closed-loop-spec.md](docs/closed-loop-spec.md)。 ## 贡献 根据项目许可，欢迎贡献。安全报告通过 [SECURITY.md](SECURITY.md) 而不是公共问题提交。 ## 许可 GPL-3.0-or-later。参见 [LICENSE](LICENSE)。在相同许可下接受贡献。 ## 支持 Foreman 代理安全是免费的 GPL。如果它帮助您保持代理工作更安全、节省令牌或减少电费，您想支持一下，可以访问：<https://ko-fi.com/aXL333>。