ECC Go 安全规则详解：密钥管理、gosec 静态扫描与 context 超时治理

本篇指南聚焦 ECC 仓库中的 Go 安全规则文件 .cursor/rules/golang-security.md，讲解这条 Cursor 规则的触发机制（frontmatter 配置）、它所继承的通用安全基线，以及其三大核心实践：基于环境变量的密钥管理、gosec 静态安全扫描、以及用 context.Context 做超时控制。读完之后，你将理解 ECC 如何将“通用安全规则 + 语言专属规则”分层下发给 AI Agent，并能在自己的 Go 项目中直接套用其中给出的代码与命令。

规则文件与触发机制

ECC 将面向 AI 编码助手的安全规范组织为 Markdown 规则文件。Go 安全规则的 Cursor 版本位于 .cursor/rules/golang-security.md，其文件头部使用 frontmatter 声明了规则的元信息：

---
description: "Go security extending common rules"
globs: ["**/*.go", "**/go.mod", "**/go.sum"]
alwaysApply: false
---

这三个字段决定了规则如何被 Cursor 消费：

• description：规则的一句话描述，说明本文件是在通用安全规则之上补充 Go 专属内容；
• globs：触发文件模式。只有当编辑或引用的文件匹配 **/*.go、**/go.mod、**/go.sum 时，该规则才会被注入上下文——即“按需加载”，而不是对所有文件生效；
• alwaysApply: false：显式关闭“总是应用”，与 globs 配合，保证这条规则只在 Go 相关代码路径上激活。

同一份 Go 安全规范在仓库中还有一份镜像文件 rules/golang/security.md，正文完全一致，仅 frontmatter 格式不同：

---
paths:
  - "**/*.go"
  - "**/go.mod"
  - "**/go.sum"
---

这里用 paths 字段替代了 globs。从源码结构看，两种写法分别对应 ECC 面向不同编码助手（Cursor 与 Claude Code 等）的规则分发格式，规则内容本身保持单一事实来源，再派生多语言文档版本（如 docs/zh-CN/rules/golang/security.md、docs/ja-JP/rules/golang/security.md 等）。

继承通用安全基线：提交前的强制检查

文档开头明确写道：“This file extends the common security rule with Go specific content.”——Go 安全规则是通用安全规则的增量扩展。这条通用规则在 ECC 中是 alwaysApply: true 的全局规则，其要求所有提交前必须完成一组强制检查：

• 无硬编码密钥（API key、密码、token）；
• 所有用户输入经过校验；
• SQL 注入防护（参数化查询）；
• XSS 防护（HTML 净化）；
• 启用 CSRF 保护；
• 认证/授权已验证；
• 所有端点启用限流；
• 错误信息不泄露敏感数据。

在密钥管理方面，通用规则进一步规定：绝不在源码中硬编码密钥，始终使用环境变量或密钥管理服务，在启动时校验必需密钥是否存在，并轮换任何可能已泄露的密钥。此外还定义了“安全响应协议”：一旦发现安全问题，立即停止，使用 security-reviewer agent 介入，先修复 CRITICAL 级别问题再继续，轮换已暴露密钥，并在整个代码库中排查同类问题。Go 专属规则则在这套基线之上，给出针对 Go 语言的具体落地手段——以下三节逐一展开。

密钥管理：从环境变量读取并快速失败

Go 安全规则给出的密钥管理示例非常短，但体现了“fail fast（快速失败）”原则：

apiKey := os.Getenv("OPENAI_API_KEY")
if apiKey == "" {
    log.Fatal("OPENAI_API_KEY not configured")
}

这段代码的要点：

1. 密钥来源只能是环境变量（os.Getenv），与通用规则中“ALWAYS use environment variables or a secret manager”的要求一致；
2. 启动时立即校验：如果必需的 OPENAI_API_KEY 未配置，直接 log.Fatal 终止进程，避免带着缺失的凭据进入运行期，之后才在请求失败时暴露配置问题；
3. 错误信息只提示变量名，不回显任何密钥内容本身，符合“错误消息不泄露敏感数据”的通用检查项。

