← 返回 Skills 市场

Eason Soul Guardian

Name: Eason Soul Guardian
Author: eathon

作者 eathon · GitHub ↗ · v1.0.0 · MIT-0

cross-platform ⚠ suspicious

282

总下载

当前安装

版本数

在 OpenClaw 中安装

/install eason-soul-guardian

功能描述

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

使用说明 (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.

安全使用建议

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.

功能分析

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.

能力评估

ℹ 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).

如何使用

确保已安装 OpenClaw（本地或 Docker 部署）
在对话框中输入安装命令：/install eason-soul-guardian
安装完成后，直接呼叫该 Skill 的名称或使用 /eason-soul-guardian 触发
根据 Skill 的参数说明提供必要输入，即可获得结构化输出

版本历史

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

元数据

Slug eason-soul-guardian

版本 1.0.0

许可证 MIT-0

累计安装 2

当前安装数 2

历史版本数 1

常见问题