ECC 安全规则体系：common-security 规则的强制检查清单、密钥管理与安全响应协议

ECC（The agent harness performance optimization system）将安全约束工程化为一套可直接被 AI Agent 加载的规则文件，其中 .cursor/rules/common-security.md 是通用安全规则的核心：它以 alwaysApply: true 的形式在每次会话中强制生效，定义了提交前必须通过的八项安全检查、密钥管理纪律和安全问题响应协议。读完本文，你能掌握这条规则的完整内容、它在 ECC 规则体系中的位置与分发机制，以及规则背后所引用的 security-reviewer Agent、/security-scan 命令和语言级安全扩展的具体实现。

规则文件的定位与加载机制

common-security.md 位于 ECC 的 Cursor 规则目录 .cursor/rules/ 下。该目录的组织方式是：common-* 前缀的规则适用于所有技术栈（agents、coding-style、development-workflow、git-workflow、hooks、patterns、performance、security、testing 九个通用维度），每种语言再叠加一套专属规则（如 typescript-security.md、python-security.md、golang-security.md、kotlin-security.md、swift-security.md、php-security.md）。

文件的 frontmatter 声明了它的加载策略：

---
description: "Security: mandatory checks, secret management, response protocol"
alwaysApply: true
---

alwaysApply: true 意味着这条规则不受路径匹配（paths 字段）限制，会在任何文件编辑会话中被无条件注入到 Agent 上下文。这与语言专属安全规则形成对照——例如 rules/typescript/security.md 的 frontmatter 使用 paths: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"] 按需触发。通用安全规则与语言规则的分工即由此确立：通用规则管"任何时候都必须做什么"，语言规则管"某类文件还应注意什么"。

同一份内容在 rules/common/security.md 中还有一份对应版本，供非 Cursor 环境（Claude Code、Codex 等 harness）复用。从源码结构看，.cursor/rules/ 与 rules/ 是同一规则体系在不同 harness 下的两份投影。

提交前强制安全检查清单（Mandatory Security Checks）

规则正文的第一节是提交前必须逐项核对的八项清单。原文要求：Before ANY commit（任何提交之前），确认以下每一项均满足：

• [ ] No hardcoded secrets (API keys, passwords, tokens) —— 无硬编码密钥（API 密钥、密码、令牌）
• [ ] All user inputs validated —— 所有用户输入已校验
• [ ] SQL injection prevention (parameterized queries) —— 已防 SQL 注入（使用参数化查询）
• [ ] XSS prevention (sanitized HTML) —— 已防 XSS（HTML 已清洗/转义）
• [ ] CSRF protection enabled —— 已启用 CSRF 保护
• [ ] Authentication/authorization verified —— 认证/授权已验证
• [ ] Rate limiting on all endpoints —— 所有端点已配置限流
• [ ] Error messages don't leak sensitive data —— 错误信息不泄露敏感数据

这份清单覆盖面恰好对应 Web 应用的最高频漏洞面：注入、跨站脚本、跨站请求伪造、认证授权缺陷、端点滥用和信息泄露。它不是"建议"而是"门槛"——规则将其定位为提交的先决条件。

为了理解每一项在 ECC 落地时被怎样具体化，可以看其引用的 security-reviewer Agent 中的代码模式判级表（见 agents/security-reviewer.md）。该表把清单条目映射到可直接 grep/审查的具体代码模式与严重级别：

代码模式	严重级别	修复方式
Hardcoded secrets（硬编码密钥）	CRITICAL	使用 process.env
Shell command with user input（用户输入拼接 Shell 命令）	CRITICAL	使用安全 API 或 execFile
String-concatenated SQL（字符串拼接 SQL）	CRITICAL	参数化查询
innerHTML = userInput	HIGH	使用 textContent 或 DOMPurify
fetch(userProvidedUrl)	HIGH	域名白名单
Plaintext password comparison（明文比对密码）	CRITICAL	使用 bcrypt.compare()
No auth check on route（路由无认证检查）	CRITICAL	添加认证中间件
Balance check without lock（无锁余额检查）	CRITICAL	事务中使用 FOR UPDATE
No rate limiting（无限流）	HIGH	添加 express-rate-limit
Logging passwords/secrets（日志记录密码/密钥）	MEDIUM	清洗日志输出

这张表回答了通用清单中"输入校验""SQL 注入""限流""错误信息泄露"等条目在代码层面的判定标准，例如：清单中"Rate limiting on all endpoints"落到实现层就是"无 express-rate-limit（或同类中间件）判为 HIGH"，"Error messages don't leak sensitive data"对应"日志中出现密码/密钥判为 MEDIUM"。

密钥管理纪律（Secret Management）

规则第二节给出四条密钥管理铁律：

• NEVER 在源码中硬编码任何密钥
• ALWAYS 使用环境变量或密钥管理器（secret manager）
• 在启动时校验必需密钥是否存在
• 对任何可能已暴露的密钥进行轮换（rotation）

第四点容易被忽视，但在安全响应实践中是关键闭环：一旦密钥进入过版本历史或日志，"改代码"并不等于"止血"，必须作废并重新签发。

这一纪律在 ECC 的语言规则层有可直接复制的落地范式。rules/typescript/security.md 给出的 TypeScript 正反示例：

// NEVER: Hardcoded secrets
const apiKey = "sk-proj-xxxxx"

// ALWAYS: Environment variables
const apiKey = process.env.API_KEY

if (!apiKey) {
  throw new Error('API_KEY not configured')
}

注意示例的后半段——启动时校验（startup validation）不是"存在就用、不存在再说"，而是显式快速失败（fail fast）：密钥缺失时立即抛出带配置名提示的错误，避免带着未配置的密钥状态进入运行期。

安全响应协议（Security Response Protocol）