这一模式可推广到任何必需凭据（数据库口令、JWT 签名密钥、第三方 token 等）：在程序入口集中读取并校验，缺失即拒绝启动。

安全扫描：gosec 静态分析

规则要求对 Go 代码使用 gosec 进行静态安全分析：

gosec ./...

./... 表示扫描当前模块下的所有包。gosec 是 Go 生态中常见的安全静态分析工具，能够识别硬编码凭证、弱哈希算法（如 MD5/SHA1 用于安全用途）、不安全的随机数使用、TLS 配置问题（如禁用证书校验）、SQL 拼接注入风险等典型模式。在 ECC 的规则体系中，把它作为 Go 项目的固定扫描手段，与通用规则中“提交前强制检查”形成呼应：Agent 或开发者在处理 **/*.go 文件时，会因 globs 匹配而被提醒执行该扫描。

需要注意的是，gosec 只做静态分析，无法替代 common 基线中要求的人工审查项（如认证/授权、限流），两者应组合使用。

超时治理：context.Context 控制外部调用

规则的第三部分要求“Always use context.Context for timeout control”，并给出最小范例：

ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()

其含义与工程价值：

• context.WithTimeout：基于父上下文派生一个 5 秒的超时上下文。任何接收该 ctx 的 I/O 操作（HTTP 请求、数据库查询等）都会在超时后被取消，避免 goroutine 因下游故障而无限挂起——这属于资源耗尽与可用性层面的安全控制；
• defer cancel()：无论函数以何种路径返回，都立即释放 WithTimeout 创建的定时器资源，防止上下文泄漏。

ECC 的 Go 模式规范 skills/golang-patterns 中同样以 context.WithTimeout(ctx, 5*time.Second) 作为外部调用的标准写法（HTTP 客户端示例中也使用 context.Background() 派生 30 秒超时），与本安全规则形成了模式层与安全层的双重印证。

与 Go 其他规则的协同

Go 安全规则并非孤立存在，而是与 ECC 的 Go 规则族按同一套 globs/paths 触发：

• rules/golang/hooks.md：在编辑 .go 文件后的 PostToolUse 钩子中运行 gofmt/goimports（自动格式化）、go vet（静态检查）、staticcheck（扩展静态检查）。其中 go vet 与 gosec 构成互补——前者偏正确性，后者偏安全性；
• rules/golang/testing.md：要求始终使用 go test -race ./... 检测数据竞争，并用 go test -cover ./... 统计覆盖率。竞态条件本身就是安全漏洞的常见来源（如竞态导致的逻辑绕过），该要求与安全基线直接相关；
• rules/golang/patterns.md 与 rules/golang/coding-style.md：约定 Go 惯用法与代码风格，保证安全写法（错误处理、超时传递）在风格层面被统一执行。

从源码结构看，ECC 的分层思路是：common 规则定义全局不可协商的安全底线（alwaysApply），语言规则按文件模式增量扩展（globs/paths 匹配才激活），hooks 规则把静态检查挂到编辑动作上自动执行。三者叠加后，Agent 在修改 Go 代码时既能“看到”安全要求，也能通过钩子“强制”执行检查。

小结

.cursor/rules/golang-security.md 虽然篇幅精炼，但它浓缩了 Go 项目安全工程化的三块基石：

1. 密钥管理：os.Getenv + 启动时快速失败，杜绝硬编码凭据；
2. 静态扫描：gosec ./... 作为固定安全门禁；
3. 超时治理：context.WithTimeout + defer cancel() 防止资源挂起泄漏。

理解这条规则后，你既可以将其作为 Agent 规则模板移植到自己的 Cursor/Claude Code 配置中（frontmatter 的 globs/alwaysApply 是触发控制的关键），也可以把其中的 Go 实践（环境变量校验、gosec、context 超时）直接落到实际项目的 CI 与代码评审清单里。