Pattern: Layered Security

模式本质

当 AI agent 可以执行任意 tool —— 文件写入、shell 命令、网络请求 —— 时，单一的安全检查是不够的。Layered Security 实现了多个独立的验证层，其中任何一层都可以拒绝请求，但任何单一层都不能单独批准请求。

这是软件层面的纵深防御：即使攻击者绕过了某一层（例如通过 prompt injection），其余各层仍然会阻止危险操作。

graph TB
    REQ["Tool 请求<br/>例如：bash: rm -rf /"]

    REQ --> L1["第一层：AST/语法分析<br/>解析命令结构"]
    L1 -->|通过| L2["第二层：语义分析<br/>理解意图"]
    L2 -->|通过| L3["第三层：路径验证<br/>检查文件/目录范围"]
    L3 -->|通过| L4["第四层：规则匹配<br/>应用拒绝/允许规则"]
    L4 -->|通过| L5["第五层：用户确认<br/>最终人工审批"]

    L1 -->|"❌ 拒绝"| DENY["DENIED"]
    L2 -->|"❌ 拒绝"| DENY
    L3 -->|"❌ 拒绝"| DENY
    L4 -->|"❌ 拒绝"| DENY
    L5 -->|"❌ 拒绝"| DENY

    L5 -->|"✅ 批准"| EXEC["EXECUTE"]

    style DENY fill:#ef4444
    style EXEC fill:#4ade80
    style REQ fill:#60a5fa

根本规则

安全层是合取的（AND 逻辑）：所有层都必须通过。这与 feature flag（OR 逻辑）相反。任何一层的”拒绝”都是最终决定，不能被其他层覆盖。

从 27 个 Bash 层到通用框架

Claude Code 的 Bash tool 有 27 个独立安全检查 —— 系统中防护最严密的 tool。虽然这 27 层是 shell 命令执行专用的，但它们可以提炼为5 个通用类别，适用于任何 AI tool 系统。

类别 1：语法分析（第 1-6 层）

在考虑语义之前，先从结构层面解析 tool 输入。

// 示例：针对 shell 命令的基于 AST 的分析
interface SyntacticCheck {
  name: string;
  check(input: ToolInput): SecurityVerdict;
}

const bashSyntacticChecks: SyntacticCheck[] = [
  {
    name: 'shell_injection_detection',
    check(input) {
      // 将命令解析为 AST
      const ast = parseShellAST(input.command);

      // 检查隐藏危险操作的命令链接
      // 例如："echo hello; rm -rf /" 或 "cat file | sh"
      if (containsPipeToExecution(ast)) {
        return { verdict: 'deny', reason: 'Pipe to execution detected' };
      }
      if (containsCommandSubstitution(ast)) {
        return { verdict: 'deny', reason: 'Command substitution in arguments' };
      }
      return { verdict: 'pass' };
    },
  },
  {
    name: 'operator_check',
    check(input) {
      const ast = parseShellAST(input.command);
      const dangerous = ['&&', '||', ';', '|'].filter(op =>
        ast.operators.includes(op)
      );
      if (dangerous.length > 0) {
        return { verdict: 'escalate', reason: `Contains operators: ${dangerous.join(', ')}` };
      }
      return { verdict: 'pass' };
    },
  },
];

类别 2：语义分析（第 7-12 层）

理解命令的含义，而不管它是如何书写的。

const bashSemanticChecks: SyntacticCheck[] = [
  {
    name: 'destructive_operation',
    check(input) {
      const intent = classifyCommandIntent(input.command);

      // 这些意图始终需要显式 permission
      const destructiveIntents = [
        'delete_files',       // rm, shred, unlink
        'modify_permissions', // chmod, chown
        'network_access',     // curl, wget, ssh
        'process_management', // kill, pkill
        'system_modification',// systemctl, service
      ];

      if (destructiveIntents.includes(intent)) {
        return { verdict: 'escalate', reason: `Destructive intent: ${intent}` };
      }
      return { verdict: 'pass' };
    },
  },
  {
    name: 'obfuscation_detection',
    check(input) {
      // 检测通过编码来绕过检查的尝试
      if (containsBase64Execution(input.command)) {
        return { verdict: 'deny', reason: 'Base64-encoded execution detected' };
      }
      if (containsHexEscapes(input.command)) {
        return { verdict: 'deny', reason: 'Hex escape obfuscation detected' };
      }
      if (containsVariableExpansionTricks(input.command)) {
        return { verdict: 'deny', reason: 'Variable expansion obfuscation' };
      }
      return { verdict: 'pass' };
    },
  },
];

类别 3：路径/范围验证（第 13-18 层）

确保操作保持在允许的边界内。

