名称： soul-guardian
版本： 0.0.2
描述： 针对智能体工作区文件的漂移检测与基线完整性防护，支持自动告警
主页： https://clawsec.prompt.security
元数据： {"openclaw":{"emoji":"👻","category":"security"}}
clawdis:
emoji: "👻"
requires:
bins: [python3]

soul-guardian 👻

保护智能体核心文件（SOUL.md、AGENTS.md 等）免受未授权更改，具备自动检测、恢复及用户告警功能。

快速开始（三步）

步骤 1：初始化基线

cd ~/.openclaw/workspace
python3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note "初始基线"

步骤 2：启用监控

python3 skills/soul-guardian/scripts/soul_guardian.py enable-monitoring

此命令将展示如何将监控集成到您的工作流中。

步骤 3：添加到 HEARTBEAT.md（推荐）

将以下内容添加到您的 HEARTBEAT.md 文件中，以实现自动监控：

## Soul Guardian 检查
- 运行 `python3 skills/soul-guardian/scripts/soul_guardian.py check --actor heartbeat --output-format alert`
- 若产生任何输出，请立即将其作为安全告警转发给用户

完成！Soul Guardian 现在将：
- ✅ 检测受保护文件的未授权更改
- ✅ 自动将 SOUL.md 和 AGENTS.md 恢复到已批准的基线版本
- ✅ 在检测到漂移并处理后向您告警

保护范围（默认策略）

命令

检查漂移（带告警输出）

python3 skills/soul-guardian/scripts/soul_guardian.py check --output-format alert

• 无漂移时静默
• 检测到漂移时输出人类可读的告警
• 非常适合与心跳机制集成

监视模式（持续监控）

python3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30

持续运行，每 30 秒检查一次。

批准有意的更改

python3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md --actor user --note "有意更新"

查看状态

python3 skills/soul-guardian/scripts/soul_guardian.py status

验证审计日志完整性

python3 skills/soul-guardian/scripts/soul_guardian.py verify-audit

告警格式

当检测到漂移时，--output-format alert 会产生类似以下格式的输出：

==================================================
🚨 SOUL GUARDIAN 安全告警
==================================================

📄 文件: SOUL.md
   模式: restore
   状态: ✅ 已恢复到已批准的基线
   预期哈希: abc123def456...
   发现哈希: 789xyz000111...
   差异已保存至: /path/to/patches/drift.patch

==================================================
请审查更改并调查漂移来源。
若为有意更改，请运行: soul_guardian.py approve --file <路径>
==================================================

此输出设计为可直接在 TUI/聊天界面中转发给用户。

安全模型

功能：
- 检测文件系统与已批准基线（sha256）的漂移
- 生成统一的差异以供审查
- 维护防篡改的审计日志（带哈希链）
- 拒绝操作符号链接
- 使用原子写入进行恢复

局限性：
- 无法证明谁做出了更改（操作者元数据仅为尽力而为）
- 若攻击者同时控制工作区和状态目录，则无法提供保护
- 不能替代备份

建议： 将状态目录存储在工作区之外，以提高恢复能力。

演示

运行完整的演示流程，查看 soul-guardian 的实际效果：

bash skills/soul-guardian/scripts/demo.sh

演示将：
1. 验证初始状态（静默检查）
2. 向 SOUL.md 注入恶意内容
3. 运行心跳检查（产生告警）
4. 显示 SOUL.md 已被恢复

故障排除

“未初始化”错误：
请先运行 init 命令以建立基线。

漂移持续发生：
检查是什么在修改您的文件。请审查审计日志和补丁文件。

希望批准某个更改：
在审查更改后，运行 approve --file <路径>。