soul-guardian

Soul Guardian 是一款专为 AI Agent 工作区设计的文件完整性监控工具，通过建立 SHA256 哈希基线，实时监控 SOUL.md、AGENTS.md 等核心配置文件的未经授权变更，并提供自动恢复与用户警报功能。该工具由 Prompt Security 团队开源维护，采用纯 Python 标准库构建，确保零外部依赖的同时实现了企业级的安全防护能力。

使用上，用户仅需三步即可完成部署：首先运行 init 命令建立初始基线，随后启用监控模式，最后将检测命令集成至 HEARTBEAT.md 实现自动化巡检。工具支持多种运行模式，包括单次检查（check）、持续监控（watch）以及变更审批（approve），并能生成人类可读的警报信息直接推送至用户界面。其默认策略对 SOUL.md 等关键文件执行自动恢复，而对 USER.md 等配置文件仅发出警报，兼顾安全性与灵活性。

该技能的显著优势在于其卓越的安全架构设计。首先，完全基于 Python 标准库实现，消除了第三方依赖带来的供应链攻击风险。其次，采用原子写入（os.replace）操作并明确拒绝符号链接处理，有效防范了 TOCTOU 竞态条件攻击和目录遍历漏洞。此外，工具维护着具备哈希链（hash chaining）技术的防篡改审计日志，所有文件变更记录均包含 SHA256 校验，确保历史操作可追溯且不可抵赖。隔离区（quarantine）机制在恢复前保存漂移文件副本，便于事后取证分析。

然而，Soul Guardian 也存在一定局限性。作为 T3 级社区来源项目，其代码虽经过安全审计但仍建议生产环境使用前进行人工审查。功能层面，工具无法严格证明变更执行者的真实身份（actor 字段依赖尽力而为的元数据记录），且当攻击者同时控制工作区和状态目录时防护将失效。此外，工具并非备份解决方案的替代品，无法恢复已删除的文件。

该技能特别适合 AI Agent 开发者、MCP 平台运维人员以及对配置文件完整性有严格安全要求的场景。对于运行关键业务 Agent 的生产环境、需要遵守合规审计要求的多用户协作场景，或是担心提示词注入攻击导致配置文件篡改的安全敏感型用户，Soul Guardian 提供了轻量级 yet 高效的防护层。

使用过程中需注意以下风险：建议将状态目录部署在工作区外部以提升弹性，使用 chmod 700 严格限制目录权限，并定期备份包含基线快照和审计日志的状态数据。监控模式持续运行会占用少量系统资源，且频繁的基线更新可能导致审计日志膨胀，需定期归档清理。