shellward 0.6.5 → 0.6.7

package/README.md

@@ -4,41 +4,52 @@
 
 # ShellWard
 
-**AI Agent Security & Compliance Gateway** — the AI agent security middleware built for **China's regulatory regime** (网安法 / PIPL / 等保2.0 / 数据出境 / AI标识). Scan your project for compliance risks, then block prompt injection, data exfiltration, and dangerous commands at runtime. Chinese-language threat detection + Chinese PII + zero dependencies — things English tools don't do.
+**AI 应用合规网关** — 为中国监管而生的 AI Agent 安全合规工具（网安法 2026 / PIPL / 等保2.0 / 数据出境 / AI标识）。先一行命令体检项目合规风险，再在运行时拦截提示注入、数据外泄与危险命令。中文威胁检测 + 中文 PII + 零依赖——英文工具不做的事。
 
 [![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-256%20passing-brightgreen)](#performance)
+[![tests](https://img.shields.io/badge/tests-263%20passing-brightgreen)](#performance)
 [![deps](https://img.shields.io/badge/dependencies-0-brightgreen)](#performance)
 
-**🌐 Website: https://jnmetacode.github.io/shellward/**
+**🌐 官网: https://jnmetacode.github.io/shellward/**
 
-[English](#demo) | [中文](#中文)
+[中文](#30-秒合规体检) | [English](#english)
 
-## 30-Second Compliance Scan
+## 30 秒合规体检
 
-Zero install, read-only, nothing uploaded. Scan your AI project for compliance risks right now:
+零安装、只读、不上传任何数据。一行命令，扫出你的 AI 项目踩了哪些合规红线：
 
 ```bash
 npx shellward scan
 ```
 
-Outputs a red/yellow/green scorecard mapped to 网安法 / PIPL / 等保2.0 / 数据出境 / AI标识, plus the concrete `file:line` findings in your project:
+输出一张映射到 **网安法 / PIPL / 等保2.0 / 数据出境 / AI标识** 的红黄绿评分卡，并精确到 `文件:行`：
 
 ```
 ## 🔍 项目实测风险
 🌐 数据出境风险: 2 ｜ 🔑 硬编码密钥: 3 ｜ 🪪 个人信息暴露: 2 ｜ 📂 .env 权限: 1
 
 - .env:2          境外大模型端点: OpenAI — 向其发送个人信息即构成数据出境
+- package.json:12 境外大模型 SDK 依赖: openai — 项目内含数据出境通道
 - src/config.ts:3 硬编码 GitHub Token: ghp_12*** — 凭据不应写入源码
 - customers.csv:2 手机号 13912*** — 个人信息出现在文件中，需评估脱敏
 
-合规得分: 75/100  [B]   🟢 8 ｜ 🟡 3 ｜ 🔴 1 ｜ ⚪ 2
+合规得分: 63/100  [C]
 ```
 
-`npx shellward scan --json` for CI · `--ci` to fail the build on critical findings · `--html report.html` for a self-contained report you can print to PDF for 备案/audit · see [GitHub Action](#github-action-pr-compliance-gate).
+`--json` 供 CI · `--ci` 发现 critical 时让构建失败 · `--html report.html` 导出可打印成 PDF 的报告（备案/审计存档）· 也可作 [GitHub Action](#github-action-pr-compliance-gate) 接入 PR 门禁。
+
+> 检测重点：**境外大模型端点与 SDK 依赖（数据出境——中国独有、英文工具没有的概念）**、硬编码密钥、文件中的中文 PII、`.env` 暴露。扫到境外模型（如 `openai` 依赖）时，**直接给出境内合规替代**（通义千问 / DeepSeek / Kimi / 智谱）及其 OpenAI 兼容 `base_url`——多数迁移只需改一个 `base_url`。
+
+更多命令、运行时防护（MCP / 插件）、与英文文档见下方 [English](#english) 章节。
+
+---
+
+## English
+
+**AI Agent Security & Compliance Gateway** — the AI agent security middleware built for **China's regulatory regime** (CSL / PIPL / MLPS 2.0 / cross-border data / AI labeling). Scan your project for compliance risks, then block prompt injection, data exfiltration, and dangerous commands at runtime. Chinese-language threat detection + Chinese PII + zero dependencies — things English tools don't do.
 
-> Detects overseas-LLM endpoints (**data-export risk** — a China-only concept English tools ignore), hardcoded secrets, Chinese PII in files, and `.env` exposure. When it finds an overseas model (e.g. an `openai` dependency), it **prescribes domestic compliant alternatives** (通义千问 / DeepSeek / Kimi / 智谱) with their OpenAI-compatible `base_url` — most migrations are just a `base_url` swap.
+Quick start: `npx shellward scan` — zero install, read-only, nothing uploaded. Outputs a red/yellow/green scorecard mapped to Chinese regulations plus concrete `file:line` findings, and prescribes domestic compliant model alternatives for any overseas LLM it finds.
 
 ## Demo
 

package/dist/cli.js

@@ -95,8 +95,8 @@ function runScan(args) {
                 body,
                 '',
                 zh
-                    ? '💡 这是只读扫描，未上传任何数据。要在运行时自动拦截风险，把 ShellWard 作为 MCP/插件接入你的 AI Agent。'
-                    : '💡 Read-only scan, nothing uploaded. To block these risks at runtime, integrate ShellWard as an MCP server/plugin in your AI agent.',
+                    ? '💡 只读扫描、不上传任何数据。得分仅反映本次可静态观测的项目风险；⚪ 待确认项需把 ShellWard 作为 MCP/插件部署为运行时防护，或人工核验后才能满足。'
+                    : '💡 Read-only scan, nothing uploaded. The score reflects only statically-observable project risk; ⚪ items require deploying ShellWard as a runtime guard (MCP/plugin) or manual review.',
             ];
             process.stdout.write(out.join('\n') + '\n');
         }

package/dist/compliance/audit.d.ts

@@ -39,12 +39,21 @@ export interface ComplianceReport {
 }
 /** 采集真实环境事实（运行时调用；测试可绕过直接注入 EnvFacts） */
 export declare function gatherEnvFacts(): EnvFacts;
+export interface AuditOptions {
+    /**
+     * ShellWard 是否作为运行时防护已部署。
+     * - true（默认）：MCP / 插件上下文，能力层确实在运行，如实评估
+     * - false：CLI 静态扫描，未部署运行时 —— 能力/审计类控制项标为顾问态，不虚报"已启用"
+     */
+    deployed?: boolean;
+}
 /**
  * 运行合规体检。
  * @param config ShellWard 当前配置
  * @param facts  环境事实；不传则从真实环境采集
+ * @param opts   评估上下文（是否已部署运行时）
  */
-export declare function runComplianceAudit(config: ShellWardConfig, facts?: EnvFacts): ComplianceReport;
+export declare function runComplianceAudit(config: ShellWardConfig, facts?: EnvFacts, opts?: AuditOptions): ComplianceReport;
 export interface ProjectComplianceResult {
     report: ComplianceReport;
     scan: ProjectScanResult;

package/dist/compliance/audit.js

@@ -67,10 +67,12 @@ function extractTs(line) {
  * 运行合规体检。
  * @param config ShellWard 当前配置
  * @param facts  环境事实；不传则从真实环境采集
+ * @param opts   评估上下文（是否已部署运行时）
  */
-export function runComplianceAudit(config, facts) {
+export function runComplianceAudit(config, facts, opts) {
     const env = facts ?? gatherEnvFacts();
-    const results = COMPLIANCE_CONTROLS.map(c => checkControl(c, config, env));
+    const deployed = opts?.deployed ?? true;
+    const results = COMPLIANCE_CONTROLS.map(c => checkControl(c, config, env, deployed));
     let passed = 0, warned = 0, failed = 0, manual = 0;
     for (const r of results) {
         if (r.status === 'pass')
@@ -116,7 +118,8 @@ export function runProjectComplianceAudit(config, root) {
             provider_en: f.provider_en,
         });
     }
-    const report = runComplianceAudit(config, env);
+    // CLI 静态扫描：未部署运行时 → 能力/审计类不虚报"已启用"，只如实评估项目证据
+    const report = runComplianceAudit(config, env, { deployed: false });
     // 发现驱动评分：项目实测风险按严重度扣分（封顶 40），使分数反映"你的真实风险"
     const penalty = computeProjectPenalty(scan);
     if (penalty > 0) {
@@ -134,7 +137,11 @@ function computeProjectPenalty(scan) {
         p += FINDING_PENALTY[f.severity];
     return Math.min(MAX_PROJECT_PENALTY, p);
 }
-function checkControl(c, config, env) {
+function checkControl(c, config, env, deployed) {
+    // 静态扫描（未部署运行时）下，能力层/审计日志类控制项无法验证 —— 标为顾问态，绝不虚报"已合规"
+    if (!deployed && (c.method === 'capability' || c.method === 'config' || c.method === 'audit')) {
+        return mk(c, 'manual', `ShellWard 运行时可提供此防护；当前为静态扫描、未部署，无法验证。整改：${c.remediation_zh}`, `Provided by ShellWard runtime; not verifiable in a static scan. ${c.remediation_en}`);
+    }
     switch (c.method) {
         case 'capability': return checkCapability(c, config);
         case 'config': return checkConfig(c, config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellward",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "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, Hermes Agent.",
   "keywords": [

package/src/cli.ts

@@ -103,8 +103,8 @@ function runScan(args: string[]) {
         body,
         '',
         zh
-          ? '💡 这是只读扫描，未上传任何数据。要在运行时自动拦截风险，把 ShellWard 作为 MCP/插件接入你的 AI Agent。'
-          : '💡 Read-only scan, nothing uploaded. To block these risks at runtime, integrate ShellWard as an MCP server/plugin in your AI agent.',
+          ? '💡 只读扫描、不上传任何数据。得分仅反映本次可静态观测的项目风险；⚪ 待确认项需把 ShellWard 作为 MCP/插件部署为运行时防护，或人工核验后才能满足。'
+          : '💡 Read-only scan, nothing uploaded. The score reflects only statically-observable project risk; ⚪ items require deploying ShellWard as a runtime guard (MCP/plugin) or manual review.',
       ]
       process.stdout.write(out.join('\n') + '\n')
     }

package/src/compliance/audit.ts

@@ -113,14 +113,25 @@ function extractTs(line: string): string | undefined {
   return m?.[1]
 }
 
+export interface AuditOptions {
+  /**
+   * ShellWard 是否作为运行时防护已部署。
+   * - true（默认）：MCP / 插件上下文，能力层确实在运行，如实评估
+   * - false：CLI 静态扫描，未部署运行时 —— 能力/审计类控制项标为顾问态，不虚报"已启用"
+   */
+  deployed?: boolean
+}
+
 /**
  * 运行合规体检。
  * @param config ShellWard 当前配置
  * @param facts  环境事实；不传则从真实环境采集
+ * @param opts   评估上下文（是否已部署运行时）
  */
-export function runComplianceAudit(config: ShellWardConfig, facts?: EnvFacts): ComplianceReport {
+export function runComplianceAudit(config: ShellWardConfig, facts?: EnvFacts, opts?: AuditOptions): ComplianceReport {
   const env = facts ?? gatherEnvFacts()
-  const results: ControlResult[] = COMPLIANCE_CONTROLS.map(c => checkControl(c, config, env))
+  const deployed = opts?.deployed ?? true
+  const results: ControlResult[] = COMPLIANCE_CONTROLS.map(c => checkControl(c, config, env, deployed))
 
   let passed = 0, warned = 0, failed = 0, manual = 0
   for (const r of results) {
@@ -170,7 +181,8 @@ export function runProjectComplianceAudit(config: ShellWardConfig, root: string)
     })
   }
 
-  const report = runComplianceAudit(config, env)
+  // CLI 静态扫描：未部署运行时 → 能力/审计类不虚报"已启用"，只如实评估项目证据
+  const report = runComplianceAudit(config, env, { deployed: false })
 
   // 发现驱动评分：项目实测风险按严重度扣分（封顶 40），使分数反映"你的真实风险"
   const penalty = computeProjectPenalty(scan)
@@ -192,7 +204,13 @@ function computeProjectPenalty(scan: ProjectScanResult): number {
   return Math.min(MAX_PROJECT_PENALTY, p)
 }
 
-function checkControl(c: ComplianceControl, config: ShellWardConfig, env: EnvFacts): ControlResult {
+function checkControl(c: ComplianceControl, config: ShellWardConfig, env: EnvFacts, deployed: boolean): ControlResult {
+  // 静态扫描（未部署运行时）下，能力层/审计日志类控制项无法验证 —— 标为顾问态，绝不虚报"已合规"
+  if (!deployed && (c.method === 'capability' || c.method === 'config' || c.method === 'audit')) {
+    return mk(c, 'manual',
+      `ShellWard 运行时可提供此防护；当前为静态扫描、未部署，无法验证。整改：${c.remediation_zh}`,
+      `Provided by ShellWard runtime; not verifiable in a static scan. ${c.remediation_en}`)
+  }
   switch (c.method) {
     case 'capability': return checkCapability(c, config)
     case 'config':     return checkConfig(c, config)