shellward 0.5.9 → 0.5.11

package/dist/update-check.js

@@ -0,0 +1,147 @@
+// src/update-check.ts — Non-blocking version check + remote vulnerability DB
+// Uses only Node.js built-in https module (zero dependencies)
+//
+// Anti-annoyance design:
+// - Network check at most once per 24 hours
+// - Same version update only notified ONCE (dismissed = silenced until next version)
+// - Vuln DB cached 24h, /check-updates always shows latest cache
+// - All network failures are silent and cached to avoid repeated timeouts
+import { get } from 'https';
+import { mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { getHomeDir } from './utils.js';
+const CACHE_DIR = join(getHomeDir(), '.openclaw', 'shellward');
+const CACHE_FILE = join(CACHE_DIR, 'update-cache.json');
+const VULN_CACHE_FILE = join(CACHE_DIR, 'vuln-db-cache.json');
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+// Remote sources
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org/shellward/latest';
+const VULN_DB_URL = 'https://raw.githubusercontent.com/jnMetaCode/shellward/main/vuln-db.json';
+/**
+ * Simple HTTPS GET with redirect support. Timeout: 5s.
+ */
+function httpsGet(url) {
+    return new Promise((resolve, reject) => {
+        const req = get(url, { timeout: 5000 }, (res) => {
+            if ((res.statusCode === 301 || res.statusCode === 302) && res.headers.location) {
+                get(res.headers.location, { timeout: 5000 }, (res2) => {
+                    let data = '';
+                    res2.on('data', (chunk) => { data += chunk.toString(); });
+                    res2.on('end', () => resolve(data));
+                    res2.on('error', reject);
+                }).on('error', reject);
+                return;
+            }
+            if (res.statusCode !== 200) {
+                reject(new Error(`HTTP ${res.statusCode}`));
+                return;
+            }
+            let data = '';
+            res.on('data', (chunk) => { data += chunk.toString(); });
+            res.on('end', () => resolve(data));
+            res.on('error', reject);
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+    });
+}
+/**
+ * Check npm for latest version.
+ *
+ * Returns result with `shouldNotify`:
+ * - true = first time seeing this new version, show the message
+ * - false = already notified for this version, stay quiet
+ * Returns null if check skipped or failed.
+ */
+export async function checkForUpdate(currentVersion) {
+    try {
+        const cache = readCache(CACHE_FILE);
+        // Use cached version if within interval
+        let latest = null;
+        if (cache && Date.now() - cache.lastCheck < CHECK_INTERVAL_MS && cache.latestVersion) {
+            latest = cache.latestVersion;
+        }
+        else {
+            // Fetch from npm
+            const body = await httpsGet(NPM_REGISTRY_URL);
+            const data = JSON.parse(body);
+            latest = data.version;
+            if (!latest || typeof latest !== 'string')
+                return null;
+            // Save to cache (preserve notifiedVersion)
+            writeCache(CACHE_FILE, {
+                lastCheck: Date.now(),
+                latestVersion: latest,
+                notifiedVersion: cache?.notifiedVersion || null,
+            });
+        }
+        const updateAvailable = compareVersions(latest, currentVersion) > 0;
+        // Determine if we should notify:
+        // Only notify if update available AND we haven't already notified for this exact version
+        const alreadyNotified = cache?.notifiedVersion === latest;
+        const shouldNotify = updateAvailable && !alreadyNotified;
+        // If we're going to notify, mark it so we don't repeat
+        if (shouldNotify) {
+            const freshCache = readCache(CACHE_FILE) || { lastCheck: Date.now(), latestVersion: latest, notifiedVersion: null };
+            freshCache.notifiedVersion = latest;
+            writeCache(CACHE_FILE, freshCache);
+        }
+        return { current: currentVersion, latest, updateAvailable, shouldNotify };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch remote vulnerability database. Cached 24h. Local fallback on failure.
+ */
+export async function fetchVulnDB() {
+    try {
+        const cached = readCache(VULN_CACHE_FILE);
+        if (cached && Date.now() - cached.lastCheck < CHECK_INTERVAL_MS && cached.vulns) {
+            return { vulns: cached.vulns, alerts: cached.alerts || [] };
+        }
+        const body = await httpsGet(VULN_DB_URL);
+        const data = JSON.parse(body);
+        const vulns = Array.isArray(data.vulnerabilities) ? data.vulnerabilities : [];
+        const alerts = Array.isArray(data.supplyChainAlerts) ? data.supplyChainAlerts : [];
+        writeCache(VULN_CACHE_FILE, { lastCheck: Date.now(), vulns, alerts });
+        return { vulns, alerts };
+    }
+    catch {
+        // Cache failure result to avoid repeated timeouts
+        const cached = readCache(VULN_CACHE_FILE);
+        const fallback = { vulns: cached?.vulns || [], alerts: cached?.alerts || [] };
+        writeCache(VULN_CACHE_FILE, { lastCheck: Date.now(), ...fallback });
+        return fallback;
+    }
+}
+/**
+ * Compare semver-like version strings. Positive if a > b, negative if a < b, 0 if equal.
+ */
+export function compareVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const diff = (pa[i] || 0) - (pb[i] || 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+// ===== Cache helpers =====
+function readCache(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(path, data) {
+    try {
+        mkdirSync(CACHE_DIR, { recursive: true, mode: 0o700 });
+        writeFileSync(path, JSON.stringify(data), { mode: 0o600 });
+    }
+    catch { /* ignore */ }
+}

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Get user home directory. Works on Windows (USERPROFILE), Linux/macOS (HOME).
+ */
+export declare function getHomeDir(): string;

package/dist/utils.js

@@ -0,0 +1,8 @@
+// src/utils.ts — Cross-platform path helpers
+import { homedir } from 'os';
+/**
+ * Get user home directory. Works on Windows (USERPROFILE), Linux/macOS (HOME).
+ */
+export function getHomeDir() {
+    return homedir() || process.env.HOME || process.env.USERPROFILE || '~';
+}

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.3",
+  "version": "0.5.10",
   "skills": ["./skills"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "shellward",
-  "version": "0.5.9",
-  "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.",
+  "version": "0.5.11",
+  "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.",
   "keywords": [
     "shellward",
     "ai-security",
@@ -20,7 +21,18 @@
     "openclaw",
     "sdk",
     "PII",
-    "agent-security"
+    "agent-security",
+    "mcp-security",
+    "mcp",
+    "claude-code",
+    "ai-safety",
+    "ai-firewall",
+    "tool-call-security",
+    "runtime-security",
+    "agent-guard",
+    "data-loss-prevention",
+    "chinese-pii",
+    "injection-detection"
   ],
   "author": "jnMetaCode",
   "license": "Apache-2.0",
@@ -30,18 +42,23 @@
     "url": "https://github.com/jnMetaCode/shellward"
   },
   "type": "module",
-  "main": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./src/index.ts",
-      "default": "./src/index.ts"
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
     }
   },
   "scripts": {
-    "test": "npx tsx test-integration.ts && npx tsx test-edge-cases.ts && npx tsx test-sdk.ts",
+    "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:integration": "npx tsx test-integration.ts",
     "test:edge": "npx tsx test-edge-cases.ts",
-    "test:sdk": "npx tsx test-sdk.ts"
+    "test:sdk": "npx tsx test-sdk.ts",
+    "test:mcp": "npx tsx test-mcp.ts",
+    "prepublishOnly": "npm run build"
   },
   "openclaw": {
     "extensions": [
@@ -50,6 +67,7 @@
   },
   "files": [
     "src/",
+    "dist/",
     "skills/",
     "openclaw.plugin.json",
     "vuln-db.json",
@@ -60,5 +78,10 @@
   ],
   "engines": {
     "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
   }
 }

package/src/audit-log.ts

@@ -2,8 +2,8 @@
 
 import { appendFileSync, mkdirSync, renameSync, statSync, writeFileSync } from 'fs'
 import { join } from 'path'
-import { getHomeDir } from './utils'
-import type { AuditEntry, ShellWardConfig } from './types'
+import { getHomeDir } from './utils.js'
+import type { AuditEntry, ShellWardConfig } from './types.js'
 
 const LOG_DIR = join(getHomeDir(), '.openclaw', 'shellward')
 const LOG_FILE = join(LOG_DIR, 'audit.jsonl')
@@ -34,13 +34,17 @@ export class AuditLog {
     } catch { /* directory may already exist */ }
   }
 
-  write(entry: Omit<AuditEntry, 'ts' | 'mode'>): void {
+  write(entry: Pick<AuditEntry, 'level' | 'layer' | 'action' | 'detail'> & Record<string, unknown>): void {
     try {
       const record: AuditEntry = {
+        ...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,
-        ...entry,
       }
       appendFileSync(LOG_FILE, JSON.stringify(record) + '\n', { mode: 0o600 })
       this.rotateIfNeeded()

package/src/auto-check.ts

@@ -4,8 +4,8 @@
 import { execSync } from 'child_process'
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import { join } from 'path'
-import { getHomeDir } from './utils'
-import { fetchVulnDB, compareVersions } from './update-check'
+import { getHomeDir } from './utils.js'
+import { fetchVulnDB, compareVersions } from './update-check.js'
 
 const OPENCLAW_DIR = join(getHomeDir(), '.openclaw')
 

package/src/commands/audit.ts

@@ -2,9 +2,9 @@
 
 import { readFileSync, statSync } from 'fs'
 import { join } from 'path'
-import { getHomeDir } from '../utils'
-import type { ShellWardConfig } from '../types'
-import { resolveLocale } from '../types'
+import { getHomeDir } from '../utils.js'
+import type { ShellWardConfig } from '../types.js'
+import { resolveLocale } from '../types.js'
 
 const LOG_FILE = join(getHomeDir(), '.openclaw', 'shellward', 'audit.jsonl')
 

package/src/commands/check-updates.ts

@@ -3,9 +3,9 @@
 import { execSync } from 'child_process'
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
-import type { ShellWardConfig } from '../types'
-import { resolveLocale } from '../types'
-import { checkForUpdate, fetchVulnDB, compareVersions } from '../update-check'
+import type { ShellWardConfig } from '../types.js'
+import { resolveLocale } from '../types.js'
+import { checkForUpdate, fetchVulnDB, compareVersions, type VulnEntry } from '../update-check.js'
 
 // Local fallback vulnerability database (used when remote fetch fails)
 // Contains only CVE-assigned vulnerabilities as minimum baseline
@@ -92,7 +92,7 @@ export function registerCheckUpdatesCommand(api: any, config: ShellWardConfig) {
       // 3. Check known vulnerabilities (remote DB with local fallback)
       lines.push(zh ? '### 已知漏洞检查' : '### Known Vulnerability Check')
 
-      let vulnDB = LOCAL_VULNS
+      let vulnDB: VulnEntry[] = LOCAL_VULNS
       let alerts: { id: string; severity: string; date: string; description_zh: string; description_en: string }[] = []
       let dbSource = 'local'
       try {

package/src/commands/harden.ts

@@ -3,10 +3,10 @@
 import { existsSync, statSync, chmodSync, readFileSync, readdirSync } from 'fs'
 import { join } from 'path'
 import { execSync } from 'child_process'
-import type { ShellWardConfig } from '../types'
-import { resolveLocale } from '../types'
+import type { ShellWardConfig } from '../types.js'
+import { resolveLocale } from '../types.js'
 
-import { getHomeDir } from '../utils'
+import { getHomeDir } from '../utils.js'
 const HOME = getHomeDir()
 
 export function registerHardenCommand(api: any, config: ShellWardConfig) {

package/src/commands/index.ts

@@ -1,13 +1,13 @@
 // src/commands/index.ts — Register all ShellWard commands
 
-import type { ShellWardConfig } from '../types'
-import { resolveLocale } from '../types'
-import { registerSecurityCommand } from './security'
-import { registerAuditCommand } from './audit'
-import { registerHardenCommand } from './harden'
-import { registerScanPluginsCommand } from './scan-plugins'
-import { registerCheckUpdatesCommand } from './check-updates'
-import { registerUpgradeOpenClawCommand } from './upgrade-openclaw'
+import type { ShellWardConfig } from '../types.js'
+import { resolveLocale } from '../types.js'
+import { registerSecurityCommand } from './security.js'
+import { registerAuditCommand } from './audit.js'
+import { registerHardenCommand } from './harden.js'
+import { registerScanPluginsCommand } from './scan-plugins.js'
+import { registerCheckUpdatesCommand } from './check-updates.js'
+import { registerUpgradeOpenClawCommand } from './upgrade-openclaw.js'
 
 export function registerAllCommands(api: any, config: ShellWardConfig) {
   const locale = resolveLocale(config)

package/src/commands/scan-plugins.ts

@@ -2,10 +2,10 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
 import { join } from 'path'
-import type { ShellWardConfig } from '../types'
-import { resolveLocale } from '../types'
+import type { ShellWardConfig } from '../types.js'
+import { resolveLocale } from '../types.js'
 
-import { getHomeDir } from '../utils'
+import { getHomeDir } from '../utils.js'
 const HOME = getHomeDir()
 const OPENCLAW_DIR = join(HOME, '.openclaw')
 

package/src/commands/security.ts

@@ -3,9 +3,9 @@
 import { readFileSync, statSync, existsSync, readdirSync } from 'fs'
 import { join } from 'path'
 import { execSync } from 'child_process'
-import { getHomeDir } from '../utils'
-import type { ShellWardConfig } from '../types'
-import { resolveLocale } from '../types'
+import { getHomeDir } from '../utils.js'
+import type { ShellWardConfig } from '../types.js'
+import { resolveLocale } from '../types.js'
 
 const LOG_DIR = join(getHomeDir(), '.openclaw', 'shellward')
 const LOG_FILE = join(LOG_DIR, 'audit.jsonl')

package/src/commands/upgrade-openclaw.ts

@@ -1,8 +1,8 @@
 // src/commands/upgrade-openclaw.ts — 一键升级 OpenClaw，减少手动操作
 
 import { execSync } from 'child_process'
-import type { ShellWardConfig } from '../types'
-import { resolveLocale } from '../types'
+import type { ShellWardConfig } from '../types.js'
+import { resolveLocale } from '../types.js'
 
 export function registerUpgradeOpenClawCommand(api: any, config: ShellWardConfig) {
   const locale = resolveLocale(config)

package/src/core/engine.ts

@@ -8,14 +8,14 @@
 import { randomBytes } from 'crypto'
 import { resolve } from 'path'
 import { homedir } from 'os'
-import { DANGEROUS_COMMANDS, splitCommands } from '../rules/dangerous-commands'
-import { PROTECTED_PATHS } from '../rules/protected-paths'
-import { INJECTION_RULES_ZH } from '../rules/injection-zh'
-import { INJECTION_RULES_EN } from '../rules/injection-en'
-import { redactSensitive } from '../rules/sensitive-patterns'
-import { AuditLog } from '../audit-log'
-import { resolveLocale, DEFAULT_CONFIG } from '../types'
-import type { ShellWardConfig, ResolvedLocale, InjectionRule } from '../types'
+import { DANGEROUS_COMMANDS, splitCommands } from '../rules/dangerous-commands.js'
+import { PROTECTED_PATHS } from '../rules/protected-paths.js'
+import { INJECTION_RULES_ZH } from '../rules/injection-zh.js'
+import { INJECTION_RULES_EN } from '../rules/injection-en.js'
+import { redactSensitive } from '../rules/sensitive-patterns.js'
+import { AuditLog } from '../audit-log.js'
+import { resolveLocale, DEFAULT_CONFIG } from '../types.js'
+import type { ShellWardConfig, ResolvedLocale, InjectionRule } from '../types.js'
 
 // ===== Result Types =====
 

package/src/index.ts

@@ -7,25 +7,25 @@
 // 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'
-import { setupPromptGuard } from './layers/prompt-guard'
-import { setupOutputScanner } from './layers/output-scanner'
-import { setupToolBlocker } from './layers/tool-blocker'
-import { setupInputAuditor } from './layers/input-auditor'
-import { setupSecurityGate } from './layers/security-gate'
-import { setupOutboundGuard } from './layers/outbound-guard'
-import { setupDataFlowGuard } from './layers/data-flow-guard'
-import { setupSessionGuard } from './layers/session-guard'
-import { registerAllCommands } from './commands/index'
-import { checkForUpdate } from './update-check'
-import { runAutoCheckOnStartup } from './auto-check'
-
-const CURRENT_VERSION = '0.5.9'
+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'
-export type { CheckResult, ScanResult, InjectionResult, ResponseCheckResult } from './core/engine'
-export type { ShellWardConfig } from './types'
+export { ShellWard } from './core/engine.js'
+export type { CheckResult, ScanResult, InjectionResult, ResponseCheckResult } from './core/engine.js'
+export type { ShellWardConfig } from './types.js'
 
 /**
  * Wrap api.on so every hook handler gets try-catch protection.

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

@@ -1,7 +1,7 @@
 // src/layers/data-flow-guard.ts — L7 OpenClaw Adapter
 // Thin adapter: wires OpenClaw hooks to ShellWard core engine for data flow tracking
 
-import type { ShellWard } from '../core/engine'
+import type { ShellWard } from '../core/engine.js'
 
 export function setupDataFlowGuard(api: any, guard: ShellWard, enforce: boolean) {
   // Track file reads via after_tool_call

package/src/layers/input-auditor.ts

@@ -2,7 +2,7 @@
 // Thin adapter: wires OpenClaw hooks to ShellWard core engine for injection detection
 // Compat: registers all known hook name variants — OpenClaw silently ignores unknown ones
 
-import type { ShellWard } from '../core/engine'
+import type { ShellWard } from '../core/engine.js'
 
 export function setupInputAuditor(api: any, guard: ShellWard, enforce: boolean) {
   // Tool call parameter scanning via before_tool_call

package/src/layers/outbound-guard.ts

@@ -2,7 +2,7 @@
 // Thin adapter: wires OpenClaw hooks to ShellWard core engine for outbound response scanning
 // Compat: registers all known hook name variants
 
-import type { ShellWard } from '../core/engine'
+import type { ShellWard } from '../core/engine.js'
 
 export function setupOutboundGuard(api: any, guard: ShellWard, enforce: boolean) {
   const handler = (event: any) => {

package/src/layers/output-scanner.ts

@@ -1,7 +1,7 @@
 // src/layers/output-scanner.ts — L2 OpenClaw Adapter
 // Thin adapter: wires OpenClaw's tool_result_persist hook to ShellWard core engine
 
-import type { ShellWard } from '../core/engine'
+import type { ShellWard } from '../core/engine.js'
 
 export function setupOutputScanner(api: any, guard: ShellWard) {
   api.on('tool_result_persist', (event: any) => {

package/src/layers/prompt-guard.ts

@@ -1,7 +1,7 @@
 // src/layers/prompt-guard.ts — L1 OpenClaw Adapter
 // Thin adapter: wires OpenClaw's before_prompt_build hook to ShellWard core engine
 
-import type { ShellWard } from '../core/engine'
+import type { ShellWard } from '../core/engine.js'
 
 export function setupPromptGuard(api: any, guard: ShellWard) {
   api.on('before_prompt_build', () => {

package/src/layers/security-gate.ts

@@ -1,7 +1,7 @@
 // src/layers/security-gate.ts — L5 OpenClaw Adapter
 // Thin adapter: registers shellward_check tool via OpenClaw's registerTool API
 
-import type { ShellWard } from '../core/engine'
+import type { ShellWard } from '../core/engine.js'
 
 function textResult(text: string) {
   return {

package/src/layers/session-guard.ts

@@ -2,7 +2,7 @@
 // Thin adapter: wires OpenClaw hooks to ShellWard core engine for session monitoring
 // Compat: registers all known hook name variants
 
-import type { ShellWard } from '../core/engine'
+import type { ShellWard } from '../core/engine.js'
 
 export function setupSessionGuard(api: any, guard: ShellWard, enforce: boolean) {
   const sessionEndHandler = () => {

package/src/layers/tool-blocker.ts

@@ -1,7 +1,7 @@
 // src/layers/tool-blocker.ts — L3 OpenClaw Adapter
 // Thin adapter: wires OpenClaw's before_tool_call hook to ShellWard core engine
 
-import type { ShellWard } from '../core/engine'
+import type { ShellWard } from '../core/engine.js'
 
 export function setupToolBlocker(api: any, guard: ShellWard, enforce: boolean) {
   api.on('before_tool_call', (event: any) => {