Skill: soul-guardian

Owner: davida-ps

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

Tags: latest:0.0.2

Version history:

v0.0.2 | 2026-02-06T17:33:12.748Z | user

Release 0.0.2 via CI

Archive index:

Archive v0.0.2: 8 files, 21147 bytes

Files: README.md (8133b), scripts/install_launchd_plist.py (6114b), scripts/onboard_state_dir.py (5520b), scripts/soul_guardian.py (35205b), scripts/test_soul_guardian.py (4030b), skill.json (1422b), SKILL.md (4422b), _meta.json (132b)

File v0.0.2:SKILL.md

---

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:

• ✅ 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.

File v0.0.2:README.md

soul-guardian

A small, dependency-free integrity guard for Clawdbot agent workspaces.

It helps you detect (and optionally auto-undo) unexpected edits to the workspace markdown files that an agent auto-loads (e.g., SOUL.md, AGENTS.md). It also records a tamper-evident audit trail of changes.

Why this exists

In many Clawdbot setups, the agent reads certain markdown files every session (identity, instructions, memory, tools, etc.). If those files drift unexpectedly (accidental edits, bad merges, unwanted automation, etc.), you want:

• detection (sha256 mismatch)
• a diff/patch artifact for review
• a record of what happened (audit log)
• optionally: an automatic restore to a known-good baseline for critical files

What it protects (default policy)

Default policy.json protects:

• Auto-restore + alert: SOUL.md, AGENTS.md
• Alert-only: USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md
• Ignored by default: memory/*.md (daily notes)

You can customize this by editing the policy file in the guardian state directory.

Security model (and limitations)

What it does well:

• Detects filesystem drift vs an approved baseline.
• Produces unified diffs (patch files) for review.
• Maintains an append-only JSONL audit log with hash chaining so log tampering is detectable.
• Refuses to operate on symlinks (reduces link attacks).
• Uses atomic writes for restores and baseline updates (os.replace).

What it does not do:

• It cannot prove who changed a file. --actor is best-effort metadata.
• It cannot protect you if an attacker can modify both the workspace and the guardian state directory.
• It is not a substitute for backups.

Recommendation (not enforced):

• Mirror/back up your guardian state directory (and/or workspace) using git and/or offsite backups.

State directory

By default, state is stored inside the workspace:

• memory/soul-guardian/
  • policy.json (what to monitor)
  • baselines.json (approved sha256 per file)
  • approved/<path> (approved snapshots)
  • audit.jsonl (append-only log with hash chain)
  • patches/*.patch (unified diffs)
  • quarantine/* (copies of drifted files before restore)

For better resilience, you can move this outside the workspace (recommended).

Install / usage

From the agent workspace root.

First run / Initialize baselines (recommended)

For resilience, create your guardian state directory outside the workspace first, then initialize baselines.

1. Onboard an external state dir (creates policy, copies any existing state, prints paths/snippets):

python3 skills/soul-guardian/scripts/onboard_state_dir.py --agent-id <agentId>

1. Initialize baselines in that external state dir:

python3 skills/soul-guardian/scripts/soul_guardian.py \
  --state-dir ~/.clawdbot/soul-guardian/<agentId> \
  init --actor sam --note "first baseline"

1. Run a check once (should be silent on OK; prints a single-line summary on drift):

python3 skills/soul-guardian/scripts/soul_guardian.py \
  --state-dir ~/.clawdbot/soul-guardian/<agentId> \
  check --actor system --note "first check"

Common commands

Status (summary):

python3 skills/soul-guardian/scripts/soul_guardian.py \
  --state-dir ~/.clawdbot/soul-guardian/<agentId> \
  status

Check for drift (default: restores restore-mode files):

python3 skills/soul-guardian/scripts/soul_guardian.py \
  --state-dir ~/.clawdbot/soul-guardian/<agentId> \
  check --actor system --note cron

Alert-only check (never restore):

python3 skills/soul-guardian/scripts/soul_guardian.py \
  --state-dir ~/.clawdbot/soul-guardian/<agentId> \
  check --no-restore

Approve intentional edits (one file):

python3 skills/soul-guardian/scripts/soul_guardian.py \
  --state-dir ~/.clawdbot/soul-guardian/<agentId> \
  approve --file SOUL.md --actor sam --note "intentional update"

Approve all policy targets (except ignored ones):

python3 skills/soul-guardian/scripts/soul_guardian.py \
  --state-dir ~/.clawdbot/soul-guardian/<agentId> \
  approve --all --actor sam --note "bulk approve"

Restore (only restore-mode files):

python3 skills/soul-guardian/scripts/soul_guardian.py \
  --state-dir ~/.clawdbot/soul-guardian/<agentId> \
  restore --file SOUL.md --actor system --note "manual restore"

Verify audit log tamper-evidence:

python3 skills/soul-guardian/scripts/soul_guardian.py \
  --state-dir ~/.clawdbot/soul-guardian/<agentId> \
  verify-audit

Policy format (policy.json)

Example:

{
  "version": 1,
  "workspaceRoot": "/path/to/workspace",
  "targets": [
    {"path": "SOUL.md", "mode": "restore"},
    {"path": "AGENTS.md", "mode": "restore"},
    {"path": "USER.md", "mode": "alert"},
    {"pattern": "memory/*.md", "mode": "ignore"}
  ]
}

• mode:
  • restore: drift triggers audit + patch + (by default) restore + quarantine copy
  • alert: drift triggers audit + patch, but does not restore
  • ignore: excluded

Onboarding: move state outside the workspace

Run the helper:

python3 skills/soul-guardian/scripts/onboard_state_dir.py

It will:

• create an external state dir (recommended default: ~/.clawdbot/soul-guardian/<agentId>/)
• copy (or move with --move) existing state from memory/soul-guardian/
• write a default policy.json if missing
• print scheduling snippets

Notes:

• <agentId> should be stable and unique per workspace (don’t point multiple workspaces at the same state dir).
• WARNING: --move deletes the old in-workspace state dir after copying.
• The external state dir can contain approved snapshots, patches, and quarantined copies of sensitive prompt/instruction/memory files. Keep permissions restrictive (e.g., chmod 700 <dir>; chmod go-rwx <dir>).

Then include --state-dir in all commands (run from the workspace root), e.g.:

cd <workspace> && python3 skills/soul-guardian/scripts/soul_guardian.py --state-dir ~/.clawdbot/soul-guardian/<agentId> check

Scheduling (cron)

A) Clawdbot Gateway Cron (recommended)

This is the default pattern when you want drift notifications to flow through Clawdbot.

Note: even when there is no drift, Clawdbot cron runs typically show an OK summary in the main session.

Example (edit paths + schedule):

clawdbot cron add \
  --name "soul-guardian: check workspace" \
  --description "Run soul-guardian check; alert when drift detected." \
  --session isolated \
  --wake now \
  --cron "*/10 * * * *" \
  --tz UTC \
  --message "Run:\ncd '<workspace>'\npython3 skills/soul-guardian/scripts/soul_guardian.py --state-dir ~/.clawdbot/soul-guardian/<agentId> check --actor cron --note 'gateway-cron'\n\nIf the command prints a line starting with 'SOUL_GUARDIAN_DRIFT', treat it as an alert. If it prints nothing, reply HEARTBEAT_OK." \
  --post-prefix "[soul-guardian]" \
  --post-mode summary

