ECC 规则体系下的 TypeScript/JavaScript 安全实践：密钥管理、Agent 审计与纵深防御指南

ECC 规则体系下的 TypeScript/JavaScript 安全实践：密钥管理、Agent 审计与纵深防御指南

【免费下载链接】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

导读

本文围绕 ECC（Agent Harness Performance Optimization System）规则体系中的 TypeScript/JavaScript 专项安全规则展开，系统讲解该规则如何与通用安全规则联动，为 Claude Code、Codex 等 Agent 驱动的 TypeScript/JS 项目提供从「密钥管理」到「Agent 自动审计」的安全基线。读完本文，你将掌握 ECC 分层规则的组织方式、TypeScript 项目中密钥管理的强制写法，以及如何借助 security-reviewer Agent、security-scan 命令与 security-review 技能对代码进行 OWASP Top 10 维度的纵深审计。

ECC 规则体系：common 层与语言层的分层设计

ECC 的安全规则不是孤立文件，而是采用「通用层 + 语言层」的分层结构，见 rules/README.md 中的目录组织说明：

rules/ ├── common/ # 语言无关的通用原则（必须安装） │ └── security.md # 通用安全规则 └── typescript/ # TypeScript/JavaScript 语言专项规则 ├── security.md # TS/JS 安全规则（扩展 common/security.md） ├── coding-style.md ├── hooks.md ├── patterns.md └── testing.md

• common 层（rules/common/security.md）定义适用于所有项目的通用原则，不含具体语言的代码示例；
• 语言层（如 rules/typescript/security.md）以「扩展」方式补充语言特有的模式、工具与代码示例，每个文件都会显式引用其 common 对应物。

当语言层规则与 common 规则冲突时，语言层规则优先（specific overrides general），这与 CSS 优先级或.gitignore的覆盖逻辑类似。

文件头：规则的作用域声明

每个语言层规则文件顶部都带有 frontmatter，声明该规则生效的路径范围：

paths: - "**/*.ts" - "**/*.tsx" - "**/*.js" - "**/*.jsx"

这表示该规则对仓库内所有 TypeScript 与 JavaScript 源码文件（含 JSX/TSX）生效，是 Agent 决定何时加载这条规则的关键元数据。

核心主题一：密钥管理（Secret Management）

规则文件 给出的核心安全约束是：严禁在源码中硬编码密钥，一律使用环境变量，并在启动时校验密钥存在性。

错误示范：硬编码密钥（绝对禁止）

// 绝对不行: 硬编码的密钥 const apiKey = "sk-proj-xxxxx"

硬编码密钥会随代码进入版本库，一旦仓库公开或泄露，攻击者可直接利用该密钥访问对应服务，造成真实资金或数据损失。

正确做法：环境变量 + 启动校验

// 始终: 环境变量 const apiKey = process.env.API_KEY if (!apiKey) { throw new Error('API_KEY not configured') }

这里的两步写法值得在工程中强制推广：

1. 从process.env读取：密钥只存在于运行环境，不进入源码与版本历史；
2. 启动时 fail-fast 校验：密钥缺失立即抛错，而不是等到运行时调用第三方 API 时才暴露「未配置」问题，避免线上故障排查成本。

与 common 层密钥规则的呼应

common/security.md 对密钥管理提出了更完整的通用要求，两者共同构成完整基线：

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

核心主题二：Agent 支持——security-reviewer

规则文件最后指明：进行全面的安全审计时，使用 security-reviewer 技能。这条指引背后是 ECC 中一组完整的 Agent 与技能配套：

• Agent 定义：agents/security-reviewer.md 定义了安全审查专家的角色，使用 sonnet 模型，配备 Read、Grep、Glob、Bash 工具，用于检测密钥泄露、SSRF、注入、不安全加密及 OWASP Top 10 漏洞；
• CLI 命令：commands/security-scan.md 提供可执行的扫描入口；
• 深度技能：skills/security-review/SKILL.md 提供完整的安全检查清单与代码模式。

调用方式

security-scan 命令可直接触发 AgentShield 扫描：

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

• path：可选，默认当前项目，可使用.claude/路径、仓库根或模板目录；
• --format：json用于 CI，markdown用于交接，html用于独立审查报告；
• --min-severity：过滤低优先级发现；
• --fix：仅应用被明确标记为安全且可自动修复的修复项。

也可在 CI（如 GitHub Actions）中将其作为强制门禁：

- uses: affaan-m/agentshield@v1 with: path: "." min-severity: "medium" fail-on-findings: true

纵深扩充：Agent 视角的 OWASP Top 10 审查流程

security-reviewer Agent 定义了标准审查工作流，可按此流程对 TypeScript 项目进行系统化检查（详见 agents/security-reviewer.md）：

