mirror of
https://github.com/prompt-security/clawsec.git
synced 2026-06-13 05:28:02 +03:00
David Abutbul
101 lines
3.4 KiB
Markdown
101 lines
3.4 KiB
Markdown
---
|
|
name: soul-guardian
|
|
version: 0.0.1
|
|
description: Drift detection + baseline integrity guard for an agent workspace's auto-loaded prompt/instruction markdown files (SOUL.md, AGENTS.md, etc.), with per-file policies, tamper-evident audit logging, and optional auto-restore.
|
|
homepage: https://clawsec.prompt.security
|
|
metadata: {"openclaw":{"emoji":"👻","category":"security"}}
|
|
clawdis:
|
|
emoji: "👻"
|
|
requires:
|
|
bins: [python3]
|
|
---
|
|
|
|
# soul-guardian
|
|
|
|
Use this skill to detect and respond to unexpected edits in the workspace files that the agent auto-loads.
|
|
|
|
## Installation Options
|
|
|
|
You can get soul-guardian in two ways:
|
|
|
|
### Option A: Bundled with ClawSec Suite (Recommended)
|
|
|
|
**If you've installed clawsec-suite, you may already have this!**
|
|
|
|
Soul-guardian is bundled alongside ClawSec Suite to provide file integrity and drift detection capabilities. When you install the suite, if you don't already have soul-guardian installed, it will be deployed from the bundled copy.
|
|
|
|
**Advantages:**
|
|
- Convenient - no separate download needed
|
|
- Standard location - installed to `~/.openclaw/skills/soul-guardian/`
|
|
- Preserved - if you already have soul-guardian installed, it won't be overwritten
|
|
- Single verification - integrity checked as part of suite package
|
|
|
|
### Option B: Standalone Installation (This Page)
|
|
|
|
Install soul-guardian independently without the full suite.
|
|
|
|
**When to use standalone:**
|
|
- You only need file integrity monitoring (not other suite components)
|
|
- You want to install before installing the suite
|
|
- You prefer explicit control over soul-guardian installation
|
|
|
|
**Advantages:**
|
|
- Lighter weight installation
|
|
- Independent from suite
|
|
- Direct control over installation process
|
|
|
|
Continue below for standalone installation instructions.
|
|
|
|
---
|
|
|
|
## What it protects (default policy)
|
|
|
|
- **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)
|
|
|
|
Policy is stored in the guardian state directory as `policy.json`.
|
|
|
|
## Quick start (first run)
|
|
|
|
Recommended: onboard an **external** state dir, then initialize baselines there.
|
|
|
|
```bash
|
|
python3 skills/soul-guardian/scripts/onboard_state_dir.py --agent-id <agentId>
|
|
python3 skills/soul-guardian/scripts/soul_guardian.py --state-dir ~/.clawdbot/soul-guardian/<agentId> init --actor sam --note "first baseline"
|
|
```
|
|
|
|
(Full step-by-step + scheduling options are in `README.md`.)
|
|
|
|
## Commands
|
|
|
|
Run from the agent workspace root:
|
|
|
|
```bash
|
|
python3 skills/soul-guardian/scripts/soul_guardian.py status
|
|
python3 skills/soul-guardian/scripts/soul_guardian.py check
|
|
python3 skills/soul-guardian/scripts/soul_guardian.py check --no-restore
|
|
python3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md
|
|
python3 skills/soul-guardian/scripts/soul_guardian.py restore --file SOUL.md
|
|
python3 skills/soul-guardian/scripts/soul_guardian.py verify-audit
|
|
```
|
|
|
|
### State directory
|
|
|
|
- Default (backward compatible): `memory/soul-guardian/`
|
|
- Recommended external override:
|
|
|
|
```bash
|
|
python3 skills/soul-guardian/scripts/soul_guardian.py --state-dir ~/.clawdbot/soul-guardian/<agentId> check
|
|
```
|
|
|
|
## Cron pattern
|
|
|
|
Keep the existing gateway cron pattern: run `check` every N minutes and notify only when drift is detected.
|
|
|
|
For onboarding/migration to an external state directory, see `README.md` and:
|
|
|
|
```bash
|
|
python3 skills/soul-guardian/scripts/onboard_state_dir.py
|
|
```
|