shellward 0.6.1 → 0.6.3

package/README.md

@@ -4,17 +4,40 @@
 
 # ShellWard
 
-**AI Agent Security Middleware** — Protect AI agents from prompt injection, data exfiltration, and dangerous command execution. ShellWard acts as an LLM security middleware and AI agent firewall, intercepting tool calls at runtime to enforce agent guardrails before damage is done.
-
-8-layer defense-in-depth, DLP-style data flow control, zero dependencies. Works as **standalone SDK** or **OpenClaw plugin**.
+**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.
 
 [![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-183%20passing-brightgreen)](#performance)
+[![tests](https://img.shields.io/badge/tests-242%20passing-brightgreen)](#performance)
 [![deps](https://img.shields.io/badge/dependencies-0-brightgreen)](#performance)
 
 [English](#demo) | [中文](#中文)
 
+## 30-Second Compliance Scan
+
+Zero install, read-only, nothing uploaded. Scan your AI project for compliance risks right now:
+
+```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:
+
+```
+## 🔍 项目实测风险
+🌐 数据出境风险: 2 ｜ 🔑 硬编码密钥: 3 ｜ 🪪 个人信息暴露: 2 ｜ 📂 .env 权限: 1
+
+- .env:2          境外大模型端点: OpenAI — 向其发送个人信息即构成数据出境
+- src/config.ts:3 硬编码 GitHub Token: ghp_12*** — 凭据不应写入源码
+- customers.csv:2 手机号 13912*** — 个人信息出现在文件中，需评估脱敏
+
+合规得分: 75/100  [B]   🟢 8 ｜ 🟡 3 ｜ 🔴 1 ｜ ⚪ 2
+```
+
+`npx shellward scan --json` for CI · `--ci` to fail the build on critical findings · see [GitHub Action](#github-action-pr-compliance-gate).
+
+> 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.
+
 ## Demo
 
 ![ShellWard AI agent firewall demo — blocking prompt injection, data exfiltration, and reverse shell attacks in real time](https://github.com/jnMetaCode/shellward/releases/download/v0.5.0/demo-en.gif)
@@ -113,6 +136,7 @@ If installed globally (`npm i -g shellward`), simply use `"command": "shellward-
 | `check_response` | Audit AI response for canary leaks & PII exposure |
 | `scan_mcp_tool` | Scan an MCP tool definition for poisoning + rug-pull |
 | `security_status` | Get current security config & active layers |
+| `compliance_check` | 🆕 Run a China AI-compliance health check (网安法/PIPL/等保/出境/标识) → red/yellow/green scorecard |
 
 **Environment variables:**
 
@@ -155,6 +179,27 @@ openclaw plugins install shellward
 
 Zero config, 8 layers active by default.
 
+## GitHub Action (PR Compliance Gate)
+
+Block hardcoded secrets and overseas-LLM data-export risk before they merge. Add to `.github/workflows/compliance.yml`:
+
+```yaml
+name: Compliance Scan
+on: [push, pull_request]
+jobs:
+  compliance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: jnMetaCode/shellward@main
+        with:
+          path: '.'
+          fail-on-critical: 'true'   # fail the build on critical findings
+          locale: 'zh'               # auto | zh | en
+```
+
+Or run it directly without the Action: `npx shellward scan --ci`.
+
 ## 8-Layer Defense
 
 ```
@@ -298,6 +343,7 @@ Invalid regexes are skipped (never throws), so user input can't break the guard.
 
 | Command | Description |
 |---------|-------------|
+| `/compliance` | 🆕 AI compliance scorecard (网安法/PIPL/等保/出境/标识) |
 | `/security` | Security status overview |
 | `/audit [n] [filter]` | View audit log (filter: block, audit, critical, high) |
 | `/harden` | Scan & fix security issues |
@@ -372,7 +418,34 @@ ShellWard is built for teams that need runtime security for AI agents — whethe
 
 ## 中文
 
-**AI Agent 安全中间件** — 保护 AI 代理免受提示词注入、数据泄露、危险命令执行。8 层纵深防御，零依赖。
+**AI Agent 安全 · 合规网关** — 唯一为中国监管（网安法 / PIPL / 等保2.0 / 数据出境 / AI标识 GB45438）和中文语境而生的 AI Agent 安全中间件。先一键体检项目合规风险，再在运行时拦截提示注入、数据外泄与危险命令。中文威胁检测 + 中文 PII + 零依赖——英文工具不做的事。
+
+### 30 秒合规体检
+
+零安装、只读、不上传任何数据。现在就扫你的 AI 项目：
+
+```bash
+npx shellward scan
+```
+
+输出一张映射到 **网安法 / PIPL / 等保2.0 / 数据出境 / AI标识** 的红黄绿评分卡，并列出项目里 `文件:行` 级别的真实风险：
+
+```
+## 🔍 项目实测风险
+🌐 数据出境风险: 2 ｜ 🔑 硬编码密钥: 3 ｜ 🪪 个人信息暴露: 2 ｜ 📂 .env 权限: 1
+
+- .env:2          境外大模型端点: OpenAI — 向其发送个人信息即构成数据出境
+- src/config.ts:3 硬编码 GitHub Token: ghp_12*** — 凭据不应写入源码
+- customers.csv:2 手机号 13912*** — 个人信息出现在文件中，需评估脱敏
+
+合规得分: 75/100  [B]   🟢 8 ｜ 🟡 3 ｜ 🔴 1 ｜ ⚪ 2
+```
+
+`--json` 供 CI 消费 · `--ci` 发现 critical 时让构建失败 · 也可作 [GitHub Action](#github-action-pr-compliance-gate) 接入 PR 门禁。
+
+> **检测重点**：境外大模型端点（**数据出境风险** — 中国独有、英文工具没有这个概念）、硬编码密钥、文件中的中文 PII、`.env` 暴露。命令形态 `/compliance`，MCP 工具 `compliance_check`。
+
+---
 
 ![ShellWard AI Agent 安全防火墙演示 — 拦截提示词注入、数据泄露和反弹Shell攻击](https://github.com/jnMetaCode/shellward/releases/download/v0.5.0/demo-zh.gif)
 

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// src/cli.ts — ShellWard CLI 入口（零安装合规体检）
+//
+//   npx shellward            → 扫描当前项目，输出合规体检评分卡
+//   npx shellward scan [dir] → 同上，可指定目录
+//   npx shellward scan --json→ 输出 JSON（CI 用）
+//   npx shellward mcp        → 启动 MCP 服务器（stdio，向后兼容）
+//   npx shellward --help
+//
+// 设计目标：30 秒、零配置、出一张可截图的「你的项目」合规风险报告。
+import { resolve } from 'path';
+import { writeFileSync } from 'fs';
+import { ShellWard } from './core/engine.js';
+import { runProjectComplianceAudit } from './compliance/audit.js';
+import { renderComplianceReport, renderProjectFindings } from './compliance/report.js';
+import { resolveLocale } from './types.js';
+const argv = process.argv.slice(2);
+const wantsHelp = argv.includes('--help') || argv.includes('-h') || argv[0] === 'help';
+const cmd = argv[0] && !argv[0].startsWith('-') ? argv[0] : 'scan';
+async function main() {
+    if (wantsHelp) {
+        printHelp();
+        return;
+    }
+    if (cmd === 'mcp') {
+        // 转发到 MCP 服务器（import 即启动 stdio 循环）
+        await import('./mcp-server.js');
+        return;
+    }
+    if (cmd === 'scan') {
+        runScan(argv.slice(1));
+        return;
+    }
+    console.error(`未知命令: ${cmd}\n`);
+    printHelp();
+    process.exit(2);
+}
+function runScan(args) {
+    const json = args.includes('--json');
+    const ci = args.includes('--ci');
+    const outPath = flagValue(args, '--out');
+    const dirArg = args.find(a => !a.startsWith('-'));
+    const root = resolve(dirArg || process.cwd());
+    // 用环境变量解析 locale；layers/mode 用默认（代表「采用 ShellWard 默认部署」的合规覆盖）
+    const guard = new ShellWard({
+        locale: process.env.SHELLWARD_LOCALE || 'auto',
+        mode: process.env.SHELLWARD_MODE || 'enforce',
+        autoCheckOnStartup: false,
+    });
+    const locale = resolveLocale(guard.config);
+    const zh = locale === 'zh';
+    const { report, scan } = runProjectComplianceAudit(guard.config, root);
+    if (json) {
+        process.stdout.write(JSON.stringify({
+            root,
+            score: report.score,
+            grade: report.grade,
+            summary: { passed: report.passed, warned: report.warned, failed: report.failed, manual: report.manual },
+            projectScan: {
+                filesScanned: scan.filesScanned,
+                truncated: scan.truncated,
+                counts: scan.counts,
+                findings: scan.findings,
+            },
+            controls: report.results.map(r => ({
+                id: r.control.id, regulation: r.control.regulation, status: r.status,
+            })),
+        }, null, 2) + '\n');
+    }
+    else {
+        // 头条：项目实测风险（关于「你的项目」）+ 合规映射评分卡
+        const body = [
+            renderProjectFindings(scan, locale),
+            renderComplianceReport(report, locale),
+        ].join('\n');
+        if (outPath) {
+            const doc = `<!-- 扫描目录: ${root} -->\n\n` + body + '\n';
+            writeFileSync(resolve(outPath), doc, 'utf-8');
+            process.stdout.write(zh
+                ? `✅ 合规报告已导出: ${resolve(outPath)}\n   得分 ${report.score}/100 [${report.grade}]，可存档用于备案/审计。\n`
+                : `✅ Compliance report exported: ${resolve(outPath)}\n   Score ${report.score}/100 [${report.grade}].\n`);
+        }
+        else {
+            const out = [
+                zh ? `\n扫描目录: ${root}\n` : `\nScanned: ${root}\n`,
+                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.',
+            ];
+            process.stdout.write(out.join('\n') + '\n');
+        }
+    }
+    // CI 模式：有 critical 项目发现则非零退出
+    if (ci) {
+        const criticals = scan.findings.filter(f => f.severity === 'critical').length;
+        if (criticals > 0)
+            process.exit(1);
+    }
+}
+/** 取 `--flag value` 或 `--flag=value` 的值 */
+function flagValue(args, flag) {
+    const i = args.indexOf(flag);
+    if (i >= 0 && args[i + 1] && !args[i + 1].startsWith('-'))
+        return args[i + 1];
+    const eq = args.find(a => a.startsWith(flag + '='));
+    return eq ? eq.slice(flag.length + 1) : undefined;
+}
+function printHelp() {
+    const lang = (process.env.SHELLWARD_LOCALE === 'en') ? 'en' : 'zh';
+    if (lang === 'en') {
+        console.log(`ShellWard — AI compliance gateway
+
+Usage:
+  shellward [scan] [dir]   Scan a project for compliance risks (default)
+  shellward scan --json    Output JSON (for CI)
+  shellward scan --ci      Exit non-zero if critical findings
+  shellward scan --out f   Export the full report to a Markdown file
+  shellward mcp            Start MCP server (stdio)
+  shellward --help
+
+Detects: overseas LLM endpoints (data-export risk), hardcoded secrets,
+PII in files, .env permissions. Maps to CSL / PIPL / MLPS / cross-border / labeling.`);
+    }
+    else {
+        console.log(`ShellWard — AI 合规网关
+
+用法:
+  shellward [scan] [目录]   扫描项目的合规风险（默认命令）
+  shellward scan --json     输出 JSON（CI 用）
+  shellward scan --ci       有 critical 发现时非零退出
+  shellward scan --out 文件  导出完整报告为 Markdown（合规存档）
+  shellward mcp             启动 MCP 服务器（stdio）
+  shellward --help
+
+检测: 境外大模型端点(数据出境)、硬编码密钥、文件中的个人信息、.env 权限。
+映射到 网安法 / PIPL / 等保2.0 / 数据出境 / AI标识。`);
+    }
+}
+main().catch(err => {
+    console.error(`[ShellWard] ${err?.message || err}`);
+    process.exit(1);
+});

package/dist/commands/compliance.d.ts

@@ -0,0 +1,2 @@
+import type { ShellWardConfig } from '../types.js';
+export declare function registerComplianceCommand(api: any, config: ShellWardConfig): void;

package/dist/commands/compliance.js

@@ -0,0 +1,21 @@
+// src/commands/compliance.ts — /compliance 命令：一键合规体检报告
+//
+// 月1 获客钩子的命令形态。扫一遍配置 + 环境 + 审计日志 + 出境端点，
+// 输出网安法/PIPL/等保/数据出境/AI标识 的红黄绿合规评分卡。
+import { resolveLocale } from '../types.js';
+import { runComplianceAudit } from '../compliance/audit.js';
+import { renderComplianceReport } from '../compliance/report.js';
+export function registerComplianceCommand(api, config) {
+    const locale = resolveLocale(config);
+    api.registerCommand({
+        name: 'compliance',
+        description: locale === 'zh'
+            ? '📋 AI 应用合规体检（网安法/PIPL/等保/数据出境/AI标识）'
+            : '📋 AI compliance health check (CSL/PIPL/MLPS/Cross-border/Labeling)',
+        acceptsArgs: false,
+        handler: () => {
+            const report = runComplianceAudit(config);
+            return { text: renderComplianceReport(report, locale) };
+        },
+    });
+}

package/dist/commands/index.js

@@ -7,6 +7,7 @@ import { registerScanPluginsCommand } from './scan-plugins.js';
 import { registerScanMcpCommand } from './scan-mcp.js';
 import { registerCheckUpdatesCommand } from './check-updates.js';
 import { registerUpgradeOpenClawCommand } from './upgrade-openclaw.js';
+import { registerComplianceCommand } from './compliance.js';
 /** @returns number of registered commands (for the startup log). */
 export function registerAllCommands(api, config) {
     const locale = resolveLocale(config);
@@ -18,6 +19,7 @@ export function registerAllCommands(api, config) {
     registerScanMcpCommand(api, config);
     registerCheckUpdatesCommand(api, config);
     registerUpgradeOpenClawCommand(api, config);
+    registerComplianceCommand(api, config);
     // Register /cg shortcut with help
     api.registerCommand({
         name: 'cg',
@@ -30,6 +32,7 @@ export function registerAllCommands(api, config) {
 
 | 命令 | 说明 |
 |------|------|
+| \`/compliance\` | 🆕 AI 合规体检（网安法/PIPL/等保/数据出境/AI标识 红黄绿评分卡） |
 | \`/security\` | 安全状态总览（防御层、审计统计、系统检查） |
 | \`/audit [数量] [过滤]\` | 查看审计日志 (过滤: block/audit/critical/high) |
 | \`/harden\` | 安全扫描 · \`/harden fix\` 自动修复权限 |
@@ -45,6 +48,7 @@ L5 安全门 · L6 回复审计 · L7 数据流监控 · L8 会话安全`
 
 | Command | Description |
 |---------|-------------|
+| \`/compliance\` | 🆕 AI compliance check (CSL/PIPL/MLPS/cross-border/labeling scorecard) |
 | \`/security\` | Security status overview (layers, audit stats, system checks) |
 | \`/audit [count] [filter]\` | View audit log (filter: block/audit/critical/high) |
 | \`/harden\` | Security scan · \`/harden fix\` to auto-fix permissions |
@@ -58,6 +62,6 @@ L1 Prompt Guard · L2 Output Scanner · L3 Tool Blocker · L4 Input Auditor
 L5 Security Gate · L6 Outbound Guard · L7 Data Flow Guard · L8 Session Guard`,
         }),
     });
-    // 7 individual commands + /cg help
-    return 8;
+    // 8 individual commands + /cg help
+    return 9;
 }

package/dist/compliance/audit.d.ts

@@ -0,0 +1,57 @@
+import type { OverseasMatch } from '../rules/overseas-llm.js';
+import type { ProjectScanResult } from './project-scan.js';
+import type { ComplianceControl, Regulation } from './regulations.js';
+import type { ShellWardConfig } from '../types.js';
+export type ControlStatus = 'pass' | 'warn' | 'fail' | 'manual';
+export interface ControlResult {
+    control: ComplianceControl;
+    status: ControlStatus;
+    detail_zh: string;
+    detail_en: string;
+}
+export interface AuditLogFacts {
+    exists: boolean;
+    entryCount: number;
+    /** 最早一条记录时间戳 (ISO)，用于判断是否覆盖 6 个月留存 */
+    oldestTs?: string;
+    newestTs?: string;
+}
+export interface EnvFacts {
+    isRoot: boolean;
+    auditLog: AuditLogFacts;
+    /** 从环境/配置中探测到的境外大模型端点 */
+    overseas: OverseasMatch[];
+}
+export interface ComplianceReport {
+    /** 0-100 合规得分 */
+    score: number;
+    /** 总评级 */
+    grade: 'A' | 'B' | 'C' | 'D';
+    passed: number;
+    warned: number;
+    failed: number;
+    manual: number;
+    total: number;
+    results: ControlResult[];
+    generatedAt: string;
+    /** 项目实测风险造成的扣分（仅项目体检路径）；0 表示纯控制项评分 */
+    projectPenalty?: number;
+}
+/** 采集真实环境事实（运行时调用；测试可绕过直接注入 EnvFacts） */
+export declare function gatherEnvFacts(): EnvFacts;
+/**
+ * 运行合规体检。
+ * @param config ShellWard 当前配置
+ * @param facts  环境事实；不传则从真实环境采集
+ */
+export declare function runComplianceAudit(config: ShellWardConfig, facts?: EnvFacts): ComplianceReport;
+export interface ProjectComplianceResult {
+    report: ComplianceReport;
+    scan: ProjectScanResult;
+}
+/**
+ * 面向真实项目的体检：扫描项目目录的真实风险，并入评分，再跑控制项体检。
+ * 这是 CLI (`shellward scan`) 的入口 —— 报告关于「用户项目」而非「ShellWard 开关」。
+ */
+export declare function runProjectComplianceAudit(config: ShellWardConfig, root: string): ProjectComplianceResult;
+export type { Regulation };

package/dist/compliance/audit.js

@@ -0,0 +1,234 @@
+// src/compliance/audit.ts — 合规体检引擎
+//
+// 跑遍 COMPLIANCE_CONTROLS，对每个控制项给出 pass / warn / fail / manual，
+// 汇总成红黄绿评分卡。这是「一键合规体检报告」(月1 获客钩子) 的核心。
+//
+// 设计为可注入 (EnvFacts)：测试可直接喂事实，运行时则从真实环境采集。
+import { readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { getHomeDir } from '../utils.js';
+import { detectOverseasLLM } from '../rules/overseas-llm.js';
+import { scanProject } from './project-scan.js';
+import { COMPLIANCE_CONTROLS } from './regulations.js';
+const LOG_FILE = join(getHomeDir(), '.openclaw', 'shellward', 'audit.jsonl');
+const SIX_MONTHS_MS = 182 * 24 * 60 * 60 * 1000;
+/** 层能力映射：控制项 id → 必须启用的层（全部启用才 pass，部分启用 warn，全关 fail） */
+const CAPABILITY_LAYERS = {
+    'csl-content-block': ['outputScanner', 'outboundGuard'],
+    'csl-intrusion': ['inputAuditor', 'toolBlocker'],
+    'pipl-spi-detect': ['outputScanner'],
+    'pipl-minimize': ['dataFlowGuard'],
+    'pipl-auto-decision': ['securityGate'],
+    'mlps-access-control': ['securityGate'],
+    'cbdt-redact-before-export': ['dataFlowGuard'],
+};
+/** 采集真实环境事实（运行时调用；测试可绕过直接注入 EnvFacts） */
+export function gatherEnvFacts() {
+    // 1. root 检测
+    const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
+    // 2. 审计日志事实
+    const auditLog = readAuditLogFacts();
+    // 3. 出境端点探测：扫描常见环境变量中的 base_url / 端点
+    const overseas = [];
+    const seen = new Set();
+    for (const [k, v] of Object.entries(process.env)) {
+        if (!v)
+            continue;
+        if (!/(_BASE_URL|_API_BASE|_ENDPOINT|_URL|OPENAI|ANTHROPIC|GEMINI|LLM)/i.test(k))
+            continue;
+        const m = detectOverseasLLM(v);
+        if (m.isOverseas && m.endpointId && !seen.has(m.endpointId)) {
+            seen.add(m.endpointId);
+            overseas.push(m);
+        }
+    }
+    return { isRoot, auditLog, overseas };
+}
+function readAuditLogFacts() {
+    try {
+        statSync(LOG_FILE);
+        const content = readFileSync(LOG_FILE, 'utf-8');
+        const lines = content.trim().split('\n').filter(Boolean);
+        if (lines.length === 0)
+            return { exists: true, entryCount: 0 };
+        const firstTs = extractTs(lines[0]);
+        const lastTs = extractTs(lines[lines.length - 1]);
+        return { exists: true, entryCount: lines.length, oldestTs: firstTs, newestTs: lastTs };
+    }
+    catch {
+        return { exists: false, entryCount: 0 };
+    }
+}
+function extractTs(line) {
+    const m = line.match(/"ts":"([^"]+)"/);
+    return m?.[1];
+}
+/**
+ * 运行合规体检。
+ * @param config ShellWard 当前配置
+ * @param facts  环境事实；不传则从真实环境采集
+ */
+export function runComplianceAudit(config, facts) {
+    const env = facts ?? gatherEnvFacts();
+    const results = COMPLIANCE_CONTROLS.map(c => checkControl(c, config, env));
+    let passed = 0, warned = 0, failed = 0, manual = 0;
+    for (const r of results) {
+        if (r.status === 'pass')
+            passed++;
+        else if (r.status === 'warn')
+            warned++;
+        else if (r.status === 'fail')
+            failed++;
+        else
+            manual++;
+    }
+    const score = computeScore(results);
+    return {
+        score,
+        grade: gradeOf(score),
+        passed, warned, failed, manual,
+        total: results.length,
+        results,
+        generatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * 面向真实项目的体检：扫描项目目录的真实风险，并入评分，再跑控制项体检。
+ * 这是 CLI (`shellward scan`) 的入口 —— 报告关于「用户项目」而非「ShellWard 开关」。
+ */
+export function runProjectComplianceAudit(config, root) {
+    const scan = scanProject(root);
+    const env = gatherEnvFacts();
+    // 把文件中实测到的境外端点/依赖并入 facts（按 endpointId 或 provider 去重），
+    // 使数据出境项基于真实证据（含 SDK 依赖通道）
+    const seen = new Set(env.overseas.map(o => o.endpointId || o.provider_en));
+    for (const f of scan.findings) {
+        if (f.kind !== 'overseas')
+            continue;
+        const key = f.endpointId || f.provider_en || '';
+        if (!key || seen.has(key))
+            continue;
+        seen.add(key);
+        env.overseas.push({
+            isOverseas: true,
+            endpointId: f.endpointId,
+            provider_zh: f.provider_zh,
+            provider_en: f.provider_en,
+        });
+    }
+    const report = runComplianceAudit(config, env);
+    // 发现驱动评分：项目实测风险按严重度扣分（封顶 40），使分数反映"你的真实风险"
+    const penalty = computeProjectPenalty(scan);
+    if (penalty > 0) {
+        report.score = Math.max(0, report.score - penalty);
+        report.grade = gradeOf(report.score);
+        report.projectPenalty = penalty;
+    }
+    return { report, scan };
+}
+const FINDING_PENALTY = { critical: 8, high: 4, medium: 1 };
+const MAX_PROJECT_PENALTY = 40;
+function computeProjectPenalty(scan) {
+    let p = 0;
+    for (const f of scan.findings)
+        p += FINDING_PENALTY[f.severity];
+    return Math.min(MAX_PROJECT_PENALTY, p);
+}
+function checkControl(c, config, env) {
+    switch (c.method) {
+        case 'capability': return checkCapability(c, config);
+        case 'config': return checkConfig(c, config);
+        case 'audit': return checkAudit(c, env);
+        case 'env': return checkEnv(c, env);
+        case 'manual': return mk(c, 'manual', '需人工确认 / 路线图功能：' + c.remediation_zh, 'Manual / roadmap: ' + c.remediation_en);
+    }
+}
+function checkCapability(c, config) {
+    const required = CAPABILITY_LAYERS[c.id];
+    if (!required) {
+        // 未显式映射的能力项：以 enforce 模式作为兜底信号
+        return config.mode === 'enforce'
+            ? mk(c, 'pass', '能力已启用 (enforce 模式)', 'Capability active (enforce mode)')
+            : mk(c, 'warn', 'audit 模式仅记录不拦截，建议切换 enforce', 'Audit mode logs only; switch to enforce');
+    }
+    const on = required.filter(l => config.layers[l]);
+    if (on.length === required.length) {
+        const tail = config.mode === 'enforce' ? '' : '（注意：audit 模式仅记录不拦截）';
+        return mk(c, config.mode === 'enforce' ? 'pass' : 'warn', `已启用: ${required.join(', ')}${tail}`, `Enabled: ${required.join(', ')}${config.mode === 'enforce' ? '' : ' (audit mode: log-only)'}`);
+    }
+    if (on.length > 0) {
+        return mk(c, 'warn', `部分启用: ${on.join(', ')}；缺少: ${required.filter(l => !on.includes(l)).join(', ')}`, `Partially enabled; missing: ${required.filter(l => !on.includes(l)).join(', ')}`);
+    }
+    return mk(c, 'fail', `未启用: ${required.join(', ')}`, `Not enabled: ${required.join(', ')}`);
+}
+function checkConfig(c, config) {
+    return config.mode === 'enforce'
+        ? mk(c, 'pass', 'enforce 模式', 'enforce mode')
+        : mk(c, 'warn', 'audit 模式仅记录', 'audit mode logs only');
+}
+function checkAudit(c, env) {
+    const a = env.auditLog;
+    if (!a.exists || a.entryCount === 0) {
+        return mk(c, 'fail', '未发现审计日志或日志为空 — 无法满足留存与举证要求', 'No audit log found or empty — retention/evidence requirement unmet');
+    }
+    // 判断留存跨度是否覆盖 6 个月
+    if (a.oldestTs) {
+        const span = Date.now() - new Date(a.oldestTs).getTime();
+        if (span >= SIX_MONTHS_MS) {
+            return mk(c, 'pass', `审计日志 ${a.entryCount} 条，最早 ${a.oldestTs.slice(0, 10)}，已覆盖 ≥6 个月`, `${a.entryCount} entries since ${a.oldestTs.slice(0, 10)}, ≥6 months covered`);
+        }
+    }
+    return mk(c, 'warn', `审计日志已启用 (${a.entryCount} 条)，但留存尚未满 6 个月 — 需持续运行积累`, `Audit log active (${a.entryCount} entries) but <6 months retained — keep running`);
+}
+function checkEnv(c, env) {
+    if (c.id === 'mlps-not-root') {
+        return env.isRoot
+            ? mk(c, 'fail', '正在以 root 运行 — 违反最小权限原则', 'Running as root — violates least privilege')
+            : mk(c, 'pass', '非 root 运行', 'Not running as root');
+    }
+    if (c.id === 'cbdt-overseas-llm') {
+        if (env.overseas.length > 0) {
+            const names = env.overseas.map(o => o.provider_zh).join(', ');
+            const namesEn = env.overseas.map(o => o.provider_en).join(', ');
+            return mk(c, 'fail', `检测到境外大模型端点配置: ${names} — 若向其发送个人信息/重要数据即构成数据出境，须走合规路径`, `Overseas LLM endpoint(s) configured: ${namesEn} — sending PI/important data = cross-border export`);
+        }
+        return mk(c, 'pass', '未检测到境外大模型端点配置', 'No overseas LLM endpoint detected');
+    }
+    return mk(c, 'manual', '需人工确认', 'Manual check required');
+}
+function mk(control, status, detail_zh, detail_en) {
+    return { control, status, detail_zh, detail_en };
+}
+// ===== 评分 =====
+const SEVERITY_WEIGHT = {
+    critical: 4, high: 3, medium: 2, low: 1,
+};
+/**
+ * 加权得分：manual 项不计入分母（不惩罚路线图/人工项）。
+ * pass=满分, warn=半分, fail=0。
+ */
+function computeScore(results) {
+    let earned = 0, possible = 0;
+    for (const r of results) {
+        if (r.status === 'manual')
+            continue;
+        const w = SEVERITY_WEIGHT[r.control.severity];
+        possible += w;
+        if (r.status === 'pass')
+            earned += w;
+        else if (r.status === 'warn')
+            earned += w * 0.5;
+    }
+    if (possible === 0)
+        return 0;
+    return Math.round((earned / possible) * 100);
+}
+function gradeOf(score) {
+    if (score >= 90)
+        return 'A';
+    if (score >= 75)
+        return 'B';
+    if (score >= 60)
+        return 'C';
+    return 'D';
+}

package/dist/compliance/project-scan.d.ts

@@ -0,0 +1,23 @@
+export type FindingKind = 'overseas' | 'secret' | 'pii' | 'env-perm';
+export interface ProjectFinding {
+    kind: FindingKind;
+    /** 相对项目根的路径 */
+    file: string;
+    line?: number;
+    /** 人类可读结论 */
+    detail: string;
+    severity: 'critical' | 'high' | 'medium';
+    /** 仅 overseas：命中的境外端点信息，供体检评分并入 */
+    endpointId?: string;
+    provider_zh?: string;
+    provider_en?: string;
+}
+export interface ProjectScanResult {
+    root: string;
+    filesScanned: number;
+    truncated: boolean;
+    findings: ProjectFinding[];
+    counts: Record<FindingKind, number>;
+}
+/** 扫描项目目录，返回真实风险发现 */
+export declare function scanProject(root: string): ProjectScanResult;