soul-guardian 👻

---

name: soul-guardian

version: 0.0.2

description: Drift detection + baseline integrity guard for agent workspace files with automatic alerting support

homepage: https://clawsec.prompt.security

metadata: {"openclaw":{"emoji":"👻","category":"security"}}

clawdis:

emoji: "👻"

requires:

bins: [python3]

---

# 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:

---

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

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:**

**What it doesn't do:**

**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.