soul-guardian

核心用法

Soul Guardian 是一款专为 AI Agent 工作空间设计的文件完整性保护工具，通过三重机制保障核心配置文件安全：

1. 基线管理
运行 init 命令为 SOUL.md、AGENTS.md 等关键文件建立 SHA-256 哈希基线，所有后续变更均以此为准进行比对。

2. 漂移检测与响应

• check 模式：单次扫描，静默无输出表示安全，发现漂移则生成结构化告警
• watch 模式：持续监控（默认30秒间隔），适合长期运行的 Agent 环境
• 双级策略：SOUL.md/AGENTS.md 自动恢复至基线；其余文件仅告警不恢复

3. 审计与合规
采用哈希链式审计日志，支持 verify-audit 验证日志完整性，所有操作记录 actor、时间戳与变更备注，满足可追溯要求。

---

显著优点

| 维度 | 表现 |

|------|------|

| **安全架构** | 原子写入防数据损坏、拒绝符号链接防劫持、防篡改审计日志 |

| **零依赖** | 纯 Python 标准库，无供应链攻击面，部署极简 |

| **Agent 原生** | 专为 AGENT.md/SOUL.md 等 AI 工作区设计，语义贴合 |

| **告警友好** | `--output-format alert` 输出可直接嵌入 TUI/聊天界面 |

| **心跳集成** | 推荐写入 HEARTBEAT.md，实现自动化安全监控 |

---

潜在局限

• 身份归因弱：actor 字段为手动标注，无法技术层面证明变更主体
• 状态目录风险：若攻击者同时控制工作区与状态目录，基线可被同步篡改
• 非备份替代：仅恢复至最近一次批准的基线，不支持历史版本回滚
• macOS 依赖：自动调度需 launchctl，跨平台脚本需自行适配

---

适合人群

• 运行长期自主 Agent 的开发者（AutoGPT、OpenClaw 等框架用户）
• 对提示词注入、配置漂移有安全顾虑的 AI 应用团队
• 需要合规审计追踪的企业级 Agent 部署场景

---

常规风险

| 风险场景 | 缓释建议 |

|----------|----------|

| 误自动恢复覆盖合法变更 | 开发阶段改用 `alert` 模式，生产环境配合代码评审流程 |

| 状态目录与workspace同盘 | 使用 `--state-dir` 指定外部路径，物理隔离 |

| 心跳监控遗漏告警 | 确保 HEARTBEAT.md 解析逻辑正确识别非空输出 |

| 长期运行日志膨胀 | 定期归档或配置日志轮转策略 |

核心用法

soul-guardian 是一款轻量级文件完整性漂移检测与基线守护工具。它通过为 Agent 的核心配置文件（如 SOUL.md、AGENTS.md）建立 SHA-256 哈希基线，持续检查文件是否被意外或恶意篡改。一旦检测到漂移，它不仅能生成详细的差异对比，还能根据策略自动隔离被篡改文件并将其原子化恢复至批准的基线版本，确保 Agent 工作区的一致性。

显著优点

• 绝对零依赖与零网络：纯 Python 3 标准库实现，不引入任何第三方包，杜绝供应链风险；100% 本地运行，无任何网络外联，彻底消除数据外泄隐患。
• 安全架构扎实：全面实施原子写入、符号链接防护与哈希链审计日志，保证恢复操作的安全性与审计记录的不可抵赖性。
• 高度透明且可控：所有功能均为显式 opt-in，restore 模式覆盖文件时会自动生成隔离副本以供回溯；并通过清晰的 Heartbeat 集成机制，在检测到问题时立即生成结构化告警。

潜在缺点或局限性

• 依赖外部状态目录的安全性：若攻击者同时控制了工作区和用于存储基线的状态目录，则保护机制可能失效。官方建议将状态目录外置以增强韧性。
• 仅专注文件层防护：该工具只能验证文件哈希是否与基线一致，无法识别进程注入、内存篡改等更高级的攻击形式，也不能替代完整的端点安全系统。
• 环境依赖：在非 Python 3 环境不可用，且其计划任务功能目前仅辅助性支持 macOS 的 launchd 机制。

适合的目标群体

• 基于文件驱动的 AI Agent 开发者：特别是使用 SOUL.md/AGENTS.md 等规范文件定义 Agent 行为与记忆的重度用户。
• 企业级 AI 安全运维人员：需要为生产环境下的多模态 Agent 提供低成本、高可靠的自动漂移监控与一键恢复能力。
• 追求本地隐私的极客用户：重视数据处理透明度，不容忍任何网络外联行为的零信任实践者。

使用该技能可能存在的常规风险

• 启用 restore 模式可能覆盖用户最近有意修改的文件，故在执行审批前务必检查统一差异文件。
• 作为重度文件 I/O 工具，虽然在绝大多数现代硬件上性能表现良好，但在需监控海量文件的极端场景下，频繁的哈希计算可能带来 I/O 瓶颈。
• 审计日志依赖于本地文件系统的持久性，不应将其视为独立的可信证据链，建议与外部备份系统结合使用。