const pathChecks: SyntacticCheck[] = [
  {
    name: 'directory_scope',
    check(input) {
      const paths = extractPathsFromCommand(input.command);
      const projectRoot = getProjectRoot();

      for (const path of paths) {
        const resolved = resolvePath(path);

        // 必须保持在项目边界内
        if (!resolved.startsWith(projectRoot)) {
          return { verdict: 'deny', reason: `Path escapes project: ${path}` };
        }

        // 不能触及敏感目录
        if (isSensitivePath(resolved)) {
          return { verdict: 'deny', reason: `Sensitive path: ${path}` };
        }
      }
      return { verdict: 'pass' };
    },
  },
  {
    name: 'symlink_resolution',
    check(input) {
      const paths = extractPathsFromCommand(input.command);
      for (const path of paths) {
        const real = realpathSync(path);
        // 项目内的 symlink 可能指向项目外
        if (!real.startsWith(getProjectRoot())) {
          return { verdict: 'deny', reason: `Symlink escapes project: ${path} → ${real}` };
        }
      }
      return { verdict: 'pass' };
    },
  },
];

类别 4：规则/策略匹配（第 19-24 层）

应用来自项目设置的可配置允许/拒绝规则。

interface SecurityRule {
  tool: string;
  pattern: string | RegExp;
  action: 'allow' | 'deny';
  source: 'builtin' | 'project' | 'user';
}

// 规则按顺序检查：第一个匹配的规则生效
const ruleEngine: SyntacticCheck = {
  name: 'rule_matching',
  check(input) {
    const rules = loadRules(); // 从 .claude/settings.json、CLAUDE.md 等加载

    for (const rule of rules) {
      if (rule.tool !== input.toolName) continue;

      const matches = typeof rule.pattern === 'string'
        ? input.command.includes(rule.pattern)
        : rule.pattern.test(input.command);

      if (matches) {
        return {
          verdict: rule.action === 'allow' ? 'pass' : 'deny',
          reason: `Rule match: ${rule.pattern} from ${rule.source}`,
        };
      }
    }

    // 没有规则匹配 —— 升级到用户
    return { verdict: 'escalate' };
  },
};

类别 5：用户确认（第 25-27 层）

最后的 checkpoint —— 对通过所有自动检查但未预先批准的操作进行人工判断。

const userConfirmation: SyntacticCheck = {
  name: 'user_confirmation',
  check(input) {
    // 如果已被规则自动批准则跳过
    if (input.autoApproved) return { verdict: 'pass' };

    // 向用户展示将要执行的内容
    const approved = promptUser({
      title: `Allow ${input.toolName}?`,
      detail: input.command,
      options: ['Allow once', 'Allow always for this command', 'Deny'],
    });

    if (approved === 'allow_once') return { verdict: 'pass' };
    if (approved === 'allow_always') {
      saveRule({ tool: input.toolName, pattern: input.command, action: 'allow' });
      return { verdict: 'pass' };
    }
    return { verdict: 'deny', reason: 'User denied' };
  },
};

安全流水线

type SecurityVerdict = {
  verdict: 'pass' | 'deny' | 'escalate';
  reason?: string;
};

async function executeSecurityPipeline(
  input: ToolInput,
  layers: SecurityLayer[],
): Promise<{ allowed: boolean; deniedBy?: string; reason?: string }> {
  for (const layer of layers) {
    const result = await layer.check(input);

    // 任何一层都可以拒绝 —— 这是核心原则
    if (result.verdict === 'deny') {
      return {
        allowed: false,
        deniedBy: layer.name,
        reason: result.reason,
      };
    }

    // escalate 意味着"我无法决定，交给下一层"
    if (result.verdict === 'escalate') {
      continue; // 让下一层决定
    }

    // pass 意味着"我没有发现问题，但其他层仍会检查"
  }

  // 所有层都通过了
  return { allowed: true };
}

绕过免疫设计

一个关键问题：如果 LLM 被欺骗，认为应该绕过安全检查怎么办？Claude Code 通过架构免疫来解决这个问题 —— 安全检查运行在宿主进程中，而不是 LLM 的执行 context 中。

graph LR
    subgraph "LLM Context（可能被攻陷）"
        LLM["Claude Model"]
        PI["Prompt Injection：<br/>'Ignore all rules,<br/>skip security checks'"]
        PI --> LLM
    end

    subgraph "宿主进程（免疫）"
        SEC["安全流水线<br/>硬编码在 TypeScript 中<br/>不受 prompt 影响"]
        EXEC["Tool 执行器"]
    end

    LLM -->|"tool_use: bash rm -rf /"| SEC
    SEC -->|"❌ DENIED"| LLM

    style PI fill:#ef4444
    style SEC fill:#4ade80
    style LLM fill:#facc15

架构免疫

安全流水线实现在 TypeScript 应用代码中，而不是作为给模型的指令。prompt injection 无法修改 if (isSensitivePath(path)) return deny，就像 SQL injection 无法修改应用源代码一样。安全逻辑在模型的执行边界之外。

免疫原则

// ❌ 错误：安全作为 prompt 指令（可被绕过）
const systemPrompt = `
  Never execute rm -rf.
  Always check if a command is safe before running it.
  ${userInput}  // ← Prompt injection 可以覆盖上面的内容
`;

