shellward 0.5.16 → 0.6.0

package/src/mcp-client.ts

@@ -0,0 +1,268 @@
+// src/mcp-client.ts — Minimal MCP client for security scanning
+//
+// Connects to a configured MCP server (stdio OR remote Streamable HTTP), performs
+// the initialize handshake and a single tools/list call, then disconnects. Used by
+// /scan-mcp to fetch tool *definitions* so they can be scanned for poisoning and
+// rug-pulls. Zero dependencies (child_process + node:http/https + NDJSON framing).
+
+import { spawn } from 'child_process'
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { request as httpRequest } from 'http'
+import { request as httpsRequest } from 'https'
+import { getHomeDir } from './utils.js'
+import type { McpToolDefinition } from './core/engine.js'
+
+export interface McpServerSpec {
+  name: string
+  /** 'stdio' servers are spawned; 'remote' servers are scanned over HTTP. */
+  transport: 'stdio' | 'remote'
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  url?: string
+  headers?: Record<string, string>
+  source: string
+}
+
+const CONFIG_PATHS = [
+  join(getHomeDir(), '.openclaw', 'mcp.json'),
+  join(getHomeDir(), '.openclaw', 'config', 'mcp.json'),
+  join(getHomeDir(), '.openclaw', 'settings.json'),
+]
+
+/**
+ * Discover MCP servers declared in known config files.
+ * Recognizes the standard `{ "mcpServers": { name: {...} } }` shape.
+ * @param paths override config paths (tests pass a temp file)
+ */
+export function discoverMcpServers(paths: string[] = CONFIG_PATHS): McpServerSpec[] {
+  const servers: McpServerSpec[] = []
+  const seen = new Set<string>()
+
+  for (const p of paths) {
+    if (!existsSync(p)) continue
+    let parsed: any
+    try {
+      parsed = JSON.parse(readFileSync(p, 'utf8'))
+    } catch {
+      continue
+    }
+    const block = parsed?.mcpServers || parsed?.mcp?.servers
+    if (!block || typeof block !== 'object') continue
+
+    for (const [name, raw] of Object.entries<any>(block)) {
+      if (seen.has(name)) continue
+      seen.add(name)
+      if (raw && typeof raw.command === 'string') {
+        servers.push({
+          name,
+          transport: 'stdio',
+          command: raw.command,
+          args: Array.isArray(raw.args) ? raw.args.map(String) : [],
+          env: raw.env && typeof raw.env === 'object' ? raw.env : undefined,
+          source: p,
+        })
+      } else if (raw && (typeof raw.url === 'string' || typeof raw.type === 'string')) {
+        servers.push({
+          name,
+          transport: 'remote',
+          url: raw.url,
+          headers: raw.headers && typeof raw.headers === 'object' ? raw.headers : undefined,
+          source: p,
+        })
+      }
+    }
+  }
+  return servers
+}
+
+/**
+ * Spawn a stdio MCP server, initialize, and return its tool definitions.
+ * Always resolves (never hangs): on error/timeout it cleans up and rejects.
+ */
+export function listToolsStdio(spec: McpServerSpec, timeoutMs = 8000): Promise<McpToolDefinition[]> {
+  return new Promise((resolve, reject) => {
+    if (!spec.command) return reject(new Error('not a stdio server'))
+
+    let child: ReturnType<typeof spawn>
+    try {
+      child = spawn(spec.command, spec.args || [], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env, ...(spec.env || {}) },
+      })
+    } catch (e) {
+      return reject(e as Error)
+    }
+
+    let buf = Buffer.alloc(0)
+    let settled = false
+
+    const finish = (err: Error | null, tools?: McpToolDefinition[]) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try { child.kill() } catch { /* ignore */ }
+      if (err) reject(err)
+      else resolve(tools || [])
+    }
+
+    const timer = setTimeout(() => finish(new Error(`timeout after ${timeoutMs}ms`)), timeoutMs)
+    timer.unref?.()
+
+    const send = (obj: unknown) => {
+      try { child.stdin!.write(JSON.stringify(obj) + '\n') } catch { /* ignore */ }
+    }
+
+    child.on('error', (e) => finish(e))
+    child.on('exit', () => { if (!settled) finish(new Error('server exited before tools/list')) })
+    child.stderr?.on('data', () => { /* protocol uses stdout; ignore stderr logs */ })
+
+    child.stdout!.on('data', (chunk: Buffer) => {
+      buf = Buffer.concat([buf, chunk])
+      while (true) {
+        const nl = buf.indexOf(0x0a)
+        if (nl === -1) break
+        const line = buf.slice(0, nl).toString('utf8').trim()
+        buf = buf.slice(nl + 1)
+        if (!line) continue
+        let msg: any
+        try { msg = JSON.parse(line) } catch { continue }
+
+        if (msg.id === 1 && msg.result) {
+          // initialize ack → notify initialized, then request the tool list
+          send({ jsonrpc: '2.0', method: 'notifications/initialized' })
+          send({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} })
+        } else if (msg.id === 2) {
+          const tools: McpToolDefinition[] = Array.isArray(msg.result?.tools)
+            ? msg.result.tools.map((t: any) => ({
+                name: String(t.name || 'unknown'),
+                description: typeof t.description === 'string' ? t.description : undefined,
+                inputSchema: t.inputSchema && typeof t.inputSchema === 'object' ? t.inputSchema : undefined,
+              }))
+            : []
+          finish(null, tools)
+        }
+      }
+    })
+
+    send({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'shellward-scan', version: '1' },
+      },
+    })
+  })
+}
+
+// ===== Remote (Streamable HTTP) transport =====
+
+const INIT_PARAMS = {
+  protocolVersion: '2024-11-05',
+  capabilities: {},
+  clientInfo: { name: 'shellward-scan', version: '1' },
+}
+
+/**
+ * POST a single JSON-RPC message to a Streamable-HTTP MCP endpoint and return
+ * the parsed JSON-RPC response. Handles both `application/json` and
+ * `text/event-stream` (SSE) response bodies. Captures the Mcp-Session-Id header.
+ */
+function postJsonRpc(
+  url: string,
+  body: unknown,
+  headers: Record<string, string>,
+  timeoutMs: number,
+): Promise<{ json: any; sessionId?: string }> {
+  return new Promise((resolve, reject) => {
+    let u: URL
+    try { u = new URL(url) } catch { return reject(new Error(`invalid url: ${url}`)) }
+    const isHttps = u.protocol === 'https:'
+    const requestFn = isHttps ? httpsRequest : httpRequest
+    const payload = Buffer.from(JSON.stringify(body), 'utf8')
+
+    const req = requestFn(
+      {
+        protocol: u.protocol,
+        hostname: u.hostname,
+        port: u.port || (isHttps ? 443 : 80),
+        path: u.pathname + u.search,
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          accept: 'application/json, text/event-stream',
+          'content-length': payload.length,
+          ...headers,
+        },
+        timeout: timeoutMs,
+      },
+      (res) => {
+        const chunks: Buffer[] = []
+        res.on('data', (c) => chunks.push(c))
+        res.on('end', () => {
+          const sessionId = (res.headers['mcp-session-id'] as string) || undefined
+          const text = Buffer.concat(chunks).toString('utf8')
+          if ((res.statusCode || 0) >= 400) {
+            return reject(new Error(`HTTP ${res.statusCode}`))
+          }
+          const json = parseRpcBody(text)
+          if (json === undefined) return resolve({ json: null, sessionId })
+          resolve({ json, sessionId })
+        })
+      },
+    )
+    req.on('error', reject)
+    req.on('timeout', () => req.destroy(new Error(`timeout after ${timeoutMs}ms`)))
+    req.end(payload)
+  })
+}
+
+/** Extract a JSON-RPC object from a JSON or SSE (text/event-stream) body. */
+function parseRpcBody(text: string): any {
+  const trimmed = text.trim()
+  if (!trimmed) return undefined
+  // Plain JSON
+  if (trimmed[0] === '{' || trimmed[0] === '[') {
+    try { return JSON.parse(trimmed) } catch { /* fall through to SSE */ }
+  }
+  // SSE: take the last non-empty `data:` line that parses as JSON
+  let result: any
+  for (const line of trimmed.split(/\r?\n/)) {
+    const m = line.match(/^data:\s*(.*)$/)
+    if (m && m[1]) {
+      try { result = JSON.parse(m[1]) } catch { /* ignore */ }
+    }
+  }
+  return result
+}
+
+/**
+ * Initialize a remote MCP server over Streamable HTTP and return its tool
+ * definitions. Best-effort: returns [] if the server speaks an unsupported
+ * dialect. Rejects on network error / timeout.
+ */
+export async function listToolsHttp(spec: McpServerSpec, timeoutMs = 8000): Promise<McpToolDefinition[]> {
+  if (!spec.url) throw new Error('not a remote server')
+  const baseHeaders = spec.headers || {}
+
+  const init = await postJsonRpc(spec.url, { jsonrpc: '2.0', id: 1, method: 'initialize', params: INIT_PARAMS }, baseHeaders, timeoutMs)
+  const sessionHeaders = init.sessionId ? { ...baseHeaders, 'mcp-session-id': init.sessionId } : baseHeaders
+
+  // Best-effort initialized notification (ignore failures).
+  try {
+    await postJsonRpc(spec.url, { jsonrpc: '2.0', method: 'notifications/initialized' }, sessionHeaders, timeoutMs)
+  } catch { /* some servers don't need it */ }
+
+  const listed = await postJsonRpc(spec.url, { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }, sessionHeaders, timeoutMs)
+  const tools = listed.json?.result?.tools
+  if (!Array.isArray(tools)) return []
+  return tools.map((t: any) => ({
+    name: String(t.name || 'unknown'),
+    description: typeof t.description === 'string' ? t.description : undefined,
+    inputSchema: t.inputSchema && typeof t.inputSchema === 'object' ? t.inputSchema : undefined,
+  }))
+}

