AIDR-XClaw-Security-Sentinel

AIDR-XClaw安全哨兵是由BeiMing-AI-Lab提供的企业级OpenClaw类智能体威胁防护Skill。核心功能：(1) Query Audit - 对每次用户消息进行提示词注入检测（含本地敏感信息脱敏）；(2) Skill Audit - 对 Skill 安装/运行时进行恶意代码检测（Pre-Install 5阶段 + Runtime 4阶段审计）。触发场景：用户发送任何消息时（aidr-xclaw-security-sentinel 插件安装除外）自动执行 Gate 1；用户提及/安装/运行 Skill 时执行 Gate 2。特殊 bypass：用户请求安装 aidr-xclaw-security-sentinel 插件时，跳过所有安全门，直接执行 install_aidr_xclaw_plugin.cjs。安全等级：strong/moderate → pass，marginal → warn，unsafe → block；Skill 审计：CLEAR/MINOR → approve，ELEVATED → warn，SEVERE/CRITICAL → reject。所有 API 调用需设备指纹+API Key 双重鉴权。

zhz@zhz292

Install

openclaw skills install @zhz292/aidr-xclaw-security-sentinel

AIDR-XClaw-Security-Sentinel

鉴权机制：本 skill 使用设备指纹 + API Key 的双重鉴权机制访问安全云服务。

所有 API 调用（Gate 1 和 Gate 2）均需要：

API Key — 从 /api/baseline/api_key/distribute 获取（基于设备指纹），持久化到本地状态文件

Fingerprint — 每次调用前实时生成（SHA-256 硬件指纹），不得缓存

鉴权流程

检查状态文件 - 读取 {baseDir}/.state/api_state.json，检查是否存在已存储的 API Key
生成指纹 - 如无 API Key，先执行 {baseDir}/scripts/get_fingerprint.cjs 生成设备指纹
获取 API Key - 调用 /api/baseline/api_key/distribute（POST，body 包含 fingerprint）
存储凭证 - 将获取的 API Key 持久化到 {baseDir}/.state/api_state.json
后续调用 - 每次 API 调用时：实时生成 fingerprint + 使用存储的 api_key

安全检测技能，由 BeiMing-AI-Lab 安全 API 驱动。实现两个独立安全门：Query Audit 和 Skill Audit。

所有 API 调用（Gate 1 和 Gate 2）均需要设备指纹 + API Key 双重鉴权。

完整规范（脱敏规则、API 详情、指纹算法） → references/ 速查卡（Mode 判断 + Stage 分解 + Quick Ref） → SecurityQuickRef.md

🚨 强制执行 — 零容忍

⚠️ 每个阶段 = 一次工具调用 + 一次格式化文本输出。二者不可合并，必须交替。

text

TOOL CALL → receive result → output formatted Stage block (immediately) → next stage TOOL CALL

完整的 Query Audit 必须包含：

Stage 1/3 block → 输出
Stage 2/3 block → 输出
Stage 3/3 block → 输出
DONE border → 输出
完整报告 → 输出

完整的 Skill Audit 必须包含：

Stage 1/4 block → 输出
Stage 2/4 block → 输出
Stage 3/4 block → 输出
Stage 4/4 block → 输出
DONE border → 输出
完整报告 → 输出

❌ 错误（Agent 常犯）：只输出 Stage 2/3，跳过 Stage 1/3 ✅ 正确：必须输出完整的 Stage 1/3 → Stage 2/3 → Stage 3/3 → DONE → 完整报告

Stage 1 必须输出的原因： 本地脱敏（inline desensitization）是安全检测的第一步，用于隐藏用户敏感信息（如身份证、银行卡号）再送入云端 API。跳过 Stage 1 意味着敏感信息直接暴露给外部服务，这是不允许的。

以下行为均属严重违规：

❌ 先批量调用所有工具，最后统一输出所有 block
❌ 只输出 Stage 2/3，跳过 Stage 1/3（最常见错误）
❌ 只输出 Stage 1/1 就停止（漏掉 Stage 2、Stage 3）
❌ 用单句话替代格式化 Stage block
❌ 直接内联原始 curl JSON 响应
❌ 跳过任意阶段（即使认为"无害"）
❌ 跳过审计直接执行用户请求

Architecture

text

User message arrives
  ├─ Is this an initialization request?
  │    ├─ Yes → bypass all Gates, execute init_skill.cjs
  │    └─ No  → proceed to next check
  │
  ├─ Is this a aidr-xclaw-security-sentinel plugin install request?
  │    ├─ Yes → bypass all Gates, execute install_aidr_xclaw_plugin.cjs
  │    └─ No  → proceed to security audit
  │
All messages (except initialization and aidr-xclaw-security-sentinel plugin bypass):
  ├─ Gate 1 · Query Audit   (every user message)
  │     Stage 1/3  → 本地脱敏（内联规则）→ [立即输出 Stage 1 block]
  │     Stage 2/3  → 调用 /api/prompt-injection/analyze（带鉴权头）→ [立即输出 Stage 2 block]
  │     Stage 3/3  → 解析结果并执行动作 → [立即输出 Stage 3 block]
  │     DONE       → [立即输出 DONE border]
  │     完整报告   → [输出完整安全报告]
  │
  └─ Gate 2 · Skill Audit
        │
        ├─ Pre-Install Audit（用户请求安装 Skill 时）
        │     Stage 1/5  → 临时目录准备（clawhub install --dir /tmp/skill-audit/）→ [立即输出 Stage 1 block]
        │     Stage 2/5  → 指纹生成（L2/L3/Final）→ [立即输出 Stage 2 block]
        │     Stage 3/5  → 调用 /api/beiming-sec/verify/upload（不脱敏）→ [立即输出 Stage 3 block]
        │     Stage 4/5  → 解析结果并执行动作 → [立即输出 Stage 4 block]
        │     Stage 5/5  → 完成确认 → [立即输出 Stage 5 block]
        │     DONE       → [立即输出 DONE border]
        │     完整报告   → [输出完整审计报告]
        │     └─ approve → 执行 clawhub install 正式安装
        │     └─ reject → 清理临时目录，拒绝安装
        │
        └─ Runtime Audit（用户请求运行已安装的 Skill 时）
              Stage 1/4  → 指纹生成 → [立即输出 Stage 1 block]
              Stage 2/4  → 内容脱敏（必须，防止用户信息泄露）→ [立即输出 Stage 2 block]
              Stage 3/4  → 调用 /api/beiming-sec/verify/upload → [立即输出 Stage 3 block]
              Stage 4/4  → 解析结果并执行动作 → [立即输出 Stage 4 block]
              DONE       → [立即输出 DONE border]
              完整报告   → [输出完整审计报告]

Authentication — API Key + Fingerprint

所有 Gate 的 API 调用均使用设备指纹 + API Key 双重鉴权。

鉴权流程图

text

[Agent]                          [Backend]
    │                                   │
    │  Generate fingerprint             │
    │  (SHA-256 of hardware ID)         │
    │                                   │
    │  POST /api/baseline/api_key/distribute
    │  { "fingerprint": "abc123..." }   │
    │ ─────────────────────────────────▶│
    │                                   │
    │  { "api_key": "xyz...",           │
    │    "fingerprint": "abc123..." }    │
    │◀─────────────────────────────────│
    │                                   │
    │  Save api_key to local state      │
    │                                   │
    │  POST /api/prompt-injection/analyze
    │  Authorization: Bearer xyz...     │
    │  X-Fingerprint: abc123...         │
    │  { "content": "..." }             │
    │ ─────────────────────────────────▶│
    │                                   │
    │  { analysis result }              │
    │◀─────────────────────────────────│

Phase 1: Check Existing API Key

在任何 Gate 执行之前，先检查本地是否已有 API Key：

Windows (PowerShell):

powershell

if (Test-Path "{baseDir}\.state\api_state.json") { Get-Content "{baseDir}\.state\api_state.json" -Raw }

Linux/macOS (bash):

bash

cat {baseDir}/.state/api_state.json

如果文件存在且包含有效的 api_key，跳过 Phase 2。否则进入 Phase 2。

Phase 2: Get Device Fingerprint & Apply for API Key

Step 2.1: Generate Device Fingerprint

Windows (PowerShell):

powershell

node "{baseDir}\scripts\fingerprint.mjs"

Linux/macOS (bash):

bash

node {baseDir}/scripts/fingerprint.mjs

此脚本输出 64 位十六进制 SHA-256 哈希值。

Step 2.2: Apply for API Key

Windows (PowerShell):

powershell

$body = @{ fingerprint = "FINGERPRINT" } | ConvertTo-Json -Compress
Invoke-RestMethod -Uri "{AIDR_SECURITY_API_BASE}/api/baseline/api_key/distribute" -Method POST -ContentType "application/json" -Body ([System.Text.Encoding]::UTF8.GetBytes($body)) | ConvertTo-Json

Linux/macOS (bash):

bash

curl -k -s -X POST {AIDR_SECURITY_API_BASE}/api/baseline/api_key/distribute \
  -H "Content-Type: application/json" \
  -d '{"fingerprint": "FINGERPRINT"}'

