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

所属阶段：第五阶段「进阶能力」（第 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
2	所有用户输入已验证	代码审查 + Schema 验证	直接使用 req.body 不做校验
3	SQL 使用参数化查询	rg -n "'" + variable 扫描	字符串拼接 SQL
4	XSS 防护（输出转义）	检查 HTML 渲染代码	直接渲染 innerHTML
5	CSRF 防护启用	检查中间件配置	忘记添加 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.json	Hook 配置是否安全
.mcp.json	MCP 服务器配置是否可信
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	关键安全配置
Django	django-security	CSRF 中间件、密码哈希、SQL 注入防护
Spring Boot	springboot-security	Spring Security 配置、JWT、CORS
Laravel	laravel-security	加密、认证守卫、CSRF Token
Perl	perl-security	Taint 模式、输入清洗、文件权限

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 部分。