shellward 0.5.10 → 0.5.12

package/README.md

@@ -1,19 +1,23 @@
+<p align="center">
+  <img src="assets/logo.svg" alt="ShellWard Logo" width="160" />
+</p>
+
 # ShellWard
 
-**AI Agent Security Middleware** — Protect AI agents from prompt injection, data exfiltration, and dangerous command execution.
+**AI Agent Security Middleware** — Protect AI agents from prompt injection, data exfiltration, and dangerous command execution. ShellWard acts as an LLM security middleware and AI agent firewall, intercepting tool calls at runtime to enforce agent guardrails before damage is done.
 
 8-layer defense-in-depth, DLP-style data flow control, zero dependencies. Works as **standalone SDK** or **OpenClaw plugin**.
 
 [![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-112%20passing-brightgreen)](#performance)
+[![tests](https://img.shields.io/badge/tests-123%20passing-brightgreen)](#performance)
 [![deps](https://img.shields.io/badge/dependencies-0-brightgreen)](#performance)
 
 [English](#demo) | [中文](#中文)
 
 ## Demo
 
-![ShellWard Security Demo](https://github.com/jnMetaCode/shellward/releases/download/v0.5.0/demo-en.gif)
+![ShellWard AI agent firewall demo — blocking prompt injection, data exfiltration, and reverse shell attacks in real time](https://github.com/jnMetaCode/shellward/releases/download/v0.5.0/demo-en.gif)
 
 > 7 real-world scenarios: server wipe → reverse shell → prompt injection → DLP audit → data exfiltration chain → credential theft → APT attack chain
 
@@ -50,13 +54,15 @@ Your AI agent has full access to tools — shell, email, HTTP, file system. One
 
 | Platform | Integration | Note |
 |----------|------------|------|
-| **OpenClaw** | Plugin + SDK | `openclaw plugins install shellward` — adapts to available hooks |
-| **Claude Code** | SDK | Anthropic's official CLI agent |
-| **Cursor** | SDK | AI-powered coding IDE |
+| **Claude Desktop** | MCP Server | Add to `claude_desktop_config.json` — 7 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 |
 | **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 |
 
 ## Features
@@ -71,7 +77,59 @@ Your AI agent has full access to tools — shell, email, HTTP, file system. One
 
 ## Quick Start
 
-**As SDK (any AI agent platform):**
+### As MCP Server
+
+ShellWard runs as a standalone MCP server over stdio — zero dependencies, no `@modelcontextprotocol/sdk` needed.
+
+**Claude Desktop / Cursor / any MCP client:**
+
+Add to your MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "shellward": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/shellward/src/mcp-server.ts"]
+    }
+  }
+}
+```
+
+**OpenClaw:**
+
+```json
+{
+  "mcpServers": {
+    "shellward": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/shellward/src/mcp-server.ts"]
+    }
+  }
+}
+```
+
+**7 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) |
+| `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 |
+| `security_status` | Get current security config & active layers |
+
+**Environment variables:**
+
+| Variable | Values | Default |
+|----------|--------|---------|
+| `SHELLWARD_MODE` | `enforce` / `audit` | `enforce` |
+| `SHELLWARD_LOCALE` | `auto` / `zh` / `en` | `auto` |
+| `SHELLWARD_THRESHOLD` | `0`-`100` | `60` |
+
+### As SDK (any AI agent platform):
 
 ```bash
 npm install shellward
@@ -211,7 +269,7 @@ password: "MyP@ssw0rd!"       → Detected (Password)
 | Command check throughput | 125,000/sec |
 | Injection detection throughput | ~7,700/sec |
 | Dependencies | 0 |
-| Tests | 112 passing |
+| Tests | 123 passing (incl. 11 MCP) |
 
 ## Vulnerability Database
 
@@ -224,6 +282,10 @@ password: "MyP@ssw0rd!"       → Detected (Password)
 
 Remote vuln DB syncs every 24h, falls back to local DB when offline.
 
+## Use Cases
+
+ShellWard is built for teams that need runtime security for AI agents — whether you are building autonomous coding assistants, customer-facing chatbots with tool access, or internal automation powered by LLMs. Common use cases include MCP security enforcement, tool call interception and filtering, and adding agent guardrails to any LLM-powered workflow.
+
 ## Why ShellWard?
 
 | Capability | ShellWard | [agentguard](https://github.com/GoPlusSecurity/agentguard) | [pipelock](https://github.com/luckyPipewrench/pipelock) | [Sage](https://github.com/avast/sage) | [AgentSeal](https://github.com/AgentSeal/agentseal) |
@@ -251,7 +313,7 @@ Remote vuln DB syncs every 24h, falls back to local DB when offline.
 
 **AI Agent 安全中间件** — 保护 AI 代理免受提示词注入、数据泄露、危险命令执行。8 层纵深防御，零依赖。
 
-![ShellWard 安全防护演示](https://github.com/jnMetaCode/shellward/releases/download/v0.5.0/demo-zh.gif)
+![ShellWard AI Agent 安全防火墙演示 — 拦截提示词注入、数据泄露和反弹Shell攻击](https://github.com/jnMetaCode/shellward/releases/download/v0.5.0/demo-zh.gif)
 
 > 7 个真实攻击场景：服务器毁灭拦截 → 反弹 Shell → 注入检测 → DLP 审计 → 数据外泄链 → 凭证窃取 → APT 攻击链
 
@@ -261,22 +323,45 @@ Remote vuln DB syncs every 24h, falls back to local DB when offline.
 
 | 平台 | 集成方式 | 说明 |
 |------|---------|------|
-| **OpenClaw** | 插件 | `openclaw plugins install shellward`，开箱即用 |
-| **Claude Code** | SDK | Anthropic 官方 CLI Agent |
-| **Cursor** | SDK | AI 编程 IDE |
+| **Claude Desktop** | MCP 服务器 | 添加到 `claude_desktop_config.json`，7 个安全工具 |
+| **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 平台 |
 | **Dify / Coze** | SDK | 低代码 AI 平台 |
+| **任意 MCP 客户端** | MCP 服务器 | stdio JSON-RPC，零依赖 |
 | **任意 AI Agent** | SDK | `npm install shellward`，3 行代码接入 |
 
 ### 安装
 
+**MCP 服务器模式（推荐）：**
+
+在 MCP 配置中添加（适用于 Claude Desktop、Cursor、OpenClaw 等）：
+
+```json
+{
+  "mcpServers": {
+    "shellward": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/shellward/src/mcp-server.ts"]
+    }
+  }
+}
+```
+
+零依赖，原生实现 MCP 协议。提供 7 个安全工具：命令检查、注入检测、敏感数据扫描、路径保护、工具策略、响应审计、安全状态。
+
+**OpenClaw 插件模式：**
+
 ```bash
-# OpenClaw 插件
 openclaw plugins install shellward
+```
+
+**SDK 模式：**
 
-# 或 SDK 模式
+```bash
 npm install shellward
 ```
 

package/dist/audit-log.d.ts

@@ -0,0 +1,8 @@
+import type { AuditEntry, ShellWardConfig } from './types.js';
+export declare class AuditLog {
+    private config;
+    private rotating;
+    constructor(config: ShellWardConfig);
+    write(entry: Pick<AuditEntry, 'level' | 'layer' | 'action' | 'detail'> & Record<string, unknown>): void;
+    private rotateIfNeeded;
+}

package/dist/audit-log.js

@@ -0,0 +1,72 @@
+// src/audit-log.ts — JSONL audit log, zero dependencies
+import { appendFileSync, mkdirSync, renameSync, statSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { getHomeDir } from './utils.js';
+const LOG_DIR = join(getHomeDir(), '.openclaw', 'shellward');
+const LOG_FILE = join(LOG_DIR, 'audit.jsonl');
+const MAX_SIZE_BYTES = 100 * 1024 * 1024; // 100 MB
+const RISK_SCORES = {
+    CRITICAL: 10,
+    HIGH: 7,
+    MEDIUM: 4,
+    LOW: 2,
+    INFO: 0,
+};
+export class AuditLog {
+    config;
+    rotating = false;
+    constructor(config) {
+        this.config = config;
+        try {
+            mkdirSync(LOG_DIR, { recursive: true, mode: 0o700 });
+            // Ensure log file exists with restricted permissions (owner-only)
+            try {
+                statSync(LOG_FILE);
+            }
+            catch {
+                writeFileSync(LOG_FILE, '', { mode: 0o600 });
+            }
+        }
+        catch { /* directory may already exist */ }
+    }
+    write(entry) {
+        try {
+            const record = {
+                ...entry,
+                level: entry.level,
+                layer: entry.layer,
+                action: entry.action,
+                detail: entry.detail,
+                ts: new Date().toISOString(),
+                mode: this.config.mode,
+                riskScore: RISK_SCORES[entry.level] ?? 0,
+            };
+            appendFileSync(LOG_FILE, JSON.stringify(record) + '\n', { mode: 0o600 });
+            this.rotateIfNeeded();
+        }
+        catch (e) {
+            // Log failure must not break plugin, but warn via stderr
+            try {
+                process.stderr.write(`[ShellWard] audit log write failed: ${e?.message}\n`);
+            }
+            catch { }
+        }
+    }
+    rotateIfNeeded() {
+        if (this.rotating)
+            return;
+        try {
+            const stat = statSync(LOG_FILE);
+            if (stat.size > MAX_SIZE_BYTES) {
+                this.rotating = true;
+                const ts = new Date().toISOString().replace(/[:.]/g, '-');
+                renameSync(LOG_FILE, `${LOG_FILE}.${ts}.bak`);
+                writeFileSync(LOG_FILE, '', { mode: 0o600 });
+            }
+        }
+        catch { /* ignore */ }
+        finally {
+            this.rotating = false;
+        }
+    }
+}

package/dist/auto-check.d.ts

@@ -0,0 +1,26 @@
+export interface AutoCheckResult {
+    openclawVulns: {
+        id: string;
+        severity: string;
+        description: string;
+    }[];
+    pluginRisks: {
+        plugin: string;
+        risk: string;
+    }[];
+    mcpRisks: {
+        config: string;
+        risk: string;
+    }[];
+    rootWarning: boolean;
+}
+/**
+ * 执行全部自动检查，返回结果（供启动时告警用）
+ */
+export declare function runAutoCheck(locale?: 'zh' | 'en'): Promise<AutoCheckResult>;
+/**
+ * 启动时执行检查，发现问题时通过 logger 告警
+ */
+export declare function runAutoCheckOnStartup(logger: {
+    warn: (s: string) => void;
+}, locale: 'zh' | 'en'): void;

package/dist/auto-check.js

@@ -0,0 +1,167 @@
+// src/auto-check.ts — 启动时自动安全检查，减少人为操作
+// 异步执行，不阻塞启动；发现问题时通过 logger 告警
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { getHomeDir } from './utils.js';
+import { fetchVulnDB, compareVersions } from './update-check.js';
+const OPENCLAW_DIR = join(getHomeDir(), '.openclaw');
+const SUSPICIOUS_PATTERNS = [
+    { pattern: /eval\s*\(/, name: 'eval()' },
+    { pattern: /\/dev\/tcp|nc\s+-e|ncat/, name: 'reverse shell' },
+    { pattern: /webhook|exfil|callback.*http/i, name: 'data exfil' },
+];
+/**
+ * 获取 OpenClaw 版本
+ */
+function getOpenClawVersion() {
+    try {
+        const out = execSync('openclaw --version 2>&1', { timeout: 5000 }).toString().trim();
+        const match = out.match(/(\d{4}\.\d+\.\d+|\d+\.\d+\.\d+)/);
+        return match ? match[1] : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * 检查 OpenClaw 是否受已知漏洞影响
+ */
+async function checkOpenClawVulns(version, locale = 'en') {
+    const vulns = [];
+    try {
+        const { vulns: db } = await fetchVulnDB();
+        const list = db.length > 0 ? db : [
+            { affectedBelow: '1.0.111', severity: 'HIGH', id: 'CVE-2025-59536', description_zh: 'RCE via Hooks/MCP', description_en: 'RCE via Hooks/MCP' },
+            { affectedBelow: '2.0.65', severity: 'MEDIUM', id: 'CVE-2026-21852', description_zh: 'API Key exfil', description_en: 'API Key exfil' },
+        ];
+        for (const v of list) {
+            if (version !== 'unknown' && compareVersions(version, v.affectedBelow) < 0) {
+                vulns.push({
+                    id: v.id,
+                    severity: v.severity || 'MEDIUM',
+                    description: locale === 'zh'
+                        ? (v.description_zh || v.description_en || v.id)
+                        : (v.description_en || v.description_zh || v.id),
+                });
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return vulns;
+}
+/**
+ * 快速扫描插件中的高风险模式
+ */
+function scanPluginsQuick() {
+    const risks = [];
+    const dirs = [
+        join(OPENCLAW_DIR, 'extensions'),
+        join(OPENCLAW_DIR, 'plugins'),
+    ];
+    for (const dir of dirs) {
+        if (!existsSync(dir))
+            continue;
+        try {
+            for (const name of readdirSync(dir)) {
+                const p = join(dir, name);
+                if (name.startsWith('.'))
+                    continue;
+                try {
+                    const files = readdirSync(p);
+                    for (const f of files) {
+                        if (!/\.(ts|js)$/.test(f))
+                            continue;
+                        const content = readFileSync(join(p, f), 'utf-8').slice(0, 50000);
+                        for (const { pattern, name: riskName } of SUSPICIOUS_PATTERNS) {
+                            if (pattern.test(content)) {
+                                risks.push({ plugin: name, risk: riskName });
+                                break;
+                            }
+                        }
+                    }
+                }
+                catch { /* skip */ }
+            }
+        }
+        catch { /* skip */ }
+    }
+    return risks;
+}
+/**
+ * 扫描 MCP 配置中的可疑项
+ */
+function scanMcpConfig() {
+    const risks = [];
+    const configPaths = [
+        join(OPENCLAW_DIR, 'mcp.json'),
+        join(OPENCLAW_DIR, 'config', 'mcp.json'),
+        join(OPENCLAW_DIR, 'settings.json'),
+    ];
+    for (const p of configPaths) {
+        if (!existsSync(p))
+            continue;
+        try {
+            const content = readFileSync(p, 'utf-8');
+            if (/webhook|exfil|callback|pastebin|requestbin/i.test(content)) {
+                risks.push({ config: p, risk: 'suspicious URL in config' });
+            }
+            if (/command.*:.*["'](?:curl|wget|nc)\s/i.test(content)) {
+                risks.push({ config: p, risk: 'network command in MCP' });
+            }
+        }
+        catch { /* skip */ }
+    }
+    return risks;
+}
+/**
+ * 执行全部自动检查，返回结果（供启动时告警用）
+ */
+export async function runAutoCheck(locale = 'en') {
+    const ocVersion = getOpenClawVersion();
+    const [openclawVulns, pluginRisks, mcpRisks] = await Promise.all([
+        checkOpenClawVulns(ocVersion, locale),
+        Promise.resolve(scanPluginsQuick()),
+        Promise.resolve(scanMcpConfig()),
+    ]);
+    const rootWarning = typeof process.getuid === 'function' && process.getuid() === 0;
+    return { openclawVulns, pluginRisks, mcpRisks, rootWarning };
+}
+/**
+ * 启动时执行检查，发现问题时通过 logger 告警
+ */
+export function runAutoCheckOnStartup(logger, locale) {
+    runAutoCheck(locale).then(result => {
+        const zh = locale === 'zh';
+        const lines = [];
+        if (result.openclawVulns.length > 0) {
+            lines.push(zh ? '⚠️ OpenClaw 存在已知漏洞:' : '⚠️ OpenClaw has known vulnerabilities:');
+            for (const v of result.openclawVulns) {
+                lines.push(`  ${v.id} [${v.severity}]: ${v.description}`);
+            }
+            lines.push(zh ? '  请运行 /check-updates 查看详情并升级' : '  Run /check-updates for details and upgrade');
+        }
+        if (result.pluginRisks.length > 0) {
+            lines.push(zh ? '⚠️ 插件扫描发现可疑模式:' : '⚠️ Plugin scan found suspicious patterns:');
+            for (const r of result.pluginRisks.slice(0, 3)) {
+                lines.push(`  ${r.plugin}: ${r.risk}`);
+            }
+            if (result.pluginRisks.length > 3) {
+                lines.push(zh ? `  ... 共 ${result.pluginRisks.length} 项` : `  ... ${result.pluginRisks.length} total`);
+            }
+            lines.push(zh ? '  请运行 /scan-plugins 查看详情' : '  Run /scan-plugins for details');
+        }
+        if (result.mcpRisks.length > 0) {
+            lines.push(zh ? '⚠️ MCP 配置存在可疑项:' : '⚠️ Suspicious items in MCP config:');
+            for (const r of result.mcpRisks) {
+                lines.push(`  ${r.config}: ${r.risk}`);
+            }
+        }
+        if (result.rootWarning) {
+            lines.push(zh ? '⚠️ 正在以 root 运行，建议使用普通用户' : '⚠️ Running as root, consider using non-root user');
+        }
+        if (lines.length > 0) {
+            logger.warn((zh ? '[ShellWard] 自动安全检查:\n' : '[ShellWard] Auto security check:\n') + lines.join('\n'));
+        }
+    }).catch(() => { });
+}

package/dist/commands/audit.d.ts

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

package/dist/commands/audit.js

@@ -0,0 +1,75 @@
+// src/commands/audit.ts — /audit command: view recent audit log entries
+import { readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { getHomeDir } from '../utils.js';
+import { resolveLocale } from '../types.js';
+const LOG_FILE = join(getHomeDir(), '.openclaw', 'shellward', 'audit.jsonl');
+export function registerAuditCommand(api, config) {
+    const locale = resolveLocale(config);
+    api.registerCommand({
+        name: 'audit',
+        description: locale === 'zh'
+            ? '📋 查看 ShellWard 审计日志 (用法: /audit [数量] [block|audit|critical])'
+            : '📋 View ShellWard audit log (usage: /audit [count] [block|audit|critical])',
+        acceptsArgs: true,
+        handler: (ctx) => {
+            const zh = locale === 'zh';
+            const args = (ctx.args || '').trim().split(/\s+/).filter(Boolean);
+            // Parse args: count and optional filter
+            let count = 20;
+            let filter = '';
+            for (const arg of args) {
+                if (/^\d+$/.test(arg)) {
+                    count = Math.min(parseInt(arg), 100);
+                }
+                else {
+                    filter = arg.toLowerCase();
+                }
+            }
+            try {
+                statSync(LOG_FILE);
+            }
+            catch {
+                return { text: zh ? '⚠️ 审计日志文件不存在，尚无安全事件记录。' : '⚠️ Audit log not found. No security events recorded yet.' };
+            }
+            const content = readFileSync(LOG_FILE, 'utf-8');
+            let lines = content.trim().split('\n').filter(Boolean);
+            // Apply filter
+            if (filter === 'block') {
+                lines = lines.filter(l => l.includes('"action":"block"'));
+            }
+            else if (filter === 'audit') {
+                lines = lines.filter(l => l.includes('"action":"audit"'));
+            }
+            else if (filter === 'redact') {
+                lines = lines.filter(l => l.includes('"action":"redact"'));
+            }
+            else if (filter === 'critical') {
+                lines = lines.filter(l => l.includes('"level":"CRITICAL"'));
+            }
+            else if (filter === 'high') {
+                lines = lines.filter(l => l.includes('"level":"HIGH"') || l.includes('"level":"CRITICAL"'));
+            }
+            // Get last N entries
+            const recent = lines.slice(-count);
+            if (recent.length === 0) {
+                return { text: zh ? '✅ 没有匹配的审计事件。' : '✅ No matching audit events.' };
+            }
+            const header = zh
+                ? `📋 **审计日志** (最近 ${recent.length} 条${filter ? `, 过滤: ${filter}` : ''})`
+                : `📋 **Audit Log** (last ${recent.length} entries${filter ? `, filter: ${filter}` : ''})`;
+            const formatted = recent.map(line => {
+                try {
+                    const e = JSON.parse(line);
+                    const icon = e.action === 'block' ? '🚫' : e.action === 'audit' ? '📋' : e.action === 'redact' ? '🔒' : e.level === 'CRITICAL' ? '🔴' : 'ℹ️';
+                    const time = e.ts?.slice(11, 19) || '??:??:??';
+                    return `${icon} \`${time}\` **${e.layer}** ${e.action}: ${e.detail?.slice(0, 80) || ''}${e.pattern ? ` [${e.pattern}]` : ''}`;
+                }
+                catch {
+                    return line.slice(0, 100);
+                }
+            });
+            return { text: `${header}\n\n${formatted.join('\n')}` };
+        },
+    });
+}

package/dist/commands/check-updates.d.ts

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