package/src/mcp-server.ts

@@ -2,22 +2,26 @@
 // src/mcp-server.ts — ShellWard MCP Server
 //
 // Exposes ShellWard's 8-layer security engine as an MCP server.
-// Zero dependencies — implements MCP protocol over stdio natively.
+// Zero dependencies — implements MCP protocol over stdio (newline-delimited JSON).
 //
-// Usage:
-//   npx tsx src/mcp-server.ts
+// Run (production, after `npm run build` or `npm i -g shellward`):
+//   shellward-mcp           # via the published bin
+//   node dist/mcp-server.js # direct
+//
+// Run (development, from source):
+//   npm run mcp             # npx tsx src/mcp-server.ts
 //
 // MCP config (claude_desktop_config.json / openclaw settings):
 //   {
 //     "mcpServers": {
 //       "shellward": {
-//         "command": "npx",
-//         "args": ["tsx", "/path/to/shellward/src/mcp-server.ts"]
+//         "command": "shellward-mcp"
 //       }
 //     }
 //   }
 
 import { ShellWard } from './core/engine.js'
+import { McpBaseline } from './mcp-baseline.js'
 import { readFileSync } from 'fs'
 import { createInterface } from 'readline'
 import { fileURLToPath } from 'url'
@@ -58,9 +62,13 @@ const guard = new ShellWard({
     dataFlowGuard: true,
     sessionGuard: true,
   },
-  injectionThreshold: Number(process.env.SHELLWARD_THRESHOLD) || 60,
+  injectionThreshold: Number(process.env.SHELLWARD_THRESHOLD) || 40,
 })
 
