shellward 0.6.1 → 0.6.2

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 }

package/src/compliance/project-scan.ts

@@ -0,0 +1,263 @@
+// src/compliance/project-scan.ts — 项目真实风险扫描
+//
+// 体检的灵魂：报告的是「用户项目的真实风险」，不是「ShellWard 的开关」。
+// 零依赖遍历当前项目目录，找出可截图、可定位 (文件:行) 的合规风险：
+//   ① 境外大模型端点（硬编码 base_url/key）→ 数据出境风险
+//   ② 硬编码密钥（API key / 私钥 / 口令 / 连接串）
+//   ③ 文件中的中文 PII（身份证 / 手机号 / 银行卡）
+//   ④ .env 等敏感文件权限过宽
+
+import { readdirSync, statSync, readFileSync } from 'fs'
+import { join, relative, basename } from 'path'
+import { detectOverseasLLM, detectOverseasDeps, isDependencyManifest } from '../rules/overseas-llm.js'
+import { SENSITIVE_PATTERNS } from '../rules/sensitive-patterns.js'
+
+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>
+}
+
+// ===== 扫描边界（零依赖、可控） =====
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'out',
+  'vendor', 'coverage', '.venv', 'venv', '__pycache__', '.cache', 'target',
+])
+const SCAN_EXT = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+  '.py', '.go', '.rb', '.java', '.php', '.rs',
+  '.json', '.yaml', '.yml', '.toml', '.ini', '.conf', '.sh', '.txt', '.csv',
+])
+const MAX_FILES = 3000
+const MAX_FILE_BYTES = 512 * 1024
+const MAX_FINDINGS_PER_FILE = 20
+const MAX_TOTAL_FINDINGS = 500
+
+// 密钥类 vs PII 类（按 sensitive-patterns 的 id 归类）
+const SECRET_IDS = new Set([
+  'openai_key', 'anthropic_key', 'aws_access', 'github_token',
+  'generic_api_key', 'private_key', 'jwt', 'password', 'conn_string',
+])
+const PII_IDS = new Set(['id_card_cn', 'phone_cn', 'bank_card_cn', 'ssn_us', 'credit_card'])
+
+/** 扫描项目目录，返回真实风险发现 */
+export function scanProject(root: string): ProjectScanResult {
+  const findings: ProjectFinding[] = []
+  const state = { files: 0, truncated: false }
+
+  walk(root, root, findings, state)
+
+  const counts: Record<FindingKind, number> = { overseas: 0, secret: 0, pii: 0, 'env-perm': 0 }
+  for (const f of findings) counts[f.kind]++
+
+  return {
+    root,
+    filesScanned: state.files,
+    truncated: state.truncated,
+    findings,
+    counts,
+  }
+}
+
+function walk(
+  dir: string,
+  root: string,
+  findings: ProjectFinding[],
+  state: { files: number; truncated: boolean },
+): void {
+  if (state.files >= MAX_FILES || findings.length >= MAX_TOTAL_FINDINGS) {
+    state.truncated = true
+    return
+  }
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return
+  }
+
+  for (const name of entries) {
+    if (state.files >= MAX_FILES || findings.length >= MAX_TOTAL_FINDINGS) {
+      state.truncated = true
+      return
+    }
+    if (name.startsWith('.') && !name.startsWith('.env')) {
+      // 跳过隐藏文件/目录，但保留 .env*
+      if (name !== '.') continue
+    }
+    const full = join(dir, name)
+    let st
+    try {
+      st = statSync(full)
+    } catch {
+      continue
+    }
+
+    if (st.isDirectory()) {
+      if (SKIP_DIRS.has(name)) continue
+      walk(full, root, findings, state)
+      continue
+    }
+
+    if (!st.isFile()) continue
+
+    // .env 权限检查（任意大小）
+    if (/^\.env(\..+)?$/.test(name)) {
+      checkEnvPerm(full, root, st.mode, findings)
+    }
+
+    // 内容扫描：文本类扩展 + .env* + 依赖清单(含 go.mod)，且大小受限
+    const isEnv = /^\.env(\..+)?$/.test(name)
+    const isDep = isDependencyManifest(name)
+    const ext = name.includes('.') ? name.slice(name.lastIndexOf('.')) : ''
+    if (!isEnv && !isDep && !SCAN_EXT.has(ext)) continue
+    if (st.size > MAX_FILE_BYTES) continue
+
+    let content: string
+    try {
+      content = readFileSync(full, 'utf-8')
+    } catch {
+      continue
+    }
+    state.files++
+    if (isDep) scanDependencies(name, content, full, root, findings)
+    scanContent(content, full, root, findings)
+  }
+}
+
+function scanDependencies(
+  name: string,
+  content: string,
+  full: string,
+  root: string,
+  findings: ProjectFinding[],
+): void {
+  const deps = detectOverseasDeps(name, content)
+  if (deps.length === 0) return
+  const file = rel(root, full)
+  const lines = content.split('\n')
+  for (const d of deps) {
+    if (findings.length >= MAX_TOTAL_FINDINGS) break
+    // 粗定位包名所在行
+    let line: number | undefined
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].toLowerCase().includes(d.pkg.toLowerCase())) { line = i + 1; break }
+    }
+    findings.push({
+      kind: 'overseas',
+      file,
+      line,
+      detail: `境外大模型 SDK 依赖: ${d.pkg} (${d.provider_zh}) — 项目内含数据出境通道，调用即可能构成出境`,
+      severity: 'high',
+      provider_zh: d.provider_zh,
+      provider_en: d.provider_en,
+    })
+  }
+}
+
+function checkEnvPerm(full: string, root: string, mode: number, findings: ProjectFinding[]): void {
+  // 仅 POSIX 有意义；Windows 上 mode 不可靠，跳过
+  if (process.platform === 'win32') return
+  const perm = mode & 0o777
+  if (perm > 0o600) {
+    findings.push({
+      kind: 'env-perm',
+      file: rel(root, full),
+      detail: `权限过宽 (${perm.toString(8)})，建议 chmod 600 — 含密钥的 .env 不应组/其他可读`,
+      severity: 'high',
+    })
+  }
+}
+
+function scanContent(
+  content: string,
+  full: string,
+  root: string,
+  findings: ProjectFinding[],
+): void {
+  const file = rel(root, full)
+  const lines = content.split('\n')
+  let perFile = 0
+  const dedup = new Set<string>()
+
+  for (let i = 0; i < lines.length; i++) {
+    if (perFile >= MAX_FINDINGS_PER_FILE || findings.length >= MAX_TOTAL_FINDINGS) break
+    const line = lines[i]
+    if (!line || line.length > 4000) continue
+
+    // ① 境外大模型端点
+    const ov = detectOverseasLLM(line)
+    if (ov.isOverseas) {
+      const key = `overseas:${ov.endpointId}`
+      if (!dedup.has(key)) {
+        dedup.add(key)
+        findings.push({
+          kind: 'overseas',
+          file,
+          line: i + 1,
+          detail: `境外大模型端点: ${ov.provider_zh} — 向其发送个人信息/重要数据即构成数据出境`,
+          severity: 'critical',
+          endpointId: ov.endpointId,
+          provider_zh: ov.provider_zh,
+          provider_en: ov.provider_en,
+        })
+        perFile++
+      }
+    }
+
+    // ② / ③ 密钥与 PII
+    for (const pat of SENSITIVE_PATTERNS) {
+      if (perFile >= MAX_FINDINGS_PER_FILE) break
+      const isSecret = SECRET_IDS.has(pat.id)
+      const isPII = PII_IDS.has(pat.id)
+      if (!isSecret && !isPII) continue
+      const re = new RegExp(pat.regex.source, pat.regex.flags)
+      let m: RegExpExecArray | null
+      while ((m = re.exec(line)) !== null) {
+        if (pat.validate && !pat.validate(m[0])) continue
+        const key = `${pat.id}:${i}`
+        if (dedup.has(key)) break
+        dedup.add(key)
+        findings.push({
+          kind: isSecret ? 'secret' : 'pii',
+          file,
+          line: i + 1,
+          detail: isSecret
+            ? `硬编码${pat.name}: ${preview(m[0])} — 凭据不应写入源码/配置`
+            : `${pat.name}: ${preview(m[0])} — 个人信息出现在文件中，需评估最小必要与脱敏`,
+          severity: isSecret ? 'critical' : 'high',
+        })
+        perFile++
+        if (perFile >= MAX_FINDINGS_PER_FILE) break
+        if (!re.global) break
+      }
+    }
+  }
+}
+
+function preview(s: string): string {
+  return s.length > 10 ? s.slice(0, 6) + '***' : s.slice(0, 3) + '***'
+}
+
+function rel(root: string, full: string): string {
+  const r = relative(root, full)
+  return r || basename(full)
+}