clawguardian

# Guardian

**One layer in a multi-layer security stack for OpenClaw agents.**

Real agent security requires multiple layers: OpenClaw's built-in capability restrictions and
approval gates handle what the agent *can do*. Guardian handles what the agent *sees* —
intercepting malicious inputs before they reach the model.

Guardian provides signature-based pre-model scanning for prompt injection, credential
exfiltration attempts, tool abuse patterns, and social engineering attacks. It is not a complete
security solution on its own. Use it alongside OpenClaw's tool allowlists, approval gates, and
sandboxed execution for defense-in-depth.

Guardian provides two scanning modes:

- **Real-time pre-scan** — checks each incoming message before it reaches the model
- **Batch scan** — periodic sweep of workspace files and conversation logs

All data stays local. Cron setup is optional via `scripts/onboard.py --setup-crons`.

Scan results are stored in a SQLite database (`guardian.db`).

## Installation

```bash
cd ~/.openclaw/skills/guardian
./install.sh
```

## Install mechanism and review
This package includes executable scripts (including `install.sh`) and Python modules.
Review `install.sh` before running in production.
`install.sh` performs local setup/validation; optional helper `onboard.py` is opt-in for cron setup.

## Onboarding checklist
1) Optional: `python3 scripts/onboard.py --setup-crons` (scanner/report/digest crons)
2) `python3 scripts/admin.py status` (confirm running)
3) `python3 scripts/admin.py threats` (confirm signatures loaded; should show 0/blocked)
4) Optional: review `config.json` scan_paths and threshold for your environment

### First-load / self-activation
After `install.sh` completes, it writes `.guardian-activate-pending` to the workspace root
(`~/.openclaw/workspace/.guardian-activate-pending`). When OpenClaw detects this marker on
next load, it triggers `onboard.py` automatically for the self-activation flow. The marker is
removed once `onboard...

# 🛡️ Guardian — Security scanner for OpenClaw agents

Detects prompt injection, credential exfiltration, tool abuse, and social engineering in real time. Runs locally with bundled signatures.

---
## Install

```bash
clawhub install guardian
cd ~/.openclaw/skills/guardian && ./install.sh
```

## Install & safety note
This package includes executable scripts (`install.sh`, optional onboarding/API/webhook helpers).
Review `install.sh` before running in production environments.

## Onboarding checklist (fast)
1) Optional: `python3 scripts/onboard.py --setup-crons` (scanner/report/digest crons)
2) `python3 scripts/admin.py status` (confirm running)
3) `python3 scripts/admin.py threats` (confirm signatures loaded; should show 0/blocked)
4) Optional: review `config.json` scan paths and thresholds

## Scan scope
Guardian scans configured workspace paths and may read other skill/config files under those paths for detection. Use narrow `scan_paths` in `config.json` if needed.

## Quick commands
```bash
python3 scripts/admin.py status          # running?
python3 scripts/admin.py threats         # list detected threats
python3 scripts/admin.py report          # full summary
python3 scripts/admin.py update-defs     # update signatures (bundled by default)
```
Add `--json` to any command for machine-readable output.

## Dashboard
```bash
cd skills/guardian/dashboard && python3 -m http.server 8091
# http://localhost:8091/guardian.html
```

## Optional components
- **Cron helper**: `scripts/onboard.py --setup-crons` (scanner/report/digest crons)

## Python API
```python
from core.realtime import RealtimeGuard

guard = RealtimeGuard()
result = guard.scan_message("test payload", channel="telegram")
if guard.should_block(result):
    print(result.top_threat)
```

## What it protects against
- Prompt injection / indirect injection
- Credential patterns / exfiltration attempts
- Tool abuse patterns (read → send)
- Social engineering / fake authority

## How it works
- Bundled signature...