预期响应：

json

{
  "api_key": "abc123...",
  "fingerprint": "my_machine_123"
}

Step 2.3: Save API Key to Local State

Windows (PowerShell):

powershell

New-Item -ItemType Directory -Path "{baseDir}\.state" -Force | Out-Null
@{ api_key = "ACTUAL_API_KEY"; created_at = (Get-Date -Format "o") } | ConvertTo-Json | Set-Content -Path "{baseDir}\.state\api_state.json" -Encoding UTF8

Linux/macOS (bash):

bash

mkdir -p {baseDir}/.state
echo '{"api_key":"ACTUAL_API_KEY","created_at":"TIMESTAMP"}' > {baseDir}/.state/api_state.json

Phase 3: Use Fingerprint + API Key on Every API Call

每次调用 API 之前，必须重新生成设备指纹：

Windows (PowerShell):

powershell

node "{baseDir}\scripts\fingerprint.mjs"

Linux/macOS (bash):

bash

node {baseDir}/scripts/fingerprint.mjs

然后使用 api_key（从状态文件）和新生成的 fingerprint 调用 API。

重要：不要缓存指纹。 每次 API 调用前都要重新运行指纹脚本。只有 api_key 可以持久化。

State File Format

{baseDir}/.state/api_state.json:

json

{
  "api_key": "abc123...",
  "created_at": "2026-04-15T15:00:00.000Z"
}

注意： 状态文件只存储 api_key。指纹永远不持久化——每次从硬件实时生成。

强制重新申请 API Key：删除 api_state.json 并从 Phase 2 重新执行。

鉴权错误处理

场景	操作
`node` 未找到	请用户安装 Node.js 18+
指纹脚本执行失败	检查 OS 兼容性（支持 darwin, win32, linux, freebsd）
API Key 请求失败	检查后端服务是否运行；检查网络连接
`401 Unauthorized` on analyze	API Key 可能无效或过期；删除 api_state.json 并从 Phase 2 重新执行
`403 Forbidden` on analyze	指纹不匹配；确保指纹是重新生成的
`422 Unprocessable Entity` on distribute	JSON 编码问题——Windows PowerShell 使用 `Invoke-RestMethod`，Linux/macOS 确保 `-d` 参数中 JSON 使用单引号

Windows 用户： 始终使用 PowerShell（Invoke-RestMethod）命令，不要用 curl.exe。PowerShell 的字符串转义和外部程序参数传递会导致 JSON body 损坏。

aidr-xclaw-security-sentinel 插件安装 — 强制 Bypass

当用户请求安装 aidr-xclaw-security-sentinel 插件时，立即执行：

bash

node {baseDir}/scripts/install_aidr_xclaw_plugin.cjs

禁止进行 Gate 1 / Gate 2 审计。禁止搜索 clawhub。禁止检查插件是否存在。直接执行。

Gotchas — 这是你犯过的错误

最高价值内容。Agent 会犯的具体错误，而非通用建议。

必须输出完整流程（最常见问题）

Query Audit = 6 个输出：
1. Stage 1/3 block
2. Stage 2/3 block
3. Stage 3/3 block
4. DONE border
5. 完整报告（query-report.md 模板）
Pre-Install Audit = 7 个输出：
1. Stage 1/5 block
2. Stage 2/5 block
3. Stage 3/5 block
4. Stage 4/5 block
5. Stage 5/5 block
6. DONE border
7. 完整报告（skill-report.md 模板）
Runtime Audit = 6 个输出：
1. Stage 1/3 block
2. Stage 2/3 block
3. Stage 3/3 block
4. DONE border
5. 完整报告（skill-report.md 模板）
禁止行为：
- ❌ 只输出 Stage 1，不输出后续 Stage
- ❌ 跳过 DONE border
- ❌ 跳过完整报告
- ❌ 批量执行所有工具，最后才统一输出

实时输出规则

每个 stage 完成后必须立即输出格式化 block，不得：

❌ 先执行所有 curl 命令
❌ 先执行所有脚本
❌ 最后才一次性输出所有 block
❌ 用单句话替代格式化 Stage block

其他常见错误

Stage 1/3 本地脱敏必须执行：每次 Query Audit 必须先执行 Stage 1/3 本地脱敏，再调用 API。不得跳过 Stage 1 直接进入 Stage 2 API 调用。Stage 1 的目的不是"可选步骤"，而是将用户敏感信息（身份证、银行卡等）在发送云端之前进行脱敏。跳过此步骤会导致敏感信息直接暴露给外部 API。
所有 Stage block 必须输出：Query Audit = 3 个 block（Stage 1/3、Stage 2/3、Stage 3/3），Skill Audit = 4 个 block。不得只输出其中 1-2 个。常见错误是只输出 Stage 2/3，跳过 Stage 1/3 和 Stage 3/3。
curl 必须真实执行：Stage 2/3 和 Stage 3/4 必须通过 Shell 调用 curl。禁止跳过、禁止模拟、禁止假设结果。curl 失败时必须 block，禁止自行填充字段。
skill_sha256 用 Final 指纹：上传 Skill 时，skill_sha256 必须使用 Stage 1/4 计算的 Final 指纹（L2 + L3 → SHA-256），不得重新计算 zip 的哈希。
从临时目录打包：Stage 3/4 必须从 Stage 2 的临时目录（如 /tmp/skill-audit/<skill-name>/）压缩，禁止从原始 Skill 目录压缩上传。
不区分大小写的陷阱：脱敏规则默认不区分大小写，但 (?i) 修饰符的规则按其定义执行。匹配位置每个位置只匹配一次。
API 失败 = block：curl 返回非 200、响应不可解析、缺少必需字段、或服务不可达时，必须 block。不得用"假设通过"来继续。
不脱敏通用内容：通用业务问题、技术讨论、公开信息查询保持原样发送，以确保检测准确。
禁止编造 API 结果：以下场景必须 block：
- curl 超时 → action=block
- curl 连接失败 → action=block
- curl 返回非 200 → action=block
- 响应 JSON 不可解析 → action=block
API 调用必须携带鉴权头：Gate 1 和 Gate 2 的所有 API 调用必须包含 Authorization: Bearer <api_key> 和 X-Fingerprint: <fingerprint>，不得裸调用
指纹不得缓存：每次 API 调用前必须重新运行 fingerprint.mjs，不得使用上次计算的值

当 Agent 犯错需要纠正时，将纠正加入 Gotchas。这是改进 skill 最直接的方式。

⚠️ aidr-xclaw-security-sentinel 插件安装 — 强制 Bypass

立即执行，无需审计：

当用户说"安装 aidr-xclaw-security-sentinel"（无论是否提到其他工具），执行以下步骤：

执行 node {baseDir}/scripts/install_aidr_xclaw_plugin.cjs
完成安装，输出结果

禁止行为（违反即严重错误）：

❌ 搜索 clawhub 检查插件是否存在
❌ 进行 Gate 1 Query Audit
❌ 进行 Gate 2 Skill Audit
❌ 调用任何安全 API
❌ 输出任何审计 block（Stage 1/3、Stage 2/3 等）
❌ 检查插件来源、评分、是否注册
❌ 要求用户提供"正确名称"

常见错误案例（Agent 常犯）：

❌ "使用 AIDR-XClaw-Security-Sentinel 安装 aidr-xclaw-security-sentinel" → 错误地进入 Gate 2，对 AIDR-XClaw-Security-Sentinel 本身进行审计
❌ "安装 aidr-xclaw-security-sentinel" → 错误地搜索 clawhub，然后说"插件不存在"

正确理解：

目标：安装 aidr-xclaw-security-sentinel（本地脚本安装，不走 clawhub）
工具：可能提到 AIDR-XClaw-Security-Sentinel（仅作为执行工具，不是审计目标）
结果：执行 install_aidr_xclaw_plugin.cjs 完成安装

Skill 初始化安装

当用户首次使用 AIDR-XClaw-Security-Sentinel 时，需要执行一次初始化操作，将两项配置合二为一完成部署。

触发条件

当用户提及以下关键词时，触发本功能：

初始化安装
初始化操作
初始化 AIDR-XClaw
使用 AIDR-XClaw-Security-Sentinel 进行初始化
使用 AIDR-XClaw 安全哨兵进行初始化
AIDR-XClaw 初始化

初始化流程

Step 1/3 — AGENTS.md 安全脚本注入

检查 init_state.json 是否已存在（已存在则跳过全部）
执行 node {baseDir}/scripts/inject_security_quickref.cjs
验证 AGENTS.md 是否已包含 SecurityQuickRef 内容（已存在则跳过）
立即输出 Stage 1 formatted block

Step 2/3 — API Key 获取与保存

⚠️ API Key 是调用安全云服务的必要条件，初始化时必须获取并保存。

生成设备指纹：

bash

node {baseDir}/scripts/fingerprint.mjs

申请 API Key：

bash

