soul-guardian

Original：🇺🇸 English
Translated
4 scriptsChecked / no sensitive code detected

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

7installs
Sourceprompt-security/clawsec
Added on

NPX Install

npx skill4agent add prompt-security/clawsec soul-guardian

Tags

Translated version includes tags in frontmatter
agent-workspace-securitydrift-detectionbaseline-integrityautomatic-alertingsoul-guardian

SKILL.md Content

View Translation Comparison →

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

bash
cd ~/.openclaw/workspace
python3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note "initial baseline"

Step 2: Enable monitoring

bash
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:
markdown
## 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 drift
SOUL.mdrestoreAuto-restore + alert
AGENTS.mdrestoreAuto-restore + alert
USER.mdalertAlert only
TOOLS.mdalertAlert only
IDENTITY.mdalertAlert only
HEARTBEAT.mdalertAlert only
MEMORY.mdalertAlert only
memory/*.mdignoreIgnored

Commands

Check for drift (with alert output)

bash
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)

bash
python3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30
Runs continuously, checking every 30 seconds.

Approve intentional changes

bash
python3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md --actor user --note "intentional update"

View status

bash
python3 skills/soul-guardian/scripts/soul_guardian.py status

Verify audit log integrity

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