B) macOS launchd (optional, silent-on-OK)

If you want system scheduling without Clawdbot posting OK summaries, use launchd.

Because soul_guardian.py check prints nothing on OK and prints a single-line SOUL_GUARDIAN_DRIFT ... summary on drift, this tends to be silent unless something changed.

Generate + (optionally) install a LaunchAgent plist (run from the workspace root, or pass --workspace-root):

python3 skills/soul-guardian/scripts/install_launchd_plist.py \
  --state-dir ~/.clawdbot/soul-guardian/<agentId> \
  --interval-seconds 600 \
  --install

The generated plist includes WorkingDirectory set to your workspace root (recommended), so relative paths behave as expected.

The script writes drift output to log files under <state-dir>/logs/. You can tail them with the commands it prints.

Development / tests

A minimal test script is included:

python3 skills/soul-guardian/scripts/test_soul_guardian.py

It simulates a workspace in a temp directory and validates drift detection, approve/restore flow, and audit hash chain verification.

File v0.0.2:_meta.json

{ "ownerId": "kn76m78f01hqrtpgm895s0jsax80jd8v", "slug": "soul-guardian", "version": "0.0.2", "publishedAt": 1770399192748 }

File v0.0.2:skill.json

{ "name": "soul-guardian", "version": "0.0.2", "description": "Drift detection and baseline integrity guard for agent workspace prompt files. Auto-restore critical files with tamper-evident audit logging.", "author": "prompt-security", "license": "MIT", "homepage": "https://clawsec.prompt.security", "keywords": [ "security", "integrity", "drift-detection", "agents", "ai", "protection", "audit", "baseline" ], "sbom": { "files": [ { "path": "SKILL.md", "required": true, "description": "Soul guardian skill documentation" }, { "path": "scripts/soul_guardian.py", "required": true, "description": "Main guardian script" }, { "path": "scripts/onboard_state_dir.py", "required": true, "description": "State directory setup" }, { "path": "scripts/install_launchd_plist.py", "required": false, "description": "macOS launchd installer" } ] }, "openclaw": { "emoji": "👻", "category": "security", "requires": { "bins": [ "python3" ] }, "triggers": [ "soul guardian", "integrity check", "drift detection", "baseline check", "file integrity", "protect soul", "guard files", "workspace security", "tamper detection" ] } }