{"id":"c66169d9-93e4-4637-b01c-4d69d974b391","entityType":"agent","slug":"clawhub-davida-ps-soul-guardian","name":"soul-guardian","canonicalUrl":"https://www.xpersona.co/agent/clawhub-davida-ps-soul-guardian","canonicalPath":"/agent/clawhub-davida-ps-soul-guardian","generatedAt":"2026-10-09T21:40:48.857Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"description":"Drift detection + baseline integrity guard for agent workspace files with automatic alerting support Skill: soul-guardian Owner: davida-ps Summary: Drift detection + baseline integrity guard for agent workspace files with automatic alerting support Tags: latest:0.0.2 Version history: v0.0.2 | 2026-02-06T17:33:12.748Z | user Release 0.0.2 via CI Archive index: Archive v0.0.2: 8 files, 21147 bytes Files: README.md (8133b), scripts/install_launchd_plist.py (6114b), scripts/onboard_state_dir.py (5520b), scripts/soul_gua","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.7K downloads reported by the source. Last updated 4/15/2026.","installCommand":"clawhub skill install kn76m78f01hqrtpgm895s0jsax80jd8v:soul-guardian","sourceUrl":"https://clawhub.ai/davida-ps/soul-guardian","homepage":"https://clawhub.ai/davida-ps/soul-guardian","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/davida-ps/soul-guardian","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":65,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Drift detection + baseline integrity guard for agent workspace files with automatic alerting support Skill: soul-guardian Owner: davida-ps Summary: Drift detect"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"stars":null,"forks":null,"downloads":1690,"packageName":null,"latestVersion":"0.0.2","tractionLabel":"1.7K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-02-28T20:38:01.682Z","emptyReason":null},"lastUpdatedAt":"2026-04-15T00:45:39.800Z","lastCrawledAt":"2026-02-28T20:38:01.682Z","lastIndexedAt":null,"nextCrawlAt":"2026-03-01T20:38:01.682Z","lastVerifiedAt":null,"highlights":[{"version":"0.0.2","createdAt":"2026-02-06T17:33:12.748Z","changelog":"Release 0.0.2 via CI","fileCount":8,"zipByteSize":21147}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install kn76m78f01hqrtpgm895s0jsax80jd8v:soul-guardian","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-davida-ps-soul-guardian/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-davida-ps-soul-guardian/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-davida-ps-soul-guardian/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-davida-ps-soul-guardian/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-davida-ps-soul-guardian/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-davida-ps-soul-guardian/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T21:40:48.857Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-davida-ps-soul-guardian/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-davida-ps-soul-guardian/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-davida-ps-soul-guardian/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-davida-ps-soul-guardian/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"readme":"Skill: soul-guardian\n\nOwner: davida-ps\n\nSummary: Drift detection + baseline integrity guard for agent workspace files with automatic alerting support\n\nTags: latest:0.0.2\n\nVersion history:\n\nv0.0.2 | 2026-02-06T17:33:12.748Z | user\n\nRelease 0.0.2 via CI\n\nArchive index:\n\nArchive v0.0.2: 8 files, 21147 bytes\n\nFiles: README.md (8133b), scripts/install_launchd_plist.py (6114b), scripts/onboard_state_dir.py (5520b), scripts/soul_guardian.py (35205b), scripts/test_soul_guardian.py (4030b), skill.json (1422b), SKILL.md (4422b), _meta.json (132b)\n\nFile v0.0.2:SKILL.md\n\n---\nname: soul-guardian\nversion: 0.0.2\ndescription: Drift detection + baseline integrity guard for agent workspace files with automatic alerting support\nhomepage: https://clawsec.prompt.security\nmetadata: {\"openclaw\":{\"emoji\":\"👻\",\"category\":\"security\"}}\nclawdis:\n  emoji: \"👻\"\n  requires:\n    bins: [python3]\n---\n\n# soul-guardian 👻\n\nProtects your agent's core files (SOUL.md, AGENTS.md, etc.) from unauthorized changes with automatic detection, restoration, and **user alerting**.\n\n## Quick Start (3 Steps)\n\n### Step 1: Initialize baselines\n```bash\ncd ~/.openclaw/workspace\npython3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note \"initial baseline\"\n```\n\n### Step 2: Enable monitoring\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py enable-monitoring\n```\nThis shows you how to add monitoring to your workflow.\n\n### Step 3: Add to HEARTBEAT.md (Recommended)\n\nAdd this to your HEARTBEAT.md for automatic monitoring:\n\n```markdown\n## Soul Guardian Check\n- Run `python3 skills/soul-guardian/scripts/soul_guardian.py check --actor heartbeat --output-format alert`\n- If any output is produced, relay it to the user immediately as a security alert\n```\n\nThat's it! Soul Guardian will now:\n- ✅ Detect unauthorized changes to protected files\n- ✅ Auto-restore SOUL.md and AGENTS.md to approved baseline\n- ✅ Alert you when drift is detected and handled\n\n---\n\n## What it protects (default policy)\n\n| File | Mode | Action on drift |\n|------|------|-----------------|\n| SOUL.md | restore | Auto-restore + alert |\n| AGENTS.md | restore | Auto-restore + alert |\n| USER.md | alert | Alert only |\n| TOOLS.md | alert | Alert only |\n| IDENTITY.md | alert | Alert only |\n| HEARTBEAT.md | alert | Alert only |\n| MEMORY.md | alert | Alert only |\n| memory/*.md | ignore | Ignored |\n\n## Commands\n\n### Check for drift (with alert output)\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py check --output-format alert\n```\n- Silent if no drift\n- Outputs human-readable alert if drift detected\n- Perfect for heartbeat integration\n\n### Watch mode (continuous monitoring)\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30\n```\nRuns continuously, checking every 30 seconds.\n\n### Approve intentional changes\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md --actor user --note \"intentional update\"\n```\n\n### View status\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py status\n```\n\n### Verify audit log integrity\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py verify-audit\n```\n\n---\n\n## Alert Format\n\nWhen drift is detected, the `--output-format alert` produces output like:\n\n```\n==================================================\n🚨 SOUL GUARDIAN SECURITY ALERT\n==================================================\n\n📄 FILE: SOUL.md\n   Mode: restore\n   Status: ✅ RESTORED to approved baseline\n   Expected hash: abc123def456...\n   Found hash:    789xyz000111...\n   Diff saved: /path/to/patches/drift.patch\n\n==================================================\nReview changes and investigate the source of drift.\nIf intentional, run: soul_guardian.py approve --file <path>\n==================================================\n```\n\nThis output is designed to be relayed directly to the user in TUI/chat.\n\n---\n\n## Security Model\n\n**What it does:**\n- Detects filesystem drift vs approved baseline (sha256)\n- Produces unified diffs for review\n- Maintains tamper-evident audit log with hash chaining\n- Refuses to operate on symlinks\n- Uses atomic writes for restores\n\n**What it doesn't do:**\n- Cannot prove WHO made a change (actor is best-effort metadata)\n- Cannot protect if attacker controls both workspace AND state directory\n- Is not a substitute for backups\n\n**Recommendation:** Store state directory outside workspace for better resilience.\n\n---\n\n## Demo\n\nRun the full demo flow to see soul-guardian in action:\n\n```bash\nbash skills/soul-guardian/scripts/demo.sh\n```\n\nThis will:\n1. Verify clean state (silent check)\n2. Inject malicious content into SOUL.md\n3. Run heartbeat check (produces alert)\n4. Show SOUL.md was restored\n\n---\n\n## Troubleshooting\n\n**\"Not initialized\" error:**\nRun `init` first to set up baselines.\n\n**Drift keeps happening:**\nCheck what's modifying your files. Review the audit log and patches.\n\n**Want to approve a change:**\nRun `approve --file <path>` after reviewing the change.\n\nFile v0.0.2:README.md\n\n# soul-guardian\n\nA small, dependency-free integrity guard for Clawdbot agent workspaces.\n\nIt helps you detect (and optionally auto-undo) unexpected edits to the workspace markdown files that an agent auto-loads (e.g., `SOUL.md`, `AGENTS.md`). It also records a **tamper-evident** audit trail of changes.\n\n## Why this exists\n\nIn many Clawdbot setups, the agent reads certain markdown files every session (identity, instructions, memory, tools, etc.). If those files drift unexpectedly (accidental edits, bad merges, unwanted automation, etc.), you want:\n\n- detection (sha256 mismatch)\n- a diff/patch artifact for review\n- a record of what happened (audit log)\n- optionally: an automatic restore to a known-good baseline for critical files\n\n## What it protects (default policy)\n\nDefault `policy.json` protects:\n\n- **Auto-restore + alert:** `SOUL.md`, `AGENTS.md`\n- **Alert-only:** `USER.md`, `TOOLS.md`, `IDENTITY.md`, `HEARTBEAT.md`, `MEMORY.md`\n- **Ignored by default:** `memory/*.md` (daily notes)\n\nYou can customize this by editing the policy file in the guardian state directory.\n\n## Security model (and limitations)\n\nWhat it does well:\n- Detects filesystem drift vs an approved baseline.\n- Produces unified diffs (patch files) for review.\n- Maintains an **append-only JSONL audit log** with **hash chaining** so log tampering is detectable.\n- Refuses to operate on **symlinks** (reduces link attacks).\n- Uses **atomic writes** for restores and baseline updates (`os.replace`).\n\nWhat it does *not* do:\n- It cannot prove *who* changed a file. `--actor` is best-effort metadata.\n- It cannot protect you if an attacker can modify both the workspace and the guardian state directory.\n- It is not a substitute for backups.\n\nRecommendation (not enforced):\n- Mirror/back up your guardian state directory (and/or workspace) using git and/or offsite backups.\n\n## State directory\n\nBy default, state is stored inside the workspace:\n\n- `memory/soul-guardian/`\n  - `policy.json` (what to monitor)\n  - `baselines.json` (approved sha256 per file)\n  - `approved/<path>` (approved snapshots)\n  - `audit.jsonl` (append-only log with hash chain)\n  - `patches/*.patch` (unified diffs)\n  - `quarantine/*` (copies of drifted files before restore)\n\nFor better resilience, you can move this **outside** the workspace (recommended).\n\n## Install / usage\n\nFrom the agent workspace root.\n\n### First run / Initialize baselines (recommended)\n\nFor resilience, create your guardian **state directory outside** the workspace first, then initialize baselines.\n\n1) Onboard an external state dir (creates policy, copies any existing state, prints paths/snippets):\n\n```bash\npython3 skills/soul-guardian/scripts/onboard_state_dir.py --agent-id <agentId>\n```\n\n2) Initialize baselines **in that external state dir**:\n\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py \\\n  --state-dir ~/.clawdbot/soul-guardian/<agentId> \\\n  init --actor sam --note \"first baseline\"\n```\n\n3) Run a check once (should be silent on OK; prints a single-line summary on drift):\n\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py \\\n  --state-dir ~/.clawdbot/soul-guardian/<agentId> \\\n  check --actor system --note \"first check\"\n```\n\n### Common commands\n\nStatus (summary):\n\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py \\\n  --state-dir ~/.clawdbot/soul-guardian/<agentId> \\\n  status\n```\n\nCheck for drift (default: restores restore-mode files):\n\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py \\\n  --state-dir ~/.clawdbot/soul-guardian/<agentId> \\\n  check --actor system --note cron\n```\n\nAlert-only check (never restore):\n\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py \\\n  --state-dir ~/.clawdbot/soul-guardian/<agentId> \\\n  check --no-restore\n```\n\nApprove intentional edits (one file):\n\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py \\\n  --state-dir ~/.clawdbot/soul-guardian/<agentId> \\\n  approve --file SOUL.md --actor sam --note \"intentional update\"\n```\n\nApprove all policy targets (except ignored ones):\n\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py \\\n  --state-dir ~/.clawdbot/soul-guardian/<agentId> \\\n  approve --all --actor sam --note \"bulk approve\"\n```\n\nRestore (only restore-mode files):\n\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py \\\n  --state-dir ~/.clawdbot/soul-guardian/<agentId> \\\n  restore --file SOUL.md --actor system --note \"manual restore\"\n```\n\nVerify audit log tamper-evidence:\n\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py \\\n  --state-dir ~/.clawdbot/soul-guardian/<agentId> \\\n  verify-audit\n```\n\n## Policy format (`policy.json`)\n\nExample:\n\n```json\n{\n  \"version\": 1,\n  \"workspaceRoot\": \"/path/to/workspace\",\n  \"targets\": [\n    {\"path\": \"SOUL.md\", \"mode\": \"restore\"},\n    {\"path\": \"AGENTS.md\", \"mode\": \"restore\"},\n    {\"path\": \"USER.md\", \"mode\": \"alert\"},\n    {\"pattern\": \"memory/*.md\", \"mode\": \"ignore\"}\n  ]\n}\n```\n\n- `mode`:\n  - `restore`: drift triggers audit + patch + (by default) restore + quarantine copy\n  - `alert`: drift triggers audit + patch, but does not restore\n  - `ignore`: excluded\n\n## Onboarding: move state outside the workspace\n\nRun the helper:\n\n```bash\npython3 skills/soul-guardian/scripts/onboard_state_dir.py\n```\n\nIt will:\n- create an external state dir (**recommended default:** `~/.clawdbot/soul-guardian/<agentId>/`)\n- copy (or move with `--move`) existing state from `memory/soul-guardian/`\n- write a default `policy.json` if missing\n- print scheduling snippets\n\nNotes:\n- `<agentId>` should be **stable and unique per workspace** (don’t point multiple workspaces at the same state dir).\n- WARNING: `--move` deletes the old in-workspace state dir after copying.\n- The external state dir can contain **approved snapshots, patches, and quarantined copies** of sensitive prompt/instruction/memory files. Keep permissions restrictive (e.g., `chmod 700 <dir>`; `chmod go-rwx <dir>`).\n\nThen include `--state-dir` in all commands (run from the workspace root), e.g.:\n\n```bash\ncd <workspace> && python3 skills/soul-guardian/scripts/soul_guardian.py --state-dir ~/.clawdbot/soul-guardian/<agentId> check\n```\n\n## Scheduling (cron)\n\n### A) Clawdbot Gateway Cron (recommended)\n\nThis is the default pattern when you want drift notifications to flow through Clawdbot.\n\nNote: even when there is **no drift**, Clawdbot cron runs typically show an **OK summary** in the main session.\n\nExample (edit paths + schedule):\n\n```bash\nclawdbot cron add \\\n  --name \"soul-guardian: check workspace\" \\\n  --description \"Run soul-guardian check; alert when drift detected.\" \\\n  --session isolated \\\n  --wake now \\\n  --cron \"*/10 * * * *\" \\\n  --tz UTC \\\n  --message \"Run:\\ncd '<workspace>'\\npython3 skills/soul-guardian/scripts/soul_guardian.py --state-dir ~/.clawdbot/soul-guardian/<agentId> check --actor cron --note 'gateway-cron'\\n\\nIf the command prints a line starting with 'SOUL_GUARDIAN_DRIFT', treat it as an alert. If it prints nothing, reply HEARTBEAT_OK.\" \\\n  --post-prefix \"[soul-guardian]\" \\\n  --post-mode summary\n```\n\n### B) macOS launchd (optional, silent-on-OK)\n\nIf you want **system scheduling** without Clawdbot posting OK summaries, use `launchd`.\n\nBecause `soul_guardian.py check` prints **nothing** on OK and prints a single-line `SOUL_GUARDIAN_DRIFT ...` summary on drift, this tends to be silent unless something changed.\n\nGenerate + (optionally) install a LaunchAgent plist (run from the workspace root, or pass `--workspace-root`):\n\n```bash\npython3 skills/soul-guardian/scripts/install_launchd_plist.py \\\n  --state-dir ~/.clawdbot/soul-guardian/<agentId> \\\n  --interval-seconds 600 \\\n  --install\n```\n\nThe generated plist includes `WorkingDirectory` set to your workspace root (recommended), so relative paths behave as expected.\n\nThe script writes drift output to log files under `<state-dir>/logs/`.\nYou can tail them with the commands it prints.\n\n## Development / tests\n\nA minimal test script is included:\n\n```bash\npython3 skills/soul-guardian/scripts/test_soul_guardian.py\n```\n\nIt simulates a workspace in a temp directory and validates drift detection, approve/restore flow, and audit hash chain verification.\n\nFile v0.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn76m78f01hqrtpgm895s0jsax80jd8v\",\n  \"slug\": \"soul-guardian\",\n  \"version\": \"0.0.2\",\n  \"publishedAt\": 1770399192748\n}\n\nFile v0.0.2:skill.json\n\n{\n  \"name\": \"soul-guardian\",\n  \"version\": \"0.0.2\",\n  \"description\": \"Drift detection and baseline integrity guard for agent workspace prompt files. Auto-restore critical files with tamper-evident audit logging.\",\n  \"author\": \"prompt-security\",\n  \"license\": \"MIT\",\n  \"homepage\": \"https://clawsec.prompt.security\",\n  \"keywords\": [\n    \"security\",\n    \"integrity\",\n    \"drift-detection\",\n    \"agents\",\n    \"ai\",\n    \"protection\",\n    \"audit\",\n    \"baseline\"\n  ],\n  \"sbom\": {\n    \"files\": [\n      {\n        \"path\": \"SKILL.md\",\n        \"required\": true,\n        \"description\": \"Soul guardian skill documentation\"\n      },\n      {\n        \"path\": \"scripts/soul_guardian.py\",\n        \"required\": true,\n        \"description\": \"Main guardian script\"\n      },\n      {\n        \"path\": \"scripts/onboard_state_dir.py\",\n        \"required\": true,\n        \"description\": \"State directory setup\"\n      },\n      {\n        \"path\": \"scripts/install_launchd_plist.py\",\n        \"required\": false,\n        \"description\": \"macOS launchd installer\"\n      }\n    ]\n  },\n  \"openclaw\": {\n    \"emoji\": \"👻\",\n    \"category\": \"security\",\n    \"requires\": {\n      \"bins\": [\n        \"python3\"\n      ]\n    },\n    \"triggers\": [\n      \"soul guardian\",\n      \"integrity check\",\n      \"drift detection\",\n      \"baseline check\",\n      \"file integrity\",\n      \"protect soul\",\n      \"guard files\",\n      \"workspace security\",\n      \"tamper detection\"\n    ]\n  }\n}","readmeExcerpt":"Skill: soul-guardian Owner: davida-ps Summary: Drift detection + baseline integrity guard for agent workspace files with automatic alerting support Tags: latest:0.0.2 Version history: v0.0.2 | 2026-02-06T17:33:12.748Z | user Release 0.0.2 via CI Archive index: Archive v0.0.2: 8 files, 21147 bytes Files: README.md (8133b), scripts/install_launchd_plist.py (6114b), scripts/onboard_state_dir.py (5520b), scripts/soul_gua","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"cd ~/.openclaw/workspace\npython3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note \"initial baseline\""},{"language":"bash","snippet":"python3 skills/soul-guardian/scripts/soul_guardian.py enable-monitoring"},{"language":"markdown","snippet":"## Soul Guardian Check\n- Run `python3 skills/soul-guardian/scripts/soul_guardian.py check --actor heartbeat --output-format alert`\n- If any output is produced, relay it to the user immediately as a security alert"},{"language":"bash","snippet":"python3 skills/soul-guardian/scripts/soul_guardian.py check --output-format alert"},{"language":"bash","snippet":"python3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30"},{"language":"bash","snippet":"python3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md --actor user --note \"intentional update\""}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: soul-guardian\nversion: 0.0.2\ndescription: Drift detection + baseline integrity guard for agent workspace files with automatic alerting support\nhomepage: https://clawsec.prompt.security\nmetadata: {\"openclaw\":{\"emoji\":\"👻\",\"category\":\"security\"}}\nclawdis:\n  emoji: \"👻\"\n  requires:\n    bins: [python3]\n---\n\n# soul-guardian 👻\n\nProtects your agent's core files (SOUL.md, AGENTS.md, etc.) from unauthorized changes with automatic detection, restoration, and **user alerting**.\n\n## Quick Start (3 Steps)\n\n### Step 1: Initialize baselines\n```bash\ncd ~/.openclaw/workspace\npython3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note \"initial baseline\"\n```\n\n### Step 2: Enable monitoring\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py enable-monitoring\n```\nThis shows you how to add monitoring to your workflow.\n\n### Step 3: Add to HEARTBEAT.md (Recommended)\n\nAdd this to your HEARTBEAT.md for automatic monitoring:\n\n```markdown\n## Soul Guardian Check\n- Run `python3 skills/soul-guardian/scripts/soul_guardian.py check --actor heartbeat --output-format alert`\n- If any output is produced, relay it to the user immediately as a security alert\n```\n\nThat's it! Soul Guardian will now:\n- ✅ Detect unauthorized changes to protected files\n- ✅ Auto-restore SOUL.md and AGENTS.md to approved baseline\n- ✅ Alert you when drift is detected and handled\n\n---\n\n## What it protects (default policy)\n\n| File | Mode | Action on drift |\n|------|------|-----------------|\n| SOUL.md | restore | Auto-restore + alert |\n| AGENTS.md | restore | Auto-restore + alert |\n| USER.md | alert | Alert only |\n| TOOLS.md | alert | Alert only |\n| IDENTITY.md | alert | Alert only |\n| HEARTBEAT.md | alert | Alert only |\n| MEMORY.md | alert | Alert only |\n| memory/*.md | ignore | Ignored |\n\n## Commands\n\n### Check for drift (with alert output)\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py check --output-format alert\n```\n- Silent if no drift\n- Outputs human-readable alert if drift detected\n- Perfect for heartbeat integration\n\n### Watch mode (continuous monitoring)\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30\n```\nRuns continuously, checking every 30 seconds.\n\n### Approve intentional changes\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md --actor user --note \"intentional update\"\n```\n\n### View status\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py status\n```\n\n### Verify audit log integrity\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py verify-audit\n```\n\n---\n\n## Alert Format\n\nWhen drift is detected, the `--output-format alert` produces output like:\n\n```\n==================================================\n🚨 SOUL GUARDIAN SECURITY ALERT\n==================================================\n\n📄 FILE: SOUL.md\n   Mode: restore\n   Status: ✅ RESTORED to approved baseline\n   Expected hash: abc123def456...\n   Found hash:    789xyz000111...\n   Diff saved: /path/to/patches/d"},{"path":"README.md","content":"# soul-guardian\n\nA small, dependency-free integrity guard for Clawdbot agent workspaces.\n\nIt helps you detect (and optionally auto-undo) unexpected edits to the workspace markdown files that an agent auto-loads (e.g., `SOUL.md`, `AGENTS.md`). It also records a **tamper-evident** audit trail of changes.\n\n## Why this exists\n\nIn many Clawdbot setups, the agent reads certain markdown files every session (identity, instructions, memory, tools, etc.). If those files drift unexpectedly (accidental edits, bad merges, unwanted automation, etc.), you want:\n\n- detection (sha256 mismatch)\n- a diff/patch artifact for review\n- a record of what happened (audit log)\n- optionally: an automatic restore to a known-good baseline for critical files\n\n## What it protects (default policy)\n\nDefault `policy.json` protects:\n\n- **Auto-restore + alert:** `SOUL.md`, `AGENTS.md`\n- **Alert-only:** `USER.md`, `TOOLS.md`, `IDENTITY.md`, `HEARTBEAT.md`, `MEMORY.md`\n- **Ignored by default:** `memory/*.md` (daily notes)\n\nYou can customize this by editing the policy file in the guardian state directory.\n\n## Security model (and limitations)\n\nWhat it does well:\n- Detects filesystem drift vs an approved baseline.\n- Produces unified diffs (patch files) for review.\n- Maintains an **append-only JSONL audit log** with **hash chaining** so log tampering is detectable.\n- Refuses to operate on **symlinks** (reduces link attacks).\n- Uses **atomic writes** for restores and baseline updates (`os.replace`).\n\nWhat it does *not* do:\n- It cannot prove *who* changed a file. `--actor` is best-effort metadata.\n- It cannot protect you if an attacker can modify both the workspace and the guardian state directory.\n- It is not a substitute for backups.\n\nRecommendation (not enforced):\n- Mirror/back up your guardian state directory (and/or workspace) using git and/or offsite backups.\n\n## State directory\n\nBy default, state is stored inside the workspace:\n\n- `memory/soul-guardian/`\n  - `policy.json` (what to monitor)\n  - `baselines.json` (approved sha256 per file)\n  - `approved/<path>` (approved snapshots)\n  - `audit.jsonl` (append-only log with hash chain)\n  - `patches/*.patch` (unified diffs)\n  - `quarantine/*` (copies of drifted files before restore)\n\nFor better resilience, you can move this **outside** the workspace (recommended).\n\n## Install / usage\n\nFrom the agent workspace root.\n\n### First run / Initialize baselines (recommended)\n\nFor resilience, create your guardian **state directory outside** the workspace first, then initialize baselines.\n\n1) Onboard an external state dir (creates policy, copies any existing state, prints paths/snippets):\n\n```bash\npython3 skills/soul-guardian/scripts/onboard_state_dir.py --agent-id <agentId>\n```\n\n2) Initialize baselines **in that external state dir**:\n\n```bash\npython3 skills/soul-guardian/scripts/soul_guardian.py \\\n  --state-dir ~/.clawdbot/soul-guardian/<agentId> \\\n  init --actor sam --note \"first baseline\"\n```\n\n3) Run a check once (should be silent on OK; prints a s"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn76m78f01hqrtpgm895s0jsax80jd8v\",\n  \"slug\": \"soul-guardian\",\n  \"version\": \"0.0.2\",\n  \"publishedAt\": 1770399192748\n}"},{"path":"skill.json","content":"{\n  \"name\": \"soul-guardian\",\n  \"version\": \"0.0.2\",\n  \"description\": \"Drift detection and baseline integrity guard for agent workspace prompt files. Auto-restore critical files with tamper-evident audit logging.\",\n  \"author\": \"prompt-security\",\n  \"license\": \"MIT\",\n  \"homepage\": \"https://clawsec.prompt.security\",\n  \"keywords\": [\n    \"security\",\n    \"integrity\",\n    \"drift-detection\",\n    \"agents\",\n    \"ai\",\n    \"protection\",\n    \"audit\",\n    \"baseline\"\n  ],\n  \"sbom\": {\n    \"files\": [\n      {\n        \"path\": \"SKILL.md\",\n        \"required\": true,\n        \"description\": \"Soul guardian skill documentation\"\n      },\n      {\n        \"path\": \"scripts/soul_guardian.py\",\n        \"required\": true,\n        \"description\": \"Main guardian script\"\n      },\n      {\n        \"path\": \"scripts/onboard_state_dir.py\",\n        \"required\": true,\n        \"description\": \"State directory setup\"\n      },\n      {\n        \"path\": \"scripts/install_launchd_plist.py\",\n        \"required\": false,\n        \"description\": \"macOS launchd installer\"\n      }\n    ]\n  },\n  \"openclaw\": {\n    \"emoji\": \"👻\",\n    \"category\": \"security\",\n    \"requires\": {\n      \"bins\": [\n        \"python3\"\n      ]\n    },\n    \"triggers\": [\n      \"soul guardian\",\n      \"integrity check\",\n      \"drift detection\",\n      \"baseline check\",\n      \"file integrity\",\n      \"protect soul\",\n      \"guard files\",\n      \"workspace security\",\n      \"tamper detection\"\n    ]\n  }\n}"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Drift detection + baseline integrity guard for agent workspace files with automatic alerting support Skill: soul-guardian Owner: davida-ps Summary: Drift detection + baseline integrity guard for agent workspace files with automatic alerting support Tags: latest:0.0.2 Version history: v0.0.2 | 2026-02-06T17:33:12.748Z | user Release 0.0.2 via CI Archive index: Archive v0.0.2: 8 files, 21147 bytes Files: README.md (8133b), scripts/install_launchd_plist.py (6114b), scripts/onboard_state_dir.py (5520b), scripts/soul_gua","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":774,"uniquenessScore":53,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:40:48.857Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}