modbender 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
cd ~/.openclaw/workspace
python3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note "initial baseline"
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:
## 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
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
python3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md --actor user --note "intentional update"
View status
python3 skills/soul-guardian/scripts/soul_guardian.py status
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:
==================================================
🚨 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.
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:
bash skills/soul-guardian/scripts/demo.sh
This will:
- 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.