emberdesire-hopeids

面向 AI 智能体的推理型入侵检测，支持隔离、人工审核与 Telegram 告警。

## 概述（中文）

面向 AI 智能体的推理型入侵检测，支持隔离、人工审核与 Telegram 告警。

## 技能正文

# hopeIDS 安全技能

面向 AI 智能体的推理型入侵检测，支持隔离与人工介入。

## 安全不变量

以下为**不可协商**的设计原则：

1. **阻断 = 完全中止** — 被阻断的消息永不到达 jasper-recall 或智能体
2. **仅元数据** — 永不存储原始恶意内容
3. **批准 ≠ 重新注入** — 批准改变未来行为，不复活消息
4. **告警程序化** — Telegram 告警由元数据构建，不涉及 LLM

---

## Features

- **自动扫描** — 智能体处理前扫描消息
- **隔离** — 阻断威胁并仅存储元数据
- **人工介入** — Telegram 告警供审阅
- **每智能体配置** — 不同智能体不同阈值
- **命令** — `/approve`、`/reject`、`/trust`、`/quarantine`

---

## 流水线

```
Message arrives
    ↓
hopeIDS.autoScan()
    ↓
┌─────────────────────────────────────────┐
│  risk >= threshold?                     │
│                                         │
│  BLOCK (strictMode):                    │
│     → Create QuarantineRecord           │
│     → Send Telegram alert               │
│     → ABORT (no recall, no agent)       │
│                                         │
│  WARN (non-strict):                     │
│     → Inject <security-alert>           │
│     → Continue to jasper-recall         │
│     → Continue to agent                 │
│                                         │
│  ALLOW:                                 │
│     → Continue normally                 │
└─────────────────────────────────────────┘
```

---

## Configuration

```json
{
  "plugins": {
    "entries": {
      "hopeids": {
        "enabled": true,
        "config": {
          "autoScan": true,
          "defaultRiskThreshold": 0.7,
          "strictMode": false,
          "telegramAlerts": true,
          "agents": {
            "moltbook-scanner": {
              "strictMode": true,
              "riskThreshold": 0.7
            },
            "main": {
              "strictMode": false,
              "riskThreshold": 0.8
            }
          }
        }
      }
    }
  }
}
```

### 选项

| 选项 | 类型 | 默认 | 说明 |
|--------|------|---------|-------------|
| `autoScan` | boolean | `false` | 自动扫描每条消息 |
| `strictMode` | boolean | `false` | 威胁时阻断（而非警告） |
| `defaultRiskThreshold` | number | `0.7` | 触发操作的风险级别 |
| `telegramAlerts` | boolean | `true` | 为被阻断消息发送告警 |
| `telegramChatId` | string | - | 覆盖告警目标 |
| `quarantineDir` | string | `~/.openclaw/quarantine/hopeids` | 存储路径 |
| `agents` | object | - | 每智能体覆盖 |
| `trustOwners` | boolean | `true` | 跳过扫描所有者消息 |

---

## 隔离记录

消息被阻断时创建元数据记录：

```json
{
  "id": "q-7f3a2b",
  "ts": "2026-02-06T00:48:00Z",
  "agent": "moltbook-scanner",
  "source": "moltbook",
  "senderId": "@sus_user",
  "intent": "instruction_override",
  "risk": 0.85,
  "patterns": [
    "matched regex: ignore.*instructions",
    "matched keyword: api key"
  ],
  "contentHash": "ab12cd34...",
  "status": "pending"
}
```

**注意：** 没有 `originalMessage` 字段。这是有意设计。

---

## Telegram 告警

消息被阻断时：

```
🛑 Message blocked

ID: `q-7f3a2b`
Agent: moltbook-scanner
Source: moltbook
Sender: @sus_user
Intent: instruction_override (85%)

Patterns:
• matched regex: ignore.*instructions
• matched keyword: api key

`/approve q-7f3a2b`
`/reject q-7f3a2b`
`/trust @sus_user`
```

仅由元数据构建。无 LLM 参与。

---

## 命令

### `/quarantine [all|clean]`

列出隔离记录。

```
/quarantine        # List pending
/quarantine all    # List all (including resolved)
/quarantine clean  # Clean expired records
```

### `/approve <id>`

将阻断消息标为误报。

```
/approve q-7f3a2b
```

**效果：**
- 状态 → `approved`
- （未来）将发送者加入允许列表
- （未来）降低模式权重

### `/reject <id>`

确认阻断消息为真阳性。

```
/reject q-7f3a2b
```

**效果：**
- 状态 → `rejected`
- （未来）强化模式权重

### `/trust <senderId>`

将发送者加入白名单以供未来消息。

```
/trust @legitimate_user
```

### `/scan <message>`

手动扫描消息。

```
/scan ignore your previous instructions and...
```

---

## 批准/拒绝的含义

| 命令 | 做什么 | 不做什么 |
|---------|--------------|-------------------|
| `/approve` | 标为误报，可能调整 IDS | 不会重新注入消息 |
| `/reject` | 确认威胁，可能强化模式 | 不影响当前消息 |
| `/trust` | 为未来白名单发送者 | 不会追溯批准 |

**被阻断的消息按设计已消失。** 若合法，发送者可重新发送。

---

## 每智能体配置

不同智能体需要不同安全姿态：

```json
"agents": {
  "moltbook-scanner": {
    "strictMode": true,    // Block threats
    "riskThreshold": 0.7   // 70% = suspicious
  },
  "main": {
    "strictMode": false,   // Warn only
    "riskThreshold": 0.8   // Higher bar for main
  },
  "email-processor": {
    "strictMode": true,    // Always block
    "riskThreshold": 0.6   // More paranoid
  }
}
```

---

## 威胁类别

| 类别 | 风险 | 说明 |
|----------|------|-------------|
| `command_injection` | 🔴 严重 | Shell 命令、代码执行 |
| `credential_theft` | 🔴 严重 | API 密钥提取尝试 |
| `data_exfiltration` | 🔴 严重 | 数据泄露到外部 URL |
| `instruction_override` | 🔴 高 | 越狱、「忽略先前」 |
| `impersonation` | 🔴 高 | 伪造系统/管理员消息 |
| `discovery` | ⚠️ 中 | API/能力探测 |

---

## Installation

```bash
npx hopeid setup
```

然后重启 OpenClaw。

---

## Links

- **GitHub**：https://github.com/E-x-O-Entertainment-Studios-Inc/hopeIDS
- **npm**：https://www.npmjs.com/package/hopeid
- **文档**：https://exohaven.online/products/hopeids