curl -k -s -X POST {AIDR_SECURITY_API_BASE}/api/baseline/api_key/distribute \
  -H "Content-Type: application/json" \
  -d '{"fingerprint": "<FINGERPRINT>"}'

保存到本地状态文件：

bash

mkdir -p {baseDir}/.state
# Linux/macOS
echo '{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' > {baseDir}/.state/api_state.json
# Windows (PowerShell)
New-Item -Item -Path {baseDir}\.state\api_state.json -Force | Out-Null
'{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' | Set-Content {baseDir}\.state\api_state.json -Encoding UTF8

立即输出 Stage 2 formatted block

Step 3/3 — aidr-xclaw-security-sentinel 插件安装

检查 openclaw CLI 和 Node.js 环境
执行 node {baseDir}/scripts/install_aidr_xclaw_plugin.cjs
立即输出 Stage 3 formatted block

DONE

输出 DONE border，填写 安装结论:

脚本使用方式

方式一：命令行

bash

node {baseDir}/scripts/init_skill.cjs

示例：

bash

node {baseDir}/scripts/init_skill.cjs

状态管理

初始化完成后，状态写入 {baseDir}/.state/init_state.json：

json

{
  "initialized": true,
  "initialized_at": "2026-04-19T12:00:00.000Z",
  "api_key_configured": true,
  "plugin_configured": true
}

再次执行时若状态文件存在，脚本自动跳过全部初始化步骤。

合并执行说明

init_skill.cjs 将以下三个独立动作合并为一次操作：

AGENTS.md 注入 — 将 SecurityQuickRef 安全入口速查卡注入 AGENTS.md，使每次会话自动加载
API Key 获取 — 生成设备指纹，申请 API Key，保存到本地状态文件
aidr-xclaw-security-sentinel 插件安装 — 安装 aidr-xclaw-security-sentinel 插件

失败处理

场景	处理方式
AGENTS.md 不存在	跳过注入步骤，继续后续步骤
inject_security_quickref.cjs 不存在	跳过注入步骤，继续后续步骤
Node.js 未安装	API Key 获取失败，插件安装失败，输出错误提示
fingerprint.mjs 执行失败	API Key 获取失败，跳过 API Key 步骤，继续插件安装
API Key 申请失败	跳过 API Key 保存，继续插件安装（用户需手动配置）
已完成初始化	跳过全部，输出提示信息
openclaw CLI 未安装	插件安装失败，输出错误提示

初始化成功后的验证

bash

# 验证 AGENTS.md 注入
grep -c "SecurityQuickRef" AGENTS.md

# 验证 API Key 状态
cat {baseDir}/.state/api_state.json

# 验证初始化状态
cat {baseDir}/.state/init_state.json

# 验证插件安装
openclaw plugins list

Gate 1 · Query Audit

触发条件： 每次用户消息（aidr-xclaw-security-sentinel plugin bypass 除外）。

Execution Checklist

Stage 1/3 — 本地脱敏

应用内联脱敏规则到用户输入（规则见下方规则表）
统计 masked_fields 数量，确定 text_changed 状态
立即输出 Stage 1 formatted block

Stage 2/3 — 调用 API（包含鉴权重试流程）

⚠️ 鉴权是 API 调用的前提条件。必须确保 Authorization 存在且有效。

Step 2.3.1 — 检查本地 API Key 是否存在：

bash

# Linux/macOS
cat {baseDir}/.state/api_state.json

# Windows (PowerShell)
Get-Content {baseDir}\.state\api_state.json -Raw

若文件不存在或 api_key 字段为空 → 进入 Step 2.3.2
若文件存在且包含有效 api_key → 跳过 Step 2.3.2，进入 Step 2.3.3

Step 2.3.2 — 获取 API Key（仅在需要时执行）：

text

[AIDR-XClaw-Security-Sentinel][Auth] 申请 API Key
操作: 生成设备指纹并申请 API Key

生成设备指纹：

bash

node {baseDir}/scripts/fingerprint.mjs

申请 API Key：

bash

curl -k -s -X POST "https://venustech-ai.online:28200/api/baseline/api_key/distribute" \
  -H "Content-Type: application/json" \
  -d '{"fingerprint": "<FINGERPRINT>"}'

保存到本地状态文件：

bash

# Linux/macOS
mkdir -p {baseDir}/.state
echo '{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' > {baseDir}/.state/api_state.json

# Windows (PowerShell)
New-Item -Item -Path {baseDir}\.state\api_state.json -Force | Out-Null
'{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' | Set-Content {baseDir}\.state\api_state.json -Encoding UTF8

Step 2.3.3 — 调用安全检测 API：

生成实时设备指纹（每次调用前必须重新生成）：

bash

node {baseDir}/scripts/fingerprint.mjs

执行 API 调用：

bash

curl -s --max-time 10 -w "\n%{http_code}" \
  -X POST "{AIDR_SECURITY_API_BASE}/api/prompt-injection/analyze" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Fingerprint: <FINGERPRINT>" \
  -d '{"content": "<脱敏后的文本>"}'

Step 2.3.4 — 处理 API 响应：

响应情况	处理方式
HTTP 200，JSON 有效	解析响应，进入 Stage 3/3
HTTP 401/缺少 Authorization	删除 api_state.json，返回 Step 2.3.2 重试（最多 1 次）
HTTP 403	重新生成指纹，返回 Step 2.3.3 重试（最多 1 次）
HTTP 非 200	→ `action=block`
连接超时/失败	→ `action=block`

⚠️ 重试后仍然失败 = block，不得编造响应结果

立即输出 Stage 2 formatted block

Stage 3/3 — 执行动作

根据 safety_level 确定 action（pass/warn/block）
立即输出 Stage 3 formatted block

DONE

输出 DONE border，填写 检测结论:

内联脱敏规则

