soul-guardian

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

Security Scan

The skill's code, instructions, and optional installer are consistent with a local workspace integrity guard; it requires only python3, performs purely local file/audit operations, and its scheduling/restore behavior is opt-in.

Purpose & Capability

Name/description (drift detection + integrity guard) match the included scripts and policy files. The scripts operate on workspace files, maintain baselines/patches/audit logs, and optionally install scheduling plumbing — all expected for this purpose. No unrelated credentials, binaries, or external services are requested.

Instruction Scope

SKILL.md instructs the agent to run the included Python scripts to init/check/approve/restore and to optionally use cron/launchd. The runtime behavior described (local checks, diffs, audit log, optional restore) matches the implementation. Minor inconsistency: SKILL.md/README mention a demo script (demo.sh) but that file is not present in the manifest.

Install Mechanism

No install spec is declared (instruction-only), which matches the provided code files. The only installer-like script writes a launchd plist and optionally invokes launchctl when --install is passed; that is a local, platform-specific action and not a hidden network download. No remote downloads or package installs are used.

Credentials

The skill declares no required environment variables or credentials and doesn't access external secrets. It stores state under a configurable state directory (default: in-workspace memory tree) and recommends placing it outside the workspace for resilience; this is proportional to its function. The default policy (auto-restore of SOUL.md and AGENTS.md) is powerful but justified by the stated purpose.

Persistence & Privilege

The skill is not always-enabled and model invocation is allowed (platform default). It writes local state (approved snapshots, patches, audit logs) and can optionally write a LaunchAgents plist and call launchctl when the operator requests installation — that requires explicit consent. Because it can auto-restore critical agent files, operators should ensure baselines are correct and the state dir is protected; otherwise auto-restore could reinforce a malicious baseline.

Assessment

This skill is internally consistent with its stated goal, but review these before enabling it: - Inspect the approved baselines and policy.json before enabling auto-restore. If the baselines contain malicious or undesired content, the guardian will restore that content automatically. - Prefer moving the state directory outside the workspace (the README recommends this); state dir contains snapshots, patches and quarantined copies of prompts/instructions and should be protected (restrict permissions, back it up). - Be cautious when running the installer with --install: that mode writes a plist to ~/Library/LaunchAgents and invokes launchctl (system-level scheduling). Only run install if you understand and consent to scheduling the check process. - The demo.sh referenced in docs is not present in the manifest; do not run commands you cannot inspect. Run the included test scripts in a safe, temporary workspace to validate behavior before enabling on a production workspace. If you want stronger guarantees: keep the guardian's state dir on a separate, backed-up host or storage, restrict access (chmod 700), and manually review any detected drift patches before approving or enabling automatic restores.

Protects your agent's core files (SOUL.md, AGENTS.md, etc.) from unauthorized changes with automatic detection, restoration, and user alerting.

Operational Notes

• Required runtime: python3
• Optional runtime: openclaw for cron integration, launchctl for macOS scheduling, bash for the demo helper
• Side effects: can auto-restore protected files to their approved baseline and writes audit/quarantine state locally
• Network behavior: none by default
• Trust model: any scheduling is opt-in, but restore mode intentionally overwrites drifted files

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.