shellward 0.5.16 → 0.6.1

package/dist/rules/tool-poisoning.js

@@ -0,0 +1,96 @@
+// src/rules/tool-poisoning.ts — MCP tool-poisoning detection rules
+//
+// Tool poisoning = malicious instructions hidden in an MCP tool's *metadata*
+// (description / parameter descriptions) that the LLM reads but the human never
+// sees in the UI. These are distinct from generic prompt-injection in user text:
+// they target the agent at tool-discovery time. Patterns below are tuned for the
+// common public PoCs (Invariant Labs, MCP-Shield, Snyk agent-scan).
+export const TOOL_POISONING_RULES = [
+    // ===== Hidden instruction markup =====
+    {
+        id: 'tp_important_tag',
+        name: 'Hidden <IMPORTANT>/<system> directive in description',
+        pattern: /<\s*(?:important|system|secret|instructions?|admin)\s*>/i,
+        riskScore: 45,
+        category: 'hidden_instruction',
+    },
+    {
+        id: 'tp_before_using',
+        name: 'Pre-tool instruction injection',
+        pattern: /before\s+(?:using|calling|invoking|running)\s+(?:any\s+other|this|the|another)\s+tool/i,
+        riskScore: 40,
+        category: 'hidden_instruction',
+    },
+    {
+        id: 'tp_zh_before_using',
+        name: '工具描述内前置指令注入',
+        pattern: /(?:在使用|调用|执行)(?:任何)?(?:其他|这个|该)?工具(?:之前|前)/,
+        riskScore: 40,
+        category: 'hidden_instruction',
+    },
+    // ===== Concealment ("don't tell the user") =====
+    {
+        id: 'tp_do_not_tell',
+        name: 'Instruction to hide activity from user',
+        pattern: /(?:do\s+not|don'?t|never)\s+(?:tell|inform|mention|notify|reveal|show)\s+(?:to\s+)?(?:the\s+)?(?:user|human|operator)/i,
+        riskScore: 45,
+        category: 'concealment',
+    },
+    {
+        id: 'tp_zh_do_not_tell',
+        name: '指示对用户隐藏行为',
+        pattern: /(?:不要|不得|切勿|别)(?:告诉|告知|提示|通知|让)?(?:用户|使用者)(?:知道|看到|发现)?/,
+        riskScore: 45,
+        category: 'concealment',
+    },
+    {
+        id: 'tp_without_user',
+        name: 'Act without user knowledge/consent',
+        pattern: /without\s+(?:the\s+)?(?:user'?s?\s+)?(?:knowledge|consent|awareness|noticing|telling)/i,
+        riskScore: 40,
+        category: 'concealment',
+    },
+    // ===== Sensitive data access from a tool description =====
+    {
+        id: 'tp_read_secrets',
+        // Bare mention of a sensitive path is only weakly suspicious — legitimate
+        // tools (dotenv loaders, ssh managers) and security tools name these too.
+        // Scored below threshold so it must corroborate another signal to block.
+        name: 'Description references sensitive files',
+        pattern: /(?:~\/\.ssh|id_rsa|\.aws\/credentials|\.env\b|\.cursor\/mcp\.json|\.npmrc|\/etc\/passwd|\.config\/.*(?:token|secret|credential))/i,
+        riskScore: 25,
+        category: 'data_access',
+    },
+    {
+        id: 'tp_pass_file_contents',
+        name: 'Description asks to pass file/secret contents as a parameter',
+        pattern: /(?:pass|include|read|send|provide|attach)\s+(?:the\s+)?(?:full\s+)?(?:contents?|content|value)\s+of\s+(?:the\s+)?(?:file|\S*(?:key|token|secret|password|credential))/i,
+        riskScore: 35,
+        category: 'data_access',
+    },
+    // ===== Exfiltration hints =====
+    {
+        id: 'tp_exfil_url',
+        name: 'Description instructs sending data to a URL',
+        pattern: /(?:send|transmit|upload|post|exfiltrate|forward)\s+(?:it|this|the\s+\w+|data|results?)?\s*(?:to|via)\s+(?:https?:\/\/|the\s+(?:webhook|endpoint|server|url))/i,
+        riskScore: 40,
+        category: 'exfiltration',
+    },
+    {
+        id: 'tp_exfiltrate_verb',
+        // "exfiltrate" in a tool description is almost never benign.
+        name: 'Exfiltration verb in description',
+        pattern: /\bexfiltrat(?:e|ion|ing)\b/i,
+        riskScore: 35,
+        category: 'exfiltration',
+    },
+    {
+        id: 'tp_sidechannel',
+        // A bare side-channel hostname is weak on its own (could be documentation);
+        // scored below threshold so it must accompany another signal to block.
+        name: 'Known exfiltration side-channel keyword',
+        pattern: /\b(?:webhook\.site|requestbin|pastebin|ngrok\.io|burpcollaborator|interact\.sh|oast\b)/i,
+        riskScore: 25,
+        category: 'exfiltration',
+    },
+];

package/dist/types.d.ts

@@ -14,6 +14,38 @@ export interface ShellWardConfig {
         sessionGuard: boolean;
     };
     injectionThreshold: number;
+    /** User-supplied rules merged on top of the built-ins (additive; allowedTools wins). */
+    customRules?: CustomRules;
+}
+/** A user-defined PII/secret pattern (regex source as a string for JSON-friendliness). */
+export interface CustomSensitivePattern {
+    id: string;
+    name: string;
+    pattern: string;
+    flags?: string;
+    replacement?: string;
+}
+/** A user-defined dangerous-command pattern. */
+export interface CustomCommandRule {
+    id: string;
+    pattern: string;
+    flags?: string;
+    description?: string;
+}
+/**
+ * Extension points for any platform embedding ShellWard. All fields are optional
+ * and ADDITIVE on top of the built-in rules — except `allowedTools`, which always
+ * wins (a tool listed there is never blocked and is treated as low-risk).
+ */
+export interface CustomRules {
+    blockedTools?: string[];
+    allowedTools?: string[];
+    sensitiveTools?: string[];
+    outboundTools?: string[];
+    honeypotPaths?: string[];
+    sensitivePatterns?: CustomSensitivePattern[];
+    dangerousCommands?: CustomCommandRule[];
+    injectionRules?: InjectionRule[];
 }
 export type ResolvedLocale = 'zh' | 'en';
 export interface AuditEntry {

package/dist/types.js

@@ -13,7 +13,9 @@ export const DEFAULT_CONFIG = {
         dataFlowGuard: true,
         sessionGuard: true,
     },
-    injectionThreshold: 60,
+    // 40 catches single high-confidence signals (one strong rule = a block) while
+    // keeping benign "act as…"-style phrasing (≤35) safe. Calibrated against bench/.
+    injectionThreshold: 40,
 };
 /**
  * Detect locale from system environment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellward",
-  "version": "0.5.16",
+  "version": "0.6.1",
   "mcpName": "io.github.jnMetaCode/shellward",
   "description": "AI agent security & MCP security middleware — prompt injection detection, AI firewall, runtime guardrails & data-loss prevention for LLM tool calls. 8-layer defense against data exfiltration & dangerous commands. Zero dependencies. SDK + OpenClaw plugin. Supports LangChain, AutoGPT, Claude Code, Cursor, OpenAI Agents, Hermes Agent.",
   "keywords": [
@@ -57,11 +57,13 @@
   "scripts": {
     "build": "tsc",
     "mcp": "npx tsx src/mcp-server.ts",
-    "test": "npx tsx test-sdk.ts && npx tsx test-integration.ts && npx tsx test-edge-cases.ts && npx tsx test-mcp.ts",
+    "test": "npx tsx test-sdk.ts && npx tsx test-integration.ts && npx tsx test-edge-cases.ts && npx tsx test-rugpull.ts && npx tsx test-redos.ts && npx tsx test-mcp-client.ts && npx tsx test-mcp.ts",
+    "test:redos": "npx tsx test-redos.ts",
     "test:integration": "npx tsx test-integration.ts",
     "test:edge": "npx tsx test-edge-cases.ts",
     "test:sdk": "npx tsx test-sdk.ts",
     "test:mcp": "npx tsx test-mcp.ts",
+    "bench": "npx tsx bench/run.ts",
     "prepublishOnly": "npm run build"
   },
   "openclaw": {

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/jnMetaCode/shellward",
     "source": "github"
   },
-  "version": "0.5.15",
+  "version": "0.6.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "shellward",
-      "version": "0.5.15",
+      "version": "0.6.1",
       "runtime": "node",
       "transport": {
         "type": "stdio"

package/src/auto-check.ts

@@ -6,6 +6,7 @@ import { existsSync, readFileSync, readdirSync } from 'fs'
 import { join } from 'path'
 import { getHomeDir } from './utils.js'
 import { fetchVulnDB, compareVersions } from './update-check.js'
+import { discoverMcpServers } from './mcp-client.js'
 
 const OPENCLAW_DIR = join(getHomeDir(), '.openclaw')
 
@@ -13,6 +14,7 @@ export interface AutoCheckResult {
   openclawVulns: { id: string; severity: string; description: string }[]
   pluginRisks: { plugin: string; risk: string }[]
   mcpRisks: { config: string; risk: string }[]
+  mcpServerCount: number
   rootWarning: boolean
 }
 
@@ -131,7 +133,9 @@ export async function runAutoCheck(locale: 'zh' | 'en' = 'en'): Promise<AutoChec
     Promise.resolve(scanMcpConfig()),
   ])
   const rootWarning = typeof process.getuid === 'function' && process.getuid() === 0
-  return { openclawVulns, pluginRisks, mcpRisks, rootWarning }
+  let mcpServerCount = 0
+  try { mcpServerCount = discoverMcpServers().filter(s => s.transport === 'stdio').length } catch { /* ignore */ }
+  return { openclawVulns, pluginRisks, mcpRisks, mcpServerCount, rootWarning }
 }
 
 /**
@@ -172,6 +176,12 @@ export function runAutoCheckOnStartup(logger: { warn: (s: string) => void }, loc
       lines.push(zh ? '⚠️ 正在以 root 运行，建议使用普通用户' : '⚠️ Running as root, consider using non-root user')
     }
 
+    if (result.mcpServerCount > 0) {
+      lines.push(zh
+        ? `🔌 检测到 ${result.mcpServerCount} 个 MCP 服务器 — 运行 /scan-mcp 检测工具投毒与 rug-pull`
+        : `🔌 ${result.mcpServerCount} MCP server(s) configured — run /scan-mcp to check for tool poisoning & rug-pulls`)
+    }
+
     if (lines.length > 0) {
       logger.warn((zh ? '[ShellWard] 自动安全检查:\n' : '[ShellWard] Auto security check:\n') + lines.join('\n'))
     }

package/src/commands/index.ts

@@ -6,10 +6,12 @@ import { registerSecurityCommand } from './security.js'
 import { registerAuditCommand } from './audit.js'
 import { registerHardenCommand } from './harden.js'
 import { registerScanPluginsCommand } from './scan-plugins.js'
+import { registerScanMcpCommand } from './scan-mcp.js'
 import { registerCheckUpdatesCommand } from './check-updates.js'
 import { registerUpgradeOpenClawCommand } from './upgrade-openclaw.js'
 
-export function registerAllCommands(api: any, config: ShellWardConfig) {
+/** @returns number of registered commands (for the startup log). */
+export function registerAllCommands(api: any, config: ShellWardConfig): number {
   const locale = resolveLocale(config)
 
   // Register individual commands
@@ -17,6 +19,7 @@ export function registerAllCommands(api: any, config: ShellWardConfig) {
   registerAuditCommand(api, config)
   registerHardenCommand(api, config)
   registerScanPluginsCommand(api, config)
+  registerScanMcpCommand(api, config)
   registerCheckUpdatesCommand(api, config)
   registerUpgradeOpenClawCommand(api, config)
 
@@ -36,6 +39,7 @@ export function registerAllCommands(api: any, config: ShellWardConfig) {
 | \`/audit [数量] [过滤]\` | 查看审计日志 (过滤: block/audit/critical/high) |
 | \`/harden\` | 安全扫描 · \`/harden fix\` 自动修复权限 |
 | \`/scan-plugins\` | 扫描已安装插件的安全风险 |
+| \`/scan-mcp\` | 扫描已配置 MCP 服务器（工具投毒 + rug-pull） |
 | \`/check-updates\` | 检查 OpenClaw 版本和已知漏洞 |
 | \`/upgrade-openclaw\` | 一键升级 OpenClaw · \`/upgrade-openclaw yes\` 直接执行 |
 
@@ -50,6 +54,7 @@ L5 安全门 · L6 回复审计 · L7 数据流监控 · L8 会话安全`
 | \`/audit [count] [filter]\` | View audit log (filter: block/audit/critical/high) |
 | \`/harden\` | Security scan · \`/harden fix\` to auto-fix permissions |
 | \`/scan-plugins\` | Scan installed plugins for security risks |
+| \`/scan-mcp\` | Scan configured MCP servers (tool poisoning + rug-pull) |
 | \`/check-updates\` | Check OpenClaw version and known vulnerabilities |
 | \`/upgrade-openclaw\` | Upgrade OpenClaw · \`/upgrade-openclaw yes\` to execute |
 
@@ -58,4 +63,7 @@ L1 Prompt Guard · L2 Output Scanner · L3 Tool Blocker · L4 Input Auditor
 L5 Security Gate · L6 Outbound Guard · L7 Data Flow Guard · L8 Session Guard`,
     }),
   })
