v0.5.0: Core engine refactor — DLP model, SDK mode, 8-layer defense

Major architecture changes:
- Extract platform-agnostic core engine (src/core/engine.ts)
- Layers become thin adapters calling core engine methods
- L2 Output Scanner: audit-only (no redaction), data returns in full
- L7 Data Flow Guard: block external sends after sensitive data access
- Add bash network exfiltration detection (curl POST, wget, nc bypass)
- Add auto-check on startup (OpenClaw vulns, plugin risks, MCP config)
- Add supported platforms to README (OpenClaw, Claude Code, Cursor, LangChain, etc.)
- Demo: 7 scenarios (ZH + EN), covering APT attack chain simulation
- Tests: 112 passing (38 integration + 42 edge + 32 SDK)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jnMetaCode

.gitignore

@@ -39,3 +39,4 @@ promo/
 
 # External repos
 awesome-llm-security/
+*.mp4

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.5.0] - 2026-03-14
+
+### Added
+- **ShellWard Core Engine** (`src/core/engine.ts`): Platform-agnostic AI Agent Security Middleware
+- **SDK 模式**: `import { ShellWard } from 'shellward'` — 任意 AI Agent 平台可用
+- **Windows 兼容**: 使用 `os.homedir()` 替代 `process.env.HOME`，支持 Windows
+- **npm scripts**: `npm run test` 运行全部 112 项测试
+
+### Changed
+- **L2/L6 审计模式**: PII 仅检测并记录审计，不再脱敏 — 内部使用允许，L7 拦截外泄
+- **架构重构**: OpenClaw 层改为薄适配器，核心逻辑集中在 engine.ts
+- **README**: 更新为审计模式说明，移除脱敏误导
+- **package.json**: 增加 exports、scripts，描述对齐定位文档
+
+### Fixed
+- tool-blocker: file_delete 正确传入 operation='delete'
+- update-check: writeCache 前确保目录存在
+- test-integration: 审计日志路径使用 homedir() 兼容 Windows
+
 ## [0.3.0] - 2026-03-12
 
 ### Added

README.md

@@ -1,21 +1,21 @@
 # ShellWard
 
-**你的 AI Agent 正在"裸奔"—— 身份证号、手机号、银行卡号明文跑在对话里。**
+**AI Agent Security Middleware** — 保护 AI 代理免受提示词注入、数据泄露、危险工具执行。
 
