shellward 0.5.10 → 0.5.12

package/dist/index.js

@@ -0,0 +1,137 @@
+// src/index.ts — ShellWard: AI Agent Security Middleware
+//
+// Two usage modes:
+//   1. SDK (any platform):  import { ShellWard } from 'shellward'
+//   2. OpenClaw plugin:     import shellward from 'shellward'
+//
+// See docs/定位.md — ShellWard is an AI Agent Security Layer,
+// NOT just an OpenClaw plugin. The core engine is platform-agnostic.
+import { ShellWard } from './core/engine.js';
+import { setupPromptGuard } from './layers/prompt-guard.js';
+import { setupOutputScanner } from './layers/output-scanner.js';
+import { setupToolBlocker } from './layers/tool-blocker.js';
+import { setupInputAuditor } from './layers/input-auditor.js';
+import { setupSecurityGate } from './layers/security-gate.js';
+import { setupOutboundGuard } from './layers/outbound-guard.js';
+import { setupDataFlowGuard } from './layers/data-flow-guard.js';
+import { setupSessionGuard } from './layers/session-guard.js';
+import { registerAllCommands } from './commands/index.js';
+import { checkForUpdate } from './update-check.js';
+import { runAutoCheckOnStartup } from './auto-check.js';
+const CURRENT_VERSION = '0.5.10';
+// Re-export core engine for SDK usage
+export { ShellWard } from './core/engine.js';
+/**
+ * Wrap api.on so every hook handler gets try-catch protection.
+ * If a security hook throws, we log the error and fail-safe:
+ * - before_tool_call: block (deny on error, safer than allow)
+ * - other hooks: return undefined (don't break the chain)
+ *
+ * Returns boolean indicating whether hook registration succeeded.
+ * This allows layers to detect missing hooks and register fallbacks.
+ */
+function createSafeApi(api, guard) {
+    return {
+        ...api,
+        on(hookName, handler, opts) {
+            const isBlockHook = hookName === 'before_tool_call';
+            const wrappedHandler = (event) => {
+                try {
+                    return handler(event);
+                }
+                catch (err) {
+                    const msg = err?.message || String(err);
+                    guard.log.write({
+                        level: 'CRITICAL',
+                        layer: 'L0',
+                        action: 'error',
+                        detail: `Hook ${opts?.name || hookName} threw: ${msg.slice(0, 200)}`,
+                    });
+                    try {
+                        api.logger.warn(`[ShellWard] Hook error in ${opts?.name || hookName}: ${msg}`);
+                    }
+                    catch { }
+                    if (isBlockHook) {
+                        return { block: true, blockReason: `⚠️ [ShellWard] Internal error in security check — operation blocked for safety` };
+                    }
+                    return undefined;
+                }
+            };
+            try {
+                api.on(hookName, wrappedHandler, opts);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+// OpenClaw plugin entry point
+export default {
+    id: 'shellward',
+    register(api) {
+        const guard = new ShellWard(api.config);
+        const enforce = guard.config.mode === 'enforce';
+        const safe = createSafeApi(api, guard);
+        const startMsg = guard.locale === 'zh'
+            ? `[ShellWard] AI Agent 安全中间件已启动 (v${CURRENT_VERSION}, 模式: ${guard.config.mode})`
+            : `[ShellWard] AI Agent Security Middleware started (v${CURRENT_VERSION}, mode: ${guard.config.mode})`;
+        api.logger.info(startMsg);
+        // === Defense Layers (L1-L8) — thin adapters calling core engine ===
+        if (guard.config.layers.promptGuard) {
+            setupPromptGuard(safe, guard);
+        }
+        if (guard.config.layers.outputScanner) {
+            setupOutputScanner(safe, guard);
+        }
+        if (guard.config.layers.toolBlocker) {
+            setupToolBlocker(safe, guard, enforce);
+        }
+        if (guard.config.layers.inputAuditor) {
+            setupInputAuditor(safe, guard, enforce);
+        }
+        // L5 uses raw api for registerTool (not a hook)
+        if (guard.config.layers.securityGate) {
+            setupSecurityGate(api, guard, enforce);
+        }
+        if (guard.config.layers.outboundGuard) {
+            setupOutboundGuard(safe, guard, enforce);
+        }
+        if (guard.config.layers.dataFlowGuard) {
+            setupDataFlowGuard(safe, guard, enforce);
+        }
+        if (guard.config.layers.sessionGuard) {
+            setupSessionGuard(safe, guard, enforce);
+        }
+        // === Slash Commands ===
+        if (api.registerCommand) {
+            registerAllCommands(api, guard.config);
+            api.logger.info('[ShellWard] 6 commands registered');
+        }
+        const allLayers = ['promptGuard', 'outputScanner', 'toolBlocker', 'inputAuditor', 'securityGate', 'outboundGuard', 'dataFlowGuard', 'sessionGuard'];
+        const enabledCount = allLayers.filter(k => guard.config.layers[k]).length;
+        const layerMsg = guard.locale === 'zh'
+            ? `[ShellWard] ${enabledCount} 层防御已激活 — 敏感数据审计 | 注入检测 | 外泄拦截`
+            : `[ShellWard] ${enabledCount} defense layers active`;
+        api.logger.info(layerMsg);
+        guard.log.write({
+            level: 'INFO',
+            layer: 'L1',
+            action: 'allow',
+            detail: `ShellWard v${CURRENT_VERSION} started with ${enabledCount} layers`,
+        });
+        checkForUpdate(CURRENT_VERSION).then(result => {
+            if (result?.shouldNotify) {
+                const msg = guard.locale === 'zh'
+                    ? `[ShellWard] 新版本 v${result.latest} 可用 (当前 v${result.current})`
+                    : `[ShellWard] Update available: v${result.latest} (current v${result.current})`;
+                api.logger.warn(msg);
+            }
+        }).catch(() => { });
+        // 启动时自动安全检查（OpenClaw 漏洞、插件风险、MCP 配置、root 运行）
+        if (guard.config.autoCheckOnStartup !== false) {
+            runAutoCheckOnStartup(api.logger, guard.locale);
+        }
+    },
+};

package/dist/layers/data-flow-guard.d.ts

@@ -0,0 +1,2 @@
+import type { ShellWard } from '../core/engine.js';
+export declare function setupDataFlowGuard(api: any, guard: ShellWard, enforce: boolean): void;

package/dist/layers/data-flow-guard.js

@@ -0,0 +1,23 @@
+// src/layers/data-flow-guard.ts — L7 OpenClaw Adapter
+// Thin adapter: wires OpenClaw hooks to ShellWard core engine for data flow tracking
+export function setupDataFlowGuard(api, guard, enforce) {
+    // Track file reads via after_tool_call
+    api.on('after_tool_call', (event) => {
+        const toolName = String(event.toolName || '').toLowerCase();
+        const params = (event.params && typeof event.params === 'object') ? event.params : {};
+        const path = String(params.path || params.file_path || params.filename || params.target || '');
+        if (guard.isReadTool(toolName) && path) {
+            guard.trackFileRead(event.toolName, path);
+        }
+    }, { name: 'shellward.data-flow-read-tracker', priority: 50 });
+    // Block outbound sends when sensitive data was recently accessed
+    api.on('before_tool_call', (event) => {
+        const toolName = String(event.toolName || '');
+        const params = (event.params && typeof event.params === 'object') ? event.params : {};
+        const result = guard.checkOutbound(toolName, params);
+        if (!result.allowed && enforce) {
+            return { block: true, blockReason: `🚫 [ShellWard] ${result.reason}` };
+        }
+    }, { name: 'shellward.data-flow-egress', priority: 250 });
+    api.logger.info('[ShellWard] L7 Data Flow Guard enabled');
+}

package/dist/layers/input-auditor.d.ts

@@ -0,0 +1,2 @@
+import type { ShellWard } from '../core/engine.js';
+export declare function setupInputAuditor(api: any, guard: ShellWard, enforce: boolean): void;

package/dist/layers/input-auditor.js

@@ -0,0 +1,33 @@
+// src/layers/input-auditor.ts — L4 OpenClaw Adapter
+// Thin adapter: wires OpenClaw hooks to ShellWard core engine for injection detection
+// Compat: registers all known hook name variants — OpenClaw silently ignores unknown ones
+export function setupInputAuditor(api, guard, enforce) {
+    // Tool call parameter scanning via before_tool_call
+    api.on('before_tool_call', (event) => {
+        const args = (event.params && typeof event.params === 'object') ? event.params : {};
+        const texts = guard.extractTextFields(args);
+        if (texts.length === 0)
+            return;
+        const toolName = String(event.toolName || '');
+        const threshold = guard.getInjectionThreshold(toolName);
+        const fullText = texts.join('\n');
+        const result = guard.checkInjection(fullText, { source: toolName, threshold });
+        if (!result.safe && enforce) {
+            const reason = guard.locale === 'zh'
+                ? `检测到可能的提示词注入攻击!\n风险评分: ${result.score}/100\n匹配规则: ${result.matched.map(m => m.name).join(', ')}`
+                : `Potential prompt injection detected!\nRisk score: ${result.score}/100\nMatched: ${result.matched.map(m => m.name).join(', ')}`;
+            return { block: true, blockReason: `⚠️ [ShellWard] ${reason}` };
+        }
+    }, { name: 'shellward.input-auditor', priority: 300 });
+    // Message scanning: register ALL known naming conventions
+    // OpenClaw silently ignores unknown hooks (no error thrown), so register all variants
+    const messageHandler = (event) => {
+        const content = typeof event.content === 'string' ? event.content : '';
+        if (!content)
+            return;
+        guard.checkInjection(content, { source: 'message' });
+    };
+    api.on('message_received', messageHandler, { name: 'shellward.message-auditor', priority: 100 });
+    api.on('message:received', messageHandler, { name: 'shellward.message-auditor-v2', priority: 100 });
+    api.logger.info(`[ShellWard] L4 Input Auditor enabled`);
+}

package/dist/layers/outbound-guard.d.ts

@@ -0,0 +1,2 @@
+import type { ShellWard } from '../core/engine.js';
+export declare function setupOutboundGuard(api: any, guard: ShellWard, enforce: boolean): void;

package/dist/layers/outbound-guard.js

@@ -0,0 +1,22 @@
+// src/layers/outbound-guard.ts — L6 OpenClaw Adapter
+// Thin adapter: wires OpenClaw hooks to ShellWard core engine for outbound response scanning
+// Compat: registers all known hook name variants
+export function setupOutboundGuard(api, guard, enforce) {
+    const handler = (event) => {
+        const content = event.content;
+        if (!content || typeof content !== 'string')
+            return undefined;
+        const result = guard.checkResponse(content);
+        if (result.canaryLeak && enforce) {
+            const warning = guard.locale === 'zh'
+                ? '⚠️ [ShellWard] 检测到安全异常，本次回复已被拦截。可能存在提示词注入攻击。'
+                : '⚠️ [ShellWard] Security anomaly detected, this response was blocked. Possible prompt injection attack.';
+            return { content: warning };
+        }
+        return undefined;
+    };
+    // Register ALL known naming conventions — OpenClaw silently ignores unknown ones
+    api.on('message_sending', handler, { name: 'shellward.outbound-guard', priority: 100 });
+    api.on('message:sent', handler, { name: 'shellward.outbound-guard-v2', priority: 100 });
+    api.logger.info('[ShellWard] L6 Outbound Guard enabled');
+}

package/dist/layers/output-scanner.d.ts

@@ -0,0 +1,2 @@
+import type { ShellWard } from '../core/engine.js';
+export declare function setupOutputScanner(api: any, guard: ShellWard): void;

package/dist/layers/output-scanner.js

@@ -0,0 +1,16 @@
+// src/layers/output-scanner.ts — L2 OpenClaw Adapter
+// Thin adapter: wires OpenClaw's tool_result_persist hook to ShellWard core engine
+export function setupOutputScanner(api, guard) {
+    api.on('tool_result_persist', (event) => {
+        const msg = event.message;
+        if (!msg || !Array.isArray(msg.content))
+            return undefined;
+        for (const block of msg.content) {
+            if (block.type === 'text' && typeof block.text === 'string') {
+                guard.scanData(block.text, msg.toolName);
+            }
+        }
+        return undefined;
+    }, { name: 'shellward.output-scanner', priority: 100 });
+    api.logger.info('[ShellWard] L2 Output Scanner enabled');
+}

package/dist/layers/prompt-guard.d.ts

@@ -0,0 +1,2 @@
+import type { ShellWard } from '../core/engine.js';
+export declare function setupPromptGuard(api: any, guard: ShellWard): void;

package/dist/layers/prompt-guard.js

@@ -0,0 +1,14 @@
+// src/layers/prompt-guard.ts — L1 OpenClaw Adapter
+// Thin adapter: wires OpenClaw's before_prompt_build hook to ShellWard core engine
+export function setupPromptGuard(api, guard) {
+    api.on('before_prompt_build', () => {
+        guard.log.write({
+            level: 'INFO',
+            layer: 'L1',
+            action: 'inject',
+            detail: 'Security prompt injected',
+        });
+        return { prependSystemContext: guard.getSecurityPrompt() };
+    }, { name: 'shellward.prompt-guard', priority: 100 });
+    api.logger.info('[ShellWard] L1 Prompt Guard enabled');
+}

package/dist/layers/security-gate.d.ts

@@ -0,0 +1,2 @@
+import type { ShellWard } from '../core/engine.js';
+export declare function setupSecurityGate(api: any, guard: ShellWard, enforce: boolean): void;

package/dist/layers/security-gate.js

@@ -0,0 +1,49 @@
+// src/layers/security-gate.ts — L5 OpenClaw Adapter
+// Thin adapter: registers shellward_check tool via OpenClaw's registerTool API
+function textResult(text) {
+    return {
+        content: [{ type: 'text', text }],
+        details: {},
+    };
+}
+export function setupSecurityGate(api, guard, enforce) {
+    if (!api.registerTool) {
+        api.logger.warn('[ShellWard] L5 Security Gate skipped: registerTool not available');
+        return;
+    }
+    const toolDescription = guard.locale === 'zh'
+        ? '在执行任何 Shell 命令、文件删除、邮件发送或支付操作前，必须先调用此工具进行安全检查。传入 action 类型和具体参数。'
+        : 'MUST be called before executing any shell command, file deletion, email sending, or payment operation. Pass the action type and parameters for security review.';
+    api.registerTool({
+        name: 'shellward_check',
+        label: 'ShellWard Security Check',
+        description: toolDescription,
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    description: 'The action to check: exec, file_delete, file_write, send_email, payment, etc.',
+                },
+                details: {
+                    type: 'string',
+                    description: 'The specific command, file path, or operation details',
+                },
+            },
+            required: ['action', 'details'],
+        },
+        execute: async (_toolCallId, params) => {
+            const action = typeof params.action === 'string' ? params.action.trim() : '';
+            const details = typeof params.details === 'string' ? params.details.trim() : '';
+            if (!action) {
+                return textResult(JSON.stringify({ status: 'DENIED', reason: 'action parameter is required' }));
+            }
+            const result = guard.checkAction(action, details);
+            return textResult(JSON.stringify({
+                status: result.allowed ? 'ALLOWED' : 'DENIED',
+                reason: result.reason,
+            }));
+        },
+    });
+    api.logger.info('[ShellWard] L5 Security Gate registered');
+}

package/dist/layers/session-guard.d.ts

@@ -0,0 +1,2 @@
+import type { ShellWard } from '../core/engine.js';
+export declare function setupSessionGuard(api: any, guard: ShellWard, enforce: boolean): void;

package/dist/layers/session-guard.js

@@ -0,0 +1,34 @@
+// src/layers/session-guard.ts — L8 OpenClaw Adapter
+// Thin adapter: wires OpenClaw hooks to ShellWard core engine for session monitoring
+// Compat: registers all known hook name variants
+export function setupSessionGuard(api, guard, enforce) {
+    const sessionEndHandler = () => {
+        guard.log.write({
+            level: 'INFO',
+            layer: 'L8',
+            action: 'detect',
+            detail: guard.locale === 'zh'
+                ? '会话结束 — 安全审计完成'
+                : 'Session ended — security audit complete',
+        });
+    };
+    // Register ALL known naming conventions for session end
+    api.on('session_end', sessionEndHandler, { name: 'shellward.session-end', priority: 50 });
+    api.on('session:end', sessionEndHandler, { name: 'shellward.session-end-v2', priority: 50 });
+    api.on('command:new', sessionEndHandler, { name: 'shellward.session-end-fallback', priority: 50 });
+    const subagentHandler = (event) => {
+        const mode = event.mode || 'unknown';
+        guard.log.write({
+            level: 'MEDIUM',
+            layer: 'L8',
+            action: 'detect',
+            detail: guard.locale === 'zh'
+                ? `子 Agent 创建: mode=${mode}, agentId=${event.agentId || 'unknown'}`
+                : `Subagent spawning: mode=${mode}, agentId=${event.agentId || 'unknown'}`,
+        });
+    };
+    // Register ALL known naming conventions for subagent monitoring
+    api.on('subagent_spawning', subagentHandler, { name: 'shellward.subagent-guard', priority: 100 });
+    api.on('subagent:spawning', subagentHandler, { name: 'shellward.subagent-guard-v2', priority: 100 });
+    api.logger.info('[ShellWard] L8 Session Guard enabled');
+}

package/dist/layers/tool-blocker.d.ts

@@ -0,0 +1,2 @@
+import type { ShellWard } from '../core/engine.js';
+export declare function setupToolBlocker(api: any, guard: ShellWard, enforce: boolean): void;

package/dist/layers/tool-blocker.js

@@ -0,0 +1,28 @@
+// src/layers/tool-blocker.ts — L3 OpenClaw Adapter
+// Thin adapter: wires OpenClaw's before_tool_call hook to ShellWard core engine
+export function setupToolBlocker(api, guard, enforce) {
+    api.on('before_tool_call', (event) => {
+        const tool = String(event.toolName || '');
+        const args = (event.params && typeof event.params === 'object') ? event.params : {};
+        const toolCheck = guard.checkTool(tool);
+        if (!toolCheck.allowed && enforce) {
+            return { block: true, blockReason: `🚫 [ShellWard] ${toolCheck.reason}` };
+        }
+        if (guard.isExecTool(tool)) {
+            const cmd = String(args.command ?? args.cmd ?? '');
+            const cmdCheck = guard.checkCommand(cmd, tool);
+            if (!cmdCheck.allowed && enforce) {
+                return { block: true, blockReason: `🚫 [ShellWard] ${cmdCheck.reason}` };
+            }
+        }
+        const rawPath = String(args.path || args.file_path || args.filename || args.target || '');
+        if (rawPath && guard.isWriteOrDeleteTool(tool)) {
+            const op = /delete|remove/i.test(tool) ? 'delete' : 'write';
+            const pathCheck = guard.checkPath(rawPath, op, tool);
+            if (!pathCheck.allowed && enforce) {
+                return { block: true, blockReason: `🚫 [ShellWard] ${pathCheck.reason}` };
+            }
+        }
+    }, { name: 'shellward.tool-blocker', priority: 200 });
+    api.logger.info('[ShellWard] L3 Tool Blocker enabled');
+}

package/dist/mcp-server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};