shellward 0.6.1 → 0.6.3

package/src/cli.ts

@@ -0,0 +1,154 @@
+#!/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: string[]) {
+  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 as any) || 'auto',
+    mode: (process.env.SHELLWARD_MODE as any) || '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: string[], flag: string): string | undefined {
+  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/src/commands/compliance.ts

@@ -0,0 +1,25 @@
+// src/commands/compliance.ts — /compliance 命令：一键合规体检报告
+//
+// 月1 获客钩子的命令形态。扫一遍配置 + 环境 + 审计日志 + 出境端点，
+// 输出网安法/PIPL/等保/数据出境/AI标识 的红黄绿合规评分卡。
+
+import type { ShellWardConfig } from '../types.js'
+import { resolveLocale } from '../types.js'
+import { runComplianceAudit } from '../compliance/audit.js'
+import { renderComplianceReport } from '../compliance/report.js'
+
+export function registerComplianceCommand(api: any, config: ShellWardConfig) {
+  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/src/commands/index.ts

@@ -9,6 +9,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: any, config: ShellWardConfig): number {
@@ -22,6 +23,7 @@ export function registerAllCommands(api: any, config: ShellWardConfig): number {
   registerScanMcpCommand(api, config)
   registerCheckUpdatesCommand(api, config)
   registerUpgradeOpenClawCommand(api, config)
+  registerComplianceCommand(api, config)
 
   // Register /cg shortcut with help
   api.registerCommand({
@@ -35,6 +37,7 @@ export function registerAllCommands(api: any, config: ShellWardConfig): number {
 
 | 命令 | 说明 |
 |------|------|
+| \`/compliance\` | 🆕 AI 合规体检（网安法/PIPL/等保/数据出境/AI标识 红黄绿评分卡） |
 | \`/security\` | 安全状态总览（防御层、审计统计、系统检查） |
 | \`/audit [数量] [过滤]\` | 查看审计日志 (过滤: block/audit/critical/high) |
 | \`/harden\` | 安全扫描 · \`/harden fix\` 自动修复权限 |
@@ -50,6 +53,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 |
@@ -64,6 +68,6 @@ 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/src/compliance/audit.ts

@@ -0,0 +1,310 @@
+// 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 type { OverseasMatch } from '../rules/overseas-llm.js'
+import { scanProject } from './project-scan.js'
+import type { ProjectScanResult } from './project-scan.js'
+import { COMPLIANCE_CONTROLS } from './regulations.js'
+import type { ComplianceControl, Regulation, Severity } from './regulations.js'
+import type { ShellWardConfig } from '../types.js'
+
+const LOG_FILE = join(getHomeDir(), '.openclaw', 'shellward', 'audit.jsonl')
+const SIX_MONTHS_MS = 182 * 24 * 60 * 60 * 1000
+
+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
+}
+
+/** 层能力映射：控制项 id → 必须启用的层（全部启用才 pass，部分启用 warn，全关 fail） */
+const CAPABILITY_LAYERS: Record<string, (keyof ShellWardConfig['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(): EnvFacts {
+  // 1. root 检测
+  const isRoot = typeof process.getuid === 'function' && process.getuid() === 0
+
+  // 2. 审计日志事实
+  const auditLog = readAuditLogFacts()
+
+  // 3. 出境端点探测：扫描常见环境变量中的 base_url / 端点
+  const overseas: OverseasMatch[] = []
+  const seen = new Set<string>()
+  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(): AuditLogFacts {
+  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: string): string | undefined {
+  const m = line.match(/"ts":"([^"]+)"/)
+  return m?.[1]
+}
+
+/**
+ * 运行合规体检。
+ * @param config ShellWard 当前配置
+ * @param facts  环境事实；不传则从真实环境采集
+ */
+export function runComplianceAudit(config: ShellWardConfig, facts?: EnvFacts): ComplianceReport {
+  const env = facts ?? gatherEnvFacts()
+  const results: ControlResult[] = 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(),
+  }
+}
+
+export interface ProjectComplianceResult {
+  report: ComplianceReport
+  scan: ProjectScanResult
+}
+
+/**
+ * 面向真实项目的体检：扫描项目目录的真实风险，并入评分，再跑控制项体检。
+ * 这是 CLI (`shellward scan`) 的入口 —— 报告关于「用户项目」而非「ShellWard 开关」。
+ */
+export function runProjectComplianceAudit(config: ShellWardConfig, root: string): ProjectComplianceResult {
+  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 } as const
+const MAX_PROJECT_PENALTY = 40
+
+function computeProjectPenalty(scan: ProjectScanResult): number {
+  let p = 0
+  for (const f of scan.findings) p += FINDING_PENALTY[f.severity]
+  return Math.min(MAX_PROJECT_PENALTY, p)
+}
+
+function checkControl(c: ComplianceControl, config: ShellWardConfig, env: EnvFacts): ControlResult {
+  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: ComplianceControl, config: ShellWardConfig): ControlResult {
+  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: ComplianceControl, config: ShellWardConfig): ControlResult {
+  return config.mode === 'enforce'
+    ? mk(c, 'pass', 'enforce 模式', 'enforce mode')
+    : mk(c, 'warn', 'audit 模式仅记录', 'audit mode logs only')
+}
+
+function checkAudit(c: ComplianceControl, env: EnvFacts): ControlResult {
+  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: ComplianceControl, env: EnvFacts): ControlResult {
+  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: ComplianceControl, status: ControlStatus, detail_zh: string, detail_en: string): ControlResult {
+  return { control, status, detail_zh, detail_en }
+}
+
+// ===== 评分 =====
+
+const SEVERITY_WEIGHT: Record<Severity, number> = {
+  critical: 4, high: 3, medium: 2, low: 1,
+}
+
+/**
+ * 加权得分：manual 项不计入分母（不惩罚路线图/人工项）。
+ * pass=满分, warn=半分, fail=0。
+ */
+function computeScore(results: ControlResult[]): number {
+  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: number): 'A' | 'B' | 'C' | 'D' {
+  if (score >= 90) return 'A'
+  if (score >= 75) return 'B'
+  if (score >= 60) return 'C'
+  return 'D'
+}
+
+export type { Regulation }