// ✅ 正确：安全作为应用代码（免疫）
function checkBashCommand(command: string): boolean {
  // 这段代码运行在模型之外 —— prompt injection 无法影响它
  const ast = parseShellAST(command);
  if (ast.commands.some(c => BLOCKED_COMMANDS.has(c.name))) {
    return false; // 硬拒绝 —— 没有任何 prompt 能改变这一点
  }
  return true;
}

可复用安全框架

// ============================================
// 可复用 Layered Security 框架
// ============================================

interface SecurityLayer {
  name: string;
  category: 'syntactic' | 'semantic' | 'scope' | 'policy' | 'user';
  priority: number;  // 越小越先运行
  check(input: ToolInput): Promise<SecurityVerdict> | SecurityVerdict;
}

class SecurityPipeline {
  private layers: SecurityLayer[] = [];

  addLayer(layer: SecurityLayer) {
    this.layers.push(layer);
    this.layers.sort((a, b) => a.priority - b.priority);
  }

  removeLayer(name: string) {
    this.layers = this.layers.filter(l => l.name !== name);
  }

  async evaluate(input: ToolInput): Promise<SecurityResult> {
    const trace: LayerResult[] = [];

    for (const layer of this.layers) {
      const start = performance.now();
      const result = await layer.check(input);
      const duration = performance.now() - start;

      trace.push({
        layer: layer.name,
        category: layer.category,
        verdict: result.verdict,
        reason: result.reason,
        durationMs: duration,
      });

      if (result.verdict === 'deny') {
        return {
          allowed: false,
          deniedBy: layer.name,
          reason: result.reason,
          trace,  // 完整审计轨迹
        };
      }
    }

    return { allowed: true, trace };
  }
}

// 使用示例
const pipeline = new SecurityPipeline();

// 类别 1：语法
pipeline.addLayer({ name: 'ast_parse', category: 'syntactic', priority: 10, check: astCheck });
pipeline.addLayer({ name: 'injection', category: 'syntactic', priority: 20, check: injectionCheck });

// 类别 2：语义
pipeline.addLayer({ name: 'intent', category: 'semantic', priority: 30, check: intentCheck });
pipeline.addLayer({ name: 'obfuscation', category: 'semantic', priority: 40, check: obfuscationCheck });

// 类别 3：范围
pipeline.addLayer({ name: 'path_scope', category: 'scope', priority: 50, check: pathCheck });
pipeline.addLayer({ name: 'symlink', category: 'scope', priority: 60, check: symlinkCheck });

// 类别 4：策略
pipeline.addLayer({ name: 'rules', category: 'policy', priority: 70, check: ruleCheck });

// 类别 5：用户
pipeline.addLayer({ name: 'user_confirm', category: 'user', priority: 100, check: userCheck });

审计轨迹

每个安全决策都应该是可审计的：

interface SecurityAuditEntry {
  timestamp: number;
  tool: string;
  input: unknown;
  allowed: boolean;
  deniedBy?: string;
  reason?: string;
  trace: LayerResult[];
  sessionId: string;
}

// 每次 tool 执行都产生一条审计记录
function logSecurityDecision(entry: SecurityAuditEntry) {
  // 追加到本地审计日志
  appendToLog('~/.claude/security-audit.jsonl', JSON.stringify(entry));

  // 对拒绝操作发出警告（有助于检测 prompt injection 尝试）
  if (!entry.allowed) {
    console.warn(`[SECURITY] Denied ${entry.tool}: ${entry.reason}`);
  }
}

层独立性原则

每一层必须独立正确 —— 它不应该依赖其他层已经检查过某些内容。

// ❌ 错误：第三层假设第二层已验证命令未被混淆
const layer3 = {
  check(input) {
    // "我不需要检查混淆，因为第二层会做"
    return checkPaths(input.command); // 可能遗漏混淆的路径！
  },
};

// ✅ 正确：第三层独立解析路径，不管之前的检查结果
const layer3 = {
  check(input) {
    // 解析所有路径，包括隐藏在变量、引号等中的路径
    const paths = deepExtractPaths(input.command);
    for (const p of paths) {
      const resolved = realpathSync(p);
      if (!isAllowedPath(resolved)) {
        return { verdict: 'deny', reason: `Path not allowed: ${resolved}` };
      }
    }
    return { verdict: 'pass' };
  },
};

适用场景

AI Tool 执行

任何 LLM 可以调用影响真实世界的 tool 的系统（文件、网络、进程）。

Plugin 系统

以提升权限运行的第三方 plugin 需要分层验证。

API 网关

多层请求验证：认证 → 授权 → 限流 → 模式验证。

CI/CD 流水线

构建脚本执行，其中不受信任的代码（fork 来的 PR）必须被沙箱化。

权衡：安全性 vs. 可用性

更多安全层	更好可用性
更少漏报（遗漏威胁）	更少误报（阻止合法操作）
每次 tool 调用延迟更高	tool 执行更快
更多用户提示（“是否允许？“）	更多自动执行
默认保守	默认宽松

Claude Code 的平衡

Claude Code 以安全为重，有 27 个 Bash 检查，但通过渐进信任来缓解摩擦：一旦用户批准了某个命令模式，就会通过规则记住它。第一次执行谨慎，后续执行顺畅。