第 24 课：安全（下）— 防御机制与实战

王小酱
11 阅读7分钟

所属阶段：第五阶段「进阶能力」（第 23-27 课） 前置条件：第 23 课（安全威胁） 本课收获：完成 AgentShield 扫描 + 编写一个安全 Hook

一、本课概述

上一课我们从攻击者视角理解了 AI 代理面临的威胁。本课切换到防御者视角：

  1. 8 项安全检查清单 — 每次提交前必须过的安全关卡
  2. AgentShield 扫描工具 — 自动化检测 .claude/ 目录的安全漏洞
  3. 沙箱化策略 — 从身份、环境、网络、文件四个维度隔离风险
  4. 安全响应协议 — 发现安全问题后的标准操作流程
  5. 框架安全 Skill — 特定框架的安全最佳实践

掌握这些防御手段后，你就拥有了一套完整的 AI 代理安全防护体系。

二、8 项安全检查清单

rules/common/security.md 定义了提交前必须完成的 8 项安全检查。这不是建议，而是强制要求：

#检查项验证方法典型错误
1无硬编码密钥rg -n 'sk-|AKIA|password\s*=' .把 API Key 写在源码中
2所有用户输入已验证代码审查 + Schema 验证直接使用 req.body 不做校验
3SQL 使用参数化查询rg -n "'" + variable 扫描字符串拼接 SQL
4XSS 防护（输出转义）检查 HTML 渲染代码直接渲染 innerHTML
5CSRF 防护启用检查中间件配置忘记添加 CSRF Token
6认证/授权已验证检查路由守卫端点没有权限检查
7速率限制已配置检查限流中间件API 端点无频率限制
8错误信息不泄露敏感数据检查错误处理代码返回完整堆栈跟踪给客户端

2.1 在 ECC 中的执行方式

这 8 项检查不是靠人记住的，而是通过多层自动化保障：

代码编写完成
    ↓
code-reviewer Agent（自动审查代码质量 + 安全）
    ↓
security-reviewer Agent（专项安全审查）
    ↓
PreToolUse Hook（提交前拦截危险操作）
    ↓
/security-scan 命令（手动触发全面扫描）
    ↓
AgentShield（扫描 .claude/ 配置安全）
    ↓
通过所有检查 → 允许提交

三、AgentShield 扫描工具

3.1 什么是 AgentShield

AgentShield 是 ECC 提供的自动化安全扫描工具，专门检查 AI 代理配置中的安全漏洞。

它扫描的目标不是你的业务代码，而是代理本身的配置：

扫描目标检查内容
CLAUDE.md是否被注入恶意 Prompt
settings.jsonHook 配置是否安全
.mcp.jsonMCP 服务器配置是否可信
Hook 脚本是否包含危险命令
Agent 定义是否请求过多权限
Skill 文件是否包含隐藏指令

3.2 运行 AgentShield

# 基本扫描
npx ecc-agentshield scan

# 扫描指定目录
npx ecc-agentshield scan --path .claude/

# 输出详细报告
npx ecc-agentshield scan --verbose

# 也可以通过 ECC 命令触发
# /security-scan

3.3 扫描报告解读

AgentShield 扫描报告会列出发现的问题和严重程度：

AgentShield Scan Results
========================

[CRITICAL] .claude/settings.json
  - Hook "post-edit" executes curl command with external URL
  - Risk: Data exfiltration via hook

[HIGH] CLAUDE.md
  - Contains instruction override pattern: "ignore previous instructions"
  - Risk: Prompt injection in project config

[MEDIUM] .mcp.json
  - MCP server "data-fetcher" has no network restrictions
  - Risk: Unrestricted external access

[LOW] agents/custom-reviewer.md
  - Agent requests Bash tool without scope limitation
  - Risk: Broad shell access

Summary: 1 CRITICAL, 1 HIGH, 1 MEDIUM, 1 LOW

处理优先级：CRITICAL 必须立即修复，HIGH 应在提交前修复，MEDIUM 尽快处理，LOW 可以计划修复。

四、沙箱化策略

the-security-guide.md 的核心原则是：如果代理被攻破，爆炸半径必须足够小。

4.1 身份隔离