+// Rug-pull baseline store (lazy-persisted; only used when a `server` is supplied).
+// SHELLWARD_BASELINE_PATH relocates the store (tests/sandboxes use a temp file).
+const baseline = new McpBaseline(process.env.SHELLWARD_BASELINE_PATH || undefined)
+
 // ===== Tool Definitions =====
 
 const TOOLS = [
@@ -77,12 +85,12 @@ const TOOLS = [
   },
   {
     name: 'check_injection',
-    description: 'Detect prompt injection attempts in text. Supports 32+ rules for Chinese and English, with hidden character detection.',
+    description: 'Detect prompt injection attempts in text. Supports 37+ rules for Chinese and English, with hidden character detection.',
     inputSchema: {
       type: 'object' as const,
       properties: {
         text: { type: 'string', description: 'Text to scan for injection attempts' },
-        threshold: { type: 'number', description: 'Detection threshold 0-100 (default: 60, lower = stricter)' },
+        threshold: { type: 'number', description: 'Detection threshold 0-100 (default: 40, lower = stricter)' },
       },
       required: ['text'],
     },
@@ -132,6 +140,21 @@ const TOOLS = [
       required: ['content'],
     },
   },
+  {
+    name: 'scan_mcp_tool',
+    description: 'Scan an MCP tool definition for tool-poisoning (hidden/invisible-character instructions, concealment directives, sensitive-file access, exfiltration hints) AND rug-pull (description silently changed since first seen). Pass a tool as { name, description, inputSchema }; provide "server" to enable rug-pull baselining.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        name: { type: 'string', description: 'Tool name' },
+        description: { type: 'string', description: 'Tool description to scan' },
+        inputSchema: { type: 'object', description: 'Tool JSON Schema (optional) — nested parameter descriptions are scanned too' },
+        server: { type: 'string', description: 'MCP server name (optional) — enables rug-pull detection by fingerprinting the tool across runs' },
+        threshold: { type: 'number', description: 'Detection threshold (default: 40)' },
+      },
+      required: ['name'],
+    },
+  },
   {
     name: 'security_status',
     description: 'Get current ShellWard security status: mode, active layers, detection capabilities.',
@@ -221,6 +244,44 @@ function executeTool(name: string, args: Record<string, unknown>): unknown {
       }
     }
 
