sentinel-shield

OpenClaw 代理的运行时安全性。监控工具调用、实施速率限制、扫描提示注入并对可疑行为发出警报。保护您的网关令牌和代理会话免遭信息窃取者和会话劫持。

# Sentinel Shield — Runtime Security for OpenClaw Agents

*Everyone else secures the model. We secure the agent.*

Sentinel Shield is a lightweight security layer for OpenClaw agents. It monitors what your agent **does** — not just what it says — and alerts you before damage is done.

## What It Protects Against

- **Stolen gateway tokens** — Rate limiting + anomaly detection catches unauthorized sessions
- **Prompt injection** — Scans inbound content for 16+ injection pattern signatures  
- **Session hijacking** — Behavioral fingerprinting flags sessions that don't match your patterns
- **Runaway agents** — 50-call/60s sliding window kills runaway loops automatically
- **Silent exfiltration** — File integrity monitoring on critical OpenClaw files

## Quick Commands

### Status Check
```bash
node {baseDir}/scripts/sentinel.js status
```
Returns current health, active session stats, and recent alert summary.

### Security Audit
```bash
node {baseDir}/scripts/sentinel.js audit
```
Full audit: file integrity, rate limit state, injection scanner status, anomaly log.

### Recent Alerts
```bash
node {baseDir}/scripts/sentinel.js alerts [--hours 24]
```
Shows alerts from the last N hours (default: 24).

### Rate Limit Status
```bash
node {baseDir}/scripts/sentinel.js ratelimit
```
Shows current call counts per window for all monitored tools.

### Kill Switch
```bash
node {baseDir}/scripts/sentinel.js kill
```
Emergency stop. Terminates active rate counters, logs kill event, sends Telegram alert.

### Run Injection Scan
```bash
node {baseDir}/scripts/sentinel.js scan --text "some content to check"
```
Manually scan text for injection signatures.

### Initialize / Reset Baselines
```bash
node {baseDir}/scripts/sentinel.js init
```
Establishes file integrity baselines for critical OpenClaw files.

## Configuration

Edit `{baseDir}/config/shield.json` to customize:

```json
{
  "rateLimit": {
    "maxCalls": 50,
    "windowSeconds": 60,
    "alertThreshold": 40
  },
  "telegram": {
    "enabled": true,
    "botToken": "YOUR_BOT_TOKEN",
    "chatId": "YOUR_CHAT_ID"
  },
  "monitoredFiles": [
    "~/.openclaw/openclaw.json",
    "~/.openclaw/credentials",
    "~/.ssh/authorized_keys",
    "/etc/passwd"
  ],
  "injectionScanning": true,
  "alertLevel": "medium"
}
```

## Setup (Telegram Alerts)

1. Create a Telegram bot via @BotFather → copy the token
2. Message your bot to get your chat ID: `https://api.telegram.org/bot<TOKEN>/getUpdates`
3. Add both to `{baseDir}/config/shield.json`

## How to Use in Agent Sessions

When you see a suspicious message or want to verify your session is clean:

**User:** "Run a security check"
**Action:** Run `node {baseDir}/scripts/sentinel.js status`

**User:** "Show me recent security alerts"  
**Action:** Run `node {baseDir}/scripts/sentinel.js alerts`

**User:** "Scan this text for injection: [text]"
**Action:** Run `node {baseDir}/scripts/sentinel.js scan --text "[text]"`

**User:** "Emergency stop sentinel"
**Action:** Run `node {baseDir}/scripts/sentinel.js kill`

## Alert Levels

| Level | Trigger | Action |
|-------|---------|--------|
| INFO | Normal activity logged | Write to log only |
| MEDIUM | Rate limit >80% | Log + Telegram |
| HIGH | Rate limit hit, injection detected | Log + Telegram + kill option |
| CRITICAL | File integrity violation | Log + Telegram + alert all channels |

## Files Monitored (Default)

- `~/.openclaw/openclaw.json` — Gateway auth token (THE critical file)
- `~/.openclaw/credentials` — Stored credentials
- `~/.ssh/authorized_keys` — SSH access control
- `/etc/passwd` — System user accounts
- `/etc/sudoers` — Privilege escalation paths

## Version History

- **v0.2.0** — Rate limiting (50/60s sliding window), Telegram alerts, clawhub distribution
- **v0.1.0** — File integrity monitoring, process scanning, injection detection (16 patterns)

---

## 中文说明

# Sentinel Shield — OpenClaw 代理的运行时安全防护

