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.

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)

FileModeAction on driftSOUL.mdrestoreAuto-restore + alertAGENTS.mdrestoreAuto-restore + alertUSER.mdalertAlert onlyTOOLS.mdalertAlert onlyIDENTITY.mdalertAlert onlyHEARTBEAT.mdalertAlert onlyMEMORY.mdalertAlert onlymemory/*.mdignoreIgnored

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.