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 . 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 ================================================== 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 after reviewing the change.