Back to Details

soul-guardian

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

soul-guardian 👻

Soul Guardian 👻

Protects your agent's core files (SOUL.md, AGENTS.md, etc.) from unauthorized changes with automatic detection, restoration, and user alerting.
保护你的Agent核心文件（SOUL.md、AGENTS.md等）免受未授权更改，具备自动检测、恢复以及用户告警功能。

Quick Start (3 Steps)

快速开始（3步）

Step 1: Initialize baselines

步骤1：初始化基线

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

Step 2: Enable monitoring

步骤2：启用监控

bash
python3 skills/soul-guardian/scripts/soul_guardian.py enable-monitoring
This shows you how to add monitoring to your workflow.
bash
python3 skills/soul-guardian/scripts/soul_guardian.py enable-monitoring
此步骤将展示如何将监控添加到你的工作流中。

Step 3: Add to HEARTBEAT.md (Recommended)

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

Add this to your HEARTBEAT.md for automatic monitoring:
markdown
undefined
将以下内容添加到HEARTBEAT.md以实现自动监控：
markdown
undefined

Soul Guardian Check

Soul Guardian 检查

  • 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

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

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

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

---

What it protects (default policy)

默认保护范围（默认策略）

FileModeAction on drift
SOUL.mdrestoreAuto-restore + alert
AGENTS.mdrestoreAuto-restore + alert
USER.mdalertAlert only
TOOLS.mdalertAlert only
IDENTITY.mdalertAlert only
HEARTBEAT.mdalertAlert only
MEMORY.mdalertAlert only
memory/*.mdignoreIgnored
文件模式漂移时操作
SOUL.md恢复自动恢复 + 告警
AGENTS.md恢复自动恢复 + 告警
USER.md告警仅告警
TOOLS.md告警仅告警
IDENTITY.md告警仅告警
HEARTBEAT.md告警仅告警
MEMORY.md告警仅告警
memory/*.md忽略忽略

Commands

命令说明

Check for drift (with alert output)

检查漂移（带告警输出）

bash
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
bash
python3 skills/soul-guardian/scripts/soul_guardian.py check --output-format alert
  • 无漂移时静默
  • 检测到漂移时输出人类可读的告警信息
  • 非常适合与心跳机制集成

Watch mode (continuous monitoring)

监控模式（持续监控）

bash
python3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30
Runs continuously, checking every 30 seconds.
bash
python3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30
持续运行，每30秒检查一次。

Approve intentional changes

批准有意更改

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 approve --file SOUL.md --actor user --note "intentional update"

View status

查看状态

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

Verify audit log integrity

验证审计日志完整性

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

Alert Format

告警格式

When drift is detected, the 
--output-format alert
produces output like:
==================================================
🚨 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>
==================================================
This output is designed to be relayed directly to the user in TUI/chat.
检测到漂移时，
--output-format alert
参数会生成如下格式的输出：
==================================================
🚨 SOUL GUARDIAN 安全告警
==================================================

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

==================================================
请查看更改并调查漂移来源。
若为有意更改，请运行: soul_guardian.py approve --file <路径>
==================================================
此输出设计为可直接在终端界面（TUI）或聊天窗口中转发给用户。

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.
功能说明：
  • 检测文件系统与已批准基线的漂移（基于sha256哈希）
  • 生成统一差异供审核
  • 通过哈希链维护防篡改审计日志
  • 拒绝处理符号链接
  • 恢复操作使用原子写入
局限性：
  • 无法证明谁进行了更改（actor为尽最大努力收集的元数据）
  • 若攻击者同时控制工作区和状态目录，则无法提供保护
  • 不能替代备份
建议： 将状态目录存储在工作区外部以提升抗攻击能力。

Demo

演示

Run the full demo flow to see soul-guardian in action:
bash
bash skills/soul-guardian/scripts/demo.sh
This will:
  1. Verify clean state (silent check)
  2. Inject malicious content into SOUL.md
  3. Run heartbeat check (produces alert)
  4. Show SOUL.md was restored
运行完整演示流程以查看Soul Guardian的实际效果：
bash
bash skills/soul-guardian/scripts/demo.sh
演示将：
  1. 验证干净状态（静默检查）
  2. 向SOUL.md注入恶意内容
  3. 运行心跳检查（生成告警）
  4. 展示SOUL.md已被恢复

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.
“未初始化”错误： 先运行
init
命令设置基线。
漂移反复出现： 检查是什么在修改你的文件。查看审计日志和差异文件。
想要批准某更改： 查看更改后运行
approve --file <路径>
命令。