soul-guardian 👻

通过自动检测、恢复和用户警报，保护您智能体的核心文件（如SOUL.md、AGENTS.md等）免受未经授权的更改。。快速入门（三步）

步骤 1：初始化基线

步骤 2：启用监控

cd ~/.openclaw/workspace
python3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note "initial baseline"

此步骤向您展示如何向工作流添加监控。

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

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

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

完成！Soul Guardian 现在将：

## Soul Guardian Check
- Run `python3 skills/soul-guardian/scripts/soul_guardian.py check --actor heartbeat --output-format alert`
- If any output is produced, relay it to the user immediately as a security alert

✅ 检测受保护文件的未经授权更改

• ✅ 自动将 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 "intentional update"

查看状态

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

验证审计日志完整性

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

告警格式

当检测到偏差时，--output-format alert会产生类似如下的输出：

==================================================
🚨 SOUL GUARDIAN SECURITY ALERT
==================================================

📄 FILE: SOUL.md
   Mode: restore
   Status: ✅ RESTORED to approved baseline
   Expected hash: abc123def456...
   Found hash:    789xyz000111...
   Diff saved: /path/to/patches/drift.patch

==================================================
Review changes and investigate the source of drift.
If intentional, run: soul_guardian.py approve --file <path>
==================================================

此输出设计为直接通过TUI/聊天中继给用户。

安全模型

它能做什么：

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

它不能做什么：

• 无法证明**谁**做出了变更（操作者信息仅为尽力而为的元数据）
• 如果攻击者同时控制了工作区**和**状态目录，则无法提供保护
• 不能替代备份

建议：将状态目录存储在workspace之外以增强恢复能力。

演示

运行完整演示流程以查看soul-guardian的实际运作：

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

这将：

1. 验证清洁状态（静默检查）
2. 向SOUL.md注入恶意内容
3. 运行心跳检查（产生警报）
4. 显示SOUL.md已恢复

故障排除

“未初始化”错误：运行init首先以设置基线。

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

想要批准一个更改：运行approve --file <路径>在审查更改之后。