tencent-claw-shield 0.1.0-beta.4

package/README.md

@@ -0,0 +1,319 @@
+# Claw Shield — AI Agent Runtime Security Plugin
+
+[English](#english) | [中文](#中文)
+
+---
+
+<a id="中文"></a>
+
+**Claw Shield** 是由腾讯安全 WAF 团队打造的 **AI Agent 运行时安全防护插件**，为 [OpenClaw](https://docs.openclaw.ai) Agent 提供全生命周期的安全治理能力。
+
+---
+
+### 核心防护能力
+
+Claw Shield 在 Agent 运行时的关键节点自动拦截并执行安全检测，覆盖以下防护场景：
+
+#### 输入安全防护
+
+- **提示词注入检测** — 识别并拦截恶意 Prompt Injection 攻击
+- **敏感内容过滤** — 对用户输入中的违规、有害内容进行实时检测
+
+#### 工具调用防护
+
+- **危险工具拦截** — 对高风险工具调用（如文件操作、命令执行）进行实时阻断
+- **参数合规校验** — 检测工具调用参数中的越权、注入等安全风险
+- **Skill 安全审计** — 自动收集并上报 Agent 已安装的 Skill 信息，支持远端检测与策略管控
+
+#### 输出安全防护
+
+- **内容脱敏** — 对 Agent 输出中的敏感信息（如密钥、个人隐私）进行自动脱敏
+- **外发内容审查** — 在消息发送前进行安全检查，防止敏感信息泄露
+
+#### 模型交互防护
+
+- **LLM 请求审计** — 记录并检测发送给大模型的请求内容
+- **响应内容检测** — 对模型返回结果进行安全合规检查
+
+#### 安全运营
+
+- **安全事件留痕** — 自动记录所有安全检测事件，支持查询与审计
+- **实时遥测上报** — 基于 WebSocket 长连接的心跳与数据上报，实现集中化安全态势感知
+- **远端策略管控** — 所有防护策略由远端安全服务统一下发，支持动态调整，无需重启 Agent
+
+---
+
+### 技术特性
+
+- **零侵入集成** — 作为 OpenClaw 标准插件运行，无需修改 Agent 业务代码
+- **同步 + 异步双路径** — 关键路径（如工具调用阻断）采用同步检测确保实时拦截；非关键路径采用异步检测降低延迟影响
+- **高可用容错** — 远端服务不可达时自动 fallback 放行，不影响 Agent 正常运行
+- **闭源加密交付** — 核心代码经混淆加密处理，安全可控
+
+---
+
+### 环境要求
+
+- **Node.js >= 20**（LTS 版本，推荐 20.x 或 22.x）
+- [OpenClaw](https://docs.openclaw.ai) Agent 运行环境
+
+---
+
+### 快速安装
+
+```bash
+npx -y tencent-claw-shield install --global
+```
+
+安装过程中会依次提示配置：
+
+1. **API Key** — 用于远端安全服务认证
+2. **Server 地址** — 远端安全检测服务的 IP 和端口
+3. **WebSocket 地址** — 遥测上报服务的 IP 和端口
+
+也支持非交互式安装：
+
+```bash
+npx -y tencent-claw-shield install --global \
+  --api-key '<your-api-key>' \
+  --server-address <[http|https://]ip:port> \
+  --ws-address <[ws|wss://]ip:port>
+```
+
+> Server 地址支持 `http://` 和 `https://` 协议前缀（如 `https://203.0.113.1:443`），不填默认为 `http`。
+> WebSocket 地址支持 `ws://` 和 `wss://` 协议前缀（如 `wss://203.0.113.1:8081`），不填默认为 `ws`。
+> HTTPS / WSS 模式下均会自动跳过证书校验。
+
+#### 其他常用命令
+
+```bash
+# 更新插件
+npx -y tencent-claw-shield update --global
+
+# 一次性修改 API Key + Server + WebSocket 地址（交互式依次提示）
+npx -y tencent-claw-shield set-config
+
+# 也可通过参数直接传入（非交互式）
+npx -y tencent-claw-shield set-config --api-key '<key>' --server-address <ip:port> --ws-address <ip:port>
+
+# 单独修改 API Key
+npx -y tencent-claw-shield set-api-key --global
+
+# 单独修改 Server 地址（支持 https 协议前缀）
+npx -y tencent-claw-shield set-server --server-address <ip:port>
+npx -y tencent-claw-shield set-server --server-address https://203.0.113.1:443
+
+# 单独修改 WebSocket 地址（支持 wss 协议前缀）
+npx -y tencent-claw-shield set-websocket --ws-address <ip:port>
+npx -y tencent-claw-shield set-websocket --ws-address wss://203.0.113.1:8081
+
+# 热刷新配置
+npx -y tencent-claw-shield reload
+```
+
+#### 卸载
+
+```bash
+# 一键卸载（保留认证文件，方便重新安装时复用）
+npx -y tencent-claw-shield uninstall --global
+
+# 完全卸载（同时删除认证文件）
+npx -y tencent-claw-shield uninstall --global --purge
+```
+
+#### 临时关闭 / 恢复防护
+
+```bash
+# 一键关闭所有防护（安全检测、遥测上报、Skills 上报全部暂停）
+npx -y tencent-claw-shield bypass
+
+# 恢复所有防护
+npx -y tencent-claw-shield resume
+```
+
+> Bypass 模式下插件仍然加载在 OpenClaw 中，但所有 Hook 会直接放行，不会调用远端检测服务。执行 `resume` 后立即恢复全部防护能力，无需重启 Gateway。
+
+---
+
+### 接入说明
+
+Claw Shield 的安全检测能力依赖**远端防护策略服务**。您需要在远端平台完成安全策略配置后，插件才能正常提供防护。
+
+当前版本以 OpenClaw Agent 为首要集成目标，后续计划支持更多 AI Agent 框架接入。
+
+#### 咨询与接入
+
+如果您希望了解更多产品信息或接入使用，请联系：
+
+**邮箱：lukayi@tencent.com**
+
+---
+
+### 关于我们
+
+Claw Shield 由**腾讯安全 WAF 团队**研发，致力于为 AI Agent 生态提供专业的运行时安全防护方案。
+
+---
+
+### License
+
+UNLICENSED — 本软件为闭源商业软件，未经授权不得复制、修改或分发。
+
+---
+
+<a id="english"></a>
+
+[English](#english) | [中文](#中文)
+
+**Claw Shield** is an **AI Agent runtime security plugin** built by the **Tencent Security WAF Team**, providing full-lifecycle security governance for [OpenClaw](https://docs.openclaw.ai) Agents.
+
+---
+
+### Core Security Capabilities
+
+Claw Shield automatically intercepts and performs security checks at critical points during Agent runtime, covering the following scenarios:
+
+#### Input Protection
+
+- **Prompt Injection Detection** — Identifies and blocks malicious Prompt Injection attacks
+- **Sensitive Content Filtering** — Real-time detection of harmful or non-compliant content in user input
+
+#### Tool Call Protection
+
+- **Dangerous Tool Blocking** — Real-time blocking of high-risk tool calls (e.g., file operations, command execution)
+- **Parameter Compliance Validation** — Detects privilege escalation, injection, and other security risks in tool call parameters
+- **Skill Security Audit** — Automatically collects and reports installed Skill information for remote detection and policy enforcement
+
+#### Output Protection
+
+- **Content Redaction** — Automatically redacts sensitive information (e.g., secrets, personal data) in Agent output
+- **Outbound Content Review** — Security checks before message delivery to prevent sensitive data leakage
+
+#### Model Interaction Protection
+
+- **LLM Request Audit** — Records and inspects content sent to large language models
+- **Response Content Detection** — Security compliance checks on model responses
+
+#### Security Operations
+
+- **Security Event Logging** — Automatically records all security detection events with full query and audit support
+- **Real-time Telemetry** — Heartbeat and data reporting via WebSocket for centralized security posture awareness
+- **Remote Policy Management** — All security policies are centrally managed and dynamically pushed from the remote security service, with no Agent restart required
+
+---
+
+### Technical Highlights
+
+- **Zero-intrusion Integration** — Runs as a standard OpenClaw plugin with no changes to Agent business code
+- **Sync + Async Dual Path** — Critical paths (e.g., tool call blocking) use synchronous detection for real-time enforcement; non-critical paths use async detection to minimize latency impact
+- **High Availability & Fault Tolerance** — Automatically falls back to allow when the remote service is unreachable, ensuring uninterrupted Agent operation
+- **Closed-source Encrypted Delivery** — Core code is obfuscated and encrypted for security
+
+---
+
+### Requirements
+
+- **Node.js >= 20** (LTS version, recommended 20.x or 22.x)
+- [OpenClaw](https://docs.openclaw.ai) Agent runtime environment
+
+---
+
+### Quick Install
+
+```bash
+npx -y tencent-claw-shield install --global
+```
+
+The installer will prompt you to configure the following in sequence:
+
+1. **API Key** — For remote security service authentication
+2. **Server Address** — IP and port of the remote security detection service
+3. **WebSocket Address** — IP and port of the telemetry reporting service
+
+Non-interactive installation is also supported:
+
+```bash
+npx -y tencent-claw-shield install --global \
+  --api-key '<your-api-key>' \
+  --server-address <[http|https://]ip:port> \
+  --ws-address <[ws|wss://]ip:port>
+```
+
+> Server addresses support `http://` and `https://` protocol prefixes (e.g., `https://203.0.113.1:443`). Defaults to `http` if omitted.
+> WebSocket addresses support `ws://` and `wss://` protocol prefixes (e.g., `wss://203.0.113.1:8081`). Defaults to `ws` if omitted.
+> Certificate verification is automatically skipped in HTTPS / WSS mode.
+
+#### Common Commands
+
+```bash
+# Update plugin
+npx -y tencent-claw-shield update --global
+
+# Configure API Key + Server + WebSocket at once (interactive prompts)
+npx -y tencent-claw-shield set-config
+
+# Or pass all parameters directly (non-interactive)
+npx -y tencent-claw-shield set-config --api-key '<key>' --server-address <ip:port> --ws-address <ip:port>
+
+# Modify API Key only
+npx -y tencent-claw-shield set-api-key --global
+
+# Modify Server address only (supports https:// prefix)
+npx -y tencent-claw-shield set-server --server-address <ip:port>
+npx -y tencent-claw-shield set-server --server-address https://203.0.113.1:443
+
+# Modify WebSocket address only (supports wss:// prefix)
+npx -y tencent-claw-shield set-websocket --ws-address <ip:port>
+npx -y tencent-claw-shield set-websocket --ws-address wss://203.0.113.1:8081
+
+# Hot-reload configuration
+npx -y tencent-claw-shield reload
+```
+
+#### Uninstall
+
+```bash
+# Uninstall (keeps auth files for easy reinstallation)
+npx -y tencent-claw-shield uninstall --global
+
+# Full uninstall (also removes auth files)
+npx -y tencent-claw-shield uninstall --global --purge
+```
+
+#### Temporarily Disable / Restore Protection
+
+```bash
+# Disable all protection (security checks, telemetry, Skills reporting all paused)
+npx -y tencent-claw-shield bypass
+
+# Restore all protection
+npx -y tencent-claw-shield resume
+```
+
+> In bypass mode, the plugin remains loaded in OpenClaw but all Hooks pass through directly without calling the remote detection service. Running `resume` immediately restores full protection — no Gateway restart required.
+
+---
+
+### Integration Guide
+
+Claw Shield's security detection capabilities rely on a **remote security policy service**. You need to complete security policy configuration on the remote platform before the plugin can provide protection.
+
+The current version primarily targets OpenClaw Agent integration, with plans to support additional AI Agent frameworks in the future.
+
+#### Contact & Onboarding
+
+For more product information or to get started, please contact:
+
+**Email: lukayi@tencent.com**
+
+---
+
+### About Us
+
+Claw Shield is developed by the **Tencent Security WAF Team**, dedicated to providing professional runtime security solutions for the AI Agent ecosystem.
+
+---
+
+### License
+
+UNLICENSED — This is closed-source commercial software. Unauthorized copying, modification, or distribution is prohibited.

package/dist/contracts/core.d.ts

@@ -0,0 +1,277 @@
+import type { ShieldApprovalCategory, ShieldFailMode, ShieldSeverity, ShieldStage, ShieldSurface } from "../types";
+/** 统一钩子名称枚举：对应 Agent 生命周期中的各个检测点 */
+export type ShieldCanonicalHookName = "message_received" | "before_llm_request" | "before_tool_call" | "message_sending" | "before_message_write" | "tool_result_persist";
+/**
+ * 兼容别名：历史代码使用 ShieldHookName，等价于统一钩子名
+ * 后续建议优先使用 ShieldCanonicalHookName
+ */
+export type ShieldHookName = ShieldCanonicalHookName;
+/** 宿主类型 */
+export type HostType = "openclaw" | "langchain" | "custom";
+/** 宿主信息（用于跨宿主接入时标识来源） */
+export type HostInfo = {
+    hostType: HostType;
+    hostVersion?: string;
+};
+/** 钩子信封基础类型：所有钩子事件的公共字段 */
+export type HookEnvelopeBase = {
+    /** 统一钩子名：评估引擎优先依赖该字段 */
+    canonicalHook: ShieldCanonicalHookName;
+    /** 宿主原始钩子名（不同宿主可不一致） */
+    hostHookName: string;
+    surface: ShieldSurface;
+    timestamp: number;
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+    sessionKey?: string;
+    hostInfo?: HostInfo;
+    /** 宿主平台传递的上下文信息 */
+    hostContext: Record<string, unknown>;
+};
+/** 入口钩子信封：用户消息到达时触发 */
+export type IngressEnvelope = HookEnvelopeBase & {
+    canonicalHook: "message_received";
+    hostHookName: "message_received" | "before_prompt_build";
+    surface: "ingress";
+    payload: {
+        message: unknown;
+    };
+};
+/** LLM 请求钩子信封：向大模型发送请求前触发 */
+export type LlmRequestEnvelope = HookEnvelopeBase & {
+    canonicalHook: "before_llm_request";
+    hostHookName: "llm_input";
+    surface: "llm";
+    payload: {
+        provider: string;
+        model: string;
+        prompt: string;
+        systemPrompt?: string;
+        historyMessages: unknown[];
+        skillNames?: string[];
+    };
+};
+/** 工具调用钩子信封：执行工具调用前触发 */
+export type ToolCallEnvelope = HookEnvelopeBase & {
+    canonicalHook: "before_tool_call";
+    hostHookName: "before_tool_call";
+    surface: "tool";
+    payload: {
+        toolName: string;
+        toolParams: Record<string, unknown>;
+    };
+};
+/** 出口钩子信封：向用户发送消息前触发 */
+export type EgressEnvelope = HookEnvelopeBase & {
+    canonicalHook: "message_sending";
+    hostHookName: "message_sending";
+    surface: "egress";
+    payload: {
+        message: unknown;
+        channel?: string;
+    };
+};
+/** 持久化钩子信封：写入消息或工具结果前触发 */
+export type PersistEnvelope = HookEnvelopeBase & {
+    canonicalHook: "before_message_write" | "tool_result_persist";
+    hostHookName: "before_message_write" | "tool_result_persist";
+    surface: "persist";
+    payload: {
+        message?: unknown;
+        toolName?: string;
+        toolResult?: unknown;
+    };
+};
+/** 钩子信封联合类型：所有钩子信封的联合 */
+export type HookEnvelope = IngressEnvelope | LlmRequestEnvelope | ToolCallEnvelope | EgressEnvelope | PersistEnvelope;
+/** 原因代码：标识安全问题的分类 */
+export type ReasonCode = "prompt_injection" | "retrieval_poisoning" | "sensitive_action" | "egress_exfiltration" | "mcp_allowlist_violation" | "model_governance_violation" | "approval_required" | "unknown";
+/** 标准化的检测发现：将各种来源的发现统一为标准格式 */
+export type NormalizedFinding = {
+    findingId: string;
+    detector: string;
+    reasonCode: ReasonCode;
+    severity: ShieldSeverity;
+    summary: string;
+    tags: string[];
+    evidence?: Record<string, unknown>;
+    matchedRuleIds?: string[];
+};
+/** 审批工单草案：创建审批请求时的初始数据 */
+export type ApprovalTicketDraft = {
+    category: ShieldApprovalCategory;
+    reason: string;
+    severity: ShieldSeverity;
+    tags?: string[];
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+    toolName?: string;
+    /** 审批来源绑定（关联外部审批系统） */
+    sourceBinding?: {
+        source: string;
+        externalApprovalId?: string;
+    };
+    /** 相关资源信息 */
+    resource?: {
+        toolName?: string;
+        provider?: string;
+        model?: string;
+    };
+};
+/** 运行暂停草案：创建运行暂停时的初始数据 */
+export type RunHoldDraft = {
+    toolName: string;
+    toolParams?: Record<string, unknown>;
+    /** 暂停时所处的护盾阶段 */
+    stageAtHold: ShieldStage;
+    /** 暂停时的失败模式 */
+    failModeAtHold: ShieldFailMode;
+    category?: ShieldApprovalCategory;
+    severity?: ShieldSeverity;
+    reason?: string;
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+};
+/** 执行计划草案：描述即将执行的操作类型和要求 */
+export type ExecutionPlanDraft = {
+    /** 操作类型：llm_request=LLM请求 | tool_call=工具调用 | message_send=消息发送 */
+    actionType: "llm_request" | "tool_call" | "message_send";
+    /** 要求的后端环境 */
+    requiredBackend?: "local" | "sandbox" | "remote_controlled";
+    /** 沙箱配置 */
+    sandboxProfile?: string;
+    /** 审批模式 */
+    approvalMode?: "none" | "required" | "already_bound";
+    /** 预算配置 */
+    budgetProfile?: string;
+};
+/**
+ * 决策效果联合类型：描述护栏决策产生的各种效果
+ * - allow: 放行
+ * - redact: 脱敏（指定字段和替换值）
+ * - block: 拦截（附带原因）
+ * - queue_approval: 排队等待审批
+ * - create_run_hold: 暂停运行
+ * - require_model_profile: 要求使用指定模型配置
+ * - restrict_model: 限制可用的模型/提供商
+ * - route_execution: 路由到指定执行计划
+ * - emit_audit: 发出审计事件
+ */
+export type DecisionEffect = {
+    type: "allow";
+} | {
+    type: "redact";
+    targets: Array<{
+        field: string;
+        replacement: string;
+        ruleId?: string;
+        value?: unknown;
+    }>;
+} | {
+    type: "block";
+    reason: string;
+} | {
+    type: "queue_approval";
+    ticket: ApprovalTicketDraft;
+} | {
+    type: "create_run_hold";
+    hold: RunHoldDraft;
+} | {
+    type: "require_model_profile";
+    profileId: string;
+} | {
+    type: "restrict_model";
+    allowedProviderIds?: string[];
+    allowedModelIds?: string[];
+} | {
+    type: "route_execution";
+    plan: ExecutionPlanDraft;
+} | {
+    type: "emit_audit";
+    eventType: string;
+};
+/** 护栏决策：一次完整的安全评估决策结果 */
+export type GuardrailDecision = {
+    decisionId: string;
+    /** 触发决策的钩子信封引用 */
+    envelopeRef: {
+        /** 统一钩子名 */
+        canonicalHook: ShieldCanonicalHookName;
+        /** 宿主原始钩子名（可选，跨宿主时可能与 canonicalHook 不同） */
+        hostHookName?: string;
+        surface: ShieldSurface;
+        agentId?: string;
+        runId?: string;
+        sessionId?: string;
+    };
+    /** 当前护盾阶段 */
+    stage: ShieldStage;
+    severity: ShieldSeverity;
+    /** 标准化检测发现列表 */
+    findings: NormalizedFinding[];
+    /** 决策产生的效果列表 */
+    effects: DecisionEffect[];
+    /** 原因代码列表 */
+    reasonCodes: ReasonCode[];
+    tags: string[];
+    /** 是否为模拟模式 */
+    simulated: boolean;
+    /** 评估耗时（毫秒） */
+    durationMs: number;
+};
+/** 审批状态 */
+export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled";
+/** 审批工单（完整版）：在草案基础上增加了 ID、状态和时间戳等运行时字段 */
+export type ApprovalTicket = ApprovalTicketDraft & {
+    approvalId: string;
+    incidentId?: string;
+    status: ApprovalStatus;
+    createdAt: number;
+    resolvedAt?: number;
+    resolvedBy?: string;
+    note?: string;
+};
+/** 运行暂停状态 */
+export type RunHoldStatus = "pending" | "approved_waiting_resume" | "resumed" | "rejected" | "expired" | "cancelled";
+/** 运行暂停工单（完整版）：在草案基础上增加了 ID、状态和时间戳 */
+export type RunHoldTicket = RunHoldDraft & {
+    holdId: string;
+    approvalId: string;
+    status: RunHoldStatus;
+    createdAt: number;
+    resumedAt?: number;
+    cancelledAt?: number;
+};
+/** 执行计划（完整版）：在草案基础上增加了模型限制和出口策略等 */
+export type ExecutionPlan = ExecutionPlanDraft & {
+    planId: string;
+    allowedProviderIds?: string[];
+    allowedModelIds?: string[];
+    requiredModelProfile?: string;
+    /** 出口策略：限制目标地址和渠道 */
+    egressPolicy?: {
+        destinationAllowlist?: string[];
+        channelAllowlist?: string[];
+    };
+};
+/** 审计事件类型枚举 */
+export type AuditEventType = "decision.made" | "decision.blocked" | "approval.queued" | "approval.resolved" | "run_hold.created" | "run_hold.resumed" | "hitl.deadletter.queued" | "hitl.deadletter.resolved";
+/** 审计事件：记录系统中发生的每一个重要安全事件 */
+export type AuditEvent = {
+    eventId: string;
+    eventType: AuditEventType;
+    timestamp: number;
+    decisionId?: string;
+    approvalId?: string;
+    holdId?: string;
+    agentId?: string;
+    runId?: string;
+    sessionId?: string;
+    /** 事件的详细数据 */
+    payload: Record<string, unknown>;
+    /** Schema 版本号 */
+    schemaVersion: 1;
+};

package/dist/contracts/events.d.ts

@@ -0,0 +1,35 @@
+/** 护盾网关事件常量：定义所有可以通过网关发布的事件名称 */
+export declare const SHIELD_GATEWAY_EVENTS: {
+    readonly decision: "shield.decision";
+    readonly blocked: "shield.blocked";
+    readonly stageChanged: "shield.stage.changed";
+    readonly approvalQueued: "shield.approval.queued";
+    readonly approvalResolved: "shield.approval.resolved";
+    readonly hitlDeadLetterQueued: "shield.hitl.deadletter.queued";
+    readonly hitlDeadLetterResolved: "shield.hitl.deadletter.resolved";
+};
+/** 网关事件的通用包装类型 */
+export type GatewayEvent<T = unknown> = {
+    eventName: string;
+    data: T;
+};
+/** 决策事件数据：决策做出时附带的信息 */
+export type DecisionEventData = {
+    decisionId: string;
+    hook: string;
+    surface: string;
+    stage: string;
+    severity: string;
+    effects: unknown[];
+    reasonCodes: string[];
+    simulated: boolean;
+    durationMs: number;
+};
+/** 拦截事件数据：请求被拦截时附带的信息 */
+export type BlockedEventData = {
+    decisionId: string;
+    hook: string;
+    surface: string;
+    reason: string;
+    findings: unknown[];
+};