runtime-sentinel

OpenClaw 的一项运行时安全能力。用于防御 ClawHavoc 所揭示的威胁面：植入后门的能力（backdoored skills）、通过外部数据（如邮件、网页）触发的提示词注入（prompt injection）、凭据窃取（credential exfiltration），以及进程级滥用（process-level abuse）。

免费版：能力完整性校验、基础注入扫描。
高级版（x402/USDC/Base）：持续守护守护进程监控、网络出站流量监控、进程行为异常检测、完整审计日志。

快速上手

# 对所有已安装能力执行一次性审计（免费）
sentinel audit

# 启动持续运行的守护进程（高级版 — 将提示支付 x402）
sentinel daemon start

# 在安装前扫描单个能力
sentinel check 

runtime-sentinel 防御的威胁类型

完整威胁矩阵详见 references/threat-model.md。简要如下：

工作流程

1 — 首次设置

# 安装二进制程序（由 scripts/src/ 构建）
cargo install --path scripts/ --bin sentinel

# 验证安装并打印钱包地址
sentinel setup

sentinel setup 将执行以下操作：

• 生成或导入一个 Base 钱包（BIP-39 格式，保存于 ~/.sentinel/wallet）
• 打印钱包地址，供用户充值 USDC 以开通高级版功能
• 执行一次免费的基础审计，并输出结果

2 — 按需审计（免费）

当用户发出类似“扫描我的能力”、“审计”、“检查威胁”等指令时：

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

输出：结构化报告，包含哈希不匹配项、注入模式识别结果及暴露的凭据信息。无需支付费用。

3 — 安装前单能力检查（免费）

当用户希望在执行 clawhub install 前对某能力进行安全评估时：

sentinel check 

输出风险评分（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. 重试原始请求 —— 支付成功后即获得对应周期的访问权限

用户将在钱包签署任何交易之前看到明确标示的价格。全程非托管（non-custodial）。完整支付流程参见 references/x402-payment.md。

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

sentinel daemon start    # 前台运行，日志写入 ~/.sentinel/daemon.log
# 如需后台运行，可在 shell 中执行：
#   sentinel daemon start > ~/.sentinel/daemon.log 2>&1 &
#   disown
sentinel daemon status
sentinel daemon stop
sentinel daemon logs     # 实时查看审计日志（tail）

守护进程持续监控以下内容：

• ~/.openclaw/skills/** 下的文件变更（基于 inotify / FSEvents）
• ~/.openclaw/SOUL.md 和 MEMORY.md 是否发生未授权写入
• 能力子进程发起的网络连接
• 子进程树中是否存在未声明的 Shell 命令调用

告警将通过 OpenClaw 的通知系统推送，并同步写入审计日志。

结果解读

风险等级定义

• LOW（低风险）：无任何问题，或仅为信息性提示（例如能力申请网络访问且已在元数据中明确声明）
• MEDIUM（中风险）：存在未声明的权限请求、可疑行为模式或哈希值过期
• HIGH（高风险）：命中已知恶意模式、凭据明文暴露、或存在未声明的出站流量
• CRITICAL（严重风险）：检测到正在发生的凭据外泄行为、反向 Shell 特征，或 SOUL.md 文件被篡改

遇到 HIGH / CRITICAL 风险时的操作建议

1. sentinel isolate —— 隔离该能力（将其移出活跃能力目录）
2. 查阅 ~/.sentinel/audit.log 中的具体发现详情
3. 检查该能力在 ClawHub 上关联的 VirusTotal 报告
4. 若确认为恶意能力，请执行 clawhub uninstall 并通过 sentinel report 提交举报

参考文档

需要深入了解时请阅读以下文件：

• references/threat-model.md —— 完整威胁矩阵与攻击手法说明，涵盖 ClawHavoc 及同类活动
• references/x402-payment.md —— x402 支付流程、钱包配置与常见问题排查
• references/binary-build.md —— 如何从源码构建 sentinel、支持的跨平台编译目标及 CI/CD 流程

高级版功能所需的钱包配置

sentinel wallet show      # 显示钱包地址与当前 USDC 余额
sentinel wallet fund      # 输出 USDC 充值二维码与地址
sentinel wallet export    # 导出助记词用于备份（请务必妥善保管）
sentinel wallet recover   # 在新设备上通过助记词恢复钱包

为保障守护进程模式不间断运行，推荐最低钱包余额：$1 USDC（按扫描频率不同，约可覆盖 20–100 天）。

隐私说明

sentinel 完全本地运行。不会向任何服务器发送能力内容、文件路径或扫描结果。唯一向外发起的请求包括：

1. 向 Base 协助者（facilitator）验证 x402 支付（仅含金额与钱包地址）
2. 可选：VirusTotal 哈希查询（仅上传哈希值，不上传文件内容）

以上两类网络请求均可通过 --offline 参数禁用，适用于气隙环境（air-gapped environments）；但离线模式下仅支持免费版功能。