*其他人都在保护模型，而我们保护代理本身。*

Sentinel Shield 是一个面向 OpenClaw 代理的轻量级安全层。它监控代理所**做**的事——而不仅仅是它所说的话——并在损害造成之前向你发出警报。

## 它能防护什么

- **网关令牌被窃取** — 速率限制 + 异常检测可捕获未授权会话
- **提示注入** — 扫描入站内容，匹配 16+ 种注入模式特征  
- **会话劫持** — 行为指纹识别会标记与你既有模式不符的会话
- **失控代理** — 60 秒内 50 次调用的滑动窗口会自动终止失控循环
- **静默数据外泄** — 对关键 OpenClaw 文件进行文件完整性监控

## 快速命令

### 状态检查
```bash
node {baseDir}/scripts/sentinel.js status
```
返回当前健康状况、活动会话统计以及近期警报摘要。

### 安全审计
```bash
node {baseDir}/scripts/sentinel.js audit
```
全面审计：文件完整性、速率限制状态、注入扫描器状态、异常日志。

### 近期警报
```bash
node {baseDir}/scripts/sentinel.js alerts [--hours 24]
```
显示过去 N 小时内的警报（默认：24）。

### 速率限制状态
```bash
node {baseDir}/scripts/sentinel.js ratelimit
```
显示所有受监控工具在各窗口内的当前调用计数。

### 紧急终止开关（Kill Switch）
```bash
node {baseDir}/scripts/sentinel.js kill
```
紧急停止。终止活动的速率计数器，记录终止事件，并发送 Telegram 警报。

### 运行注入扫描
```bash
node {baseDir}/scripts/sentinel.js scan --text "some content to check"
```
手动扫描文本以查找注入特征。

### 初始化 / 重置基线
```bash
node {baseDir}/scripts/sentinel.js init
```
为关键 OpenClaw 文件建立文件完整性基线。

## 配置

编辑 `{baseDir}/config/shield.json` 进行自定义：

```json
{
  "rateLimit": {
    "maxCalls": 50,
    "windowSeconds": 60,
    "alertThreshold": 40
  },
  "telegram": {
    "enabled": true,
    "botToken": "YOUR_BOT_TOKEN",
    "chatId": "YOUR_CHAT_ID"
  },
  "monitoredFiles": [
    "~/.openclaw/openclaw.json",
    "~/.openclaw/credentials",
    "~/.ssh/authorized_keys",
    "/etc/passwd"
  ],
  "injectionScanning": true,
  "alertLevel": "medium"
}
```

## 安装设置（Telegram 警报）

1. 通过 @BotFather 创建一个 Telegram 机器人 → 复制令牌
2. 给你的机器人发消息以获取你的 chat ID：`https://api.telegram.org/bot<TOKEN>/getUpdates`
3. 将二者都添加到 `{baseDir}/config/shield.json`

## 如何在代理会话中使用

当你看到可疑消息，或想确认会话未被污染时：

**用户：** "Run a security check"
**操作：** 运行 `node {baseDir}/scripts/sentinel.js status`

**用户：** "Show me recent security alerts"  
**操作：** 运行 `node {baseDir}/scripts/sentinel.js alerts`

**用户：** "Scan this text for injection: [text]"
**操作：** 运行 `node {baseDir}/scripts/sentinel.js scan --text "[text]"`

**用户：** "Emergency stop sentinel"
**操作：** 运行 `node {baseDir}/scripts/sentinel.js kill`

## 警报级别

| 级别 | 触发条件 | 操作 |
|-------|---------|--------|
| INFO | 记录正常活动 | 仅写入日志 |
| MEDIUM | 速率限制 >80% | 日志 + Telegram |
| HIGH | 达到速率限制、检测到注入 | 日志 + Telegram + 可选终止 |
| CRITICAL | 文件完整性遭破坏 | 日志 + Telegram + 警报所有渠道 |

## 受监控的文件（默认）

- `~/.openclaw/openclaw.json` — 网关认证令牌（最关键的文件）
- `~/.openclaw/credentials` — 已存储的凭据
- `~/.ssh/authorized_keys` — SSH 访问控制
- `/etc/passwd` — 系统用户账户
- `/etc/sudoers` — 提权路径

## 版本历史

- **v0.2.0** — 速率限制（60 秒内 50 次的滑动窗口）、Telegram 警报、clawhub 分发
- **v0.1.0** — 文件完整性监控、进程扫描、注入检测（16 种模式）