← Back to Skills Marketplace
282
Downloads
0
Stars
2
Active Installs
1
Versions
Install in OpenClaw
/install eason-soul-guardian
Description
Drift detection + baseline integrity guard for agent workspace files with automatic alerting support
README (SKILL.md)
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 \x3Cpath>
==================================================
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 \x3Cpath> after reviewing the change.
Usage Guidance
This skill appears to do what it claims: local integrity checks, diffs, quarantine, and a tamper-evident audit log. Before installing or enabling scheduled runs: 1) Review and secure the state directory (it will contain approved snapshots and quarantined copies of prompt/instruction files — treat it as sensitive and set restrictive permissions or store offsite). 2) Be cautious when running install/--install or launchctl steps: those will create persistent scheduled jobs on your machine. 3) Note the small packaging oddities (version mismatch in metadata and a referenced demo.sh that is missing) — you may want to verify the source or request the missing demo before trusting the package. 4) Run the included tests in an isolated temp workspace to validate behavior if you want additional assurance. Overall, the code is local-only (no network exfiltration observed) and consistent with its stated purpose.
Capability Analysis
Type: OpenClaw Skill
Name: eason-soul-guardian
Version: 1.0.0
The 'soul-guardian' skill is a security utility designed to monitor workspace file integrity using SHA256 baselines and a tamper-evident, hash-chained audit log. It includes capabilities for auto-restoring critical instruction files (SOUL.md, AGENTS.md) and provides a macOS launchd installer (scripts/install_launchd_plist.py) to establish persistent background monitoring. While the code is well-documented, follows security best practices (e.g., atomic writes, symlink refusal, and quarantine of drifted files), and lacks evidence of malicious intent, its core functions of system persistence and modification of the agent's primary instruction files constitute high-risk behaviors that warrant a suspicious classification under the provided guidelines.
Capability Assessment
Purpose & Capability
The skill's name and description match the included scripts: it implements local drift detection, baselines, patch creation, and an audit log. It only needs python3 and no external credentials. Minor inconsistencies: multiple metadata/version strings differ (registry metadata lists v1.0.0 while skill files indicate v0.0.2), and SKILL.md references a demo.sh that is not present in the file manifest — these are likely packaging/metadata issues rather than functional mismatches.
Instruction Scope
SKILL.md and scripts restrict actions to workspace files and an optional external state directory; runtime instructions show only local file reads/writes, audit log updates, diffs, and optional scheduling. The instructions do not ask the agent to read unrelated system secrets or call external endpoints.
Install Mechanism
This is instruction-only (no external download/install). All included code is local Python with no network fetches. The included helper can generate and (optionally) install a macOS launchd plist; that installer calls launchctl when invoked, which is expected but should be run consciously by the user.
Credentials
No environment variables or external credentials are requested. The tool stores approved snapshots, patches, and quarantined copies (which may contain sensitive prompts/instructions) in the state directory — the README and onboarding scripts explicitly recommend placing that directory outside the workspace and restricting permissions (e.g., chmod 700). Treat the state dir as sensitive and secure it appropriately.
Persistence & Privilege
The skill is not force-installed (always: false) and is invocable by the agent. It does provide helpers to schedule itself (Clawdbot cron examples and a macOS launchd installer). Scheduling/install steps are explicit and require user action; they are expected for a monitoring tool but are privileged operations (writing launchd plists and calling launchctl).
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install eason-soul-guardian - After installation, invoke the skill by name or use
/eason-soul-guardian - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
Initial release of soul-guardian: drift detection and baseline integrity guard for agent workspace files.
- Detects unauthorized changes to key workspace files (SOUL.md, AGENTS.md, etc.)
- Automatically restores protected files and alerts the user when drift is detected
- Provides commands for baseline initialization, continuous monitoring, approval of intentional changes, status checks, and audit verification
- Outputs security alerts in a clear, user-friendly format for integration with HEARTBEAT workflows
- Maintains a tamper-evident, hash-chained audit log and supports unified diffs for change review
Metadata
Frequently Asked Questions
What is Eason Soul Guardian?
Drift detection + baseline integrity guard for agent workspace files with automatic alerting support. It is an AI Agent Skill for Claude Code / OpenClaw, with 282 downloads so far.
How do I install Eason Soul Guardian?
Run "/install eason-soul-guardian" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is Eason Soul Guardian free?
Yes, Eason Soul Guardian is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does Eason Soul Guardian support?
Eason Soul Guardian is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created Eason Soul Guardian?
It is built and maintained by eathon (@eathon); the current version is v1.0.0.
More Skills