runtime-sentinel

OpenClaw 代理的运行时安全守护者。每当出现以下情况时，请使用此技能 用户提到安全、技能安全、提示注入、恶意软件、可疑 行为、凭证泄露、网络监控、技能完整性或 爪破坏攻击。还会触发诸如“此技能安全吗”之类的短语， “审核我的技能”、“检查威胁”、“我的特工表现得很奇怪”、 “扫描恶意软件”、“保护我的代理”或对安装的内容有任何疑问 技能是在运行时执行的。 runtime-sentinel 提供五种主动防御： 技能完整性哈希、即时注入检测、凭证暴露 审计、网络出口监控和流程异常检测。免费套餐 涵盖散列和基本注入扫描。高级功能（连续 守护进程、出口监控、进程异常检测）通过 x402 进行门控 Base 上的 USDC 小额支付 — 无需帐户或 API 密钥。

# runtime-sentinel

A runtime security skill for OpenClaw. Defends against the threat landscape
exposed by ClawHavoc: backdoored skills, prompt injection via external data,
credential exfiltration, and process-level abuse.

**Free tier**: skill integrity checks, basic injection scanning.  
**Premium** (x402/USDC/Base): continuous daemon monitoring, network egress
monitoring, process anomaly detection, full audit log.

---

## Quick start

```
# One-shot audit of all installed skills (free)
sentinel audit

# Continuous guardian daemon (premium — will prompt for x402 payment)
sentinel daemon start

# Scan a single skill before installing
sentinel check <skill-path-or-clawhub-id>
```

---

## What runtime-sentinel defends against

See `references/threat-model.md` for the full threat matrix. In brief:

| Threat | Feature | Tier |
|---|---|---|
| Tampered skill files post-install | Integrity hashing | Free |
| Prompt injection via email/web/skill output | Injection scanner | Free |
| Plaintext secrets in skill dirs / SOUL.md | Credential auditor | Free |
| Unexpected outbound connections | Egress monitor | Premium |
| Shell commands outside declared behavior | Process anomaly | Premium |
| Continuous real-time protection | Daemon mode | Premium |

---

## Workflow

### 1 — First-time setup

```bash
# Install the binary (built from scripts/src/)
cargo install --path scripts/ --bin sentinel

# Verify installation and print wallet address
sentinel setup
```

`sentinel setup` will:
- Generate or import a Base wallet (BIP-39, stored in `~/.sentinel/wallet`)
- Print the wallet address so the user can fund it with USDC for premium
- Run a free baseline audit and print results

### 2 — On-demand audit (free)

When the user says anything like "scan my skills", "audit", "check for threats":

```bash
sentinel audit [--path ~/.openclaw/skills]
```

Output: a structured report of hash mismatches, injection patterns, and
exposed credentials. No payment required.

### 3 — Single skill check before install (free)

When the user wants to vet a skill before running `clawhub install`:

```bash
sentinel check <skill-directory-or-clawhub-id>
```

Prints a risk score (LOW / MEDIUM / HIGH / CRITICAL) with findings.

### 4 — Premium features via x402

When the user asks for daemon mode, egress monitoring, or process anomaly
detection, `sentinel` will automatically:

1. Hit the sentinel API endpoint
2. Receive a `402 Payment Required` with price in the `X-Payment-Request`
   header (typically $0.01–$0.05/day for daemon mode)
3. Sign the USDC transfer from `~/.sentinel/wallet`
4. Retry the request — access granted for the paid period

The user will see the price *before* their wallet signs anything. All
non-custodial. See `references/x402-payment.md` for the full payment flow.

### 5 — Daemon mode (premium)

```bash
sentinel daemon start    # runs in foreground, writes to ~/.sentinel/daemon.log
# Run in background from your shell if needed:
#   sentinel daemon start > ~/.sentinel/daemon.log 2>&1 &
#   disown
sentinel daemon status
sentinel daemon stop
sentinel daemon logs     # tail the audit log
```

The daemon watches:
- `~/.openclaw/skills/**` for file mutations (inotify / FSEvents)
- `~/.openclaw/SOUL.md` and `MEMORY.md` for unauthorized writes
- Network connections made by skill subprocesses
- Child process trees for undeclared shell commands

Alerts are delivered via OpenClaw's notification system and written to the
audit log.

---

## Interpreting results

### Risk levels

- **LOW**: No findings, or informational only (e.g. skill requests network
  but declares it)
- **MEDIUM**: Undeclared permission, suspicious pattern, or stale hash
- **HIGH**: Known malicious pattern, credential exposure, or undeclared
  egress
- **CRITICAL**: Active exfiltration attempt, reverse shell indicator, or
  SOUL.md mutation

### What to do on HIGH / CRITICAL

1. `sentinel isolate <skill-name>` — quarantines the skill (moves it out of
   the active skills directory)
2. Review the finding in `~/.sentinel/audit.log`
3. Check the skill's ClawHub VirusTotal report
4. If confirmed malicious, `clawhub uninstall <skill>` and report via
   `sentinel report <skill-name>`

---

## Reference files

Read these when you need deeper detail:

- `references/threat-model.md` — Full threat matrix and attack descriptions
  from ClawHavoc and similar campaigns
- `references/x402-payment.md` — x402 payment flow, wallet setup, and
  troubleshooting
