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:

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

---

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.