ECC 安全指南实战提交前强制检查、密钥管理与安全响应协议的工程化落地【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文基于 ECCThe agent harness performance optimization system仓库中的通用安全规则系统讲解任何提交之前必须完成的八项强制安全检查、密钥管理的四条铁律以及发现安全问题时应当遵循的五步响应协议。作为补充文章深入剖析仓库中与之配套的 security-reviewer 专业 Agent、security-review 技能与 /security-scan 自动化扫描命令帮助你在 Claude Code、Codex、Opencode、Cursor 等 Agent 驱动的开发工作流中把安全从事后补救变成提交前强制门禁。一、提交前的八项强制安全检查ECC 在 rules/common/security.md日文版见 docs/ja-JP/rules/common/security.md中文版见 docs/zh-CN/rules/common/security.md中规定在任何提交commit之前都必须逐项核对以下安全检查清单。这并非可选的最佳实践建议而是规则层面要求所有开发工作流强制执行的门禁。1. 无硬编码密钥API 密钥、密码、令牌源代码中不允许出现任何形式的硬编码密钥。在 skills/security-review/SKILL.md 中这一点以 FAIL/PASS 对照的方式给出了明确示范// FAIL: 绝不这样做 const apiKey sk-proj-xxxxx // 硬编码密钥 const dbPassword password123 // 明文密码在源码中 // PASS: 始终这样做 const apiKey process.env.OPENAI_API_KEY const dbUrl process.env.DATABASE_URL同时要求提交前核实.env.local已被加入.gitignore、git 历史中不残留密钥、生产环境密钥交由托管平台管理。2. 所有用户输入经过验证一切外部输入都必须经过白名单式校验而非黑名单。skill 中给出了基于 zod 的 Schema 校验模式先定义CreateUserSchema在进入业务逻辑之前用parse强制校验类型、长度与取值范围非法输入直接返回 400 错误。文件上传场景则必须三重限制——大小默认上限 5MB、MIME 类型、扩展名白名单任一不满足即拒绝。3. SQL 注入防护参数化查询禁止用字符串拼接构造 SQL。skill 明确指出如下写法是危险的// DANGEROUS - SQL 注入漏洞 const query SELECT * FROM users WHERE email ${userEmail} await db.query(query)正确做法是使用参数化查询或查询构造器await db.query( SELECT * FROM users WHERE email $1, [userEmail] )同时在 OWASP 检查中确认 ORM/查询构造器使用正确、所有数据库查询均参数化。4. XSS 防护净化 HTML渲染任何用户提供的 HTML 之前必须净化。skill 推荐使用 DOMPurify 并采用白名单模式仅放行b、i、em、strong、p等安全标签不放行任何属性同时配置严格的内容安全策略CSP作为纵深防御default-src self、object-src none、frame-ancestors none。需要特别注意的是CSP 应从严格策略起步unsafe-inline与unsafe-eval会大幅削弱 CSP 的保护效果只能作为有明确移除计划的临时兼容手段。5. CSRF 保护已启用所有改变状态的请求都必须携带并校验 CSRF Token如通过X-CSRF-Token请求头验证Cookie 一律使用SameSiteStrict属性。推荐采用双重提交 CookieDouble-submit cookie模式参考 skills/security-review/SKILL.md。6. 认证/授权已验证令牌不得存放于 localStorage易受 XSS 窃取应使用HttpOnly; Secure; SameSiteStrict的 Cookie。授权方面任何敏感操作如删除用户必须先校验调用者角色再放行否则返回 403。数据库层建议启用行级安全Row Level Security确保用户只能访问属于自己的数据行。7. 所有端点实施速率限制所有 API 端点都必须有速率限制昂贵操作如搜索使用更严格的阈值。skill 给出的典型配置为常规接口 15 分钟窗口内 100 次请求搜索接口 1 分钟窗口内 10 次请求同时支持基于 IP 与基于已认证用户的限流。8. 错误信息不泄露敏感数据对外错误信息必须泛化内部细节只进服务端日志// FAIL: 暴露内部细节 catch (error) { return NextResponse.json( { error: error.message, stack: error.stack }, { status: 500 } ) } // PASS: 泛化错误信息 catch (error) { console.error(Internal error:, error) return NextResponse.json( { error: An error occurred. Please try again. }, { status: 500 } ) }日志同样禁止输出密码、令牌、完整卡号等敏感字段只保留email、userId、卡号后四位等最小必要信息。二、密钥管理四条铁律原文档将密钥管理抽象为四条不可妥协的规则绝不在源代码中硬编码密钥——API 密钥、数据库口令、令牌一律不得出现在源码中始终使用环境变量或密钥管理器——通过process.env读取或交由专门的密钥管理系统托管在启动时验证所需密钥是否存在——应用启动阶段即检查关键环境变量缺失则立即报错终止避免运行到一半才因密钥缺失而崩溃轮换任何可能已暴露的密钥——一旦怀疑泄露立即重新生成而不是抱有侥幸心理。skill 中对应的启动校验模式为// 验证密钥存在 if (!apiKey) { throw new Error(OPENAI_API_KEY not configured) }此外验证清单还要求确认.env.local已被.gitignore排除、git 提交历史中不包含任何密钥痕迹。这一点对使用 git 协作的团队尤其关键——密钥一旦进入历史单纯删除文件并不能清除泄露风险必须配合历史清理与密钥轮换。三、安全响应协议发现漏洞后的五步处置原文档定义了发现安全问题时的标准处置流程共五步立即停止——暂停当前一切开发与发布动作防止问题扩大使用 security-reviewer 代理——调用仓库内置的安全审查 Agent 进行专业分析在继续之前修复关键CRITICAL问题——只有高危漏洞清零后才能恢复工作流轮换任何已暴露的密钥——覆盖可能已泄露这一假设下的所有凭据审查整个代码库是否存在类似问题——修复单点之后做全库排查杜绝同类模式复现。这五步与 agents/security-reviewer.md 中定义的应急响应流程相互印证发现 CRITICAL 漏洞后该 Agent 会输出详细报告、立即告警项目负责人、给出安全代码示例、验证修复有效性并在凭据暴露时执行密钥轮换。同时该 Agent 内部还有Prompt Defense Baseline防线防止提示注入、数据泄露与越权指令——这恰好呼应了错误信息不泄露敏感数据与认证/授权已验证两条提交前检查项在 Agent 侧的对偶实现。四、security-reviewer 代理把安全检查交给专业 Agent原文档将 security-reviewer 列为安全响应的核心工具。仓库在 agents/security-reviewer.md 中给出了该 Agent 的完整定义它是安全漏洞检测与修复专家建议在编写处理用户输入、认证、API 端点或敏感数据的代码之后主动调用。其核心职责包括六项漏洞检测——识别 OWASP Top 10 及常见安全问题密钥检测——查找硬编码的 API 密钥、密码、令牌输入验证——确保所有用户输入被正确净化认证/授权——核验访问控制是否到位依赖安全——检查存在漏洞的 npm 包npm audit --audit-levelhigh安全编码规范——强制执行安全编码模式。在代码模式审查环节该 Agent 维护了一张发现即标记的风险模式表其中包含了与八项强制检查一一对应的严重级别与修复建议风险模式严重级别修复方式硬编码密钥CRITICAL改用process.env含用户输入的 Shell 命令CRITICAL使用安全 API 或execFile字符串拼接 SQLCRITICAL参数化查询innerHTML 用户输入HIGH用textContent或 DOMPurifyfetch(用户提供的 URL)HIGH域名白名单明文密码比较CRITICAL使用bcrypt.compare()路由缺少认证检查CRITICAL增加认证中间件无速率限制HIGH引入限流中间件记录密码/密钥的日志MEDIUM净化日志输出该 Agent 还强调五大安全原则——纵深防御Defense in Depth、最小权限Least Privilege、安全失败Fail Securely、不信任输入Dont Trust Input、定期更新Update Regularly并专门列出了常见误报场景如.env.example中的占位变量、测试文件中明确标注的测试凭据、本就公开的 API 密钥、用作校验和的哈希值要求标记之前先核实上下文。这一设计让自动化安全审查在高告警噪音环境中依然保持高信噪比。五、自动化安全扫描/security-scan 命令与 CI 门禁在规则文档之外仓库还提供了将安全检查自动化的配套命令。commands/security-scan.md 定义的/security-scan命令针对 Agent、hook、MCP、权限与密钥等面运行 AgentShield 扫描并把结果整理为带优先级的修复计划/security-scan [path] [--format text|json|markdown|html] [--min-severity low|medium|high|critical] [--fix]path可选默认扫描当前项目也可指向.claude/目录、仓库根目录或模板目录--format输出格式CI 场景用json交接场景用markdown独立审查报告用html--min-severity过滤低优先级发现项--fix仅应用 AgentShield 明确标记为安全可自动修复的修复。命令底层优先调用确定性扫描引擎npx ecc-agentshield scan --path ${TARGET_PATH:-.} --format text并强调不得虚构发现项以 AgentShield 输出为事实来源将扫描事实与后续人工判断相分离。其输出契约包括安全等级与评分、按严重级别与运行时置信度分组的计数、带精确路径的 CRITICAL/HIGH 发现项、独立的低置信度发现分组、修复顺序以及本次扫描的运行方式。该命令同样适用于 GitHub Actions可将其作为强制质量门禁接入 CI- uses: affaan-m/agentshieldv1 with: path: . min-severity: medium fail-on-findings: true如此配置后任何包含中等级别以上安全发现的提交都会在 CI 阶段直接失败把提交前强制检查从开发者自觉升级为流水线强制与规则文档中的八项检查形成规则 Agent 自动化三层落地体系。六、部署前的完整检查清单与落地建议将规则文档与 skills/security-review/SKILL.md 中的部署前清单合并即可得到一份可直接对照执行的完整门禁密钥全部置于环境变量、所有输入已验证、查询全部参数化、用户内容已净化、CSRF 保护启用、令牌处理正确、角色检查到位、所有端点限流、生产环境强制 HTTPS、安全响应头CSP、X-Frame-Options已配置、错误与日志均不含敏感数据、依赖无已知漏洞且 lock 文件已提交、RLS 已启用、CORS 配置正确、文件上传受限于大小与类型。在 Agent 驱动的开发实践中推荐的工作流是编写涉及认证、用户输入、API 端点或敏感数据的代码之后主动调用 security-reviewer 代理进行 OWASP Top 10 检查与代码模式审查提交前逐项核对八项强制检查清单对 Agent、hook、MCP、权限与密钥等运行时面用/security-scan做确定性扫描最终在 CI 中以fail-on-findings把安全底线固化为自动化门禁。Security is not optional——这条规则正是 ECC 将安全内建于开发流程而非附加于流程之后的核心主张。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考