- `references/binary-build.md` — How to build `sentinel` from source, cross-
  compilation targets, CI/CD

---

## Wallet setup for premium features

```bash
sentinel wallet show      # print address and USDC balance
sentinel wallet fund      # print QR code and address to send USDC
sentinel wallet export    # export mnemonic for backup (handle carefully)
sentinel wallet recover   # restore from mnemonic on a new machine
```

Minimum recommended balance for uninterrupted daemon mode: **$1 USDC**
(roughly 20–100 days of coverage depending on scan frequency).

---

## Privacy

`sentinel` is fully local. No skill content, file paths, or scan results are
sent to any server. The only outbound calls are:

1. x402 payment verification to the Base facilitator (amount + wallet address
   only)
2. Optional: VirusTotal hash lookups (hash only, no file content)

Both can be disabled with `--offline` for air-gapped environments (free tier
only in offline mode).

---

## 中文说明

# runtime-sentinel

一个面向 OpenClaw 的运行时安全技能。防御 ClawHavoc 暴露的威胁态势：被植入后门的技能、通过外部数据的提示注入、凭证外泄以及进程级滥用。

**免费套餐**：技能完整性检查、基础注入扫描。  
**高级版**（x402/USDC/Base）：持续守护进程监控、网络出口监控、进程异常检测、完整审计日志。

---

## 快速开始

```
# One-shot audit of all installed skills (free)
sentinel audit

# Continuous guardian daemon (premium — will prompt for x402 payment)
sentinel daemon start

# Scan a single skill before installing
sentinel check <skill-path-or-clawhub-id>
```

---

## runtime-sentinel 防御什么

完整的威胁矩阵参见 `references/threat-model.md`。简而言之：

| 威胁 | 功能 | 套餐 |
|---|---|---|
| 安装后被篡改的技能文件 | 完整性哈希 | 免费 |
| 通过邮件/网页/技能输出的提示注入 | 注入扫描器 | 免费 |
| 技能目录 / SOUL.md 中的明文密钥 | 凭证审计器 | 免费 |
| 意外的出站连接 | 出口监控器 | 高级版 |
| 超出已声明行为的 Shell 命令 | 进程异常检测 | 高级版 |
| 持续的实时保护 | 守护进程模式 | 高级版 |

---

## 工作流

### 1 — 首次设置

```bash
# Install the binary (built from scripts/src/)
cargo install --path scripts/ --bin sentinel

# Verify installation and print wallet address
sentinel setup
```

`sentinel setup` 将会：
- 生成或导入一个 Base 钱包（BIP-39，存储于 `~/.sentinel/wallet`）
- 打印钱包地址，以便用户为其充值 USDC 以使用高级功能
- 运行一次免费的基线审计并打印结果

### 2 — 按需审计（免费）

当用户说出类似 "scan my skills"、"audit"、"check for threats" 的内容时：

```bash
sentinel audit [--path ~/.openclaw/skills]
```

输出：一份关于哈希不匹配、注入模式和暴露凭证的结构化报告。无需付费。

### 3 — 安装前的单技能检查（免费）

当用户希望在运行 `clawhub install` 之前甄别某个技能时：

```bash
sentinel check <skill-directory-or-clawhub-id>
```

打印一个风险评分（LOW / MEDIUM / HIGH / CRITICAL）及相关发现。

### 4 — 通过 x402 使用高级功能

当用户请求守护进程模式、出口监控或进程异常检测时，`sentinel` 将自动：

1. 命中 sentinel API 端点
2. 收到一个 `402 Payment Required`，价格位于 `X-Payment-Request` 头中（守护进程模式通常为 $0.01–$0.05/天）
3. 从 `~/.sentinel/wallet` 签署 USDC 转账
4. 重试请求 —— 在付费期内被授予访问权限

在钱包签署任何内容*之前*，用户会先看到价格。全程非托管。完整支付流程参见 `references/x402-payment.md`。

### 5 — 守护进程模式（高级版）

```bash
sentinel daemon start    # runs in foreground, writes to ~/.sentinel/daemon.log
# Run in background from your shell if needed:
#   sentinel daemon start > ~/.sentinel/daemon.log 2>&1 &
#   disown
sentinel daemon status
sentinel daemon stop
sentinel daemon logs     # tail the audit log
```

守护进程会监视：
- `~/.openclaw/skills/**` 的文件变更（inotify / FSEvents）
- `~/.openclaw/SOUL.md` 和 `MEMORY.md` 的未授权写入
- 技能子进程发起的网络连接
- 子进程树中未声明的 Shell 命令

告警通过 OpenClaw 的通知系统发送，并写入审计日志。

---

## 解读结果

### 风险级别

- **LOW**：无发现，或仅为信息性提示（例如技能请求网络但已声明）
- **MEDIUM**：未声明的权限、可疑模式或过期的哈希
- **HIGH**：已知的恶意模式、凭证暴露或未声明的出口连接
- **CRITICAL**：正在进行的外泄尝试、反向 Shell 迹象，或 SOUL.md 被篡改

### 在 HIGH / CRITICAL 时该怎么做

1. `sentinel isolate <skill-name>` —— 隔离该技能（将其移出活动技能目录）
2. 在 `~/.sentinel/audit.log` 中查看该发现
3. 检查该技能在 ClawHub 上的 VirusTotal 报告
4. 如确认为恶意，运行 `clawhub