soul-guardian 👻
Protects your agent's core files (SOUL.md, AGENTS.md, etc.) from unauthorized changes with automatic detection, restoration, and user alerting.
Quick Start (3 Steps)
Step 1: Initialize baselines
CODEBLOCK0
Step 2: Enable monitoring
python3 skills/soul-guardian/scripts/soul_guardian.py enable-monitoring
This shows you how to add monitoring to your workflow.
Step 3: Add to HEARTBEAT.md (Recommended)
Add this to your HEARTBEAT.md for automatic monitoring:
CODEBLOCK2
That's it! Soul Guardian will now:
- - ✅ Detect unauthorized changes to protected files
- ✅ Auto-restore SOUL.md and AGENTS.md to approved baseline
- ✅ Alert you when drift is detected and handled
What it protects (default policy)
| File | Mode | Action on drift |
|---|
| SOUL.md | restore | Auto-restore + alert |
| AGENTS.md |
restore | Auto-restore + alert |
| USER.md | alert | Alert only |
| TOOLS.md | alert | Alert only |
| IDENTITY.md | alert | Alert only |
| HEARTBEAT.md | alert | Alert only |
| MEMORY.md | alert | Alert only |
| memory/*.md | ignore | Ignored |
Commands
Check for drift (with alert output)
python3 skills/soul-guardian/scripts/soul_guardian.py check --output-format alert
- - Silent if no drift
- Outputs human-readable alert if drift detected
- Perfect for heartbeat integration
Watch mode (continuous monitoring)
python3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30
Runs continuously, checking every 30 seconds.
Approve intentional changes
CODEBLOCK5
View status
CODEBLOCK6
Verify audit log integrity
python3 skills/soul-guardian/scripts/soul_guardian.py verify-audit
Alert Format
When drift is detected, the --output-format alert produces output like:
CODEBLOCK8
This output is designed to be relayed directly to the user in TUI/chat.
Security Model
What it does:
- - Detects filesystem drift vs approved baseline (sha256)
- Produces unified diffs for review
- Maintains tamper-evident audit log with hash chaining
- Refuses to operate on symlinks
- Uses atomic writes for restores
What it doesn't do:
- - Cannot prove WHO made a change (actor is best-effort metadata)
- Cannot protect if attacker controls both workspace AND state directory
- Is not a substitute for backups
Recommendation: Store state directory outside workspace for better resilience.
Demo
Run the full demo flow to see soul-guardian in action:
CODEBLOCK9
This will:
- 1. Verify clean state (silent check)
- Inject malicious content into SOUL.md
- Run heartbeat check (produces alert)
- Show SOUL.md was restored
Troubleshooting
"Not initialized" error:
Run init first to set up baselines.
Drift keeps happening:
Check what's modifying your files. Review the audit log and patches.
Want to approve a change:
Run approve --file <path> after reviewing the change.
soul-guardian 👻
通过自动检测、恢复和用户告警，保护您的智能体核心文件（SOUL.md、AGENTS.md 等）免受未经授权的更改。
快速入门（3 步）
第 1 步：初始化基线
bash
cd ~/.openclaw/workspace
python3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note initial baseline
第 2 步：启用监控
bash
python3 skills/soul-guardian/scripts/soul_guardian.py enable-monitoring
这将向您展示如何将监控添加到工作流程中。
第 3 步：添加到 HEARTBEAT.md（推荐）
将此内容添加到您的 HEARTBEAT.md 以实现自动监控：
markdown
Soul Guardian 检查
- - 运行 python3 skills/soul-guardian/scripts/soul_guardian.py check --actor heartbeat --output-format alert
- 如果产生任何输出，立即将其作为安全警报转发给用户
就是这样！Soul Guardian 现在将：
- - ✅ 检测受保护文件的未经授权更改
- ✅ 自动将 SOUL.md 和 AGENTS.md 恢复至已批准的基线
- ✅ 在检测到并处理漂移时向您发出警报
保护内容（默认策略）
| 文件 | 模式 | 漂移时操作 |
|---|
| SOUL.md | 恢复 | 自动恢复 + 告警 |
| AGENTS.md |
恢复 | 自动恢复 + 告警 |
| USER.md | 告警 | 仅告警 |
| TOOLS.md | 告警 | 仅告警 |
| IDENTITY.md | 告警 | 仅告警 |
| HEARTBEAT.md | 告警 | 仅告警 |
| MEMORY.md | 告警 | 仅告警 |
| memory/*.md | 忽略 | 忽略 |
命令
检查漂移（带告警输出）
bash
python3 skills/soul-guardian/scripts/soul_guardian.py check --output-format alert
- - 无漂移时静默
- 检测到漂移时输出人类可读的告警
- 非常适合心跳集成
监控模式（持续监控）
bash
python3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30
持续运行，每 30 秒检查一次。
批准有意更改
bash
python3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md --actor user --note intentional update
查看状态
bash
python3 skills/soul-guardian/scripts/soul_guardian.py status
验证审计日志完整性
bash
python3 skills/soul-guardian/scripts/soul_guardian.py verify-audit
告警格式
当检测到漂移时，--output-format alert 会产生如下输出：
==================================================
🚨 SOUL GUARDIAN 安全告警
==================================================
📄 文件：SOUL.md
模式：恢复
状态：✅ 已恢复至已批准基线
预期哈希：abc123def456...
发现哈希：789xyz000111...
差异保存至：/path/to/patches/drift.patch
==================================================
审查更改并调查漂移来源。
如果是有意更改，请运行：soul_guardian.py approve --file
==================================================
此输出设计为直接在 TUI/聊天中转发给用户。
安全模型
功能：
- - 检测文件系统与已批准基线之间的漂移（sha256）
- 生成统一差异以供审查
- 维护带有哈希链的防篡改审计日志
- 拒绝操作符号链接
- 使用原子写入进行恢复
不包含的功能：
- - 无法证明谁进行了更改（actor 是尽力而为的元数据）
- 如果攻击者同时控制工作区和状态目录，则无法保护
- 不能替代备份
建议： 将状态目录存储在工作区之外以获得更好的弹性。
演示
运行完整演示流程，查看 soul-guardian 的实际运行：
bash
bash skills/soul-guardian/scripts/demo.sh
这将：
- 1. 验证干净状态（静默检查）
- 向 SOUL.md 注入恶意内容
- 运行心跳检查（产生告警）
- 显示 SOUL.md 已被恢复
故障排除
未初始化错误：
先运行 init 来设置基线。
持续发生漂移：
检查是什么在修改您的文件。查看审计日志和补丁。
想要批准更改：
在审查更改后运行 approve --file 。