规则第三节定义了发现安全问题时的五步协议，原文步骤为：

1. STOP immediately —— 立即停止当前工作
2. Use security-reviewer agent —— 调用 security-reviewer Agent
3. Fix CRITICAL issues before continuing —— 先修复 CRITICAL 级问题再继续
4. Rotate any exposed secrets —— 轮换所有已暴露的密钥
5. Review entire codebase for similar issues —— 全库排查同类问题

协议的设计逻辑是"止血优先、批量排查"：第 2 步把单点发现升级为系统化审查，第 4 步处理已外泄凭证，第 5 步防止"修了一个洞、同类漏洞还藏在别处"。

security-reviewer Agent 的实际职责

协议中的 security-reviewer 并非占位符，而是仓库中一个完整的 Agent 定义文件 agents/security-reviewer.md。其 frontmatter 声明了工具集（Read, Grep, Glob, Bash）与触发时机：

Security vulnerability detection and remediation specialist. Use PROACTIVELY after writing code that handles user input, authentication, API endpoints, or sensitive data.

它的能力面包括：

• OWASP Top 10 逐项核查（agents/security-reviewer.md）：注入（查询是否参数化、ORM 是否安全使用）、认证失效（密码是否 bcrypt/argon2 哈希、JWT 是否校验）、敏感数据暴露（HTTPS 是否强制、密钥是否在环境变量、日志是否清洗）、XXE、访问控制失效、错误配置（默认凭据、生产环境调试模式）、XSS、不安全反序列化、已知依赖漏洞（npm audit 是否干净）、日志不足。
• 分析命令（agents/security-reviewer.md）：npm audit --audit-level=high 与 npx eslint . --plugin security 作为初始扫描手段。
• 误报边界（agents/security-reviewer.md）：.env.example 中的环境变量、测试文件中标记清晰的测试凭据、意图公开的 API key、用作校验和（而非密码）的 SHA256/MD5——"Always verify context before flagging"（标记前必须核实上下文）。
• 紧急响应（agents/security-reviewer.md）：发现 CRITICAL 漏洞时出具详细报告、立即通知项目负责人、提供安全代码示例、验证修复生效、若凭证外泄则轮换密钥。
• 触发时机（agents/security-reviewer.md）：新 API 端点、认证代码变更、用户输入处理、数据库查询变更、文件上传、支付代码、外部 API 集成、依赖升级时 ALWAYS 执行；生产事故、依赖 CVE、用户安全报告、重大版本发布前 IMMEDIATELY 执行。

/security-scan 命令：规则的可执行延伸

规则要求"提交前逐项检查"，ECC 同时提供了把检查自动化的命令入口 commands/security-scan.md。该命令运行 AgentShield 扫描器，覆盖 agent、hook、MCP、权限与密钥五个表面（surface），用法为：

/security-scan [path] [--format text|json|markdown|html] [--min-severity low|medium|high|critical] [--fix]

其底层优先调用打包的确定性扫描引擎（commands/security-scan.md）：

npx ecc-agentshield scan --path "${TARGET_PATH:-.}" --format text

该命令的输出契约与响应协议第 3、4、5 步严丝合缝：按严重级别与运行时置信度分组统计、给出 CRITICAL/HIGH 发现的精确文件路径与修复步骤、区分"可安全自动修复"与"需人工判断"的项，修复后要求重跑扫描并报告修复前后分数对比。它还可以在 CI 中以强制门禁方式接入（commands/security-scan.md 给出的 GitHub Actions 片段），配合 min-severity: medium 与 fail-on-findings: true 实现"提交前检查"的机器化执行。

规则的分发：从 .cursor/rules 到其他 harness

common-security.md 不只服务 Cursor。同步脚本 scripts/sync-ecc-to-codex.sh 在把 ECC 资产同步到本地 Codex CLI 环境时，会把 .cursor/rules/ 下的九个 common-* 规则打包为一个规则包提示文件（ecc-rules-pack-common.md），其中明确列出 common-security.md 并要求"Treat these as strict defaults for planning, implementation, review, and verification in this repo"（将其作为本仓库计划、实现、评审与验证的严格默认）（scripts/sync-ecc-to-codex.sh）。

同时该脚本还会生成一个 ecc-tool-security-audit 工具提示（scripts/sync-ecc-to-codex.sh），其审计步骤——依赖漏洞扫描、高信号密钥扫描（OpenAI keys、GitHub tokens、AWS keys、私钥）、风险代码模式扫描（eval(、dangerouslySetInnerHTML、未清洗的 innerHTML、SQL 字符串插值）——正是通用安全清单的可执行版本。也就是说，alwaysApply: true 的通用安全规则在 ECC 生态中既是被 Agent 常驻阅读的规范，也是被同步脚本分发给不同 harness 的策略基线，还是被扫描工具周期性校验的验收标准。

小结：三层落地的通用安全规则

把 common-security.md 放回 ECC 的规则体系中，可以看到通用安全规则由三层机制共同保证执行：

1. 规范层：alwaysApply: true 的八项提交前清单、四条密钥铁律、五步响应协议，随每次会话注入 Agent 上下文；
2. 执行层：security-reviewer Agent 提供 OWASP Top 10 核查流程、代码模式判级表和误报边界，/security-scan 命令提供 AgentShield 确定性扫描与 CI 门禁；
3. 分发层：rules/common/security.md 的同源副本与 scripts/sync-ecc-to-codex.sh 的规则包机制，把同一套安全策略铺开到 Cursor、Claude Code、Codex 等多 harness 环境。

这套结构对开发者工程实践的直接启示是：把安全清单从"文档里的建议"变成"Agent 会话的常驻约束 + 工具链的可验证门禁"，是低成本提高安全下限的可行路径。