+
+  // 7 individual commands + /cg help
+  return 8
 }

package/src/commands/scan-mcp.ts

@@ -0,0 +1,118 @@
+// src/commands/scan-mcp.ts — /scan-mcp: connect to configured MCP servers and
+// scan their tool definitions for poisoning + rug-pulls.
+//
+// Safety model (mirrors Snyk agent-scan): scanning spawns the configured stdio
+// servers, so it is an explicit user action — never auto-run at startup.
+
+import { ShellWard } from '../core/engine.js'
+import { McpBaseline } from '../mcp-baseline.js'
+import { discoverMcpServers, listToolsStdio, listToolsHttp } from '../mcp-client.js'
+import type { ShellWardConfig } from '../types.js'
+import { resolveLocale } from '../types.js'
+
+export function registerScanMcpCommand(api: any, config: ShellWardConfig) {
+  const locale = resolveLocale(config)
+
+  api.registerCommand({
+    name: 'scan-mcp',
+    description: locale === 'zh'
+      ? '🔌 扫描已配置的 MCP 服务器（工具投毒 + rug-pull 检测）'
+      : '🔌 Scan configured MCP servers (tool poisoning + rug-pull)',
+    acceptsArgs: false,
+    handler: async () => {
+      const zh = locale === 'zh'
+      const guard = new ShellWard(config)
+      const baseline = new McpBaseline()
+      const lines: string[] = []
+
+      lines.push(zh ? '🔌 **MCP 服务器安全扫描**' : '🔌 **MCP Server Security Scan**')
+      lines.push('')
+
+      const servers = discoverMcpServers()
+      if (servers.length === 0) {
+        lines.push(zh
+          ? 'ℹ️ 未发现已配置的 MCP 服务器（检查 ~/.openclaw/mcp.json 等）。'
+          : 'ℹ️ No configured MCP servers found (checked ~/.openclaw/mcp.json etc).')
+        return { text: lines.join('\n') }
+      }
+
+      const stdioServers = servers.filter(s => s.transport === 'stdio')
+      const remoteServers = servers.filter(s => s.transport === 'remote')
+
+      lines.push(zh
+        ? `发现 ${servers.length} 个服务器（${stdioServers.length} 个 stdio，${remoteServers.length} 个远程）`
+        : `Found ${servers.length} servers (${stdioServers.length} stdio, ${remoteServers.length} remote)`)
+      lines.push('')
+
+      let totalTools = 0
+      let poisoned = 0
+      let rugPulls = 0
+      let unreachable = 0
+
+      for (const server of servers) {
+        let tools
+        try {
+          tools = server.transport === 'remote'
+            ? await listToolsHttp(server)
+            : await listToolsStdio(server)
+        } catch (e: any) {
+          unreachable++
+          const where = server.transport === 'remote' ? server.url || 'remote' : 'stdio'
+          lines.push(zh
+            ? `### ⚠️ ${server.name} (${where}) — 无法连接 (${e?.message || 'error'})`
+            : `### ⚠️ ${server.name} (${where}) — unreachable (${e?.message || 'error'})`)
+          lines.push('')
+          continue
+        }
+
+        const serverIssues: string[] = []
+        for (const tool of tools) {
+          totalTools++
+          const scan = guard.scanToolDefinition(tool)
+          const rp = baseline.record(McpBaseline.keyFor(server.name, tool.name), tool)
+
+          if (!scan.safe) {
+            poisoned++
+            serverIssues.push(zh
+              ? `  🔴 \`${tool.name}\` 工具投毒 (评分 ${scan.score}): ${scan.findings.map(f => f.name).join('; ')}`
+              : `  🔴 \`${tool.name}\` poisoned (score ${scan.score}): ${scan.findings.map(f => f.name).join('; ')}`)
+          }
+          if (rp.status === 'changed') {
+            rugPulls++
+            serverIssues.push(zh
+              ? `  🟠 \`${tool.name}\` 描述自上次以来被修改 (rug-pull 嫌疑)`
+              : `  🟠 \`${tool.name}\` description changed since last seen (possible rug-pull)`)
+          }
+        }
+
+        const icon = serverIssues.length > 0 ? '🔴' : '✅'
+        const tag = server.transport === 'remote' ? ' (remote)' : ''
+        lines.push(`### ${icon} ${server.name}${tag}`)
+        lines.push(zh ? `  ${tools.length} 个工具` : `  ${tools.length} tools`)
+        if (serverIssues.length === 0) {
+          lines.push(zh ? '  ✅ 未发现问题' : '  ✅ No issues found')
+        } else {
+          lines.push(...serverIssues)
+        }
+        lines.push('')
+      }
+
+      baseline.save()
+
+      // Summary
+      lines.push('---')
+      lines.push(zh
+        ? `扫描了 ${totalTools} 个工具 · 🔴 投毒 ${poisoned} · 🟠 rug-pull ${rugPulls} · ⚠️ 无法连接 ${unreachable}`
+        : `Scanned ${totalTools} tools · 🔴 poisoned ${poisoned} · 🟠 rug-pull ${rugPulls} · ⚠️ unreachable ${unreachable}`)
+      if (poisoned === 0 && rugPulls === 0) {
+        lines.push(zh ? '✅ **所有 MCP 工具通过扫描**' : '✅ **All MCP tools passed**')
+      } else {
+        lines.push(zh
+          ? '⚠️ **发现可疑 MCP 工具 — 请审查或移除对应服务器**'
+          : '⚠️ **Suspicious MCP tools found — review or remove the server**')
+      }
+
+      return { text: lines.join('\n') }
+    },
+  })
+}