What makes soul-guardian notable?

1.7K downloads. Trust evidence available

How should soul-guardian be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

agentCLAWHUBUnverified

soul-guardian

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

OpenClaw

View on ClawHub

Rank

Safety

Downloads

1.7k

Updated

Apr 15, 2026

Version

0.0.2

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 1.7K downloads reported by the source. Last updated 4/15/2026.

Avoid when

Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor: Clawhubvendor · observed Apr 15, 2026
Protocol compatibility: OpenClawcompatibility · observed Apr 15, 2026
Adoption signal: 1.7K downloadsadoption · observed Apr 15, 2026
Latest release: 0.0.2release · observed Feb 6, 2026
Handshake status: UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install kn76m78f01hqrtpgm895s0jsax80jd8v:soul-guardian

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: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-davida-ps-soul-guardian/snapshot"

Documentation

CLAWHUB

14,727 characters of source documentation, loaded on request.

Extracted files

4 files captured from the source.

SKILL.md

---
name: soul-guardian
version: 0.0.2
description: Drift detection + baseline integrity guard for agent workspace files with automatic alerting support
homepage: https://clawsec.prompt.security
metadata: {"openclaw":{"emoji":"👻","category":"security"}}
clawdis:
  emoji: "👻"
  requires:
    bins: [python3]
---

# 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
```bash
cd ~/.openclaw/workspace
python3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note "initial baseline"
```

### Step 2: Enable monitoring
```bash
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:

```markdown
## 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)
```bash
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)
```bash
python3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30
```
Runs continuously, checking every 30 seconds.

### Approve intentional changes
```bash
python3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md --actor user --note "intentional update"
```

### View status
```bash
python3 skills/soul-guardian/scripts/soul_guardian.py status
```

### Verify audit log integrity
```bash
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/d

README.md

# soul-guardian

A small, dependency-free integrity guard for Clawdbot agent workspaces.

It 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.

## Why this exists

In 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:

- detection (sha256 mismatch)
- a diff/patch artifact for review
- a record of what happened (audit log)
- optionally: an automatic restore to a known-good baseline for critical files

## What it protects (default policy)

Default `policy.json` protects:

- **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)

You can customize this by editing the policy file in the guardian state directory.

## Security model (and limitations)

What it does well:
- Detects filesystem drift vs an approved baseline.
- Produces unified diffs (patch files) for review.
- Maintains an **append-only JSONL audit log** with **hash chaining** so log tampering is detectable.
- Refuses to operate on **symlinks** (reduces link attacks).
- Uses **atomic writes** for restores and baseline updates (`os.replace`).

What it does *not* do:
- It cannot prove *who* changed a file. `--actor` is best-effort metadata.
- It cannot protect you if an attacker can modify both the workspace and the guardian state directory.
- It is not a substitute for backups.

Recommendation (not enforced):
- Mirror/back up your guardian state directory (and/or workspace) using git and/or offsite backups.

## State directory

By default, state is stored inside the workspace:

- `memory/soul-guardian/`
  - `policy.json` (what to monitor)
  - `baselines.json` (approved sha256 per file)
  - `approved/<path>` (approved snapshots)
  - `audit.jsonl` (append-only log with hash chain)
  - `patches/*.patch` (unified diffs)
  - `quarantine/*` (copies of drifted files before restore)

For better resilience, you can move this **outside** the workspace (recommended).

## Install / usage

From the agent workspace root.

### First run / Initialize baselines (recommended)

For resilience, create your guardian **state directory outside** the workspace first, then initialize baselines.

1) Onboard an external state dir (creates policy, copies any existing state, prints paths/snippets):

```bash
python3 skills/soul-guardian/scripts/onboard_state_dir.py --agent-id <agentId>
```

2) Initialize baselines **in that external state dir**:

```bash
python3 skills/soul-guardian/scripts/soul_guardian.py \
  --state-dir ~/.clawdbot/soul-guardian/<agentId> \
  init --actor sam --note "first baseline"
```

3) Run a check once (should be silent on OK; prints a s

_meta.json

{
  "ownerId": "kn76m78f01hqrtpgm895s0jsax80jd8v",
  "slug": "soul-guardian",
  "version": "0.0.2",
  "publishedAt": 1770399192748
}

skill.json

{
  "name": "soul-guardian",
  "version": "0.0.2",
  "description": "Drift detection and baseline integrity guard for agent workspace prompt files. Auto-restore critical files with tamper-evident audit logging.",
  "author": "prompt-security",
  "license": "MIT",
  "homepage": "https://clawsec.prompt.security",
  "keywords": [
    "security",
    "integrity",
    "drift-detection",
    "agents",
    "ai",
    "protection",
    "audit",
    "baseline"
  ],
  "sbom": {
    "files": [
      {
        "path": "SKILL.md",
        "required": true,
        "description": "Soul guardian skill documentation"
      },
      {
        "path": "scripts/soul_guardian.py",
        "required": true,
        "description": "Main guardian script"
      },
      {
        "path": "scripts/onboard_state_dir.py",
        "required": true,
        "description": "State directory setup"
      },
      {
        "path": "scripts/install_launchd_plist.py",
        "required": false,
        "description": "macOS launchd installer"
      }
    ]
  },
  "openclaw": {
    "emoji": "👻",
    "category": "security",
    "requires": {
      "bins": [
        "python3"
      ]
    },
    "triggers": [
      "soul guardian",
      "integrity check",
      "drift detection",
      "baseline check",
      "file integrity",
      "protect soul",
      "guard files",
      "workspace security",
      "tamper detection"
    ]
  }
}

Github ReposUpdated 4h agoRank 70

AionUi

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!

MCPOPENCLAW

Github ReposUpdated 6mo agoRank 70

activepieces

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

OPENCLAW

Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.