+    case 'scan_mcp_tool': {
+      const tool = {
+        name: String(args.name || 'unknown'),
+        description: typeof args.description === 'string' ? args.description : undefined,
+        inputSchema: (args.inputSchema && typeof args.inputSchema === 'object')
+          ? (args.inputSchema as Record<string, unknown>)
+          : undefined,
+      }
+      const result = guard.scanToolDefinition(
+        tool,
+        typeof args.threshold === 'number' ? { threshold: args.threshold } : undefined,
+      )
+
+      // Optional rug-pull detection: fingerprint the tool across runs.
+      let rugPull: { status: string; changed: boolean } | null = null
+      if (typeof args.server === 'string' && args.server) {
+        const rp = baseline.record(McpBaseline.keyFor(args.server, tool.name), tool)
+        baseline.save()
+        rugPull = { status: rp.status, changed: rp.status === 'changed' }
+      }
+
+      return {
+        tool_name: result.toolName,
+        safe: result.safe && !(rugPull?.changed),
+        score: result.score,
+        threshold: result.threshold,
+        hidden_chars: result.hiddenChars,
+        rug_pull: rugPull,
+        findings: result.findings.map(f => ({
+          id: f.id,
+          name: f.name,
+          category: f.category,
+          score: f.score,
+          source: f.source,
+        })),
+      }
+    }
+
     case 'security_status': {
       return {
         mode: guard.config.mode,
@@ -229,7 +290,8 @@ function executeTool(name: string, args: Record<string, unknown>): unknown {
         layers: guard.config.layers,
         capabilities: [
           'command_safety_check (17 dangerous patterns)',
-          'prompt_injection_detection (32+ rules, zh+en)',
+          'prompt_injection_detection (37+ rules, zh+en)',
+          'mcp_tool_poisoning_scan (description + schema)',
           'pii_detection (CN ID/phone/bank + global)',
           'path_protection (12 protected patterns)',
           'tool_policy (block payment/transfer)',

package/src/rules/dangerous-commands.ts

@@ -5,7 +5,8 @@ import type { DangerousCommandRule } from '../types.js'
 export const DANGEROUS_COMMANDS: DangerousCommandRule[] = [
   {
     id: 'rm_rf_root',
-    pattern: /rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+-[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*\s+-[a-zA-Z]*r|-[a-zA-Z]*rf[a-zA-Z]*)\s+[\/~]/i,
+    // Match -rf / -fr (combined, either order) and the two-flag forms, then a path.
+    pattern: /rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+-[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*\s+-[a-zA-Z]*r|-[a-zA-Z]*(?:rf|fr)[a-zA-Z]*)\s+[\/~]/i,
     description_zh: '递归强制删除根目录或用户目录',
     description_en: 'Recursive force delete on root or home directory',
   },
@@ -113,5 +114,8 @@ export const DANGEROUS_COMMANDS: DangerousCommandRule[] = [
  * - Trim whitespace
  */
 export function splitCommands(cmd: string): string[] {
-  return cmd.split(/\s*(?:;|&&|\|\||[\r\n]+)\s*/).filter(Boolean)
+  // Split on separators only, then trim in JS. The previous `\s*(...)\s*` form
+  // backtracked catastrophically on long whitespace runs (ReDoS) — splitting
+  // without the surrounding `\s*` is linear.
+  return cmd.split(/(?:;|&&|\|\||[\r\n]+)/).map(s => s.trim()).filter(Boolean)
 }

package/src/rules/injection-en.ts

@@ -24,9 +24,26 @@ export const INJECTION_RULES_EN: InjectionRule[] = [
     name: 'System prompt extraction',
     pattern: '(?:output|print|show|reveal|display|repeat|leak|dump)\\s+(?:your\\s+)?(?:system|initial|original|full)?\\s*(?:prompt|instructions?|rules?|guidelines?)',
     flags: 'i',
-    riskScore: 30,
+    // High-confidence single signal — legit users rarely ask to dump the prompt.
+    riskScore: 40,
     category: 'exfiltration',
   },
+  {
+    id: 'en_disregard',
+    name: 'Disregard prior context',
+    pattern: 'disregard\\s+(?:the\\s+)?(?:above|previous|prior|earlier|preceding|all|these|those)',
+    flags: 'i',
+    riskScore: 40,
+    category: 'override',
+  },
+  {
+    id: 'en_no_guidelines',
+    name: 'Operate without guidelines',
+    pattern: '(?:no|without|free\\s+of|free\\s+from)\\s+(?:ethical\\s+|content\\s+|safety\\s+)?(?:guidelines?|content\\s+policy|restrictions?|filters?|guardrails?|limitations?)',
+    flags: 'i',
+    riskScore: 30,
+    category: 'override',
+  },
   {
     id: 'en_developer_mode',
     name: 'Developer/admin mode',
@@ -38,11 +55,19 @@ export const INJECTION_RULES_EN: InjectionRule[] = [
   {
     id: 'en_no_restriction',
     name: 'Remove restrictions',
-    pattern: '(?:remove|disable|turn\\s+off|bypass|ignore|skip|override|circumvent)\\s+(?:all\\s+)?(?:restrictions?|constraints?|safety|filters?|guardrails?|limitations?|safeguards?)',
+    pattern: '(?:remove|disable|turn\\s+off|bypass|ignore|skip|override|circumvent)\\s+(?:all\\s+|your\\s+|the\\s+)?(?:safety\\s+|content\\s+)?(?:restrictions?|constraints?|safety|filters?|guardrails?|limitations?|safeguards?|guidelines?|rules?|policy)',
     flags: 'i',
     riskScore: 40,
     category: 'override',
   },
+  {
+    id: 'en_new_instructions',
+    name: 'New/updated instructions marker',
+    pattern: '(?:^|[\\n.])\\s*(?:new|updated|revised|additional|important)\\s+instructions?\\b',
+    flags: 'i',
+    riskScore: 30,
+    category: 'injection',
+  },
   {
     id: 'en_do_anything',
     name: 'Do Anything Now (DAN)',

package/src/rules/injection-zh.ts

@@ -6,7 +6,8 @@ export const INJECTION_RULES_ZH: InjectionRule[] = [
   {
     id: 'zh_ignore_prev',
     name: '忽略之前指令',
-    pattern: '(?:请|你要|现在)?忽略(?:之前|上面|以上|前面|所有)(?:的)?(?:指令|指示|规则|提示|要求|约束)',
+    // Allow intervening qualifiers (e.g. 忽略之前的所有指令) between 忽略 and the noun.
+    pattern: '(?:请|你要|现在)?忽略(?:之前|上面|以上|前面|所有|这些|那些|一切|的)*(?:指令|指示|规则|提示|要求|约束)',
     riskScore: 40,
     category: 'override',
   },
@@ -21,7 +22,18 @@ export const INJECTION_RULES_ZH: InjectionRule[] = [
     id: 'zh_system_prompt',
     name: '系统提示窃取',
     pattern: '(?:输出|显示|打印|告诉我|重复|泄露|展示)(?:你的)?(?:系统|初始|原始)?(?:提示词|system\\s*prompt|指令|规则|约束)',
-    riskScore: 30,
+    // System-prompt extraction is a high-confidence single signal — legit users
+    // rarely ask the model to dump its own prompt.
+    riskScore: 40,
+    category: 'exfiltration',
+  },
+  {
+    id: 'zh_system_prompt_rev',
+    name: '系统提示窃取(语序倒置)',
+    // Noun-first phrasing, e.g. 把你的系统提示词完整输出给我
+    pattern: '(?:系统|初始|原始)?(?:提示词|system\\s*prompt).{0,8}(?:输出|发给|发送|告诉|给我|泄露|打印|复述|展示)',
+    flags: 'i',
+    riskScore: 40,
     category: 'exfiltration',
   },
   {
@@ -38,6 +50,14 @@ export const INJECTION_RULES_ZH: InjectionRule[] = [
     riskScore: 40,
     category: 'override',
   },
+  {
+    id: 'zh_no_restriction_rev',
+    name: '解除限制(语序倒置)',
+    // Noun-first phrasing, e.g. 把所有限制都取消掉
+    pattern: '(?:限制|约束|安全限制|过滤|审查|规则限制)(?:都|全部|统统)?(?:取消|解除|移除|去掉|关闭|解除掉|取消掉)',
+    riskScore: 40,
+    category: 'override',
+  },
   {
     id: 'zh_do_not_refuse',
     name: '禁止拒绝',
@@ -90,8 +110,9 @@ export const INJECTION_RULES_ZH: InjectionRule[] = [
   {
     id: 'zh_send_to_url',
     name: '发送到外部 URL',
+    // Sending anything to an external URL is a high-confidence exfil signal.
     pattern: '(?:发送|传输|上传|转发|发)(?:到|给|至)\\s*https?://',
-    riskScore: 35,
+    riskScore: 40,
     category: 'exfiltration',
   },
   {
@@ -127,7 +148,9 @@ export const INJECTION_RULES_ZH: InjectionRule[] = [
   {
     id: 'zh_mixed_lang_injection',
     name: '中英混合注入',
-    pattern: '(?:please|pls|now)?\\s*(?:ignore|forget|disregard)\\s+.*(?:指令|规则|之前|以上)|(?:忽略|忘记|跳过).*(?:instruction|rule|prompt|previous)',
+    // Bound the `.*` gaps (was unbounded → O(n^2) backtracking / ReDoS on long
+    // repeated trigger input). Mixed-language markers sit close together.
+    pattern: '(?:please|pls|now)?\\s*(?:ignore|forget|disregard)\\s+.{0,40}?(?:指令|规则|之前|以上)|(?:忽略|忘记|跳过).{0,40}?(?:instruction|rule|prompt|previous)',
     flags: 'i',
     riskScore: 40,
     category: 'override',

package/src/rules/sensitive-patterns.ts

@@ -80,13 +80,19 @@ export const SENSITIVE_PATTERNS: SensitivePattern[] = [
   {
     id: 'phone_cn',
     name: '手机号 / CN Phone',
-    regex: /(?<!\d)1[3-9]\d{9}(?!\d)/g,
+    // Restrict the 2nd–3rd digits to real CN carrier segment allocations so
+    // arbitrary 11-digit numbers (order IDs, timestamps) don't false-positive.
+    // 13x · 14[falsey skip 2/3] · 15x(skip 4) · 16[2567] · 17x · 18x · 19x(skip 4)
+    regex: /(?<!\d)1(?:3\d|4[01456789]|5[0-35-9]|6[2567]|7[0-8]|8\d|9[0-35-9])\d{8}(?!\d)/g,
     replacement: '[REDACTED:手机号]',
   },
   {
     id: 'bank_card_cn',
-    name: '银行卡号 / CN Bank Card',
-    regex: /(?<!\d)(?:62|4|5[1-5])\d{14,17}(?!\d)/g,
+    name: '银行卡号 / CN UnionPay Card',
+    // UnionPay-only (BIN 62). Visa (4xxx) / Mastercard (5[1-5]xx) are handled by
+    // the `credit_card` rule — keeping them out of here removes the double-match
+    // that mislabeled international cards as CN bank cards.
+    regex: /(?<!\d)62\d{14,17}(?!\d)/g,
     replacement: '[REDACTED:银行卡号]',
     validate: validateLuhn,
   },
@@ -134,14 +140,40 @@ export function scanForSensitive(text: string): ScanMatch[] {
   return results
 }
 
+/**
+ * Compile user-supplied pattern strings into SensitivePattern objects.
+ * Invalid regexes are skipped (never throws). The global flag is always added.
+ */
+export function compileSensitivePatterns(
+  patterns: { id: string; name: string; pattern: string; flags?: string; replacement?: string }[],
+): SensitivePattern[] {
+  const out: SensitivePattern[] = []
+  for (const p of patterns || []) {
+    try {
+      const flags = (p.flags || '').includes('g') ? p.flags! : `${p.flags || ''}g`
+      out.push({
+        id: p.id,
+        name: p.name,
+        regex: new RegExp(p.pattern, flags),
+        replacement: p.replacement ?? `[REDACTED:${p.name}]`,
+      })
+    } catch { /* skip invalid pattern */ }
+  }
+  return out
+}
+
 /**
  * Redact all sensitive data in text. Returns [redactedText, findings[]]
+ * @param extra additional patterns merged after the built-ins
  */
-export function redactSensitive(text: string): [string, { id: string; name: string; count: number }[]] {
+export function redactSensitive(
+  text: string,
+  extra: SensitivePattern[] = [],
+): [string, { id: string; name: string; count: number }[]] {
   let result = text
   const findings: { id: string; name: string; count: number }[] = []
 
-  for (const pat of SENSITIVE_PATTERNS) {
+  for (const pat of [...SENSITIVE_PATTERNS, ...extra]) {
     const regex = new RegExp(pat.regex.source, pat.regex.flags)
     let count = 0
     result = result.replace(regex, (match) => {