原则：不要给代理你的个人身份。

❌ 错误做法：
- 代理使用你的 Gmail 发邮件
- 代理使用你的 GitHub 个人 Token
- 代理使用你的 Slack 账号

✅ 正确做法：
- 创建专用账号 agent@yourdomain.com
- 使用短期、范围受限的 Token
- 创建专用 Bot 用户

关键思维：如果你的代理拥有和你相同的账号权限，那么被攻破的代理就是被攻破的你。

4.2 环境隔离

原则：不受信任的工作应在隔离环境中运行。

# Docker Compose 沙箱示例
services:
  agent:
    build: .
    user: "1000:1000"
    working_dir: /workspace
    volumes:
      - ./workspace:/workspace:rw
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    networks:
      - agent-internal

networks:
  agent-internal:
    internal: true    # 关键：禁止外部网络访问

4.3 网络隔离

原则：默认无网络，按需开放。

# 一次性容器：无网络、限制在 /workspace
docker run -it --rm \
  -v "$(pwd)":/workspace \
  -w /workspace \
  --network=none \
  node:20 bash

--network=none 确保即使代理被攻破，也无法"回拨"（phone home）。

4.4 文件路径限制

原则：最小权限原则 — 只允许访问必要的路径。

{
  "permissions": {
    "deny": [
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(**/.env*)",
      "Write(~/.ssh/**)",
      "Write(~/.aws/**)",
      "Bash(curl * | bash)",
      "Bash(ssh *)",
      "Bash(scp *)",
      "Bash(nc *)"
    ]
  }
}

这不是完整的安全策略，但它是一个高杠杆的起点 — 投入极小，收益极大。

五、安全响应协议

当发现安全问题时，ECC 定义了一套标准的响应流程：

5.1 五步响应流程

第一步：STOP
    │ 立即停止当前操作，不要试图"先修完再说"
    ↓
第二步：security-reviewer Agent
    │ 启动安全审查 Agent，对问题进行全面评估
    ↓
第三步：修复 CRITICAL 问题
    │ 优先修复最高优先级的安全漏洞
    ↓
第四步：轮换可能泄露的密钥
    │ 任何可能已暴露的密钥、Token、密码 → 立即轮换
    ↓
第五步：全库排查
    │ 排查整个代码库中是否存在类似问题

5.2 密钥泄露应急

如果发现密钥可能已泄露：

密钥类型应急操作
API Key立即在提供商后台轮换
数据库密码修改密码 + 审查访问日志
SSH 密钥重新生成密钥对 + 更新授权列表
GitHub Token撤销 + 重新生成 + 检查权限范围
环境变量更新部署配置 + 验证无残留

关键原则：假设泄露已经被利用。不要抱侥幸心理。

六、编写安全 Hook

6.1 PreToolUse Hook：拦截危险命令

编写一个 PreToolUse Hook，在 Agent 尝试执行危险 Bash 命令时进行拦截：

// scripts/hooks/security-guard.js
const DANGEROUS_PATTERNS = [
  /rm\s+(-rf?|--recursive)\s+\//,     // rm -rf /
  /curl\s+.*\|\s*bash/,                // curl | bash
  /wget\s+.*\|\s*sh/,                  // wget | sh
  /chmod\s+777/,                        // chmod 777
  />\s*\/etc\//,                        // 写入 /etc/
  /ssh\s+/,                             // SSH 连接
  /nc\s+(-l|--listen)/,                // netcat 监听
  /ANTHROPIC_BASE_URL/,                 // 环境变量劫持
];

function run(rawInput) {
  let input;
  try {
    input = JSON.parse(rawInput);
  } catch {
    return;  // 解析失败，不阻塞
  }

  if (input.tool_name !== 'Bash') return;

  const command = input.tool_input?.command || '';

  for (const pattern of DANGEROUS_PATTERNS) {
    if (pattern.test(command)) {
      return JSON.stringify({
        decision: 'block',
        reason: `Security guard: blocked dangerous command matching ${pattern}`,
      });
    }
  }
}

module.exports = { run };

6.2 注册 Hook

在 .claude/settings.json 中注册：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/hooks/security-guard.js"
          }
        ]
      }
    ]
  }
}

