danieljustus/symaira-guard

# Symaira Guard (`symguard`) **为 agent 自主性提供的人类控制。** [](https://github.com/danieljustus/symaira-guard/actions/workflows/ci.yml) [](https://go.dev/) [](https://github.com/danieljustus/symaira-guard/blob/main/LICENSE) ## 简介 `symguard` 位于 AI 客户端与其调用的工具之间。它会检查每一个 MCP 工具调用，对风险进行分类，执行本地策略，在需要时请求人工批准，并记录防篡改的审计轨迹。 ``` AI client / agent → symguard → MCP servers / CLIs / APIs / Symaira tools ``` agent 依然可以获取有用的工具。人类则保留可强制执行的边界。 ## 目的 MCP 解决了 AI 客户端与工具服务器之间的互操作性。但它没有解决： - 工具投毒及“诱骗”攻击（被篡改的工具描述） - 升级为工具调用的提示词注入 - 无限制的 shell / 文件系统 / 网络 / 密钥访问 - 高风险操作缺乏人工批准 - 通过工具输出窃取密钥 - 跨 agent 委托风险 `symguard` 就是缺失的本地控制层。 ## 当前状态（目前已实现） `symguard` 处于早期阶段。CLI 目前仅实现了： ``` $ symguard version symguard dev go go1.26 os/arch darwin/arm64 built 2026-01-01 (compile-time placeholder) $ symguard doctor symguard doctor ... binary ok go runtime ok config not configured (no config file found) policy not loaded audit log not initialized All basic checks passed. Run 'symguard scan' after setup for full diagnostics. ``` `doctor` 会打印一组固定的静态检查；它目前还不会读取真实的 配置文件或运行实时诊断。目前还没有 `scan`、`policy`、`proxy`、 `pin`、`audit` 或 `remote` 子命令——此点以下的所有内容均为 **设计意图，而非已发布的行为**。目前有两个内部包用于支持这一方向：`internal/config`（用于默认值/规则的 TOML schema， 尚未接入 CLI）和 `internal/discovery`（解析来自 Hermes/Claude Desktop/Cursor/VS Code/OpenCode 的 MCP 配置文件， 尚未通过任何命令暴露）。 ## 计划功能 ### 1. 扫描 发现跨本地 AI 客户端配置的 MCP 服务器，并按风险对其工具进行分类。 ``` symguard scan # scan all clients symguard scan --client hermes # scan one client symguard scan --format json # machine-readable output ``` ### 2. 策略 定义决定哪些内容可以通过的本地规则： ``` [defaults] shell = "ask" read_secret = "deny" write_file = "ask" [[rules]] match.server = "symmemory" match.tool = "memory_search" decision = "allow" [[rules]] match.command_contains = ["rm -rf", "curl | sh"] decision = "deny" ``` 决策选项：`allow`、`ask`、`deny`、`redact`、`readonly`、`sandbox`。其 TOML schema 已存在于 `internal/config` 中，但尚未有任何功能对其进行评估。 ### 3. 代理 作为针对每次工具调用执行策略的 MCP 代理运行： ``` symguard proxy --config ~/.config/symguard/config.toml ``` 每次工具调用都会经过分类、策略检查、（可选的）人工批准，然后才被转发至上游。敏感输出在到达 agent 之前可进行脱敏处理。 ### 4. 锁定 存储 MCP 工具描述和 schema 的哈希值。如果工具的描述发生改变（隐藏指令、范围扩大），`symguard` 会对其进行标记： ``` WARNING: Tool schema changed for server "filesystem" tool "read_file". Policy: require re-approval ``` ### 5. 审计 带有哈希链的只追加本地审计日志。记录请求的内容、匹配的策略、批准者、执行的内容以及返回的结果。 单靠哈希链只能防止**修改**已保留的条目—— 它无法阻止**截断**日志（直接删除最近的条目；对剩余内容进行的链式检查依然会通过，因为没有任何东西锚定应存在的条目数量）。`internal/audit`（尚未创建） 在编写第一行代码之前，必须决定它要提供两种保证中的哪一种： - **修改检测** —— 哈希链，始终在作用域内。 - **截断检测** —— 需要一种额外的机制：在可用的情况下进行操作系统级的 只追加强制执行（Linux 上的 `chattr +a`，`O_APPEND`-only 文件描述符），和/或定期签名并外部存储链头的检查点（例如镜像到 `symmemory`），以便针对上一次检查点，依然可以检测到被截断的本地日志。 在 `internal/audit` 提供其中之一前，上文的“防篡改”仅意味着 防修改——一旦实现了截断保证（或决定暂不提供），此文件将随之更新。 ### 6. 远程访问 后续阶段将添加基于现有传输方式（SSH、Tailscale、LAN/mDNS）的 agent 感知远程 MCP 访问——这不是一个新的 VPN，而是在你已信任的工具之上叠加策略和审计。 上述 2–6 节目前均未实现——本代码库中目前尚不存在任何策略引擎、代理、 锁定、审计日志或远程访问代码。 ## 风险等级 | 风险 | 示例 | 默认值 | |------|----------|---------| | `read_public` | 文档、README、公共网络 | allow | | `read_private` | 代码库文件、笔记、本地文档 | allow 或 ask | | `read_secret` | `.env`、SSH 密钥、vault 条目 | ask / deny | | `write_file` | patch、覆盖、创建文件 | ask | | `shell` | 命令执行 | ask | | `network` | 出站 API / Web 请求 | ask | | `browser` | cookies、会话、Web 自动化 | ask | | `credential_use` | 使用密钥但不泄露 | ask once / scoped | | `deploy` | release、push、基础设施变更 | ask every time | | `destructive` | delete、wipe、reset、revoke | ask / deny | 上表仅通过**名称**对工具进行分类——这是必要的第一步， 但本身并不充分。`scan` 的风险分类器还会将工具的风险*向下*限制（绝不向上），前提是该工具在同一会话中已被解析为 `allow` 的另一个工具之外，提供的**零边际能力**。 示例：`read_file` 工具在上表中归类为 `read_private`，但如果同一客户端已经拥有一个被解析为 `allow` 的不受限制的 `shell` 工具，那么 `read_file` 提供的能力就不存在 `shell` 尚未提供的——cat 是 shell 的严格子集—— 因此 `scan` 将其降级为 `allow` 并说明原因 （`no marginal capability over already-allowed tool: shell`）。如果 `shell` 本身是 `ask` 或 `deny`，则 `read_file` 保持其 `read_private` 分类 不变。 ## Symaira 生态系统定位 `symguard` 是一个**公开的、自托管的核心**工具。没有 Pro、租户或计费代码。 ``` ┌─────────────────────────────────────────┐ │ AI clients / agents │ │ Hermes · Claude · Cursor · OpenCode ... │ └───────────────────┬─────────────────────┘ ▼ ┌──────────────┐ │ symguard │ ← trust boundary └──────┬───────┘ ▼ symvault · symmemory · symscope · symseek · ... ``` 可选的运行时集成，对兄弟项目没有编译时依赖。 ## 原则 - **本地优先。** 策略决策在你的机器上进行。无需强制的云账号。 - **平庸即是好。** 没有定制的 VPN，没有 NAT 穿透，没有 WireGuard daemon。重用现有的传输方式。 - **发现 ≠ 信任。** 发现远程 MCP 服务器绝不自动意味着获得权限。 - **agent 身份。** Agent 和运行是具有 TTL 和限定授权的一等身份。 - **可解释性。** 每一个决策都有原因。行动前先模拟。失败后进行诊断。 ## 非目标 不是聊天前端，不是 SIEM，不是纯云 SaaS，不是 VPN 替代品，也不是完整的端点保护平台。 ## 构建 需要 Go 1.26+。无外部依赖——仅使用 Go 标准库。 ``` # 构建二进制文件 make build # 运行测试 make test # Lint (golangci-lint 或 go vet 备选) make lint # 在构建时设置版本字符串 make build VERSION=v1.0.0 ``` 或者直接使用 `go`： ``` go build -ldflags "-X main.version=dev" -o symguard ./cmd/symguard go vet ./... go test ./... ``` ### 快速开始 ``` ./symguard version # print version and build info ./symguard doctor # check system health ``` ## 状态 处于非常早期的开发阶段。已实现：`version` 和 `doctor` CLI 命令， 以及两个尚未接入任何命令的内部库包（`config` schema，MCP 客户端 `discovery`）。 本 README 中的其他所有内容（扫描、策略引擎、代理、锁定、审计、远程访问）均仅为设计意图。 完整设计文档请参阅 [docs/intern/IDEA.md](docs/intern/IDEA.md)。

标签：AI代理, EVTX分析, Go语言, MCP网关, Python安全, Streamlit, 人工智能, 安全网关, 文档结构分析, 日志审计, 用户模式Hook绕过, 程序破解, 访问控制