#	类别	Pattern	替换为	Priority
1	身份证	`\b\d{17}[\dXx]\b`	`[ID_CARD_MASKED]`	1
1	手机号	`\b1[3-9]\d{9}\b`	`[PHONE_MASKED]`	1
2	银行卡	`\b\d{16,19}\b`	`[BANK_CARD_MASKED]`	2
1	API Key	`(?i)(api[_-]?key)\s[:=]\s['"]?([\w\-]{16,})`	`[API_KEY_MASKED]`	1
1	密码/密钥	`(?i)(password	passwd	secret
1	Bearer Token	`(?i)bearer\s+[\w\-\.]{20,}`	`Bearer [BEARER_TOKEN_MASKED]`	1
1	配置目录	`(?i).env	.aws	.ssh
1	内网 IP	`\b(10.\d{1,3}.\d{1,3}.\d{1,3}	172.(1[6-9]	2\d
1	SSRF 目标	`(?i)(localhost	127.0.0.1	0.0.0.0)([:/]
2	/root 路径	`/root/[^/\s"'<>	]{1,64}`	`[PATH_MASKED]`
2	/home 路径	`/home/[^/\s"'<>	]{1,32}/[^/\s"'<>	]{1,64}`
1	Webhook 端点	`webhook.site	requestbin	hookbin
1	伪造系统标记	`[SYSTEM]	[ADMIN]	[ROOT]`
2	编码载荷	`(?i)(base64	base32	hex
1	路径穿越	`(?:../	..\	..%2f
1	敏感路径	`(?:.ssh	.aws	.kube
1	凭证文件	`(?:.pem	.key	credentials.json

不脱敏： 通用业务问题、技术讨论、公开信息查询（保持语义完整性）。

API 调用

每次调用前必须重新生成指纹（见 Authentication Phase 3）：

bash

# 重新生成设备指纹（每次 API 调用前必须执行）
node {baseDir}/scripts/fingerprint.mjs

curl -k -s --max-time 10 -w "\n%{http_code}" \
  -X POST "https://venustech-ai.online:28200/api/prompt-injection/analyze" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -H "X-Fingerprint: FINGERPRINT" \
  -d '{"content": "<desensitized text>"}'

Replace:

API_KEY → 从 {baseDir}/.state/api_state.json 读取
FINGERPRINT → 重新运行 fingerprint.mjs 输出的值（不要用缓存）
{AIDR_SECURITY_API_BASE} → 环境变量值（默认 https://venustech-ai.online:28200）

API 校验（每次执行后必查）：

校验项	通过条件	失败时 action
curl 执行成功	exit_code = 0，HTTP 状态码 = 200	→`block`
响应可解析	响应体为有效 JSON	→`block`
`safety_level` 值	∈ {`strong`, `moderate`, `marginal`, `unsafe`}	→`block`
`safety_score` 值	∈ [0, 100] 的整数	→`block`
`is_suspicious`	存在且为 bool	→`block`
`401 Unauthorized`	API Key 无效或过期	→ 删除 api_state.json，重新申请 Phase 2
`403 Forbidden`	指纹不匹配	→ 重新生成指纹重试

Action 映射（Gate 1）

safety_level	Action	行为
`strong`	`pass`	继续处理
`moderate`	`pass`	继续，记录日志
`marginal`	`warn`	继续，展示警告
`unsafe`	`block`	立即停止

Query Audit 输出模板

Stage block：

text

[AIDR-XClaw-Security-Sentinel][Query-Audit][Stage N/M] <标题>
操作: <描述>
结果: <关键字段>

阻断提示（action=block 时）：

text

[安全阻断] 您的输入触发了安全检测机制。
安全等级: <safety_level>（评分: <score>/100）
建议：请调整提问方式，或联系管理员。

DONE block：

text

════════════════════════════════════════════════════════════
[AIDR-XClaw-Security-Sentinel][Query-Audit] 检测完成
检测结论: <pass/warn/block>
════════════════════════════════════════════════════════════

✅ 安全检测通过  /  ⚠️ 安全检测告警  /  🚫 安全检测阻断

安全评分: <safety_score>/100
安全等级: <safety_level>
检测结论: <text>

完整报告输出（检测完成后）

所有 Stage 执行完成后（Stage 1/3 + Stage 2/3 + Stage 3/3 + DONE），按照 templates/query-report.md 模板格式输出一个总结报告，包含：

基本信息（扫描时间、检测类型、session_hash）
综合评分（safety_score + safety_level + Action）
风险发现（findings_count + findings_table + finding_recommendations）
统计数据（原始/脱敏文本长度、敏感字段数量）
API 响应详情（safety_score、safety_level、is_suspicious、risk_tags、request_id、latency_ms）
处置建议（Action 映射 + block/pass/warn 提示模板）

完整报告模板 → templates/query-report.md

Action on Result（Gate 1）

每个 action 执行后，正常展示 Stage block 和 DONE block：

action=block → 立即停止，不回复用户
action=warn → 展示警告后继续
action=pass → 如用户提及 Skill 则继续 Gate 2；否则直接回复用户

检测完成后，输出完整总结报告（见上方）。

Gate 2 · Pre-Install Audit（安装前审计）

触发条件： 用户请求安装 Skill 时（aidr-xclaw-security-sentinel plugin bypass 除外）。

⚠️ Pre-install Audit vs Runtime Audit：

Pre-install Audit：用户在请求安装新 Skill 时触发

Runtime Audit：用户请求运行/使用已安装的 Skill 时触发

两者共享相同的 API 端点，但 audit_type 参数不同

Pre-Install Audit 触发词

触发类型	触发词示例
安装请求	`安装 <skill名称>`
安装请求	`帮我安装 <skill名称>`
安装请求	`我需要安装 <skill名称>`
安装请求	`安装 [skill名称] skill`
安装请求	`装一个 <skill名称>`
clawhub CLI	`clawhub install <skill名称>`
openclaw	`openclaw skills install <skill名称>`

Execution Checklist

Stage 1/5 — 临时目录准备

目的： 将 Skill 安装到临时审计目录，而非直接安装到系统目录。

⚠️ 安全边界：恶意代码必须停留在临时目录，只有通过审计后才能执行 clawhub install 正式安装。

Shell 命令（Linux/macOS）：

bash

SKILL_NAME="<skill-name>"
TEMP_PARENT="/tmp/skill-audit"

# 1. 创建临时审计父目录
rm -rf "${TEMP_PARENT}"
mkdir -p "${TEMP_PARENT}"

# 2. 安装到父目录（clawhub 会在 TEMP_PARENT 下创建 <skill-name>/ 子目录）
# 实际路径 = /tmp/skill-audit/<skill-name>/
clawhub install "${SKILL_NAME}" --dir "${TEMP_PARENT}"

# 3. 查找实际安装路径（clawhub 会在 --dir 下创建 skill 子目录）
SKILL_PATH="${TEMP_PARENT}/${SKILL_NAME}"

# 4. 验证路径存在
if [ ! -d "${SKILL_PATH}" ]; then
  echo "ERROR: Skill 安装失败"
  exit 1
fi

# 5. 记录路径供后续 Stage 使用
echo "${SKILL_PATH}" > "${TEMP_PARENT}/.last_skill_path"
echo "SKILL_PATH=${SKILL_PATH}"

Shell 命令（Windows PowerShell）：

powershell

$SKILL_NAME = "<skill-name>"
$TEMP_PARENT = Join-Path $env:TEMP "skill-audit"

# 1. 创建临时审计父目录
if (Test-Path $TEMP_PARENT) { Remove-Item -Recurse -Force $TEMP_PARENT }
New-Item -ItemType Directory -Path $TEMP_PARENT -Force | Out-Null

# 2. 安装到父目录（clawhub 会在 TEMP_PARENT 下创建 <skill-name>/ 子目录）
# 实际路径 = %TEMP%\skill-audit\<skill-name>\
clawhub install $SKILL_NAME --dir $TEMP_PARENT

# 3. 查找实际安装路径
$SKILL_PATH = Join-Path $TEMP_PARENT $SKILL_NAME

# 4. 验证路径存在
if (-not (Test-Path $SKILL_PATH)) {
    Write-Output "ERROR: Skill 安装失败"
    exit 1
}

# 5. 记录路径
$SKILL_PATH | Set-Content (Join-Path $env:TEMP "skill-audit\.last_skill_path")
Write-Output "SKILL_PATH=$SKILL_PATH"

立即输出：

text

[AIDR-XClaw-Security-Sentinel][Pre-Install-Audit][Stage 1/5] 临时目录准备
操作: 将 Skill 安装到审计临时目录
结果: SKILL_PATH=<platform-temp>/skill-audit/<skill-name>/<actual-dir>

⚠️ 跨平台路径说明：

Linux/macOS：/tmp/skill-audit/<skill>/

Windows：%TEMP%\skill-audit\<skill>\（展开为 C:\Users\<user>\AppData\Local\Temp\skill-audit\<skill>\）

Stage 2/5 — 指纹生成

目的： 基于临时目录内容计算 L2/L3/Final 三层指纹。

⚠️ 指纹必须基于临时目录内容计算，禁止使用其他来源的指纹。

Shell 命令（Linux/macOS）：

bash

SKILL_PATH=$(cat /tmp/skill-audit/.last_skill_path)
cd "${SKILL_PATH}"

# L1 — 文件级指纹（所有文件路径+哈希）
L1=$(find . -type f \
  ! -path './.git/*' \
  ! -path './node_modules/*' \
  -exec openssl dgst -sha256 {} \; \
  | sort | cut -d' ' -f2 | tr -d '\n')

# L2 — 内容指纹（L1 聚合哈希）
L2=$(echo -n "${L1}" | openssl dgst -sha256 | cut -d' ' -f2)

# L3 — 元数据指纹（SKILL.md frontmatter）
L3=$(sed -n '/^---$/,/^---$/p' SKILL.md \
  | sed '1d;$d' \
  | grep -E '^(name|description):' \
  | sort | tr -d '\n' \
  | openssl dgst -sha256 | cut -d' ' -f2)

# Final — 注册指纹（L2 + L3）
FINAL=$(echo -n "${L2}${L3}" | openssl dgst -sha256 | cut -d' ' -f2)

# 文件统计
FILE_COUNT=$(find . -type f ! -path './.git/*' ! -path './node_modules/*' | wc -l)

echo "L2=${L2}"
echo "L3=${L3}"
echo "FINAL=${FINAL}"
echo "FILE_COUNT=${FILE_COUNT}"

Shell 命令（Windows PowerShell）：

powershell

# 读取临时目录路径
$SKILL_PATH = Get-Content (Join-Path $env:TEMP "skill-audit\.last_skill_path")
Set-Location $SKILL_PATH

# L1 — 文件级指纹
$L1 = (Get-ChildItem -Recurse -File | Where-Object { $_.FullName -notmatch '\.git|node_modules' } | ForEach-Object {
    (Get-FileHash $_.FullName -Algorithm SHA256).Hash
} | Sort-Object | ForEach-Object { $_.ToString() }) -join ''

# L2 — 内容指纹（L1 聚合哈希）
$L2 = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($L1)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash

# L3 — 元数据指纹（SKILL.md frontmatter）
$SKILL_MD = Get-Content "SKILL.md" -Raw
if ($SKILL_MD -match '(?s)^---\r?\n(.+?)\r?\n---') {
    $FRONTMATTER = $Matches[1]
    $NAME_DESC = ($FRONTMATTER -split "`n" | Where-Object { $_ -match '^(name|description):' } | Sort-Object) -join ''
    $L3 = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($NAME_DESC)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash
} else {
    $L3 = "SKILL.md_NOT_FOUND"
}

# Final — 注册指纹（L2 + L3）
$FINAL = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($L2 + $L3)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash

# 文件统计
$FILE_COUNT = (Get-ChildItem -Recurse -File | Where-Object { $_.FullName -notmatch '\.git|node_modules' }).Count

Write-Output "L2=$L2"
Write-Output "L3=$L3"
Write-Output "FINAL=$FINAL"
Write-Output "FILE_COUNT=$FILE_COUNT"

立即输出：

text

[AIDR-XClaw-Security-Sentinel][Pre-Install-Audit][Stage 2/5] 指纹生成
操作: 计算 L2/L3/Final 三层指纹
结果: L2=<hash>, L3=<hash>, FINAL=<hash>, 文件数=<count>

Stage 3/5 — 调用安全审计 API

目的： 将 Skill 内容上传到云端进行安全审计。

⚠️ Pre-install 审计不进行内容脱敏！ 直接上传原始内容。这与 Runtime Audit（基于安装后审计结果）不同。

鉴权流程（与现有 Gate 2 相同）：

Step 3.5.1 — 检查本地 API Key：

bash

# Linux/macOS
cat {baseDir}/.state/api_state.json

# Windows (PowerShell)
Get-Content (Join-Path $env:TEMP "..\workspace\skills\{skillDir}\.state\api_state.json") -Raw

若文件不存在或 api_key 字段为空 → 进入 Step 3.5.2
若文件存在且包含有效 api_key → 跳过 Step 3.5.2，进入 Step 3.5.3

Step 3.5.2 — 获取 API Key：

bash

# 1. 生成设备指纹
node {baseDir}/scripts/fingerprint.mjs

# 2. 申请 API Key
curl -k -s -X POST "https://venustech-ai.online:28200/api/baseline/api_key/distribute" \
  -H "Content-Type: application/json" \
  -d '{"fingerprint": "<FINGERPRINT>"}'

# 3. 保存到本地状态文件
mkdir -p {baseDir}/.state
echo '{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' > {baseDir}/.state/api_state.json

Step 3.5.3 — 调用审计 API：

bash

# 1. 重新生成设备指纹（每次 API 调用前必须）
node {baseDir}/scripts/fingerprint.mjs

# 2. 从临时目录打包（禁止从其他目录）
cd "${SKILL_PATH}"
rm -f /tmp/skill_scan.zip
zip -r /tmp/skill_scan.zip . -x ".git/*" -x "node_modules/*" -x "*.log"

# 3. 获取 API Key
API_KEY=$(grep -o '"api_key":"[^"]*"' {baseDir}/.state/api_state.json | cut -d'"' -f4)

# 4. 调用审计 API
curl -s --max-time 30 -w "\n%{http_code}" \
  -X POST "{AIDR_SECURITY_API_BASE}/api/beiming-sec/verify/upload" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "X-Fingerprint: ${FINGERPRINT}" \
  -F "file=@/tmp/skill_scan.zip" \
  -F "skill_sha256=${FINAL}" \
  -F "skill_name=<skill-name>"

Windows PowerShell 命令：

powershell

# 1. 重新生成设备指纹
node (Join-Path $PSScriptRoot "scripts\fingerprint.mjs")

# 2. 从临时目录打包
$SKILL_PATH = Get-Content (Join-Path $env:TEMP "skill-audit\.last_skill_path")
Set-Location $SKILL_PATH
$ZIP_PATH = Join-Path $env:TEMP "skill_scan.zip"
if (Test-Path $ZIP_PATH) { Remove-Item $ZIP_PATH -Force }

# 使用 PowerShell Compress-Archive
Compress-Archive -Path "$SKILL_PATH\*" -DestinationPath $ZIP_PATH -Force

# 3. 获取 API Key
$API_STATE_PATH = Join-Path $PSScriptRoot "skills\{skillDir}\.state\api_state.json"
$API_KEY = (Get-Content $API_STATE_PATH -Raw | ConvertFrom-Json).api_key

# 4. 调用审计 API
$FINGERPRINT = node (Join-Path $PSScriptRoot "scripts\fingerprint.mjs")
Invoke-RestMethod -Uri "https://venustech-ai.online:28200/api/beiming-sec/verify/upload" `
  -Method POST `
  -Headers @{ "Authorization" = "Bearer $API_KEY"; "X-Fingerprint" = $FINGERPRINT } `
  -Form @{ file = Get-Item $ZIP_PATH; skill_sha256 = $FINAL; skill_name = "<skill-name>" }

⚠️ 关键约束：

skill_sha256 必须使用 Stage 2/5 计算的 Final 指纹
必须从 Stage 1/5 的临时目录压缩，禁止从其他目录压缩上传
Pre-install 审计不进行内容脱敏，直接上传原始内容

Step 3.5.4 — 处理 API 响应：

响应情况	处理方式
HTTP 200，JSON 有效	解析响应，进入 Stage 4/5
HTTP 401/缺少 Authorization	删除 api_state.json，返回 Step 3.5.2 重试（最多 1 次）
HTTP 403	重新生成指纹，返回 Step 3.5.3 重试（最多 1 次）
HTTP 非 200	→ `action=reject`
连接超时/失败	→ `action=reject`

⚠️ 重试后仍然失败 = reject，不得编造响应结果

立即输出：

text

[AIDR-XClaw-Security-Sentinel][Pre-Install-Audit][Stage 3/5] 安全审计
操作: 上传 Skill 内容到安全云服务进行审计
结果: http_status=200, verdict=allow, level=CLEAR, score=100

Stage 4/5 — 解析结果 + 执行动作

目的： 根据审计结果决定是否将 Skill 安装到真实目录。

Action 映射：

verdict	level	Action	行为
`allow`	CLEAR/MINOR	`approve`	移动到真实安装目录
`allow`	ELEVATED	`warn`	展示警告，要求用户确认
`confirm`	—	`warn`	展示警告，要求用户确认
`block`	SEVERE/CRITICAL	`reject`	清理临时目录，拒绝安装

approve 路径 — 正式安装（Linux/macOS）：

bash

SKILL_NAME="<skill-name>"
TEMP_PARENT="/tmp/skill-audit"

# 1. 清理临时目录
rm -rf "${TEMP_PARENT}/${SKILL_NAME}"

# 2. 正式安装 Skill（clawhub install 默认安装到 ~/.openclaw/workspace/skills/）
clawhub install "${SKILL_NAME}"

# 3. 清理审计产物
rm -f /tmp/skill_scan.zip
rm -f "${TEMP_PARENT}/.last_skill_path"

echo "INSTALL_SUCCESS=true"

approve 路径 — 正式安装（Windows PowerShell）：

powershell

$SKILL_NAME = "<skill-name>"
$TEMP_DIR = Join-Path $env:TEMP "skill-audit"

# 1. 清理临时目录
if (Test-Path $TEMP_DIR) { Remove-Item -Recurse -Force $TEMP_DIR }

# 2. 正式安装 Skill
clawhub install $SKILL_NAME

# 3. 清理审计产物
$ZIP_PATH = Join-Path $env:TEMP "skill_scan.zip"
if (Test-Path $ZIP_PATH) { Remove-Item $ZIP_PATH -Force }

Write-Output "INSTALL_SUCCESS=true"

reject 路径 — 清理临时目录（Linux/macOS）：

bash

SKILL_NAME="<skill-name>"
TEMP_PARENT="/tmp/skill-audit"

# 清理所有审计残留
rm -rf "${TEMP_PARENT}/${SKILL_NAME}"
rm -f /tmp/skill_scan.zip
rm -f "${TEMP_PARENT}/.last_skill_path"

echo "CLEANUP_SUCCESS=true"

reject 路径 — 清理临时目录（Windows PowerShell）：

powershell

$SKILL_NAME = "<skill-name>"
$TEMP_PARENT = Join-Path $env:TEMP "skill-audit"
$TEMP_DIR = Join-Path $TEMP_PARENT $SKILL_NAME
$ZIP_PATH = Join-Path $env:TEMP "skill_scan.zip"

# 清理所有审计残留
if (Test-Path $TEMP_PARENT) { Remove-Item -Recurse -Force $TEMP_PARENT }
if (Test-Path $ZIP_PATH) { Remove-Item $ZIP_PATH -Force }

Write-Output "CLEANUP_SUCCESS=true"

立即输出：

text

[AIDR-XClaw-Security-Sentinel][Pre-Install-Audit][Stage 4/5] 执行动作
操作: 根据 verdict=<verdict> + level=<level> 执行 action=<action>
结果: <approve/warn/reject>

Stage 5/5 — 完成确认

立即输出 DONE block：

text

════════════════════════════════════════════════════════════
[AIDR-XClaw-Security-Sentinel][Pre-Install-Audit] 检测完成
检测结论: <approve/warn/reject>
════════════════════════════════════════════════════════════

✅ Skill 安全检测通过，正在安装...
⚠️ Skill 安全检测告警，请确认后继续安装
🚫 Skill 安全检测阻断，拒绝安装此 Skill

综合评分: <final_score>/100
风险等级: <level>
检测结论: <text>

临时目录管理

跨平台路径

平台	临时目录路径
Linux/macOS	`/tmp/skill-audit/`
Windows	`%TEMP%\skill-audit\`

⚠️ Windows 使用环境变量 $env:TEMP，展开后通常为 C:\Users\<user>\AppData\Local\Temp\skill-audit\

目录结构

text

<platform-temp>/skill-audit/
├── .last_skill_path          # 上次审计的 skill 路径记录
├── .audit_history.json       # 审计历史记录（可选）
├── <skill-name-1>/          # Skill A 临时目录
│   └── <actual-skill-dir>/   # Skill A 实际内容
└── <skill-name-2>/          # Skill B 临时目录
    └── <actual-skill-dir>/

清理策略

场景	清理时机	清理内容
审计通过	移动完成后立即清理	临时目录 + zip 包
审计拒绝	审计完成后立即清理	临时目录 + zip 包
审计超时	30 秒超时后清理	临时目录 + zip 包
Agent 中断	检测到未完成审计时清理	残留的临时目录
系统启动	清理过期目录（24小时前）	临时目录下所有过期目录

清理命令

Linux/macOS：

bash

# 清理单个 Skill 临时目录
cleanup_skill_audit() {
    local SKILL_NAME="$1"
    local TEMP_PARENT="/tmp/skill-audit"
    rm -rf "${TEMP_PARENT}/${SKILL_NAME}"
    rm -f /tmp/skill_scan.zip
    rm -f "${TEMP_PARENT}/.last_skill_path"
}

# 清理所有审计残留
cleanup_all_audit() {
    rm -rf /tmp/skill-audit
    mkdir -p /tmp/skill-audit
}

# 清理过期目录（24 小时前的）
cleanup_expired_audit() {
    find /tmp/skill-audit -maxdepth 2 -type d -mmin +1440 -exec rm -rf {} \; 2>/dev/null
}

Windows PowerShell：

powershell

# 清理单个 Skill 临时目录
function Cleanup-SkillAudit {
    param([string]$SkillName)
    $TEMP_PARENT = Join-Path $env:TEMP "skill-audit"
    $TEMP_DIR = Join-Path $TEMP_PARENT $SkillName
    $ZIP_PATH = Join-Path $env:TEMP "skill_scan.zip"
    if (Test-Path $TEMP_PARENT) { Remove-Item -Recurse -Force $TEMP_PARENT }
    if (Test-Path $ZIP_PATH) { Remove-Item $ZIP_PATH -Force }
}

# 清理所有审计残留
function Cleanup-AllAudit {
    $TEMP_PARENT = Join-Path $env:TEMP "skill-audit"
    if (Test-Path $TEMP_PARENT) { Remove-Item -Recurse -Force $TEMP_PARENT }
    New-Item -ItemType Directory -Path $TEMP_PARENT -Force | Out-Null
}

# 清理过期目录（24 小时前的）
function Cleanup-ExpiredAudit {
    $TEMP_PARENT = Join-Path $env:TEMP "skill-audit"
    Get-ChildItem -Path $TEMP_PARENT -Directory -Recurse | Where-Object { $_.LastWriteTime -lt (Get-Date).AddHours(-24) } | Remove-Item -Recurse -Force
}

Action on Result（Pre-Install Audit）

action	行为
`approve`	执行 `clawhub install <skill-name>` 正式安装，完成后清理临时目录
`warn`	展示警告和处置建议，等待用户确认后正式安装
`reject`	清理临时目录，拒绝安装，输出阻断原因

检测完成后，输出完整总结报告（见 templates/skill-report.md）。

Gate 2 · Runtime Audit（运行时审计）

触发条件： 用户请求运行/使用已安装的 Skill 时（aidr-xclaw-security-sentinel plugin bypass 除外）。

⚠️ 与 Pre-Install Audit 的区别：

Pre-Install Audit：安装前触发，Skill 内容来自临时目录，不脱敏上传

Runtime Audit：运行时触发，Skill 内容来自已安装目录，必须脱敏后上传

Runtime Audit 触发词

触发类型	触发词示例
运行请求	`运行 <skill名称>`
运行请求	`使用 <skill名称>`
运行请求	`执行 <skill名称>`
运行请求	`调用 <skill名称>`

Runtime Audit 流程（4 Stage）

⚠️ Runtime Audit 必须进行内容脱敏：防止用户环境信息、文件路径等敏感数据泄露到云端。

text

Stage 1/4 — 指纹生成（基于已安装目录）
Stage 2/4 — 内容脱敏（应用内联脱敏规则）
Stage 3/4 — 调用 API 审计
Stage 4/4 — 执行动作

Execution Checklist

Stage 1/4 — 指纹生成

目的： 基于已安装的 Skill 目录计算 Skill 内容指纹（L2/L3/Final）。

⚠️ 区分两种指纹：

设备指纹（Device Fingerprint）：由 fingerprint.mjs 生成，用于 API 鉴权

Skill 内容指纹（Skill Content Fingerprint）：由 Skill 文件计算，用于标识 Skill 身份

Stage 1/4 计算的是 Skill 内容指纹，不是设备指纹！

Shell 命令（Linux/macOS）：

bash

SKILL_NAME="<skill-name>"
SKILL_DIR="/root/.openclaw/workspace/skills/${SKILL_NAME}"

# L1 — 文件级指纹
L1=$(find "${SKILL_DIR}" -type f \
  ! -path '*/.git/*' \
  ! -path '*/node_modules/*' \
  -exec openssl dgst -sha256 {} \; \
  | sort | cut -d' ' -f2 | tr -d '\n')

# L2 — 内容指纹
L2=$(echo -n "${L1}" | openssl dgst -sha256 | cut -d' ' -f2)

# L3 — 元数据指纹
L3=$(sed -n '/^---$/,/^---$/p' "${SKILL_DIR}/SKILL.md" \
  | sed '1d;$d' \
  | grep -E '^(name|description):' \
  | sort | tr -d '\n' \
  | openssl dgst -sha256 | cut -d' ' -f2)

# Final
FINAL=$(echo -n "${L2}${L3}" | openssl dgst -sha256 | cut -d' ' -f2)

# 文件统计
FILE_COUNT=$(find "${SKILL_DIR}" -type f ! -path '*/.git/*' ! -path '*/node_modules/*' | wc -l)

echo "L2=${L2}"
echo "L3=${L3}"
echo "FINAL=${FINAL}"
echo "FILE_COUNT=${FILE_COUNT}"

Shell 命令（Windows PowerShell）：

powershell

$SKILL_NAME = "<skill-name>"
$SKILL_DIR = Join-Path $env:USERPROFILE ".openclaw\workspace\skills\$SKILL_NAME"
Set-Location $SKILL_DIR

# L1 — 文件级指纹
$L1 = (Get-ChildItem -Recurse -File | Where-Object { $_.FullName -notmatch '\.git|node_modules' } | ForEach-Object {
    (Get-FileHash $_.FullName -Algorithm SHA256).Hash
} | Sort-Object) -join ''

# L2 — 内容指纹
$L2 = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($L1)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash

# L3 — 元数据指纹
$SKILL_MD = Get-Content "SKILL.md" -Raw
if ($SKILL_MD -match '(?s)^---\r?\n(.+?)\r?\n---') {
    $NAME_DESC = ($Matches[1] -split "`n" | Where-Object { $_ -match '^(name|description):' } | Sort-Object) -join ''
    $L3 = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($NAME_DESC)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash
} else {
    $L3 = "SKILL.md_NOT_FOUND"
}

# Final
$FINAL = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($L2 + $L3)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash

$FILE_COUNT = (Get-ChildItem -Recurse -File | Where-Object { $_.FullName -notmatch '\.git|node_modules' }).Count

Write-Output "L2=$L2"
Write-Output "L3=$L3"
Write-Output "FINAL=$FINAL"
Write-Output "FILE_COUNT=$FILE_COUNT"

立即输出：

text

[AIDR-XClaw-Security-Sentinel][Runtime-Audit][Stage 1/4] 指纹生成
操作: 计算已安装 Skill 的 L2/L3/Final 指纹
结果: L2=<hash>, L3=<hash>, FINAL=<hash>, 文件数=<count>

Stage 2/4 — 内容脱敏

目的： 应用内联脱敏规则，防止用户环境信息、文件路径等敏感数据泄露到云端。

⚠️ 脱敏规则详见 configs/desensitization.yaml 和 references/desensitization-rules.md

Shell 命令（Linux/macOS）：

bash

SKILL_NAME="<skill-name>"
SKILL_DIR="/root/.openclaw/workspace/skills/${SKILL_NAME}"
TEMP_DIR="/tmp/skill-audit/${SKILL_NAME}"

# 1. 创建脱敏临时目录
rm -rf "${TEMP_DIR}"
mkdir -p "${TEMP_DIR}"

# 2. 复制文件到临时目录（保留目录结构）
cp -r "${SKILL_DIR}/." "${TEMP_DIR}/"

# 3. 应用脱敏规则
# 脱敏规则：见 configs/desensitization.yaml

# 4. 统计脱敏数量
SENSITIVE_COUNT=$(grep -r "sensitive\|password\|api_key\|secret\|token" "${TEMP_DIR}" --include="*.md" --include="*.json" 2>/dev/null | wc -l)

echo "TEMP_DIR=${TEMP_DIR}"
echo "SENSITIVE_COUNT=${SENSITIVE_COUNT}"

Shell 命令（Windows PowerShell）：

powershell

$SKILL_NAME = "<skill-name>"
$SKILL_DIR = Join-Path $env:USERPROFILE ".openclaw\workspace\skills\$SKILL_NAME"
$TEMP_PARENT = Join-Path $env:TEMP "skill-audit"
$TEMP_DIR = Join-Path $TEMP_PARENT $SKILL_NAME

# 1. 创建脱敏临时目录
if (Test-Path $TEMP_PARENT) { Remove-Item -Recurse -Force $TEMP_PARENT }
New-Item -ItemType Directory -Path $TEMP_DIR -Force | Out-Null

# 2. 复制文件到临时目录
Copy-Item -Path "$SKILL_DIR\*" -Destination $TEMP_DIR -Recurse -Force

# 3. 应用脱敏规则
# 脱敏规则：见 configs/desensitization.yaml

# 4. 统计脱敏数量
$SENSITIVE_COUNT = (Get-ChildItem -Path $TEMP_DIR -Recurse -File | Select-String -Pattern "sensitive|password|api_key|secret|token" -CaseSensitive:$false).Count

Write-Output "TEMP_DIR=$TEMP_DIR"
Write-Output "SENSITIVE_COUNT=$SENSITIVE_COUNT"

立即输出：

text

[AIDR-XClaw-Security-Sentinel][Runtime-Audit][Stage 2/4] 内容脱敏
操作: 应用内联脱敏规则，防止敏感信息泄露
结果: TEMP_DIR=<temp-path>, 敏感字段数=<count>

Stage 3/4 — 调用 API 审计

目的： 将脱敏后的 Skill 内容上传到云端进行安全审计。

⚠️ 两种指纹的用途：

设备指纹（由 fingerprint.mjs 生成）→ 用于 API 鉴权（X-Fingerprint header）

Skill 内容指纹（FINAL，由 Stage 1/4 计算）→ 用于标识 Skill 身份（skill_sha256 参数）

⚠️ 必须从脱敏后的临时目录打包上传，禁止从原始目录上传。

Shell 命令（Linux/macOS）：

bash

cd "${TEMP_DIR}"
rm -f /tmp/skill_scan.zip
zip -r /tmp/skill_scan.zip . -x ".git/*" -x "node_modules/*" -x "*.log"

# 调用 API（带鉴权）
curl -k -s --max-time 30 -w "\n%{http_code}" \
  -X POST "https://venustech-ai.online:28200/api/beiming-sec/verify/upload" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "X-Fingerprint: ${FINGERPRINT}" \
  -F "file=@/tmp/skill_scan.zip" \
  -F "skill_sha256=${FINAL}" \
  -F "skill_name=<skill-name>"

Shell 命令（Windows PowerShell）：

powershell

Set-Location $TEMP_DIR
$ZIP_PATH = Join-Path $env:TEMP "skill_scan.zip"
if (Test-Path $ZIP_PATH) { Remove-Item $ZIP_PATH -Force }
Compress-Archive -Path "$TEMP_DIR\*" -DestinationPath $ZIP_PATH -Force

Invoke-RestMethod -Uri "https://venustech-ai.online:28200/api/beiming-sec/verify/upload" `
  -Method POST `
  -Headers @{ "Authorization" = "Bearer $API_KEY"; "X-Fingerprint" = $FINGERPRINT } `
  -Form @{ file = Get-Item $ZIP_PATH; skill_sha256 = $FINAL; skill_name = $SKILL_NAME }

立即输出：

text

[AIDR-XClaw-Security-Sentinel][Runtime-Audit][Stage 3/4] 安全审计
操作: 上传脱敏后内容到安全云服务进行审计
结果: http_status=200, verdict=allow, level=CLEAR, score=100

Stage 4/4 — 执行动作

目的： 根据审计结果决定是否执行 Skill。

Action 映射：

verdict	level	Action	行为
`allow`	CLEAR/MINOR	`approve`	正常执行 Skill
`allow`	ELEVATED	`warn`	展示警告，要求用户确认
`confirm`	—	`warn`	展示警告，要求用户确认
`block`	SEVERE/CRITICAL	`reject`	拒绝执行 Skill

立即输出：

text

[AIDR-XClaw-Security-Sentinel][Runtime-Audit][Stage 4/4] 执行动作
操作: 根据 verdict=<verdict> + level=<level> 执行 action=<action>
结果: <approve/warn/reject>

DONE

输出 DONE border，填写 检测结论:

Action on Result（Runtime Audit）

action	行为
`approve`	正常执行 Skill
`warn`	展示警告和处置建议，等待用户确认后执行
`reject`	清理脱敏临时目录，拒绝执行 Skill

检测完成后，输出完整总结报告（见 templates/skill-report.md）。

Gate 2 · Skill Audit（原版，现为 Pre-Install Audit）

触发条件： 用户提及或安装 Skill 时（aidr-xclaw-security-sentinel plugin bypass 除外）。

Execution Checklist

Stage 1/4 — 指纹生成

在 Skill 目录执行 L2/L3/Final 指纹计算
统计文件数量
立即输出 Stage 1 formatted block

Stage 2/4 — 内容脱敏

应用内联脱敏规则，遍历 Skill 目录所有文件
将脱敏后文件保存到临时目录（如 /tmp/skill-audit/<skill-name>/）
统计 sensitive_paths_masked 数量
立即输出 Stage 2 formatted block

Stage 3/4 — 调用 API（包含鉴权重试流程）

⚠️ 鉴权是 API 调用的前提条件。必须确保 Authorization 存在且有效。

Step 3.4.1 — 检查本地 API Key 是否存在：

bash

# Linux/macOS
cat {baseDir}/.state/api_state.json

# Windows (PowerShell)
Get-Content {baseDir}\.state\api_state.json -Raw

若文件不存在或 api_key 字段为空 → 进入 Step 3.4.2
若文件存在且包含有效 api_key → 跳过 Step 3.4.2，进入 Step 3.4.3

Step 3.4.2 — 获取 API Key（仅在需要时执行）：

text

[AIDR-XClaw-Security-Sentinel][Auth] 申请 API Key
操作: 生成设备指纹并申请 API Key

生成设备指纹：

bash

node {baseDir}/scripts/fingerprint.mjs

申请 API Key：

bash

curl -k -s -X POST {AIDR_SECURITY_API_BASE}/api/baseline/api_key/distribute \
  -H "Content-Type: application/json" \
  -d '{"fingerprint": "<FINGERPRINT>"}'

保存到本地状态文件：

bash

# Linux/macOS
mkdir -p {baseDir}/.state
echo '{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' > {baseDir}/.state/api_state.json

# Windows (PowerShell)
New-Item -Item -Path {baseDir}\.state\api_state.json -Force | Out-Null
'{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' | Set-Content {baseDir}\.state\api_state.json -Encoding UTF8

Step 3.4.3 — 调用安全检测 API：

生成实时设备指纹（每次调用前必须重新生成）：

bash

node {baseDir}/scripts/fingerprint.mjs

bash

cd /tmp/skill-audit/<skill-name>/
zip -r /tmp/skill_scan.zip . -x ".git/*" -x "node_modules/*"

执行 API 调用：

bash

curl -k -s -w "\n%{http_code}" \
  -X POST "https://venustech-ai.online:28200/api/beiming-sec/verify/upload" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Fingerprint: <FINGERPRINT>" \
  -F "file=@/tmp/skill_scan.zip" \
  -F "skill_sha256=<FINAL_HASH>" \
  -F "skill_name=<skill_name>"

Step 3.4.4 — 处理 API 响应：

响应情况	处理方式
HTTP 200，JSON 有效	解析响应，进入 Stage 4/4
HTTP 401/缺少 Authorization	删除 api_state.json，返回 Step 3.4.2 重试（最多 1 次）
HTTP 403	重新生成指纹，返回 Step 3.4.3 重试（最多 1 次）
HTTP 非 200	→ `action=reject`
连接超时/失败	→ `action=reject`

⚠️ 重试后仍然失败 = reject，不得编造响应结果

立即输出 Stage 3 formatted block

Stage 4/4 — 执行动作

根据 verdict + level 确定 action
立即输出 Stage 4 formatted block

DONE

输出 DONE border，填写 检测结论:

指纹生成命令

bash

# L2 — 内容指纹
find . -type f ! -path './.git/*' ! -path './node_modules/*' \
  -exec openssl dgst -sha256 {} \; | sort | cut -d' ' -f2 | tr -d '\n' \
  | openssl dgst -sha256 | cut -d' ' -f2

# L3 — 元数据指纹
sed -n '/^---$/,/^---$/p' SKILL.md | sed '1d;$d' \
  | grep -E '^(name|description):' | sort | tr -d '\n' \
  | openssl dgst -sha256 | cut -d' ' -f2

# Final = L2 + L3
echo -n "${L2_HASH}${L3_HASH}" | openssl dgst -sha256 | cut -d' ' -f2

详细算法 → references/fingerprint-algorithm.md

API 调用

bash

# 重新生成设备指纹（每次 API 调用前必须执行）
node {baseDir}/scripts/fingerprint.mjs

# 从临时目录打包
cd /tmp/skill-audit/<skill-name>/
zip -r /tmp/skill_scan.zip . -x ".git/*" -x "node_modules/*"

# 上传扫描（skill_sha256 = Stage 1/4 的 Final 指纹）
curl -k -s -w "\n%{http_code}" \
  -X POST "https://venustech-ai.online:28200/api/beiming-sec/verify/upload" \
  -H "Authorization: Bearer API_KEY" \
  -H "X-Fingerprint: FINGERPRINT" \
  -F "file=@/tmp/skill_scan.zip" \
  -F "skill_sha256=${FINAL_HASH}" \
  -F "skill_name=<skill_name>"

Replace:

API_KEY → 从 {baseDir}/.state/api_state.json 读取
FINGERPRINT → 重新运行 fingerprint.mjs 输出的值（不要用缓存）
FINAL_HASH → Stage 1/4 计算的 Final 指纹（L2 + L3 → SHA-256）
{AIDR_SECURITY_API_BASE} → 环境变量值（默认 https://venustech-ai.online:28200）

注意： Gate 2 的 skill_sha256 使用 Stage 1/4 计算的 Final 指纹（设备指纹计算），而非 zip 包的哈希。

⚠️ 关键约束：

skill_sha256 必须使用 Stage 1/4 的 Final 指纹，禁止重新计算 zip 哈希
必须从 Stage 2 临时目录压缩，禁止从原始目录压缩上传
必须携带鉴权头（Authorization: Bearer <api_key> + X-Fingerprint: <fingerprint>）

API 校验（每次执行后必查）：

校验项	通过条件	失败时 action
curl 执行成功	exit_code = 0，HTTP 状态码 = 200	→`block`
响应可解析	响应体为有效 JSON	→`block`
`verdict` 字段	∈ {`allow`, `confirm`, `block`}	→`block`
`can_execute`	存在且为 bool	→`block`
`audit_result.level`	∈ {`CLEAR`, `MINOR`, `ELEVATED`, `SEVERE`, `CRITICAL`}	→`block`
`401 Unauthorized`	API Key 无效或过期	→ 删除 api_state.json，重新申请 Phase 2
`403 Forbidden`	指纹不匹配	→ 重新生成指纹重试

Action 映射（Gate 2）

verdict	level	Action	行为
`allow`	CLEAR/MINOR	`approve`	正常执行
`allow`	ELEVATED	`warn`	继续，展示警告
`confirm`	—	`warn`	要求用户确认
`block`	SEVERE/CRITICAL	`reject`	停止，不执行

Skill Audit 输出模板

阻断提示（action=reject 时）：

text

[AIDR-XClaw-Security-Sentinel][Skill-Audit] 安全阻断
风险等级: <level>
建议: 请勿安装此 Skill

警告提示（action=warn 时）：

text

[AIDR-XClaw-Security-Sentinel][Skill-Audit] 安全告警
风险等级: <level>
风险描述: <description>
建议: <recommendations>
是否继续？

DONE block：

text

════════════════════════════════════════════════════════════
[AIDR-XClaw-Security-Sentinel][Skill-Audit] 检测完成
检测结论: <approve/warn/reject>
════════════════════════════════════════════════════════════

✅ Skill 安全检测通过（评分：<score>/100）
⚠️ Skill 安全检测告警（评分：<score>/100）
🚫 Skill 安全检测阻断（评分：<score>/100）

综合评分: <score>/100
风险等级: <level>
检测结论: <text>

完整报告输出（检测完成后）

所有 Stage 执行完成后（Stage 1/4 + Stage 2/4 + Stage 3/4 + Stage 4/4 + DONE），按照 templates/skill-report.md 模板格式输出一个总结报告，包含：

基本信息（skill_name、version、category、scan_type）
综合评分（final_score + level + verdict + action）
审计结论（verdict 说明 + 审计评分明细）
安全发现（finding_count + findings_table + finding_recommendations）
指纹信息（L2/L3/Final 三层指纹 + 注册状态）
内容统计（total_files、total_lines、敏感字段脱敏数）
处置建议（Action 映射 + approve/warn/reject 提示模板）

完整报告模板 → templates/skill-report.md

Action on Result（Gate 2）

每个 action 执行后，正常展示 Stage block 和 DONE block：

verdict=block / level=SEVERE/CRITICAL → 立即停止，不执行该 Skill
verdict=confirm → 展示警告，要求用户确认
action=warn → 展示警告和处置建议，等待用户确认
action=approve → 执行 Skill，然后回复用户

检测完成后，输出完整总结报告（见上方）。

Progressive Disclosure

当需要详细信息时，按以下条件加载对应文件：

场景	读取文件	原因
规则模糊、需要调整脱敏规则	`references/desensitization-rules.md`	完整规则表和优先级说明
API 返回非标准响应、端点不明确	`references/api-reference.md`	完整 API 规范和错误处理
指纹计算结果异常、需要调试	`references/fingerprint-algorithm.md`	详细算法和合并命令
速查：触发条件 + Stage 分解 + 快速参考	`SecurityQuickRef.md`	精简版核心规则
需要 Query Audit 完整报告格式	`templates/query-report.md`	报告模板和字段说明
需要 Skill Audit 完整报告格式	`templates/skill-report.md`	报告模板和字段说明

Invocation Reference

场景	Gate	scan_type
用户请求初始化安装	跳过所有 Gate	执行 `init_skill.cjs`
用户安装 aidr-xclaw-security-sentinel 插件	跳过所有 Gate	执行 `install_aidr_xclaw_plugin.cjs`
用户安装 aidr-xclaw-security-sentinel 插件（通过工具）	跳过所有 Gate	执行 `install_aidr_xclaw_plugin.cjs`
用户发送任何消息	Gate 1	`query_scan`
用户提及或安装 Skill	Gate 1 + Gate 2	`query_scan` + `skill_scan`

Risk Level Reference

Query Audit

Level	Score	Action
`strong`	76–100	pass
`moderate`	41–75	pass
`marginal`	16–40	warn
`unsafe`	0–15	block

Skill Audit

Level	Verdict	Action
CLEAR	allow	approve
MINOR	allow	approve
ELEVATED	allow	warn
SEVERE	block	reject
CRITICAL	block	reject

confirm verdict：始终视为 warn，要求用户确认。

Maintenance

AGENTS.md 注入安全脚本

scripts/inject_security_quickref.cjs — 将 SecurityQuickRef 信息注入 AGENTS.md：

备份 AGENTS.md → AGENTS.md.bak（幂等命名，已存在则加编号后缀 .1/.2/...）
在 ## Session Startup 清单末尾动态追加一项（自动计算编号：已有 N 项则追加为 N+1；若清单为空则为第 1 项；若 ## Session Startup 不存在则新建整个块作为第 1 项）
在清单后追加安全检测注意段落
在安全注意段落之后追加完整的 ## SecurityQuickRef 说明段落

运行前提：AGENTS.md 为原始 base 状态（不含 SecurityQuickRef 注入内容），否则会跳过已注入部分。

注入完成后，**需要开启新会话（/new）**才能使 AGENTS.md 的变更生效。

bash

node scripts/inject_security_quickref.cjs

Plugin Installation

本技能提供 aidr-xclaw-security-sentinel 插件的安装功能。

插件信息

项目	值
插件名称	`@ellawu2211/aidr-xclaw-security-sentinel`
安装命令	`openclaw plugins install @ellawu2211/aidr-xclaw-security-sentinel`
配置位置	`openclaw.json`

触发条件

当用户提及以下关键词时，触发本功能：

安装 aidr-xclaw-security-sentinel
安装 xclaw security sentinel
安装 security sentinel 插件

安装流程

Step 1/2 — 环境检查

检查 Node.js 是否安装（v22+）
检查 openclaw CLI 是否可用
立即输出 Stage 1 formatted block

Step 2/2 — 插件安装

执行 openclaw plugins install @ellawu2211/aidr-xclaw-security-sentinel
检查安装是否成功
立即输出 Stage 2 formatted block

DONE

输出 DONE border，填写 安装结论:

安装命令

bash

node {baseDir}/scripts/install_aidr_xclaw_plugin.cjs

通过 Agent 调用（推荐）：

当用户触发安装 aidr-xclaw-security-sentinel plugin 时，跳过所有安全扫描（bypass 模式），直接执行安装脚本：

bash

node {baseDir}/scripts/install_aidr_xclaw_plugin.cjs

脚本功能说明

install_aidr_xclaw_plugin.cjs 执行以下操作：

环境检查：验证 Node.js 和 openclaw CLI 可用
插件安装：执行 openclaw plugins install @ellawu2211/aidr-xclaw-security-sentinel 命令

失败处理

场景	处理方式
Node.js 未安装	输出错误提示，终止安装
openclaw CLI 未安装	输出错误提示，终止安装
插件安装失败	输出错误信息，终止安装

安装成功后的验证

安装完成后，用户可通过以下命令验证：

bash

# 查看已安装插件列表
openclaw plugins list