@omni-shield/ai-assistant-security-openclaw 1.0.0-beta1

package/README.md

@@ -0,0 +1,54 @@
+# AI Assistant Security Plugin
+
+`@omni-shield/ai-assistant-security-openclaw` is a security plugin designed for OpenClaw to protect your Large Language Models (LLM) and Agent lifecycle from harmful requests and sensitive data leakage.
+
+## Key Features
+
+- **Multi-dimensional Protection**: Covers LLM requests, pre-tool calls (Before Tool Call), and tool result persistence (Tool Result Persist).
+- **Global Interception**: Hooks into `global.fetch` to provide automated security auditing for underlying model calls.
+- **Smart Degradation (Circuit Breaker)**: Built-in error handling and self-healing logic. Automatically enters degradation mode when security API failures exceed the threshold, ensuring business continuity.
+- **Session Synchronization**: Automatically synchronizes OpenClaw session files to mark intercepted content when a request is blocked.
+- **Risk Label Support**: Supports returning specific risk labels (e.g., PII, Prompt Injection) and displaying them in block messages.
+
+## Quick Start
+
+Bundled plugins are disabled by default in OpenClaw. You can enable it using the following command:
+
+```bash
+openclaw plugins enable ai-assistant-security-openclaw
+```
+
+Restart the Gateway after enabling.
+
+## Configuration
+
+Configure the plugin in your OpenClaw configuration file:
+
+```yaml
+plugins:
+  ai-assistant-security-openclaw:
+    enabled: true
+    config:
+      endpoint: "https://your-security-api-endpoint"  # Security API endpoint (Required)
+      apiKey: "your-api-key-here"                     # API Key (Required)
+      appId: "your-app-id"                            # Application Identifier (Required)
+      timeoutMs: 5000                                 # API timeout in ms, default is no limit
+      logRecord: true                                 # Enable plugin runtime logs, default is false
+      failureThreshold: 3                             # Failures before entering degradation, default is 3
+      retryInterval: 60                               # Initial retry interval in seconds after degradation, default is 60
+      maxRetryInterval: 3600                          # Max retry interval in seconds, default is 3600
+      hooks:                                          # Hook points configuration, default all true
+        fetch: true                                   # Whether to hook global.fetch
+        beforeToolCall: true                          # Whether to audit before tool execution
+        toolResultPersist: true                       # Whether to audit before persisting tool results
+```
+
+## Workflow
+
+1. **Registration & Validation**: Validates the availability of `endpoint`, `apiKey`, and `appId` during startup.
+2. **Security Audit**:
+   - **LLM Requests**: Monitors inputs sent to models.
+   - **Pre-Tool Call**: Audits the tool name and its parameters before execution.
+   - **Tool Result**: Audits raw data returned by tools to prevent sensitive information leakage.
+3. **Interception**: If a risk is detected, the plugin returns a block message or rewrites the response content accordingly.
+4. **Disaster Recovery**: If the security service is unavailable, the plugin automatically bypasses checks to prioritize business availability and periodically probes for service recovery.

package/index.ts

