Soul Guardian File Integrity Guard
Detect and handle unauthorized changes to an agent’s core workspace files.
The code and documentation show no network by default, local-workspace operation, symlink refusal, atomic writes, quarantine copies, hash-chained audit logs, and a signed-release verification procedure. However, restore mode overwrites SOUL.md/AGENTS.md by default without per-event confirmation, state may contain sensitive snapshots and may default inside the workspace, external isolation is not enforced, and the signing-key provenance is not independently confirmed in the supplied material; 8 points are deducted.
The main script, state migration helper, launchd installer, and committed integration tests cover initialization, drift, restore, approval, and audit-chain scenarios, and the static logic is broadly consistent. This review did not execute anything, while permission failures, missing files, concurrent changes, platform differences, and long-running watch behavior have limited coverage and diagnostics; the static cap also limits the score to 10, so 12 points are deducted.
The audience, OpenClaw workspace use case, commands, default protected files, restore/alert/ignore boundaries, and trigger terms are fairly clear. However, it is primarily OpenClaw-oriented, lacks Chinese-language documentation, and installation or scheduling may depend on npx/GitHub or OpenClaw/macOS; environment-fit evidence is limited, so 5 points are deducted.
The skill includes version 0.0.9, AGPL-3.0-or-later licensing, an SBOM, installation and operational notes, limitations, troubleshooting, examples, and a changelog. Information architecture is usable, but maintenance ownership, a clear update path, and publisher responsibility remain insufficiently established, while several installation and state-directory assumptions require user verification; 5 points are deducted.
The core task is to detect workspace-file drift, produce diffs, record audit events, and restore critical files. The documentation provides directly usable commands and examples, and committed tests cover the main workflow. Static review did not execute it, independent verification of restoration and alert delivery is absent, and users still must initialize baselines, configure scheduling, and secure state storage; 9 points are deducted.
The submission provides full source, a pinned version, signed-release verification instructions, an SBOM, and committed tests, enabling meaningful audit and review. There are no execution results or independent third-party reproductions in the supplied material, and the signing artifacts and key release claims are not cross-validated here; 6 points are deducted.
- Restore mode automatically overwrites protected files; confirm the baseline, policy, and recovery scope before enabling it, and keep separate backups.
- The state directory contains approved snapshots, diffs, and quarantined files that may expose prompts, identity data, or memory; place it outside the workspace with restrictive permissions.
- Core operation is local by default, but installation verification, npx installation, and retrieval of remote release artifacts may depend on GitHub or other overseas network reachability.
- This assessment is based only on static source review; scripts, tests, and signature verification were not executed.
What does this skill do, and when should you use it?
Soul Guardian is the ClawSec skill for protecting OpenClaw workspace files such as SOUL.md and AGENTS.md. It compares files with approved SHA-256 baselines, can restore selected files automatically, creates unified diffs, and emits security alerts. It also provides continuous monitoring, intentional-change approval, and hash-chained audit-log verification. Adopt it when protecting agent identity and instruction files matters, but account for the fact that restore mode intentionally overwrites drifted files.
Uses python3 to read protected workspace files and compare them with approved SHA-256 baselines; detects drift and, under the default policy, restores SOUL.md and AGENTS.md while alerting on USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, and MEMORY.md and ignoring memory/*.md; writes local audit and quarantine state and saves unified diffs; provides check, watch, approve, status, and verify-audit commands for detection, continuous monitoring, approval, status inspection, and audit verification; supports --output-format alert for human-readable alerts suitable for forwarding to a user.
- An OpenClaw administrator wants heartbeat checks to detect unexpected changes to SOUL.md or AGENTS.md.
- A personal agent owner needs automatic restoration of approved identity and behavior instructions after file drift.
- A workspace maintainer wants alerts for USER.md, TOOLS.md, or MEMORY.md without automatic overwrites.
- A security maintainer needs diffs and hash-chained audit records to investigate recurring file changes.
- A standalone-package user wants to verify the signed release manifest before trusting SKILL.md, skill.json, or the archive.
What are this skill's strengths and limitations?
- Provides SHA-256 baseline drift detection and unified diff output.
- Can restore and alert on changes to SOUL.md and AGENTS.md.
- Uses hash-chained audit logging, atomic restore writes, and refuses to operate on symlinks.
- Has no network behavior by default, and scheduling is opt-in.
- Restore mode overwrites drifted files, so false positives can replace intentional edits.
- It cannot prove who made a change; actor information is best-effort metadata.
- It cannot protect against an attacker controlling both the workspace and state directory.
- It is not a backup replacement, and the source provides no test-suite or cross-platform execution evidence.
How do you install this skill?
Install with the Vercel Skills CLI:
npx skills add prompt-security/clawsec --skill soul-guardian -a openclaw -y
For standalone installation, follow the supplied verification procedure to validate the signed release manifest, archive, SKILL.md, and skill.json before installing or extracting the archive. The source does not document installation directories or commands for other platforms.
How do you use this skill?
Initialize baselines in the OpenClaw workspace:
cd ~/.openclaw/workspace
python3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note "initial baseline"
Enable monitoring guidance:
python3 skills/soul-guardian/scripts/soul_guardian.py enable-monitoring
For heartbeat-based checks, add this to HEARTBEAT.md:
## 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
You can also run watch --interval 30 for continuous checks, approve --file <path> for reviewed intentional changes, status for current state, and verify-audit for audit-log validation.
How does this skill compare with similar options?
The README distinguishes soul-guardian from the repository’s other security skills: it focuses on OpenClaw file drift detection and baseline restoration, rather than advisory feeds, vulnerability scanning, supply-chain installation verification, or runtime traffic monitoring.