6.3 Hook 开发注意事项

注意事项说明
性能PreToolUse Hook 必须快速（<200ms），不做网络调用
容错解析错误时 exit 0，不阻塞工具执行
日志输出到 stderr，带 [SecurityGuard] 前缀
误判宁可漏报也不要误报太多（否则用户会禁用 Hook）

七、框架安全 Skill

ECC 为不同框架提供了专门的安全 Skill，每个 Skill 包含该框架特有的安全配置和最佳实践：

框架Skill关键安全配置
Djangodjango-securityCSRF 中间件、密码哈希、SQL 注入防护
Spring Bootspringboot-securitySpring Security 配置、JWT、CORS
Laravellaravel-security加密、认证守卫、CSRF Token
Perlperl-securityTaint 模式、输入清洗、文件权限

7.1 使用方式

这些 Skill 会在你使用对应框架时被自动加载。你也可以手动激活：

# 在 Claude Code 中
请使用 django-security Skill 审查我的 Django 项目安全配置

八、安全审计命令

ECC 提供了多个安全相关的命令：

命令功能
/security-scan运行 AgentShield + 代码安全扫描
/security-review触发 security-reviewer Agent 做深度审查
/harness-audit审计整个 Harness 配置的安全性

8.1 推荐的安全工作流

开发阶段：
  编写代码 → code-reviewer（包含基本安全检查）

提交前：
  /security-scan → 修复发现的问题

PR 阶段：
  /security-review → 深度安全审查

定期维护：
  /harness-audit → 审计整体配置安全
  npx ecc-agentshield scan → 扫描代理配置

九、本课练习

练习 1：运行安全扫描（10 分钟）

在你的项目中运行安全扫描：

# 基本密钥扫描
rg -n 'sk-|AKIA|password\s*=\s*["\x27][^"\x27]+["\x27]' --type-not binary .

# 扫描危险命令模式
rg -n 'curl|wget|nc|scp|ssh|enableAllProjectMcpServers|ANTHROPIC_BASE_URL' .claude/ 2>/dev/null

# 扫描隐藏 Unicode 字符
rg -nP '[\x{200B}\x{200C}\x{200D}\x{2060}\x{FEFF}\x{202A}-\x{202E}]' .

记录发现的问题（如果有的话）。

练习 2：编写安全 Hook（20 分钟）

这是本课最重要的练习。

编写一个 PreToolUse Hook，满足以下要求：

  • 拦截包含 rm -rf / 的 Bash 命令
  • 拦截包含 curl ... | bash 的命令
  • 解析失败时不阻塞（exit 0）
  • 输出日志到 stderr

你可以参考本课第六节的代码示例，也可以加入自己的规则。

练习 3：沙箱化方案设计（15 分钟）

为你最常用的开发场景设计一个沙箱化方案：

  • 身份隔离：使用什么账号？
  • 环境隔离：容器还是 VM？
  • 网络隔离：哪些端口需要开放？
  • 文件隔离：哪些路径需要 deny？

练习 4（选做）：安全响应演练

假设你在代码中发现了一个硬编码的 API Key，已经被推送到了 GitHub 公开仓库。按照安全响应协议，列出你应该执行的每一步操作。

十、本课小结

你应该记住的内容
8 项检查清单无硬编码密钥、输入验证、参数化查询、XSS/CSRF 防护、认证、限流、错误处理
AgentShield专门扫描 .claude/ 配置安全的工具
沙箱四维度身份隔离、环境隔离、网络隔离、文件路径限制
安全响应STOP → security-reviewer → 修复 → 轮换密钥 → 全库排查
Hook 防御PreToolUse Hook 可以拦截危险 Bash 命令

十一、下节预告

第 25 课：持续学习 — Instinct 提取与演化

安全是"守"的能力，学习是"进"的能力。下节课我们学习 ECC 的持续学习系统：如何从每次会话中自动提取行为模式（Instinct），如何通过置信度评分筛选有价值的学习成果，以及如何将 Instinct 演化为 Skill 和 Agent。

预习建议：浏览 skills/continuous-learning-v2/SKILL.md 的 When to Activate 和 What's New 部分。

avatar
文章
阅读
粉丝