1. 初始扫描：运行npm audit、eslint-plugin-security，搜索硬编码密钥；重点审查认证、API 端点、数据库查询、文件上传、支付与 webhook 等高危区域；
2. OWASP Top 10 逐项核对：注入、失效认证、敏感数据泄露、XXE、失效访问控制、安全配置错误、XSS、不安全反序列化、已知漏洞依赖、日志与监控不足；
3. 代码模式审查：按下表立即标记危险模式。

高危模式速查表

误报处理原则

Agent 明确要求「先验证上下文再标记」，常见的误报场景包括：.env.example中的环境变量示例（非真实密钥）、测试文件中明确标注的测试凭证、本意即为公开的公共 API 密钥、以及用于校验和而非密码的 SHA256/MD5。

深化实践：security-review 技能的十类安全检查

security-review/SKILL.md 提供了可落地的 TypeScript 安全编码模式，与规则文件构成「规则告诉你做什么，技能告诉你怎么做」的完整闭环（这也是 rules/README.md 对 Rules 与 Skills 的定位区分）。

1. 输入校验（Zod Schema）

使用 schema 校验而非黑名单过滤，白名单原则优先：

import { z } from 'zod' const CreateUserSchema = z.object({ email: z.string().email(), name: z.string().min(1).max(100), age: z.number().int().min(0).max(150) }) export async function createUser(input: unknown) { try { const validated = CreateUserSchema.parse(input) return await db.users.create(validated) } catch (error) { if (error instanceof z.ZodError) { return { success: false, errors: error.issues } } throw error } }

注意这里对外部不可信输入使用unknown类型并通过zod收窄——这与 rules/typescript/coding-style.md 中「避免any、使用unknown安全收窄」的编码风格一脉相承。

2. SQL 注入防护

严禁字符串拼接 SQL，一律使用参数化查询或查询构造器：

// 危险：SQL 注入漏洞 const query = `SELECT * FROM users WHERE email = '${userEmail}'` await db.query(query) // 安全：参数化查询 await db.query( 'SELECT * FROM users WHERE email = $1', [userEmail] )

3. 认证与会话安全

JWT 不应存于 localStorage（易受 XSS 攻击），应使用 httpOnly Cookie：

res.setHeader('Set-Cookie', `token=${token}; HttpOnly; Secure; SameSite=Strict; Max-Age=3600`)

4. XSS 与 CSP

用户提供的 HTML 必须经 DOMPurify 消毒，CSP 需从严格策略起步，避免默认使用'unsafe-inline'与'unsafe-eval'（它们会抵消 CSP 的大部分保护，应视为临时兼容债）。

5. CSRF、速率限制与敏感数据

• 状态变更操作需 CSRF Token，Cookie 统一SameSite=Strict；
• 所有 API 端点配置速率限制，昂贵操作（如搜索）使用更激进限制；
• 日志与错误信息不得泄露密码、卡号、堆栈等敏感信息，用户侧只返回通用错误提示。

6. 依赖安全

npm audit # 检查漏洞 npm audit fix # 修复可自动修复项 npm ci # 使用 lock 文件进行可复现构建

应提交 lock 文件并在 CI 中使用npm ci替代npm install。

7. 自动化安全测试

技能中还给出了安全回归测试示例：验证受保护接口返回 401、管理接口对普通用户返回 403、非法输入返回 400、超出速率限制时返回 429，可将这些用例固化到测试套件中防止安全回归。

应急响应协议：发现安全问题时的处置顺序

综合 common/security.md 与 agents/security-reviewer.md 的定义，当发现安全问题时应按以下顺序处置：

1. 立即停止当前工作；
2. 调用security-reviewerAgent 进行专项审计；
3. 先修复CRITICAL级别问题再继续；
4. 轮换任何已暴露的密钥；
5. 全量复查代码库中是否存在同类问题，并输出详细报告、通知项目负责人、提供安全修复示例并验证修复有效。

规则生效链路与配套工具

从源码结构看，这条安全规则的完整生效链路为：

• rules/typescript/security.md（语言层规则，声明.ts/.tsx/.js/.jsx作用域）→ 引用 rules/common/security.md（通用基线）；
• 规则指向 agents/security-reviewer.md（Agent 角色定义）与 skills/security-review/SKILL.md（深度技能）；
• 配套 commands/security-scan.md 提供命令化扫描入口，并可通过--min-severity与--fix参数接入 CI 门禁。

配合 rules/typescript/hooks.md 中定义的 PostToolUse 钩子（如对console.log的自动告警），ECC 可以在 Agent 编写 TypeScript 代码的每个环节持续执行安全约束，将「安全不是可选项」从口号落实为可强制、可验证的工程机制。

【免费下载链接】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