shellward 0.5.15 → 0.6.0

package/README.md

@@ -10,7 +10,7 @@
 
 [![npm](https://img.shields.io/npm/v/shellward?color=cb0000&label=npm)](https://www.npmjs.com/package/shellward)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
-[![tests](https://img.shields.io/badge/tests-123%20passing-brightgreen)](#performance)
+[![tests](https://img.shields.io/badge/tests-183%20passing-brightgreen)](#performance)
 [![deps](https://img.shields.io/badge/dependencies-0-brightgreen)](#performance)
 
 [English](#demo) | [中文](#中文)
@@ -54,13 +54,14 @@ Your AI agent has full access to tools — shell, email, HTTP, file system. One
 
 | Platform | Integration | Note |
 |----------|------------|------|
-| **Claude Desktop** | MCP Server | Add to `claude_desktop_config.json` — 7 security tools |
+| **Claude Desktop** | MCP Server | Add to `claude_desktop_config.json` — 8 security tools |
 | **Cursor** | MCP Server | Add to `.cursor/mcp.json` |
 | **OpenClaw** | MCP + Plugin + SDK | `openclaw plugins install shellward` — adapts to available hooks |
 | **Claude Code** | MCP + SDK | Anthropic's official CLI agent |
 | **LangChain** | SDK | LLM application framework |
 | **AutoGPT** | SDK | Autonomous AI agents |
 | **OpenAI Agents** | SDK | GPT agent platform |
+| **Hermes Agent** | MCP Server | Nous Research's self-improving agent — register via MCP Integration |
 | **Dify / Coze** | SDK | Low-code AI platforms |
 | **Any MCP Client** | MCP Server | stdio JSON-RPC, zero dependencies |
 | **Any AI Agent** | SDK | `npm install shellward` — 3 lines to integrate |
@@ -69,8 +70,10 @@ Your AI agent has full access to tools — shell, email, HTTP, file system. One
 
 - **8 defense layers**: prompt guard, input auditor, tool blocker, output scanner, security gate, outbound guard, data flow guard, session guard
 - **DLP model**: data returns in full (no redaction), outbound sends are blocked when PII was recently accessed
-- **PII detection**: SSN, credit cards, API keys (OpenAI/GitHub/AWS), JWT, passwords — plus Chinese ID card (GB 11643 checksum), phone, bank card (Luhn)
-- **32 injection rules**: 18 Chinese + 14 English, risk scoring, mixed-language detection
+- **PII detection**: SSN, credit cards, API keys (OpenAI/GitHub/AWS), JWT, passwords — plus Chinese ID card (GB 11643 checksum), carrier-validated mobile, UnionPay bank card (Luhn) — precision-tuned to cut false positives
+- **37 injection rules**: 20 Chinese + 17 English, risk scoring, mixed-language detection
+- **MCP tool-poisoning scan**: detects hidden instructions, invisible characters, concealment ("hide from user"), secret-file access & exfiltration hints in a tool's description/parameters
+- **MCP rug-pull detection**: fingerprints each tool's description on first sight, flags silent changes across runs
 - **Data exfiltration chain**: read sensitive data → send email / HTTP POST / curl = blocked
 - **Bash bypass detection**: catches `curl -X POST`, `wget --post`, `nc`, Python/Node network exfil
 - **Zero dependencies**, zero config, Apache-2.0
@@ -83,42 +86,32 @@ ShellWard runs as a standalone MCP server over stdio — zero dependencies, no `
 
 **Claude Desktop / Cursor / any MCP client:**
 
-Add to your MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, etc.):
+Add to your MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, OpenClaw, etc.) — no install path needed, `npx` fetches the published `shellward-mcp` bin:
 
 ```json
 {
   "mcpServers": {
     "shellward": {
       "command": "npx",
-      "args": ["tsx", "/path/to/shellward/src/mcp-server.ts"]
+      "args": ["-y", "-p", "shellward", "shellward-mcp"]
     }
   }
 }
 ```
 
-**OpenClaw:**
+If installed globally (`npm i -g shellward`), simply use `"command": "shellward-mcp"`.
 
-```json
-{
-  "mcpServers": {
-    "shellward": {
-      "command": "npx",
-      "args": ["tsx", "/path/to/shellward/src/mcp-server.ts"]
-    }
-  }
-}
-```
-
-**7 MCP tools available:**
+**8 MCP tools available:**
 
 | Tool | Description |
 |------|-------------|
 | `check_command` | Check if a shell command is safe (rm -rf, reverse shell, fork bomb...) |
-| `check_injection` | Detect prompt injection in text (32+ rules, zh+en) |
+| `check_injection` | Detect prompt injection in text (37+ rules, zh+en) |
 | `scan_data` | Scan for PII & sensitive data (CN ID/phone/bank, API keys, SSN...) |
 | `check_path` | Check if file path operation is safe (.env, .ssh, credentials...) |
 | `check_tool` | Check if tool name is allowed (blocks payment/transfer tools) |
 | `check_response` | Audit AI response for canary leaks & PII exposure |
+| `scan_mcp_tool` | Scan an MCP tool definition for poisoning + rug-pull |
 | `security_status` | Get current security config & active layers |
 
 **Environment variables:**
@@ -127,7 +120,8 @@ Add to your MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, etc.):
 |----------|--------|---------|
 | `SHELLWARD_MODE` | `enforce` / `audit` | `enforce` |
 | `SHELLWARD_LOCALE` | `auto` / `zh` / `en` | `auto` |
-| `SHELLWARD_THRESHOLD` | `0`-`100` | `60` |
+| `SHELLWARD_THRESHOLD` | `0`-`100` | `40` |
+| `SHELLWARD_BASELINE_PATH` | file path | `~/.openclaw/shellward/mcp-baseline.json` |
 
 ### As SDK (any AI agent platform):
 
@@ -173,7 +167,7 @@ User Input
   │
   ▼
 ┌───────────────────┐
-│ L4 Input Auditor  │ 32 injection rules (18 ZH + 14 EN), risk scoring
+│ L4 Input Auditor  │ 37 injection rules (20 ZH + 17 EN), risk scoring
 └───────────────────┘
   │
   ▼
@@ -239,6 +233,32 @@ password: "MyP@ssw0rd!"       → Detected (Password)
 330102199001011234              → Detected (Chinese ID Card, checksum validated)
 ```
 
+## OWASP Coverage
+
+How ShellWard maps to the **OWASP Top 10 for LLM Applications (2025)** and common **MCP** risks. Honest scope — `✅` covered, `◐` partial, `✗` out of scope.
+
+| OWASP LLM Top 10 (2025) | ShellWard | How |
+|---|:--:|---|
+| LLM01 Prompt Injection | ✅ | L1 prompt guard + L4 injection engine (32 rules, hidden-char/tag detection) |
+| LLM02 Sensitive Information Disclosure | ✅ | L2/L6 PII scan + L7 DLP exfiltration blocking |
+| LLM03 Supply Chain | ✅ | `/scan-plugins`, package-install detection, `/check-updates` CVE DB |
+| LLM04 Data & Model Poisoning | ◐ | **MCP tool-poisoning scan + rug-pull detection** (tool-definition layer) |
+| LLM05 Improper Output Handling | ✅ | L6 output scanner + canary-leak detection |
+| LLM06 Excessive Agency | ✅ | L3 tool blocker (payment/transfer), L5 security gate |
+| LLM07 System Prompt Leakage | ✅ | L1 canary token tripwire in responses |
+| LLM08 Vector & Embedding Weaknesses | ✗ | Out of scope (not a RAG/vector tool) |
+| LLM09 Misinformation | ✗ | Out of scope |
+| LLM10 Unbounded Consumption | ◐ | Fork-bomb / resource-exhaustion command blocking |
+
+| Common MCP risk | ShellWard | How |
+|---|:--:|---|
+| Tool Poisoning (hidden instructions in tool metadata) | ✅ | `scan_mcp_tool` / `/scan-mcp` |
+| Rug Pull (tool silently redefined after approval) | ✅ | description+schema fingerprint baseline |
+| Data exfiltration via tools | ✅ | L7 outbound guard (email/HTTP/curl/bash) |
+| Command injection via MCP | ✅ | `check_command` (17 dangerous patterns) |
+| Sensitive-file access | ✅ | `check_path` + honeypot tripwires |
+| Tool Shadowing / cross-server escalation | ◐ | Per-tool scan; cross-server graph analysis not yet |
+
 ## Configuration
 
 ```json
@@ -249,7 +269,30 @@ password: "MyP@ssw0rd!"       → Detected (Password)
 |--------|--------|---------|-------------|
 | `mode` | `enforce` / `audit` | `enforce` | Block + log, or log only |
 | `locale` | `auto` / `zh` / `en` | `auto` | Auto-detects from system LANG |
-| `injectionThreshold` | `0`-`100` | `60` | Risk score threshold for injection detection |
+| `injectionThreshold` | `0`-`100` | `40` | Risk score threshold (lower = stricter; calibrated via bench/) |
+
+### Custom Rules (SDK)
+
+Extend the built-in rules without forking — every field is additive, except `allowedTools` which always wins:
+
+```typescript
+const guard = new ShellWard({
+  customRules: {
+    blockedTools: ['internal_payout', 'wire_transfer'],   // add to the block policy
+    allowedTools: ['payment'],                            // trust a tool (overrides built-in block)
+    sensitivePatterns: [                                  // org-specific PII / secrets
+      { id: 'emp_id', name: 'Employee ID', pattern: 'EMP-\\d{6}' },
+    ],
+    dangerousCommands: [                                  // extra command blocklist
+      { id: 'no_shutdown', pattern: 'shutdown\\s+-h', description: 'Power-off' },
+    ],
+    honeypotPaths: ['secret_vault\\.dat$'],               // extra honeypot tripwires
+    injectionRules: [/* custom InjectionRule[] */],
+  },
+})
+```
+
+Invalid regexes are skipped (never throws), so user input can't break the guard.
 
 ## Commands (OpenClaw)
 
@@ -259,6 +302,7 @@ password: "MyP@ssw0rd!"       → Detected (Password)
 | `/audit [n] [filter]` | View audit log (filter: block, audit, critical, high) |
 | `/harden` | Scan & fix security issues |
 | `/scan-plugins` | Scan installed plugins for malicious code |
+| `/scan-mcp` | Scan configured MCP servers (stdio + remote HTTP) for tool poisoning + rug-pull |
 | `/check-updates` | Check versions & known CVEs (17 built-in) |
 
 ## Performance
@@ -269,7 +313,24 @@ password: "MyP@ssw0rd!"       → Detected (Password)
 | Command check throughput | 125,000/sec |
 | Injection detection throughput | ~7,700/sec |
 | Dependencies | 0 |
-| Tests | 123 passing (incl. 11 MCP) |
+| Tests | 183 passing (incl. 15 MCP + 12 ReDoS + live tool-poisoning scan) |
+
+## Detection Benchmark
+
+Effectiveness is measured, not asserted. `npm run bench` runs every detector over a labeled corpus (attacks **and** hard negatives — benign text that looks suspicious) and reports precision/recall/F1. The corpus and harness live in [`bench/`](./bench); CI fails on regression.
+
+| Category | Precision | Recall | F1 |
+|----------|:---------:|:------:|:--:|
+| Prompt injection | 100% | 100% | 100% |
+| Dangerous commands | 100% | 100% | 100% |
+| PII / secrets | 100% | 100% | 100% |
+| MCP tool poisoning | 100% | 100% | 100% |
+
+83 gated samples (attacks + hard negatives). Zero-width-interleaved and empty-quote (`r''m`) obfuscation are normalized before matching. The corpus also tracks **5 documented bypasses** (leetspeak, base64, non-zh/en languages, shell variable indirection) that regex/heuristics are not expected to catch — listed explicitly and excluded from the gate rather than hidden.
+
+> Numbers are on the current in-repo corpus — a floor, not a universal guarantee. Found a bypass? Add it to `bench/corpus.ts` as a labeled row and the gap becomes measurable (and CI-enforced).
+>
+> **Conservative by design:** in enforce mode ShellWard fails safe — e.g. `echo "rm -rf /"` (printing a literal) is flagged, since regex can't distinguish it from `echo "$(rm -rf /)"` (which executes).
 
 ## Vulnerability Database
 
@@ -297,7 +358,7 @@ ShellWard is built for teams that need runtime security for AI agents — whethe
 | **Zero dependencies** | ✅ (npm) | ✅ | Go binary | Cloud API | Python |
 | **Runtime blocking** | ✅ | ✅ | ✅ (proxy) | ✅ | ❌ (scanner) |
 | **Architecture** | In-process middleware | Hook-based guard | HTTP proxy | Hook + cloud | Scan + monitor |
-| **Detection rules** | 32 | 24 | 36 DLP patterns | 200+ YAML | 191+ |
+| **Detection rules** | 37 | 24 | 36 DLP patterns | 200+ YAML | 191+ |
 
 > ShellWard is the only tool with **DLP-style data flow tracking** + **Chinese language security** + **zero dependencies** in a single package.
 >
@@ -323,13 +384,14 @@ ShellWard is built for teams that need runtime security for AI agents — whethe
 
 | 平台 | 集成方式 | 说明 |
 |------|---------|------|
-| **Claude Desktop** | MCP 服务器 | 添加到 `claude_desktop_config.json`，7 个安全工具 |
+| **Claude Desktop** | MCP 服务器 | 添加到 `claude_desktop_config.json`，8 个安全工具 |
 | **Cursor** | MCP 服务器 | 添加到 `.cursor/mcp.json` |
 | **OpenClaw** | MCP + 插件 + SDK | `openclaw plugins install shellward`，开箱即用 |
 | **Claude Code** | MCP + SDK | Anthropic 官方 CLI Agent |
 | **LangChain** | SDK | LLM 应用开发框架 |
 | **AutoGPT** | SDK | 自主 AI Agent |
 | **OpenAI Agents** | SDK | GPT Agent 平台 |
+| **Hermes Agent** | MCP 服务器 | Nous Research 自改进 Agent — 通过 MCP Integration 接入 |
 | **Dify / Coze** | SDK | 低代码 AI 平台 |
 | **任意 MCP 客户端** | MCP 服务器 | stdio JSON-RPC，零依赖 |
 | **任意 AI Agent** | SDK | `npm install shellward`，3 行代码接入 |
@@ -338,20 +400,22 @@ ShellWard is built for teams that need runtime security for AI agents — whethe
 
 **MCP 服务器模式（推荐）：**
 
-在 MCP 配置中添加（适用于 Claude Desktop、Cursor、OpenClaw 等）：
+在 MCP 配置中添加（适用于 Claude Desktop、Cursor、OpenClaw 等）。无需本地路径，`npx` 会拉取已发布的 `shellward-mcp`：
 
 ```json
 {
   "mcpServers": {
     "shellward": {
       "command": "npx",
-      "args": ["tsx", "/path/to/shellward/src/mcp-server.ts"]
+      "args": ["-y", "-p", "shellward", "shellward-mcp"]
     }
   }
 }
 ```
 
-零依赖，原生实现 MCP 协议。提供 7 个安全工具：命令检查、注入检测、敏感数据扫描、路径保护、工具策略、响应审计、安全状态。
+若已全局安装（`npm i -g shellward`），直接用 `"command": "shellward-mcp"` 即可。
+
+零依赖，原生实现 MCP 协议。提供 8 个安全工具：命令检查、注入检测、敏感数据扫描、路径保护、工具策略、响应审计、**MCP 工具投毒/rug-pull 扫描**、安全状态。
 
 **OpenClaw 插件模式：**
 
@@ -380,6 +444,8 @@ guard.checkOutbound('send_email', {...})  // → { allowed: false } (读过敏
 - **DLP 模型**：数据完整返回（不脱敏），外部发送才拦截 — 用户体验零影响
 - **中文 PII**：身份证号（GB 11643 校验位）、手机号（全运营商）、银行卡号（Luhn 校验）
 - **中文注入检测**：18 条中文规则 + 14 条英文规则，支持中英混合攻击检测
+- **MCP 工具投毒扫描**：检测工具描述/参数里的隐藏指令、不可见字符、"对用户隐瞒" 类隐蔽指令、敏感文件访问与外泄提示
+- **MCP rug-pull 检测**：首次见到工具时记录描述指纹，后续被偷改即告警（`/scan-mcp` 一键扫描已配置 MCP 服务器）
 - **数据外泄链**：读敏感数据 → send_email / HTTP POST / curl 外发 = 拦截
 - **零依赖**、零配置、Apache-2.0
 
@@ -394,12 +460,31 @@ guard.checkOutbound('send_email', {...})  // → { allowed: false } (读过敏
 | **零依赖** | ✅ (npm) | ✅ | Go 二进制 | 需云 API | 需 Python |
 | **运行时拦截** | ✅ | ✅ | ✅ (proxy) | ✅ | ❌ (扫描器) |
 | **架构** | 进程内中间件 | Hook 守护 | HTTP 代理 | Hook + 云端 | 扫描 + 监控 |
-| **检测规则数** | 32 | 24 | 36 DLP 模式 | 200+ YAML | 191+ |
+| **检测规则数** | 37 | 24 | 36 DLP 模式 | 200+ YAML | 191+ |
 
 > ShellWard 是唯一同时具备 **DLP 数据流追踪** + **中文语言安全** + **零依赖** 的 AI Agent 安全工具。
 >
 > 最新研究 ([arXiv:2603.08665](https://arxiv.org/abs/2603.08665)) 显示 GenAI 在 7 小时内发现 38 个真实漏洞 — AI 驱动的攻击正在规模化，防御必须内建到 Agent 层。
 
+### 交流 · Community
+
+微信公众号 **「AI不止语」**（微信搜索 `AI_BuZhiYu`）— 技术问答 · 项目更新 · 实战文章
+
+| 渠道 | 加入方式 |
+|------|---------|
+| QQ 群 | [点击加入](https://qm.qq.com/q/EeNQA9xCxy)（群号 1071280067） |
+| 微信群 | 关注公众号后回复「群」获取入群方式 |
+
+### 姊妹项目
+
+| 项目 | 说明 |
+|------|------|
+| [ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide) | AI 编程工具实战指南 — 66 个 Claude Code 技巧 + 9 款工具最佳实践 + 可复制配置模板 |
+| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) | 187 个专业角色，让 AI 变成安全工程师、DBA、产品经理等 |
+| [agency-orchestrator](https://github.com/jnMetaCode/agency-orchestrator) | 多智能体编排引擎 — 用 YAML 编排 187 个角色协作，支持 DeepSeek/Claude/OpenAI/Ollama，零代码 |
+| [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) | AI 编程超能力 · 中文版 — 20 个 skills，让你的 AI 编程助手真正会干活 |
+| 🆕 [ai-shortfilm-prompts](https://github.com/jnMetaCode/ai-shortfilm-prompts) | AI 短片提示词方法论 — Mx-Shell《丧尸清道夫》5 段式拆解 + Skill，Seedance / 小云雀 / Sora / 可灵 / 即梦通用 |
+
 ### 作者
 
 [jnMetaCode](https://github.com/jnMetaCode) · Apache-2.0

package/dist/auto-check.d.ts

@@ -12,6 +12,7 @@ export interface AutoCheckResult {
         config: string;
         risk: string;
     }[];
+    mcpServerCount: number;
     rootWarning: boolean;
 }
 /**

package/dist/auto-check.js

@@ -5,6 +5,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');
 const SUSPICIOUS_PATTERNS = [
     { pattern: /eval\s*\(/, name: 'eval()' },
@@ -125,7 +126,12 @@ export async function runAutoCheck(locale = 'en') {
         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 };
 }
 /**
  * 启动时执行检查，发现问题时通过 logger 告警
@@ -160,6 +166,11 @@ export function runAutoCheckOnStartup(logger, locale) {
         if (result.rootWarning) {
             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/dist/commands/index.d.ts

@@ -1,2 +1,3 @@
 import type { ShellWardConfig } from '../types.js';
-export declare function registerAllCommands(api: any, config: ShellWardConfig): void;
+/** @returns number of registered commands (for the startup log). */
+export declare function registerAllCommands(api: any, config: ShellWardConfig): number;

package/dist/commands/index.js

@@ -4,8 +4,10 @@ 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';
+/** @returns number of registered commands (for the startup log). */
 export function registerAllCommands(api, config) {
     const locale = resolveLocale(config);
     // Register individual commands
@@ -13,6 +15,7 @@ export function registerAllCommands(api, config) {
     registerAuditCommand(api, config);
     registerHardenCommand(api, config);
     registerScanPluginsCommand(api, config);
+    registerScanMcpCommand(api, config);
     registerCheckUpdatesCommand(api, config);
     registerUpgradeOpenClawCommand(api, config);
     // Register /cg shortcut with help
@@ -31,6 +34,7 @@ export function registerAllCommands(api, config) {
 | \`/audit [数量] [过滤]\` | 查看审计日志 (过滤: block/audit/critical/high) |
 | \`/harden\` | 安全扫描 · \`/harden fix\` 自动修复权限 |
 | \`/scan-plugins\` | 扫描已安装插件的安全风险 |
+| \`/scan-mcp\` | 扫描已配置 MCP 服务器（工具投毒 + rug-pull） |
 | \`/check-updates\` | 检查 OpenClaw 版本和已知漏洞 |
 | \`/upgrade-openclaw\` | 一键升级 OpenClaw · \`/upgrade-openclaw yes\` 直接执行 |
 
@@ -45,6 +49,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 |
 
@@ -53,4 +58,6 @@ 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/dist/commands/scan-mcp.d.ts

@@ -0,0 +1,2 @@
+import type { ShellWardConfig } from '../types.js';
+export declare function registerScanMcpCommand(api: any, config: ShellWardConfig): void;

package/dist/commands/scan-mcp.js

@@ -0,0 +1,105 @@
+// 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 { resolveLocale } from '../types.js';
+export function registerScanMcpCommand(api, config) {
+    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 = [];
+            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) {
+                    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 = [];
+                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') };
+        },
+    });
+}

package/dist/core/engine.d.ts

@@ -30,12 +30,40 @@ export interface ResponseCheckResult {
     canaryLeak: boolean;
     sensitiveData: ScanResult;
 }
+/** Shape of an MCP tool definition (subset of the spec we inspect). */
+export interface McpToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, any>;
+}
+export interface ToolPoisoningFinding {
+    id: string;
+    name: string;
+    category: string;
+    score: number;
+    source: 'description' | 'parameter' | 'hidden_chars';
+}
+export interface ToolPoisoningResult {
+    toolName: string;
+    safe: boolean;
+    score: number;
+    threshold: number;
+    findings: ToolPoisoningFinding[];
+    hiddenChars: number;
+}
 export declare class ShellWard {
     readonly config: ShellWardConfig;
     readonly locale: ResolvedLocale;
     readonly log: AuditLog;
     private _canaryToken;
     private compiledRules;
+    private readonly blockedTools;
+    private readonly allowedTools;
+    private readonly sensitiveTools;
+    private readonly outboundTools;
+    private readonly honeypots;
+    private readonly customSensitive;
+    private readonly customDangerous;
     private sensitiveReads;
     private readonly TRACKING_WINDOW_MS;
     private readonly MAX_TRACKED_READS;
@@ -51,6 +79,13 @@ export declare class ShellWard {
         threshold?: number;
     }): InjectionResult;
     getInjectionThreshold(toolName?: string): number;
+    scanToolDefinition(tool: McpToolDefinition, options?: {
+        threshold?: number;
+    }): ToolPoisoningResult;
+    /** Scan a list of MCP tool definitions; returns only the unsafe ones. */
+    scanToolDefinitions(tools: McpToolDefinition[], options?: {
+        threshold?: number;
+    }): ToolPoisoningResult[];
     checkAction(action: string, details: string): CheckResult;
     checkResponse(content: string): ResponseCheckResult;
     markSensitiveData(toolName: string, summary: string): void;