shellward 0.5.1 → 0.5.3

package/README.md

@@ -50,7 +50,7 @@ Your AI agent has full access to tools — shell, email, HTTP, file system. One
 
 | Platform | Integration | Note |
 |----------|------------|------|
-| **OpenClaw** | Plugin | `openclaw plugins install shellward` — out of the box |
+| **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 |
 | **LangChain** | SDK | LLM application framework |

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "shellward",
   "name": "ShellWard",
   "description": "AI Agent Security Middleware — injection detection, dangerous operation blocking, PII audit (incl. Chinese ID card, phone, bank card), data exfiltration prevention. SDK + OpenClaw plugin.",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "skills": ["./skills"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "shellward",
-  "version": "0.5.1",
-  "description": "AI Agent Security Middleware | 身份证/手机号/银行卡 PII 审计 | 中文注入检测 | 8层防御 | SDK + OpenClaw — Security layer for AI agents: prompt injection, data leak detection, tool control. Chinese PII audit, 8 defense layers. Zero dependencies.",
+  "version": "0.5.3",
+  "description": "AI Agent Security Middleware — 8-layer defense against prompt injection, data exfiltration & dangerous commands. DLP model: use data freely, block external leaks. Zero dependencies. SDK + OpenClaw plugin. Supports LangChain, AutoGPT, Claude Code, Cursor, OpenAI Agents.",
   "keywords": [
     "shellward",
     "ai-security",
@@ -10,12 +10,17 @@
     "prompt-injection",
     "llm-security",
     "data-protection",
+    "data-exfiltration",
+    "dlp",
+    "guardrails",
+    "langchain",
+    "autogpt",
+    "openai",
+    "cursor",
     "openclaw",
-    "plugin",
     "sdk",
-    "身份证",
     "PII",
-    "guardrails"
+    "agent-security"
   ],
   "author": "jnMetaCode",
   "license": "Apache-2.0",

package/src/index.ts

@@ -20,7 +20,7 @@ import { registerAllCommands } from './commands/index'
 import { checkForUpdate } from './update-check'
 import { runAutoCheckOnStartup } from './auto-check'
 
-const CURRENT_VERSION = '0.5.0'
+const CURRENT_VERSION = '0.5.3'
 
 // Re-export core engine for SDK usage
 export { ShellWard } from './core/engine'
@@ -32,11 +32,14 @@ export type { ShellWardConfig } from './types'
  * 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: any, guard: ShellWard): any {
   return {
     ...api,
-    on(hookName: string, handler: Function, opts?: any) {
+    on(hookName: string, handler: Function, opts?: any): boolean {
       const isBlockHook = hookName === 'before_tool_call'
       const wrappedHandler = (event: any) => {
         try {
@@ -56,7 +59,12 @@ function createSafeApi(api: any, guard: ShellWard): any {
           return undefined
         }
       }
-      api.on(hookName, wrappedHandler, opts)
+      try {
+        api.on(hookName, wrappedHandler, opts)
+        return true
+      } catch {
+        return false
+      }
     },
   }
 }

package/src/layers/data-flow-guard.ts

@@ -1,10 +1,15 @@
 // src/layers/data-flow-guard.ts — L7 OpenClaw Adapter
-// Thin adapter: wires OpenClaw's after_tool_call + before_tool_call hooks to ShellWard core engine
+// Thin adapter: wires OpenClaw hooks to ShellWard core engine for data flow tracking
+// Compat: uses tool_result_persist as fallback when after_tool_call/before_tool_call unavailable
 
 import type { ShellWard } from '../core/engine'
 
 export function setupDataFlowGuard(api: any, guard: ShellWard, enforce: boolean) {
-  api.on('after_tool_call', (event: any) => {
+  let hasReadTracker = false
+  let hasEgressBlock = false
+
+  // Primary read tracker: after_tool_call
+  hasReadTracker = api.on('after_tool_call', (event: any) => {
     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 || '')
@@ -14,7 +19,8 @@ export function setupDataFlowGuard(api: any, guard: ShellWard, enforce: boolean)
     }
   }, { name: 'shellward.data-flow-read-tracker', priority: 50 })
 
-  api.on('before_tool_call', (event: any) => {
+  // Primary egress block: before_tool_call
+  hasEgressBlock = api.on('before_tool_call', (event: any) => {
     const toolName = String(event.toolName || '')
     const params = (event.params && typeof event.params === 'object') ? event.params : {}
 
@@ -24,5 +30,61 @@ export function setupDataFlowGuard(api: any, guard: ShellWard, enforce: boolean)
     }
   }, { name: 'shellward.data-flow-egress', priority: 250 })
 
+  // Fallback: tool_result_persist for both read tracking and egress detection
+  // When after_tool_call/before_tool_call are unavailable, we use tool_result_persist
+  // which fires for every tool result before it's persisted to transcript
+  if (!hasReadTracker || !hasEgressBlock) {
+    api.on('tool_result_persist', (event: any) => {
+      const msg = event.message
+      if (!msg) return undefined
+      const toolName = String(msg.toolName || '')
+      if (!toolName) return undefined
+      const toolLower = toolName.toLowerCase()
+
+      // Fallback read tracking: scan tool results for PII to detect sensitive data access
+      // The L2 output-scanner already does scanData() which calls markSensitiveData()
+      // So read tracking is covered. Here we also track file reads by tool name.
+      if (!hasReadTracker && guard.isReadTool(toolLower)) {
+        // We don't have the file path from tool_result_persist,
+        // but L2's scanData already marks sensitive data when PII is found in results
+        guard.log.write({
+          level: 'INFO',
+          layer: 'L7',
+          action: 'detect',
+          detail: `Read tool executed: ${toolName} (tracking via result scan)`,
+          tool: toolName,
+        })
+      }
+
+      // Fallback egress detection: check if an outbound tool was used after sensitive data
+      if (!hasEgressBlock) {
+        // We can't block here (tool already ran), but we detect and log
+        const fakeParams: Record<string, any> = {}
+        const result = guard.checkOutbound(toolName, fakeParams)
+        if (!result.allowed) {
+          guard.log.write({
+            level: 'CRITICAL',
+            layer: 'L7',
+            action: 'detect',
+            detail: guard.locale === 'zh'
+              ? `⚠️ 数据外泄检测 (无法前置拦截): ${toolName} 在访问敏感数据后执行了外发操作`
+              : `⚠️ Data exfiltration detected (pre-block unavailable): ${toolName} sent data after sensitive access`,
+            tool: toolName,
+            pattern: 'data_exfil_chain',
+          })
+        }
+      }
+
+      return undefined
+    }, { name: 'shellward.data-flow-fallback', priority: 90 })
+
+    if (!hasReadTracker) {
+      api.logger.warn('[ShellWard] L7 Data Flow Guard: after_tool_call unavailable, using result-based tracking')
+    }
+    if (!hasEgressBlock) {
+      api.logger.warn('[ShellWard] L7 Data Flow Guard: before_tool_call unavailable, using post-execution detection')
+    }
+  }
+
   api.logger.info('[ShellWard] L7 Data Flow Guard enabled')
 }

package/src/layers/input-auditor.ts

@@ -1,9 +1,11 @@
 // src/layers/input-auditor.ts — L4 OpenClaw Adapter
-// Thin adapter: wires OpenClaw's before_tool_call + message_received hooks to ShellWard core engine
+// Thin adapter: wires OpenClaw hooks to ShellWard core engine for injection detection
+// Compat: supports both old (message_received) and new (message:received) hook names
 
 import type { ShellWard } from '../core/engine'
 
 export function setupInputAuditor(api: any, guard: ShellWard, enforce: boolean) {
+  // Tool call parameter scanning via before_tool_call
   api.on('before_tool_call', (event: any) => {
     const args: Record<string, any> = (event.params && typeof event.params === 'object') ? event.params : {}
     const texts = guard.extractTextFields(args)
@@ -22,11 +24,18 @@ export function setupInputAuditor(api: any, guard: ShellWard, enforce: boolean)
     }
   }, { name: 'shellward.input-auditor', priority: 300 })
 
-  api.on('message_received', (event: any) => {
+  // Message scanning: try both OpenClaw hook naming conventions
+  const messageHandler = (event: any) => {
     const content = typeof event.content === 'string' ? event.content : ''
     if (!content) return
     guard.checkInjection(content, { source: 'message' })
-  }, { name: 'shellward.message-auditor', priority: 100 })
+  }
+
+  // Try new-style colon-separated hook name first, then legacy underscore style
+  const registered = api.on('message:received', messageHandler, { name: 'shellward.message-auditor', priority: 100 })
+  if (!registered) {
+    api.on('message_received', messageHandler, { name: 'shellward.message-auditor', priority: 100 })
+  }
 
   api.logger.info(`[ShellWard] L4 Input Auditor enabled`)
 }

package/src/layers/outbound-guard.ts

@@ -1,10 +1,11 @@
 // src/layers/outbound-guard.ts — L6 OpenClaw Adapter
-// Thin adapter: wires OpenClaw's message_sending hook to ShellWard core engine
+// Thin adapter: wires OpenClaw hooks to ShellWard core engine for outbound response scanning
+// Compat: supports both old (message_sending) and new (message:sent) hook names
 
 import type { ShellWard } from '../core/engine'
 
 export function setupOutboundGuard(api: any, guard: ShellWard, enforce: boolean) {
-  api.on('message_sending', (event: any) => {
+  const handler = (event: any) => {
     const content = event.content
     if (!content || typeof content !== 'string') return undefined
 
@@ -18,7 +19,13 @@ export function setupOutboundGuard(api: any, guard: ShellWard, enforce: boolean)
     }
 
     return undefined
-  }, { name: 'shellward.outbound-guard', priority: 100 })
+  }
+
+  // Try new-style hook name first, then legacy
+  const registered = api.on('message:sent', handler, { name: 'shellward.outbound-guard', priority: 100 })
+  if (!registered) {
+    api.on('message_sending', handler, { name: 'shellward.outbound-guard', priority: 100 })
+  }
 
   api.logger.info('[ShellWard] L6 Outbound Guard enabled')
 }

package/src/layers/session-guard.ts

@@ -1,10 +1,12 @@
 // src/layers/session-guard.ts — L8 OpenClaw Adapter
-// Thin adapter: wires OpenClaw's session_end + subagent_spawning hooks to ShellWard core engine
+// Thin adapter: wires OpenClaw hooks to ShellWard core engine for session monitoring
+// Compat: supports multiple hook naming conventions and graceful degradation
 
 import type { ShellWard } from '../core/engine'
 
 export function setupSessionGuard(api: any, guard: ShellWard, enforce: boolean) {
-  api.on('session_end', () => {
+  // Session end: try new-style, then legacy, then command-based
+  const sessionEndHandler = () => {
     guard.log.write({
       level: 'INFO',
       layer: 'L8',
@@ -13,9 +15,19 @@ export function setupSessionGuard(api: any, guard: ShellWard, enforce: boolean)
         ? '会话结束 — 安全审计完成'
         : 'Session ended — security audit complete',
     })
-  }, { name: 'shellward.session-end', priority: 50 })
+  }
 
-  api.on('subagent_spawning', (event: any) => {
+  let registered = api.on('session:end', sessionEndHandler, { name: 'shellward.session-end', priority: 50 })
+  if (!registered) {
+    registered = api.on('session_end', sessionEndHandler, { name: 'shellward.session-end', priority: 50 })
+  }
+  if (!registered) {
+    // Fallback: listen for command:new (session reset) as a proxy
+    api.on('command:new', sessionEndHandler, { name: 'shellward.session-end-fallback', priority: 50 })
+  }
+
+  // Subagent monitoring: try multiple naming conventions
+  const subagentHandler = (event: any) => {
     const mode = event.mode || 'unknown'
     guard.log.write({
       level: 'MEDIUM',
@@ -25,7 +37,16 @@ export function setupSessionGuard(api: any, guard: ShellWard, enforce: boolean)
         ? `子 Agent 创建: mode=${mode}, agentId=${event.agentId || 'unknown'}`
         : `Subagent spawning: mode=${mode}, agentId=${event.agentId || 'unknown'}`,
     })
-  }, { name: 'shellward.subagent-guard', priority: 100 })
+  }
+
+  // Try ContextEngine-style hook, then legacy
+  let subRegistered = api.on('subagent:spawning', subagentHandler, { name: 'shellward.subagent-guard', priority: 100 })
+  if (!subRegistered) {
+    subRegistered = api.on('subagent_spawning', subagentHandler, { name: 'shellward.subagent-guard', priority: 100 })
+  }
+  if (!subRegistered) {
+    api.logger.warn('[ShellWard] L8 Session Guard: subagent hooks unavailable, subagent monitoring disabled')
+  }
 
   api.logger.info('[ShellWard] L8 Session Guard enabled')
 }

package/src/layers/tool-blocker.ts

@@ -1,10 +1,12 @@
 // src/layers/tool-blocker.ts — L3 OpenClaw Adapter
 // Thin adapter: wires OpenClaw's before_tool_call hook to ShellWard core engine
+// Compat: falls back to tool_result_persist for post-execution detection if before_tool_call unavailable
 
 import type { ShellWard } from '../core/engine'
 
 export function setupToolBlocker(api: any, guard: ShellWard, enforce: boolean) {
-  api.on('before_tool_call', (event: any) => {
+  // Primary: pre-execution blocking via before_tool_call
+  const hasBeforeToolCall = api.on('before_tool_call', (event: any) => {
     const tool = String(event.toolName || '')
     const args: Record<string, any> = (event.params && typeof event.params === 'object') ? event.params : {}
 
@@ -31,5 +33,35 @@ export function setupToolBlocker(api: any, guard: ShellWard, enforce: boolean) {
     }
   }, { name: 'shellward.tool-blocker', priority: 200 })
 
+  // Fallback: post-execution detection via tool_result_persist
+  // When before_tool_call is unavailable (some OpenClaw versions), we still detect
+  // dangerous tool usage after the fact and log it for audit trail
+  if (!hasBeforeToolCall) {
+    api.on('tool_result_persist', (event: any) => {
+      const msg = event.message
+      if (!msg) return undefined
+      const tool = String(msg.toolName || '')
+      if (!tool) return undefined
+
+      // Check if the tool itself is blocked
+      const toolCheck = guard.checkTool(tool)
+      if (!toolCheck.allowed) {
+        guard.log.write({
+          level: 'CRITICAL',
+          layer: 'L3',
+          action: 'detect',
+          detail: guard.locale === 'zh'
+            ? `⚠️ 高危工具已执行 (无法前置拦截): ${tool} — ${toolCheck.reason}`
+            : `⚠️ Dangerous tool executed (pre-block unavailable): ${tool} — ${toolCheck.reason}`,
+          tool,
+        })
+      }
+
+      return undefined
+    }, { name: 'shellward.tool-blocker-fallback', priority: 190 })
+
+    api.logger.warn('[ShellWard] L3 Tool Blocker: before_tool_call hook unavailable, using post-execution detection')
+  }
+
   api.logger.info('[ShellWard] L3 Tool Blocker enabled')
 }