-唯一支持中国敏感数据保护的 OpenClaw 安全插件 — 8 层纵深防御，中文注入检测，零依赖，一行命令安装。
+唯一支持中国敏感数据保护的 AI 安全层 — 8 层纵深防御，中文注入检测，零依赖。支持 **OpenClaw 插件** 与 **独立 SDK** 两种形态。
 
 [![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-100%20passing-brightgreen)](#性能)
+[![tests](https://img.shields.io/badge/tests-112%20passing-brightgreen)](#性能)
 [![deps](https://img.shields.io/badge/dependencies-0-brightgreen)](#性能)
 
 [中文](#演示) | [English](#english)
 
 ### 演示
 
-![ShellWard 安全防护演示](https://github.com/jnMetaCode/shellward/releases/download/v0.4.0/demo-zh.gif)
+![ShellWard 安全防护演示](https://github.com/jnMetaCode/shellward/releases/download/v0.5.0/demo-zh.gif)
 
-> 5 个真实攻击场景：危险命令拦截 → 中文注入检测 → 身份证/手机/银行卡自动隐藏 → 数据外泄链阻断 → 正常操作放行
+> 7 个真实攻击场景：服务器毁灭拦截 → 反弹 Shell 阻断 → 注入检测 → DLP 审计 → 数据外泄链拦截 → 凭证窃取防护 → APT 攻击链还原
 
 ### 你的 AI Agent 正在"裸奔"
 
@@ -36,13 +36,30 @@
 ✅ 有 ShellWard:
 
   Agent 读取客户文件...
-  工具输出: "客户张三，身份证号[REDACTED:身份证号]，手机[REDACTED:手机号]，
-            银行卡[REDACTED:银行卡号]"
-  → 敏感信息在进入对话之前就被脱敏
-  → LLM 永远看不到真实数据
-  → 日志中只有脱敏后的安全内容
+  工具输出: "客户张三，身份证号330102199001011234，手机13812345678，
+            银行卡6225880137654321"
+  → L2 检测并记录审计日志（数据正常返回，供 AI 分析使用）
+  → L7 拦截：若 AI 试图将数据外发（send_email、http_request 发 body）→ 阻断
+  → 内部使用不受影响，外泄边界被守住
 ```
 
+**v0.5 保护模型**：内部使用允许（用户需要完整数据做分析），外部发送拦截（L7 数据流监控）。PII 仅审计不脱敏，避免误伤正常业务。
+
+> 💡 **核心理念：像企业防火墙一样，内部随便用，数据出不去。**
+
+### 支持平台
+
+| 平台 | 集成方式 | 说明 |
+|------|---------|------|
+| **OpenClaw** | 插件一键安装 | `openclaw plugins install shellward`，开箱即用 |
+| **Claude Code** | SDK 集成 | Anthropic 官方 CLI Agent |
+| **Cursor** | SDK 集成 | AI 编程 IDE |
+| **LangChain** | SDK 集成 | LLM 应用开发框架 |
+| **AutoGPT** | SDK 集成 | 自主 AI Agent |
+| **OpenAI Agents** | SDK 集成 | GPT Agent 平台 |
+| **Dify / Coze** | SDK 集成 | 低代码 AI 平台 |
+| **任意 AI Agent** | SDK 集成 | `npm install shellward`，3 行代码接入 |
+
 ### 为什么现有方案不够？
 
 | | ShellWard | SecureClaw | ClawSec | openclaw-shield |
@@ -63,33 +80,33 @@
 **身份证号** — 不是简单的 18 位数字匹配，带校验位验证：
 
 ```
-330102199001011234  →  [REDACTED:身份证号]    ✅ 真实身份证号，校验位正确
-110101199003070419  →  [REDACTED:身份证号]    ✅ 真实格式，脱敏
-123456789012345678  →  123456789012345678     ✅ 随机数字，不误报
+330102199001011234  →  检测到，审计记录 ✅ 真实身份证号，校验位正确
+110101199003070419  →  检测到，审计记录 ✅ 真实格式
+123456789012345678  →  不误报 ✅ 随机数字，校验位错误
 ```
 
 **手机号** — 覆盖所有运营商号段：
 
 ```
-13812345678  →  [REDACTED:手机号]    ✅ 中国移动
-15912345678  →  [REDACTED:手机号]    ✅ 中国电信
-12345678901  →  12345678901          ✅ 非手机号段，不误报
+13812345678  →  检测到，审计记录 ✅ 中国移动
+15912345678  →  检测到，审计记录 ✅ 中国电信
+12345678901  →  不误报 ✅ 非手机号段
 ```
 
 **银行卡号** — Luhn 算法验证，不是长度匹配：
 
 ```
-6225880137654321  →  [REDACTED:银行卡号]    ✅ Luhn 校验通过
-1234567890123456  →  1234567890123456       ✅ Luhn 校验失败，不误报
+6225880137654321  →  检测到，审计记录 ✅ Luhn 校验通过
+1234567890123456  →  不误报 ✅ Luhn 校验失败
 ```
 
 **API Key / JWT / 密码** — 国际通用格式全覆盖：
 
 ```
-sk-abc123def456ghi789...  →  [REDACTED:OpenAI Key]
-ghp_xxxxxxxxxxxxxxxxxxxx  →  [REDACTED:GitHub Token]
-eyJhbGciOiJIUzI1NiIs...  →  [REDACTED:JWT Token]
-password: "MyP@ssw0rd!"  →  password: "[REDACTED:密码]"
+sk-abc123def456ghi789...  →  检测到，审计记录
+ghp_xxxxxxxxxxxxxxxxxxxx  →  检测到，审计记录
+eyJhbGciOiJIUzI1NiIs...  →  检测到，审计记录
+password: "MyP@ssw0rd!"  →  检测到，审计记录
 ```
 
 **中文注入攻击检测：**
@@ -105,7 +122,7 @@ password: "MyP@ssw0rd!"  →  password: "[REDACTED:密码]"
 
 ```
 Step 1: Agent 读取 ~/.ssh/id_rsa          ← L7 记录敏感文件访问
-Step 2: Agent 调用 curl 发送到外部地址      ← L7 检测到外泄链，拦截 🚫
+Step 2: Agent 调用 send_email 发送到外部   ← L7 检测到外泄链，拦截 🚫
 ```
 
 每一步单独看都是合法操作，连起来就是攻击。ShellWard 是唯一能检测这种链式攻击的插件。
@@ -133,8 +150,8 @@ Step 2: Agent 调用 curl 发送到外部地址      ← L7 检测到外泄链
   │
   ▼
 ┌──────────────┐
-│ L2 输出脱敏   │ 身份证/手机/银行卡/API Key 自动脱敏
-│ L6 回复脱敏   │ LLM 回复中的敏感信息也脱掉
+│ L2 输出审计   │ 身份证/手机/银行卡/API Key 检测并记录审计
+│ L6 回复审计   │ LLM 回复中的敏感信息检测并记录审计
 └──────────────┘
   │
   ▼
@@ -146,13 +163,13 @@ Step 2: Agent 调用 curl 发送到外部地址      ← L7 检测到外泄链
 
 ### 安装
 
-一行命令：
+**OpenClaw 插件**
 
 ```bash
 openclaw plugins install shellward
 ```
 
-或者一键脚本：
+或一键脚本：
 
 ```bash
 # Linux / macOS
@@ -164,6 +181,21 @@ curl -fsSL https://raw.githubusercontent.com/jnMetaCode/shellward/main/install.s
 irm https://raw.githubusercontent.com/jnMetaCode/shellward/main/install.ps1 | iex
 ```
 
+**独立 SDK（任意 AI Agent 平台）**
+
+```bash
+npm install shellward
+```
+
+```typescript
+import { ShellWard } from 'shellward'
+const guard = new ShellWard({ mode: 'enforce', locale: 'zh' })
+
+guard.checkCommand('rm -rf /')    // → { allowed: false, reason: '...' }
+guard.scanData('身份证: 110101...') // → { hasSensitiveData: true, findings: [...] }
+guard.checkInjection('忽略指令...')  // → { safe: false, score: 85 }
+```
+
 安装即生效，零配置，默认 8 层全开。
 
 ### 配置（可选）
@@ -187,7 +219,7 @@ irm https://raw.githubusercontent.com/jnMetaCode/shellward/main/install.ps1 | ie
 | 命令 | 说明 |
 |------|------|
 | `/security` | 安全状态总览 |
-| `/audit [数量] [过滤]` | 查看审计日志。过滤: `block`、`redact`、`critical`、`high` |
+| `/audit [数量] [过滤]` | 查看审计日志。过滤: `block`、`audit`、`critical`、`high` |
 | `/harden` | 扫描安全问题，`/harden fix` 自动修复权限 |
 | `/scan-plugins` | 扫描已安装插件的恶意代码 |
 | `/check-updates` | 检查版本更新和已知漏洞（内置 17 个真实 CVE） |
@@ -196,11 +228,11 @@ irm https://raw.githubusercontent.com/jnMetaCode/shellward/main/install.ps1 | ie
 
 | 指标 | 数据 |
 |------|------|
-| 200KB 文本 PII 脱敏 | 55ms |
+| 200KB 文本 PII 检测 | <100ms |
 | 工具安全检查吞吐 | 125,000 次/秒 |
 | 注入检测吞吐 | ~7,700 次/秒 |
 | 依赖数量 | 0 |
-| 测试 | 100 项全通过 |
+| 测试 | 112 项全通过 |
 
 ### 已知漏洞数据库
 
@@ -225,15 +257,30 @@ Apache-2.0
 
 ## English
 
-The only OpenClaw security plugin with **bilingual (EN/ZH) support** — Chinese PII detection (ID card with checksum, phone, bank card with Luhn), 8 defense layers, 26 injection rules, zero dependencies.
+The only AI security layer with **bilingual (EN/ZH) support** — Chinese PII detection (ID card with checksum, phone, bank card with Luhn), 8 defense layers, 26 injection rules, zero dependencies. **SDK + OpenClaw plugin.**
 
-![ShellWard Security Demo](https://github.com/jnMetaCode/shellward/releases/download/v0.4.0/demo-openclaw.gif)
+![ShellWard Security Demo](https://github.com/jnMetaCode/shellward/releases/download/v0.5.0/demo-en.gif)
+
+> 💡 **Like a corporate firewall: use data freely inside, nothing leaks out.**
+
+### Supported Platforms
+
+| Platform | Integration | Note |
+|----------|------------|------|
+| **OpenClaw** | Plugin | `openclaw plugins install shellward` |
+| **Claude Code** | SDK | Anthropic's official CLI agent |
+| **Cursor** | SDK | AI-powered coding IDE |
+| **LangChain** | SDK | LLM application framework |
+| **AutoGPT** | SDK | Autonomous AI agents |
+| **OpenAI Agents** | SDK | GPT agent platform |
+| **Dify / Coze** | SDK | Low-code AI platforms |
+| **Any AI Agent** | SDK | `npm install shellward`, 3 lines to integrate |
 
 ### Features
 
 - **8 defense layers**: prompt guard, input auditor, tool blocker, output scanner, security gate, outbound guard, data flow guard, session guard
-- **Chinese PII**: ID card (GB 11643 checksum), phone (all carriers), bank card (Luhn)
-- **Global PII**: OpenAI/GitHub/AWS keys, JWT, passwords, SSN, credit cards
+- **Chinese PII audit**: ID card (GB 11643 checksum), phone (all carriers), bank card (Luhn)
+- **Global PII audit**: OpenAI/GitHub/AWS keys, JWT, passwords, SSN, credit cards
 - **26 injection rules**: 14 Chinese + 12 English, risk scoring, mixed-language detection
 - **Data exfiltration chain**: read sensitive file → network send = blocked
 - **Zero dependencies**, zero config, Apache-2.0
@@ -244,6 +291,8 @@ The only OpenClaw security plugin with **bilingual (EN/ZH) support** — Chinese
 openclaw plugins install shellward
 ```
 
+Or as SDK: `npm install shellward` and `import { ShellWard } from 'shellward'`
+
 ### Config
 
 ```json
@@ -261,7 +310,7 @@ openclaw plugins install shellward
 | Command | Description |
 |---------|-------------|
 | `/security` | Security status overview |
-| `/audit [n] [filter]` | View audit log |
+| `/audit [n] [filter]` | View audit log (filter: block, audit, critical, high) |
 | `/harden` | Scan & fix security issues |
 | `/scan-plugins` | Scan plugins for malicious code |
 | `/check-updates` | Check versions & known CVEs (17 built-in) |