@@ -0,0 +1,589 @@
+/* eslint-disable max-depth */
+import fs from 'node:fs';
+import path from 'node:path';
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+
+import pkg from './package.json';
+import { LLMShieldClient } from './src/client.js';
+import { getLabelName, type Language } from './src/labels.js';
+import { ContentTypeV2, DecisionTypeV2, type MessageV2 } from './src/types.js';
+import { generateRequestId, getDeviceFingerprint, robustExtractLastUserMessage } from './src/utils.js';
+
+function logEvent(api: OpenClawPluginApi, hook: string, data: any, logRecord: boolean): void {
+  if (logRecord) {
+    api.logger.info(`[${pkg.name}] ${hook} ${JSON.stringify(data)}`);
+  }
+}
+
+let isDegraded = false;
+let isProbing = false;
+let consecutiveFailures = 0;
+let lastRetryTime = 0;
+let failureThreshold = 3;
+let baseRetryIntervalMs = 60 * 1000; // Default 1 min
+let currentRetryIntervalMs = baseRetryIntervalMs;
+let maxRetryIntervalMs = 3600 * 1000; // Max 1 hour
+let deviceFingerprint = '';
+
+async function syncSessionContent(api: OpenClawPluginApi, originalContent: string, blockReason: string) {
+  try {
+    const pluginCfg = (api.pluginConfig ?? {}) as any;
+    const openClawDir = pluginCfg.openClawDir
+      ? api.resolvePath(pluginCfg.openClawDir)
+      : api.resolvePath('..');
+    const agentsDir = path.join(openClawDir, 'agents');
+
+    if (!fs.existsSync(agentsDir)) {
+      api.logger.error(`[${pkg.name}] Agents directory not found at ${agentsDir}`);
+      return;
+    }
+
+    const agentDirs = fs
+      .readdirSync(agentsDir)
+      .filter((f) => fs.statSync(path.join(agentsDir, f)).isDirectory());
+    let totalChanged = false;
+
+    for (const agentName of agentDirs) {
+      const sessionsJsonPath = path.join(agentsDir, agentName, 'sessions', 'sessions.json');
+      if (!fs.existsSync(sessionsJsonPath)) continue;
+
+      const sessionsData = JSON.parse(await fs.promises.readFile(sessionsJsonPath, 'utf-8'));
+
+      for (const key of Object.keys(sessionsData)) {
+        const sessionInfo = sessionsData[key];
+        const { sessionId } = sessionInfo;
+        if (!sessionId) continue;
+
+        // Use sessionFile field first, otherwise fall back to the default path
+        const sessionFilePath = sessionInfo.sessionFile
+          ? path.isAbsolute(sessionInfo.sessionFile)
+            ? sessionInfo.sessionFile
+            : path.join(agentsDir, agentName, 'sessions', sessionInfo.sessionFile)
+          : path.join(agentsDir, agentName, 'sessions', `${sessionId}.jsonl`);
+
+        if (!fs.existsSync(sessionFilePath)) continue;
+
+        const lockFilePath = `${sessionFilePath}.lock`;
+
+        // Wait for the lock file to disappear (query every 1s, wait up to 30s)
+        let lockAcquired = false;
+        const lockStartTime = Date.now();
+        const lockTimeout = 30000; // 30s
+
+        while (Date.now() - lockStartTime < lockTimeout) {
+          if (!fs.existsSync(lockFilePath)) {
+            lockAcquired = true;
+            break;
+          }
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+
+        if (!lockAcquired) {
+          api.logger.error(
+            `[${pkg.name}] Failed to acquire lock for session ${sessionId} after 30s timeout, skipping sync.`
+          );
+          continue;
+        }
+
+        // Create lock file
+        try {
+          const lockContent = {
+            pid: process.pid,
+            createdAt: new Date().toISOString()
+          };
+          await fs.promises.writeFile(lockFilePath, JSON.stringify(lockContent, null, 2));
+
+          const fileContent = await fs.promises.readFile(sessionFilePath, 'utf-8');
+          const lines = fileContent.split('\n');
+          let changed = false;
+
+          const newLines = lines.map((line) => {
+            if (!line.trim()) return line;
+            try {
+              const entry = JSON.parse(line);
+              // Match message type and role as user
+              if (entry.type === 'message' && entry.message?.role === 'user') {
+                const contentParts = entry.message.content;
+                if (Array.isArray(contentParts)) {
+                  for (const part of contentParts) {
+                    if (part.type === 'text' && typeof part.text === 'string') {
+                      // Check if the content of this session file contains the original content being checked
+                      if (part.text.includes(originalContent) && !part.text.includes(blockReason)) {
+                        // Insert marker in original content (prefer before \n[message_id:)
+                        part.text = part.text.replace(
+                          originalContent,
+                          insertBlockMarker(originalContent, blockReason)
+                        );
+                        changed = true;
+                      }
+                    }
+                  }
+                }
+              }
+              return JSON.stringify(entry);
+            } catch (e) {
+              return line;
+            }
+          });
+
+          if (changed) {
+            await fs.promises.writeFile(sessionFilePath, newLines.join('\n'));
+            totalChanged = true;
+          }
+        } finally {
+          // Release lock file
+          if (fs.existsSync(lockFilePath)) {
+            await fs.promises.unlink(lockFilePath).catch((err) => {
+              api.logger.error(`[${pkg.name}] Failed to remove lock file ${lockFilePath}: ${err}`);
+            });
+          }
+        }
+
+        if (totalChanged) break;
+      }
+      if (totalChanged) break;
+    }
+  } catch (e) {
+    api.logger.error(`[${pkg.name}] Failed to sync session content: ${e}`);
+  }
+}
+
+async function moderate(
+  api: OpenClawPluginApi,
+  client: LLMShieldClient,
+  appId: string,
+  content: string,
+  role: string,
+  source: string,
+  logRecord: boolean,
+  history?: MessageV2[]
+): Promise<{ decision?: DecisionTypeV2; labels: string[] }> {
+  // If in degradation state, check if it's time to retry
+  if (isDegraded) {
+    const now = Date.now();
+    if (now - lastRetryTime > currentRetryIntervalMs && !isProbing) {
+      isProbing = true;
+      api.logger.info(`[${pkg.name}] In degradation state, sending single probe request...`);
+      try {
+        await client.moderate(
+          {
+            Message: {
+              Role: 'user',
+              Content: 'hello',
+              ContentType: ContentTypeV2.TEXT
+            },
+            Scene: appId
+          },
+          {
+            'X-Ai-Device-Fingerprint': deviceFingerprint
+          }
+        );
+        // Probe successful, recovered
+        api.logger.info(`[${pkg.name}] Endpoint recovered, resetting degradation flag.`);
+        isDegraded = false;
+        isProbing = false;
+        consecutiveFailures = 0;
+        currentRetryIntervalMs = baseRetryIntervalMs;
+      } catch (e) {
+        lastRetryTime = Date.now();
+        isProbing = false;
+        // Exponential backoff
+        currentRetryIntervalMs = Math.min(currentRetryIntervalMs * 2, maxRetryIntervalMs);
+        api.logger.warn(
+          `[${pkg.name}] Probe failed, next retry in ${Math.round(currentRetryIntervalMs / 1000)}s.`
+        );
+        return { labels: [] };
+      }
+    } else {
+      // Still in degradation period or another probe is in flight, pass directly
+      return { labels: [] };
+    }
+  }
+
+  const requestId = generateRequestId();
+  logEvent(
+    api,
+    `${source}(check)`,
+    { content, role, appId, requestId, historyCount: history?.length },
+    logRecord
+  );
+
+  let attempt = 0;
+  const maxAttempts = 2; // 1 original + 1 retry for transient errors
+
+  while (attempt < maxAttempts) {
+    try {
+      const response = await client.moderate(
+        {
+          Message: {
+            Role: role,
+            Content: content,
+            ContentType: ContentTypeV2.TEXT
+          },
+          Scene: appId,
+          History: history
+        },
+        {
+          'X-Top-Request-Id': requestId,
+          'X-Ai-Device-Fingerprint': deviceFingerprint
+        }
+      );
+      logEvent(api, `${source}(result)`, { response, requestId }, logRecord);
+
+      // Successful call, reset consecutive failures count
+      consecutiveFailures = 0;
+      currentRetryIntervalMs = baseRetryIntervalMs;
+
+      const decision = response.Result?.Decision?.DecisionType;
+      const labels = response.Result?.RiskInfo?.Risks?.map((r) => r.Label) || [];
+      return { decision, labels };
+    } catch (error: any) {
+      attempt++;
+      const isTimeout = error?.name === 'AbortError' || error?.message?.includes('timeout');
+      const isTransient = isTimeout || (error?.status >= 500 && error?.status < 600);
+      const errorMsg = isTimeout ? 'Moderation timed out' : String(error);
+
+      if (isTransient && attempt < maxAttempts) {
+        api.logger.warn(
+          `[${pkg.name}] Transient error (${errorMsg}), retrying... (${attempt}/${maxAttempts - 1})`
+        );
+        await new Promise((resolve) => setTimeout(resolve, 500)); // Short delay before retry
+        continue;
+      }
+
+      consecutiveFailures++;
+      logEvent(api, `${source}(error)`, { error: errorMsg, requestId, consecutiveFailures }, logRecord);
+      console.error(
+        `Moderation failed (${source}) [RID:${requestId}] [Failures:${consecutiveFailures}]:`,
+        errorMsg
+      );
+
+      // Check if circuit breaker threshold is reached
+      if (consecutiveFailures >= failureThreshold) {
+        isDegraded = true;
+        lastRetryTime = Date.now();
+        api.logger.error(
+          `[${
+            pkg.name
+          }] Consecutive failures reached threshold (${failureThreshold}), entering degradation state. Next retry in ${Math.round(
+            currentRetryIntervalMs / 1000
+          )}s.`
+        );
+      }
+
+      return { labels: [] };
+    }
+  }
+
+  return { labels: [] };
+}
+
+const BLOCK_MARKER_PREFIX = '[Block By AI Assistant Security. Reason';
+
+function preprocessContent(content: string): string {
+  if (typeof content !== 'string') return content;
+  const blockIndex = content.lastIndexOf(BLOCK_MARKER_PREFIX);
+  if (blockIndex === -1) return content;
+
+  // Try to match the timestamp at the beginning, e.g., [Tue 2026-02-10 20:36 GMT+8]
+  const timestampEndIndex = content.indexOf(']');
+  if (content.startsWith('[') && timestampEndIndex !== -1 && timestampEndIndex < blockIndex) {
+    const timestamp = content.substring(0, timestampEndIndex + 1);
+    const blockedPart = content.substring(blockIndex);
+    return `${timestamp} ${blockedPart}`;
+  }
+
+  // If no timestamp is recognized at the beginning, only keep the block marker and subsequent content
+  return content.substring(blockIndex);
+}
+
+function insertBlockMarker(content: string, marker: string): string {
+  if (typeof content !== 'string') return content;
+  const suffixMarker = '\n[message_id:';
+  const index = content.lastIndexOf(suffixMarker);
+  if (index !== -1) {
+    return `${content.slice(0, index)} ${marker}${content.slice(index)}`;
+  }
+  return `${content} ${marker}`;
+}
+
+function getBlockReason(content: string, labels: string[]): string {
+  // Use English to get label names
+  const lang: Language = 'en';
+
+  // Get unique label names
+  const uniqueLabelNames = Array.from(new Set(labels.map((l) => getLabelName(l, lang))));
+  const labelText = uniqueLabelNames.length > 0 ? uniqueLabelNames.join(', ') : 'Inappropriate content';
+
+  return `${BLOCK_MARKER_PREFIX} ${labelText}]`;
+}
+
+const hookGlobalFetch = (() => {
+  let isHooked = false;
+  return (api: OpenClawPluginApi, client: LLMShieldClient, appId: string, logRecord: boolean) => {
+    if (isHooked) {
+      return;
+    }
+    isHooked = true;
+    const oldFetch = global.fetch;
+    const newFetch: typeof oldFetch = async function (...args) {
+      const url = args[0]?.toString() || '';
+      const options = (args[1] as RequestInit) || {};
+
+      // pii / prompt injection
+      if (options.body) {
+        let messagesToModerate: { role: string; content: string }[] = [];
+        let rawBody: string | undefined, jsonBody: any;
+        let bodyChanged = false;
+
+        if (typeof options.body === 'string') {
+          rawBody = options.body;
+        } else if (options.body instanceof Uint8Array || options.body instanceof ArrayBuffer) {
+          rawBody = new TextDecoder().decode(options.body);
+        }
+
+        if (rawBody) {
+          try {
+            jsonBody = JSON.parse(rawBody);
+
+            // Preprocess user messages in history: remove previous content if a block marker is identified
+            if (jsonBody && Array.isArray(jsonBody.messages) && jsonBody.messages.length > 1) {
+              for (let i = 0; i < jsonBody.messages.length - 1; i++) {
+                const m = jsonBody.messages[i];
+                if (m.role === 'user' && typeof m.content === 'string') {
+                  const newContent = preprocessContent(m.content);
+                  if (newContent !== m.content) {
+                    m.content = newContent;
+                    bodyChanged = true;
+                  }
+                }
+              }
+            }
+
+            messagesToModerate = robustExtractLastUserMessage(jsonBody);
+          } catch (e) {
+            logEvent(api, 'json_parse_failed', { url, error: String(e) }, logRecord);
+          }
+        }
+
+        if (messagesToModerate.length > 0) {
+          // 2. Prepare history (at this point, history messages have already been processed by preprocessContent above)
+          let historyV2: MessageV2[] | undefined;
+          if (jsonBody && Array.isArray(jsonBody.messages) && jsonBody.messages.length > 1) {
+            // Filter out system messages and only take the most recent 5
+            const historyMessages = jsonBody.messages
+              .slice(0, -1)
+              .filter((m: any) => m.role !== 'system')
+              .slice(-5);
+
+            historyV2 = historyMessages.map((m: any) => ({
+              Role: m.role || 'user',
+              Content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
+              ContentType: ContentTypeV2.TEXT
+            }));
+          }
+
+          const msg = messagesToModerate[0];
+          const { decision, labels } = await moderate(
+            api,
+            client,
+            appId,
+            msg.content,
+            msg.role,
+            'llm_request',
+            logRecord,
+            historyV2
+          );
+
+          if (decision === DecisionTypeV2.BLOCK) {
+            const blockReason = getBlockReason(msg.content, labels);
+            // 3. Update Session file asynchronously (background processing)
+            syncSessionContent(api, msg.content, blockReason);
+
+            logEvent(api, 'llm_request(block)', { blockReason, originalContent: msg.content }, logRecord);
+            if (jsonBody && Array.isArray(jsonBody.messages) && jsonBody.messages.length > 0) {
+              // Intercept the last message: insert block marker (prefer before \n[message_id:)
+              const lastMsg = jsonBody.messages[jsonBody.messages.length - 1];
+              lastMsg.content = insertBlockMarker(lastMsg.content, blockReason);
+              bodyChanged = true;
+            } else if (jsonBody && typeof jsonBody.prompt === 'string') {
+              jsonBody.prompt = insertBlockMarker(jsonBody.prompt, blockReason);
+              bodyChanged = true;
+            } else if (jsonBody && typeof jsonBody.input === 'string') {
+              jsonBody.input = insertBlockMarker(jsonBody.input, blockReason);
+              bodyChanged = true;
+            }
+          }
+
+          if (bodyChanged) {
+            options.body = JSON.stringify(jsonBody);
+          }
+        }
+      }
+
+      const resp = await oldFetch.apply(this, args);
+      return resp;
+    };
+    global.fetch = newFetch;
+  };
+})();
+
+const plugin = {
+  id: 'ai-assistant-security-openclaw',
+  name: pkg.name,
+  description:
+    'AI Assistant Security plugin for OpenClaw, to protect your LLM models and Agent lifecycle (including tool calls) from harmful requests.',
+  register(api: OpenClawPluginApi): void {
+    const pluginCfg = (api.pluginConfig ?? {}) as any;
+    const { endpoint, apiKey, appId } = pluginCfg;
+
+    // Calculate device fingerprint once during registration
+    if (!deviceFingerprint) {
+      deviceFingerprint = getDeviceFingerprint();
+    }
+
+    console.log(`[${pkg.name}] Device Fingerprint: ${deviceFingerprint}`);
+
+    // Update global configuration (if provided)
+    if (pluginCfg.failureThreshold !== undefined) {
+      failureThreshold = Number(pluginCfg.failureThreshold);
+    }
+    if (pluginCfg.retryInterval !== undefined) {
+      baseRetryIntervalMs = Number(pluginCfg.retryInterval) * 1000;
+      currentRetryIntervalMs = baseRetryIntervalMs;
+    }
+    if (pluginCfg.maxRetryInterval !== undefined) {
+      maxRetryIntervalMs = Number(pluginCfg.maxRetryInterval) * 1000;
+    }
+
+    // 1. Validate if apiKey and appId are empty
+    if (!apiKey || !appId) {
+      api.logger.error(
+        `[${pkg.name}] Registration failed: apiKey or appId is empty, please check the configuration.`
+      );
+      return;
+    }
+
+    // 2. Validate if endpoint is empty
+    if (!endpoint) {
+      api.logger.error(
+        `[${pkg.name}] Registration failed: endpoint is empty, please check the configuration.`
+      );
+      return;
+    }
+
+    const client = new LLMShieldClient({
+      baseUrl: endpoint,
+      apiKey,
+      timeoutMs: pluginCfg.timeoutMs ? Number(pluginCfg.timeoutMs) : undefined
+    });
+    const logRecord = !!pluginCfg.logRecord;
+    const hooksCfg = pluginCfg.hooks || {};
+    const enableFetch = hooksCfg.fetch !== false;
+    const enableBeforeToolCall = hooksCfg.beforeToolCall !== false;
+    const enableToolResultPersist = hooksCfg.toolResultPersist !== false;
+
+    // 3. Asynchronously validate endpoint connectivity and configuration
+    (async () => {
+      api.logger.info(`[${pkg.name}] Verifying configuration with moderate interface: ${endpoint}...`);
+      try {
+        await client.moderate(
+          {
+            Message: {
+              Role: 'user',
+              Content: 'hello',
+              ContentType: ContentTypeV2.TEXT
+            },
+            Scene: appId
+          },
+          {
+            'X-Ai-Device-Fingerprint': deviceFingerprint
+          }
+        );
+      } catch (e: any) {
+        api.logger.error(
+          `[${
+            pkg.name
+          }] Registration failed: Verification failed for endpoint ${endpoint}. Please check your network, apiKey, or appId configuration. Error: ${
+            e.message || e
+          }`
+        );
+        return;
+      }
+
+      // 4. Validation passed, register hook points
+      if (enableFetch) {
+        hookGlobalFetch(api, client, appId, logRecord);
+      }
+
+      // risk operations / pii
+      if (enableBeforeToolCall) {
+        api.on('before_tool_call', async (event) => {
+          const content = `Tool: ${event.toolName}, Params: ${JSON.stringify(event.params)}`;
+          const { decision, labels } = await moderate(
+            api,
+            client,
+            appId,
+            content,
+            'assistant',
+            'before_tool_call',
+            logRecord
+          );
+          if (decision === DecisionTypeV2.BLOCK) {
+            const blockReason = getBlockReason(content, labels);
+            logEvent(api, 'before_tool_call(block)', { blockReason, originalContent: content }, logRecord);
+            return { block: true, blockReason };
+          }
+        });
+      }
+
+      // risk operations / prompt injection
+      if (enableToolResultPersist) {
+        api.on('tool_result_persist', async (event) => {
+          // The actual content to be checked is event.message.content
+          const content =
+            typeof event.message?.content === 'string'
+              ? event.message.content
+              : JSON.stringify(event.message?.content || '');
+          const { decision, labels } = await moderate(
+            api,
+            client,
+            appId,
+            content,
+            'tool',
+            'tool_result_persist',
+            logRecord
+          );
+          if (decision === DecisionTypeV2.BLOCK) {
+            const blockReason = getBlockReason(content, labels);
+            logEvent(api, 'tool_result_persist(block)', { blockReason, originalContent: content }, logRecord);
+
+            // If hit, do not return block, but rewrite content and details with reason
+            const interceptedData = {
+              error: 'llm_shield_intercepted',
+              message: 'Your request has been intercepted by the LLM Application Firewall.',
+              reason: blockReason
+            };
+
+            event.message.content = [
+              {
+                type: 'text',
+                text: JSON.stringify(interceptedData, null, 2)
+              }
+            ];
+            event.message.details = interceptedData;
+
+            // Do not return block
+            return;
+          }
+        });
+      }
+
+      api.logger.info(
+        `[${pkg.name}] Plugin successfully initialized and registered hook points (fetch:${enableFetch}, beforeToolCall:${enableBeforeToolCall}, toolResultPersist:${enableToolResultPersist}).`
+      );
+    })();
+  }
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,73 @@
+{
+  "id": "ai-assistant-security-openclaw",
+  "name": "AI Assistant Security",
+  "description": "AI Assistant Security plugin for OpenClaw, to protect your LLM models and Agent lifecycle (including tool calls) from harmful requests.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "endpoint": {
+        "type": "string",
+        "description": "The API endpoint for the AI Assistant Security service."
+      },
+      "apiKey": {
+        "type": "string",
+        "description": "The API key for AI Assistant Security service."
+      },
+      "appId": {
+        "type": "string",
+        "description": "Application scenario, used to identify the business context of the current call."
+      },
+      "openClawDir": {
+        "type": "string",
+        "description": "The root directory of OpenClaw. If not provided, it defaults to the parent directory of the plugin's resolved path."
+      },
+      "logRecord": {
+        "type": "boolean",
+        "description": "Whether to enable log recording.",
+        "default": false
+      },
+      "failureThreshold": {
+        "type": "integer",
+        "description": "The number of consecutive failures before triggering degradation. Default is 3.",
+        "default": 3
+      },
+      "retryInterval": {
+        "type": "integer",
+        "description": "The base interval in seconds to retry probing after degradation. Will increase exponentially. Default is 60 (1 minute).",
+        "default": 60
+      },
+      "maxRetryInterval": {
+        "type": "integer",
+        "description": "The maximum interval in seconds for exponential backoff. Default is 3600 (1 hour).",
+        "default": 3600
+      },
+      "timeoutMs": {
+        "type": "integer",
+        "description": "Request timeout in milliseconds for the moderation API. Default is 30000.",
+        "default": 30000
+      },
+      "hooks": {
+        "type": "object",
+        "description": "Enable or disable specific hook points.",
+        "properties": {
+          "fetch": {
+            "type": "boolean",
+            "description": "Enable global fetch hook for LLM requests.",
+            "default": true
+          },
+          "beforeToolCall": {
+            "type": "boolean",
+            "description": "Enable hook for before_tool_call event.",
+            "default": true
+          },
+          "toolResultPersist": {
+            "type": "boolean",
+            "description": "Enable hook for tool_result_persist event.",
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@omni-shield/ai-assistant-security-openclaw",
+  "version": "1.0.0-beta1",
+  "type": "module",
+  "description": "AI Assistant Security plugin for OpenClaw, to protect your LLM models and Agent lifecycle (including tool calls) from harmful requests.",
+  "files": [
+    "package.json",
+    "index.ts",
+    "src",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:dev": "node scripts/publish.js --dev",
+    "publish:prod": "node scripts/publish.js"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.26"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2"
+  },
+  "dependencies": {
+    "node-machine-id": "^1.1.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.ts

@@ -0,0 +1,127 @@
+import {
+  ModerateV2Request,
+  ModerateV2Response,
+} from "./types.js";
+
+/** HTTP request error */
+export class HttpError extends Error {
+  readonly status: number;
+  readonly statusText: string;
+  readonly body?: unknown;
+
+  constructor(message: string, status: number, statusText: string, body?: unknown) {
+    super(message);
+    this.name = "HttpError";
+    this.status = status;
+    this.statusText = statusText;
+    this.body = body;
+  }
+}
+
+export interface ClientOptions {
+  /** Backend service base URL, e.g., https://xxx.byted.org */
+  baseUrl: string;
+  /** Corresponds to api_key in Go SDK */
+  apiKey: string;
+  /**
+   * Optional: custom fetch implementation (defaults to globalThis.fetch).
+   * In Node < 18, a polyfill must be provided.
+   */
+  fetchFn?: typeof fetch;
+  /** Timeout in milliseconds (defaults to 30000) */
+  timeoutMs?: number;
+}
+
+/**
+ * LLM Shield v2 TypeScript client, covers v2 capabilities only.
+ */
+export class LLMShieldClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly fetchFn: typeof fetch;
+  private readonly timeoutMs: number;
+
+  constructor(options: ClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+    this.timeoutMs = options.timeoutMs ?? 30000;
+    const fn = options.fetchFn ?? (globalThis as unknown as { fetch: typeof fetch }).fetch;
+    if (!fn) {
+      throw new Error("global fetch is unavailable. Please provide a fetch polyfill in your environment or pass an implementation via fetchFn.");
+    }
+    this.fetchFn = fn.bind(globalThis);
+  }
+
+  // -------- Internal utility methods --------
+
+  private async postJson<TReq, TRes>(path: string, body: TReq, extraHeaders?: Record<string, string>): Promise<TRes> {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const resp = await this.fetchFn(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey,
+          ...extraHeaders,
+        },
+        body: JSON.stringify(body ?? {}),
+        signal: controller.signal,
+      });
+
+      const text = await resp.text();
+
+      if (resp.status !== 200) {
+        let parsed: unknown = text;
+        try {
+          parsed = text ? JSON.parse(text) : text;
+        } catch {
+          // ignore JSON parse error
+        }
+        throw new HttpError(`Request failed with status ${resp.status}`, resp.status, resp.statusText, parsed);
+      }
+
+      try {
+        return (text ? JSON.parse(text) : {}) as TRes;
+      } catch (e) {
+        throw new Error(`JSON parsing failed: ${(e as Error).message}`, { cause: e });
+      }
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  // -------- Public methods --------
+  
+  /**
+   * Check endpoint connectivity
+   */
+  async ping(): Promise<boolean> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000); // 5s ping timeout
+
+    try {
+      const url = `${this.baseUrl}/v2/moderate`;
+      const resp = await this.fetchFn(url, {
+        method: "OPTIONS", // Use OPTIONS or a simple GET to check connectivity
+        signal: controller.signal,
+      });
+      // As long as there is a response (even 404 or 405), the endpoint is reachable
+      return !!resp.status;
+    } catch (e) {
+      return false;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Non-streaming moderation, corresponds to Go Client.Moderate.
+   */
+  async moderate(request?: ModerateV2Request, extraHeaders?: Record<string, string>): Promise<ModerateV2Response> {
+    const body: ModerateV2Request = request ?? {};
+    return this.postJson<ModerateV2Request, ModerateV2Response>("/v2/moderate", body, extraHeaders);
+  }
+}

package/src/labels.ts

@@ -0,0 +1,57 @@
+export interface LabelTranslation {
+  zh: string;
+  en: string;
+}
+
+export const LabelToTranslationMap: Record<string, LabelTranslation> = {
+  '10102000': { zh: '敏感内容', en: 'Sensitive Content' },
+  '10103005': { zh: '谩骂', en: 'Abuse' },
+  '10104000': { zh: '色情', en: 'Pornography' },
+  '10107000': { zh: '敏感内容', en: 'Sensitive Content' },
+  '10109000': { zh: '商业敏感内容', en: 'Commercial Sensitive Content' },
+  '10112000': { zh: '歧视', en: 'Discrimination' },
+  '10113002': { zh: '毒品', en: 'Drugs' },
+  '10113003': { zh: '赌博', en: 'Gambling' },
+  '10113004': { zh: '诈骗', en: 'Fraud' },
+  '10116000': { zh: '敏感内容', en: 'Sensitive Content' },
+  '10302000': { zh: '银行卡号', en: 'Bank Card Number' },
+  '10304000': { zh: '身份证号', en: 'ID Card Number' },
+  '10310000': { zh: '电子邮箱', en: 'Email Address' },
+  '10313000': { zh: '电话号码', en: 'Phone Number' },
+  '10322000': { zh: '隐私数据', en: 'Privacy Data' },
+  '10400000': { zh: '提示词攻击', en: 'Prompt Attack' },
+  '10401001': { zh: '角色扮演攻击', en: 'Role Playing Attack' },
+  '10401002': { zh: '权限提升攻击', en: 'Privilege Escalation Attack' },
+  '10401003': { zh: '对抗前后缀攻击', en: 'Adversarial Prefix/Suffix Attack' },
+  '10401004': { zh: '目标劫持攻击', en: 'Target Hijacking Attack' },
+  '10401005': { zh: '混淆和编码攻击', en: 'Obfuscation and Encoding Attack' },
+  '10401008': { zh: '少量示例攻击', en: 'Few-shot Example Attack' },
+  '10402003': { zh: '窃取提示词', en: 'Prompt Stealing' },
+  '10401013': { zh: 'URL渲染和请求攻击', en: 'URL Rendering and Requesting Attack' },
+  '10401007': { zh: '指令补齐攻击', en: 'Instruction Completion Attack' },
+  '10401011': { zh: '反向诱导攻击', en: 'Reverse Induction Attack' },
+  '10401012': { zh: '代码化描述攻击', en: 'Coded Description Attack' },
+  '10402001': { zh: '诱导生成有害内容攻击', en: 'Inducing Harmful Content Attack' },
+  '10401014': { zh: '远程代码执行攻击', en: 'Remote Code Execution Attack' },
+  '10401015': { zh: '插件投毒攻击', en: 'Plugin Poisoning Attack' },
+  '10401016': { zh: '敏感操作', en: 'Sensitive Actions' },
+  '10401017': { zh: '静默窃取', en: 'Silent Exfiltration' },
+  '10701001': { zh: '高频相似样本攻击', en: 'High-frequency Similar Samples Attack' },
+};
+
+export const isUserDefinedLabel = (label: string): boolean => {
+  const labelNum = parseInt(label, 10);
+  return labelNum >= 50000000 && labelNum <= 50099999;
+};
+
+export type Language = 'zh' | 'en';
+
+export const getLabelName = (label: string, lang: Language = 'en'): string => {
+  if (LabelToTranslationMap[label]) {
+    return LabelToTranslationMap[label][lang];
+  }
+  if (isUserDefinedLabel(label)) {
+    return lang === 'zh' ? '用户自定义标签' : 'User Defined Label';
+  }
+  return label;
+};

package/src/types.ts

@@ -0,0 +1,152 @@
+/**
+ * v2 related type definitions, matching Go SDK structure as much as possible (field names capitalized to maintain JSON compatibility).
+ */
+
+// ------------ General Metadata ------------
+
+export interface ErrorResponse {
+  Code: string;
+  Message: string;
+}
+
+export interface ResponseMetadata {
+  Error: ErrorResponse;
+  RequestId: string;
+}
+
+// ------------ Enum Definitions (consistent with Go int64 constants) ------------
+
+export enum ContentTypeV2 {
+  TEXT = 1,
+  AUDIO = 2,
+  IMAGE = 3,
+  VIDEO = 4,
+  FILE = 5,
+}
+
+export enum DecisionTypeV2 {
+  PASS = 1,
+  BLOCK = 2,
+  MARK = 3,
+  REPLACE = 4,
+  OPTIMIZE = 5,
+}
+
+export enum UserAction {
+  PASS = 1,
+  BLOCK = 2,
+  MARK = 3,
+  REPLACE = 4,
+}
+
+export enum MatchSource {
+  UNKNOWN = 0,
+  GLOBAL_CONTENTLIB = 1,
+  ADMIN_CONTENTLIB = 2,
+  USER_CONTENTLIB = 3,
+}
+
+// ------------ Core Messages and Multimodality ------------
+
+export interface MultiPart {
+  /** Content text or link */
+  Content: string;
+  /** Content type */
+  ContentType: ContentTypeV2;
+}
+
+export interface MessageV2 {
+  /** Message role: user/assistant/system/rag, etc. */
+  Role: string;
+  /** Text content or link */
+  Content: string;
+  /** Content type */
+  ContentType: ContentTypeV2;
+  /** Multimodal content, optional */
+  MultiPart?: MultiPart[];
+}
+
+// ------------ Moderate v2 Request and Response ------------
+
+export interface ModerateV2Request {
+  /** Moderation content, required in Go, kept optional here for non-streaming compatibility */
+  Message?: MessageV2;
+  /** Bound ID for streaming moderation sessions */
+  MsgID?: string;
+  /** 0: One-time moderation; 1: Streaming; 2: Force send (flush) */
+  UseStream?: number;
+  /** Scene */
+  Scene?: string;
+  /** History messages */
+  History?: MessageV2[];
+}
+
+export interface RiskMatchV2 {
+  Word: string;
+  Action?: UserAction;
+  Source: MatchSource;
+  RuleID?: string;
+}
+
+export interface PermitMatchV2 {
+  Word: string;
+  Action?: UserAction;
+  Source: MatchSource;
+  RuleID?: string;
+}
+
+export interface RiskV2 {
+  Category: string;
+  Label: string;
+  Prob?: number;
+  Matches?: RiskMatchV2[];
+}
+
+export interface RiskInfoV2 {
+  Risks: RiskV2[];
+}
+
+export interface PermitV2 {
+  Category: string;
+  Label: string;
+  Prob?: number;
+  Matches?: PermitMatchV2[];
+}
+
+export interface PermitInfoV2 {
+  Permits: PermitV2[];
+}
+
+export interface BlockDetailV2 {}
+
+export interface ReplaceDetailV2 {
+  Replacement?: MessageV2;
+}
+
+export interface DecisionDetailV2 {
+  BlockDetail?: BlockDetailV2;
+  ReplaceDetail?: ReplaceDetailV2;
+}
+
+export interface DecisionV2 {
+  DecisionType: DecisionTypeV2;
+  Detail: DecisionDetailV2;
+  DecisionStrategyID?: string;
+  HitStrategyIDs?: string[];
+}
+
+export interface ModerateV2Result {
+  MsgID: string;
+  RiskInfo?: RiskInfoV2;
+  Decision?: DecisionV2;
+  PermitInfo?: PermitInfoV2;
+  ContentInfo: string;
+  Degraded: boolean;
+  DegradeReason: string;
+}
+
+export interface ModerateV2Response {
+  ResponseMetadata: ResponseMetadata;
+  Result: ModerateV2Result;
+}
+

package/src/utils.ts

@@ -0,0 +1,78 @@
+import os from "node:os";
+import { machineIdSync } from 'node-machine-id';
+
+export function getDeviceFingerprint(): string {
+  // 使用 node-machine-id 获取设备唯一标识
+  return machineIdSync();
+}
+
+export function getLocalIP12(): string {
+  const interfaces = os.networkInterfaces();
+  for (const name of Object.keys(interfaces)) {
+    for (const iface of interfaces[name] || []) {
+      if (iface.family === "IPv4" && !iface.internal) {
+        return iface.address.split(".").map(part => part.padStart(3, "0")).join("");
+      }
+    }
+  }
+  return "000000000000";
+}
+
+export function generateRequestId(): string {
+  const now = new Date();
+  const dateStr = now.getFullYear().toString() +
+    (now.getMonth() + 1).toString().padStart(2, "0") +
+    now.getDate().toString().padStart(2, "0") +
+    now.getHours().toString().padStart(2, "0") +
+    now.getMinutes().toString().padStart(2, "0") +
+    now.getSeconds().toString().padStart(2, "0");
+  const ipStr = getLocalIP12();
+  const msStr = now.getMilliseconds().toString().padStart(3, "0");
+  const randStr = Math.floor(Math.random() * 0xFFF).toString(16).toUpperCase().padStart(3, "0");
+  return dateStr + ipStr + msStr + randStr;
+}
+
+export function containsChinese(text: string): boolean {
+  return /[\u4e00-\u9fa5]/.test(text);
+}
+
+export function robustExtractLastUserMessage(body: any): { role: string; content: string }[] {
+  if (!body || typeof body !== "object") return [];
+
+  // Handle standard OpenAI-like message format
+  if (Array.isArray(body.messages) && body.messages.length > 0) {
+    const messages = body.messages as any[];
+    const lastMessage = messages[messages.length - 1];
+    
+    // Only extract if the role of the last message is "user"
+    if (lastMessage.role !== "user") {
+      return [];
+    }
+
+    let content = "";
+    if (typeof lastMessage.content === "string") {
+      content = lastMessage.content;
+    }
+    // Handle multi-modal content array (e.g. [{ type: "text", text: "..." }])
+    else if (Array.isArray(lastMessage.content)) {
+      content = lastMessage.content
+        .filter((part: any) => part.type === "text" && typeof part.text === "string")
+        .map((part: any) => part.text)
+        .join("\n");
+    }
+
+    if (content.length > 0) {
+      return [{
+        role: "user",
+        content: content,
+      }];
+    }
+    return [];
+  }
+
+  // Handle other possible formats (e.g. anthropic, or top-level prompt)
+  if (typeof body.prompt === "string") return [{ role: "user", content: body.prompt }];
+  if (typeof body.input === "string") return [{ role: "user", content: body.input }];
+
+  return [];
+}