ECC 项目 C 安全编码规范实战指南：覆盖密钥、SQL、验证、认证与错误处理的 .NET 安全基线

ECC 项目 C# 安全编码规范实战指南：覆盖密钥、SQL、验证、认证与错误处理的 .NET 安全基线

【免费下载链接】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 仓库中面向 C# 开发者的安全规则文档为主体，结合仓库内通用安全基线、审查代理与安全技能，系统梳理 .NET/C# 应用在开发阶段必须落实的安全底线。读者学完后，可以在自己的 ASP.NET Core、EF Core 或普通 .NET 服务中直接落地一套可执行的密钥管理、SQL 注入防护、输入验证、认证授权与错误处理方案，并借助 ECC 的安全审查工具链进行自动校验。

一、规则文件概览：它是什么、管住哪些文件

本指南对应的原始文档为 docs/ja-JP/rules/csharp/security.md（其英文原版位于 rules/csharp/security.md）。该规则文件在 YAML frontmatter 中声明了它的作用范围：

paths: - "**/*.cs" - "**/*.csx" - "**/*.csproj" - "**/appsettings*.json"

也就是说，凡是仓库或工作区中出现 C# 源文件（.cs）、C# 脚本（.csx）、项目文件（.csproj）以及 ASP.NET Core 配置文件（appsettings*.json），这份安全规则都会被触发并纳入检查。

文件开头有一句关键声明：

此文件以 C# 专属内容扩展了 common/security.md。

对应到仓库根目录，被扩展的通用安全基线与日文版位于 docs/ja-JP/rules/common/security.md，英文版位于 rules/common/security.md。通用基线定义了任何语言都必须满足的强制安全检查，而这份 C# 规则则在通用基线之上补充了 .NET 生态特有的落地方式。两者是"通用要求 + 语言落地"的继承关系，阅读本指南时应将两篇文档合并理解。

通用基线中最先列出的是"提交前的强制安全检查清单"（Mandatory Security Checks），它是理解 C# 各安全小节背后动机的总纲：

• 无硬编码密钥（API 密钥、密码、令牌）
• 所有用户输入均已验证
• SQL 注入防护（参数化查询）
• XSS 防护（净化后的 HTML）
• 启用 CSRF 防护
• 认证/授权已验证
• 所有端点启用限流
• 错误消息不泄露敏感数据

接下来逐节展开 C# 规则的五个核心主题。

二、密钥管理（Secret Management）：绝不让凭据进入源码

2.1 三条铁律

C# 规则在密钥管理上给出三条硬性要求：

1. API 密钥、令牌、连接字符串绝对不要硬编码在源代码中；
2. 本地开发使用环境变量与用户机密（User Secrets），生产环境使用机密管理器（Secret Manager）；
3. appsettings.*.json中不得包含真实凭据。

第三条特别重要——很多开发者误以为配置文件不算"源码"，但appsettings.Development.json、appsettings.Production.json一旦提交到仓库，其中写入的连接字符串和密钥就会进入版本历史，等于泄露。这也是规则 frontmatter 把appsettings*.json纳入检查范围的原因。

2.2 反例与正例

规则文档给出了对比鲜明的示例：

// BAD —— 密钥硬编码在源码中 const string ApiKey = "sk-live-123"; // GOOD —— 从配置读取，缺失时立即失败 var apiKey = builder.Configuration["OpenAI:ApiKey"] ?? throw new InvalidOperationException("OpenAI:ApiKey is not configured.");

正例有两个值得注意的设计：

• 从配置系统读取：builder.Configuration是 .NET 的配置抽象，它可以同时从环境变量、User Secrets、JSON 文件、命令行等多来源合并取值，因此本地开发用 User Secrets、CI 用环境变量、生产用机密管理器，代码本身完全不用改；
• 启动即失败：使用?? throw让应用在缺少必需密钥时直接抛出异常而非带病运行。这与 rules/common/security.md 中"在启动时验证必需密钥存在（Validate that required secrets are present at startup）"的通用要求完全一致。

2.3 来自审查代理的佐证

仓库中的 C# 专职审查代理 agents/csharp-reviewer.md 将硬编码密钥（API 密钥、连接字符串）列为 CRITICAL 级别问题，要求"使用配置/机密管理器"（use configuration/secret manager）。这意味着此类问题会直接导致审查结果被 Block（阻止合并），而不是仅给出警告。

三、SQL 注入防护（SQL Injection Prevention）：参数化是唯一正解

3.1 规则要求

1. 在 ADO.NET、Dapper、EF Core 中始终使用参数化查询；
2. 绝不将用户输入拼接进 SQL 字符串；
3. 使用动态查询组装之前，必须验证排序字段与过滤操作符（防止把用户输入当作列名或操作符拼接进 ORDER BY / WHERE 子句）。

第三条常常被忽略：即使主查询参数化了，ORDER BY {userInput}或WHERE {userInput} = @v这类动态片段依然是注入点。规则明确要求先做白名单校验再组装。

3.2 规则文档示例：Dapper 参数化

const string sql = "SELECT * FROM Orders WHERE CustomerId = @customerId"; await connection.QueryAsync<Order>(sql, new { customerId });

这里使用 Dapper 的匿名对象参数绑定，@customerId由驱动单独传输，绝不参与 SQL 文本拼接，从而杜绝注入。

3.3 在其他 ORM 中的等价写法

以规则提到的三种技术为例，可分别落实为：

// ADO.NET —— 使用 SqlParameter using var cmd = new SqlCommand( "SELECT * FROM Orders WHERE CustomerId = @customerId", connection); cmd.Parameters.Add(new SqlParameter("@customerId", customerId)); // EF Core —— 参数由 LINQ/表达式树翻译 var orders = await context.Orders .Where(o => o.CustomerId == customerId) .ToListAsync(); // 动态排序 —— 先白名单校验，再使用受控映射 var allowedSort = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase) { ["date"] = "OrderDate", ["total"] = "TotalAmount", ["status"] = "Status", }; if (!allowedSort.TryGetValue(userSortField, out var column)) throw new ArgumentException("Invalid sort field"); // 然后才把 column 拼入动态 SQL / OrderBy

审查代理同样将SQL 注入（查询中的字符串拼接/插值）列为 CRITICAL，要求改用参数化查询或 EF Core，可见这是所有 C# 项目放行合并的硬性门槛。

四、输入验证（Input Validation）：在应用边界拦截脏数据

规则给出三条要求：

1. 在应用边界（application boundary）验证 DTO——即请求一进入系统、尚未接触业务逻辑时就要完成校验；
2. 使用数据注解（Data Annotations）、FluentValidation 或显式守卫子句（guard clauses）；
3. 在执行业务逻辑之前拒绝无效的模型状态。

4.1 三种落地方式

// 方式一：Data Annotations + [ApiController] 自动返回 400 public sealed record CreateOrderRequest { [Required] public Guid CustomerId { get; init; } [Range(0.01, double.MaxValue)] public decimal Amount { get; init; } } // 方式二：FluentValidation（复杂规则） public sealed class CreateOrderValidator : AbstractValidator<CreateOrderRequest> { public CreateOrderValidator() { RuleFor(x => x.Amount).GreaterThan(0); RuleFor(x => x.CustomerId).NotEmpty(); } } // 方式三：显式守卫子句（无框架依赖） if (request.Amount <= 0) throw new ArgumentOutOfRangeException(nameof(request.Amount));

在 ASP.NET Core 中，标注[ApiController]的控制器会自动做模型绑定校验，ModelState.IsValid为 false 时自动返回 400，无需手写检查。这与规则"拒绝无效模型状态后再执行逻辑"的要求直接对应。

4.2 与通用基线的呼应

通用安全基线把"所有用户输入均已验证"列为提交前强制项，skills/security-review/SKILL.md 进一步强调白名单校验而非黑名单（whitelist validation, not blacklist），并明确"错误消息不得泄露敏感信息"——即验证失败的提示应面向用户友好，而不是把内部细节带出去。

五、认证与授权（Authentication and Authorization）：交给框架，别自己造轮子

规则的三条要求：

1. 优先使用框架的认证处理器（framework auth handlers），而非自定义令牌解析——自己手写 JWT 解析、base64 解码、签名验证极易出错；
2. 在端点或处理器边界强制执行授权策略；
3. 绝不记录原始令牌、密码或 PII（个人身份信息）。

5.1 ASP.NET Core 的标准做法

// Program.cs —— 使用框架认证处理器（JWT Bearer） builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.Authority = "https://your-issuer"; options.Audience = "your-api"; }); // 端点级授权策略 builder.Services.AddAuthorization(options => { options.AddPolicy("RequireAdmin", p => p.RequireRole("admin")); }); // 控制器/最小 API 端点处强制 // [Authorize(Policy = "RequireAdmin")] 或 .RequireAuthorization("RequireAdmin")

这样令牌的签发、验签、过期、受众校验全部由框架处理，业务代码只需声明"谁可以访问什么"。

5.2 日志红线

审查代理在 CRITICAL 错误处理条目中强调：捕获异常时若直接catch { return null; }会吞掉上下文，而"记录原始令牌、密码、PII"则是更严重的红线——日志落盘后可能被运维、日志平台、备份系统层层扩散，比代码泄露更难挽回。结构化日志应只记录业务标识（如用户 ID、订单号），绝不记录凭据本身。

六、错误处理（Error Handling）：对外友好，对内详尽

规则的三条要求：

1. 向客户端返回安全的提示消息；
2. 详细异常在服务端以结构化上下文记录日志；
3. API 响应中不得暴露堆栈跟踪、SQL 文本或文件系统路径。

6.1 结构化日志示例

C# 编码风格规则 也强调"抛出具体异常并用结构化属性记录日志"，与安全规则一脉相承：

public async Task<Order> LoadOrderAsync(Guid orderId, CancellationToken cancellationToken) { try { return await repository.FindAsync(orderId, cancellationToken) ?? throw new InvalidOperationException($"Order {orderId} was not found."); } catch (Exception ex) { logger.LogError(ex, "Failed to load order {OrderId}", orderId); throw; } }

注意{OrderId}是结构化日志占位符，它让日志平台可以按 orderId 检索，而不是把敏感信息拼进消息文本。

6.2 对外响应示例

// BAD —— 把内部细节暴露给客户端 catch (Exception ex) { return Problem(detail: ex.StackTrace + ex.Message); } // GOOD —— 对外只给安全提示，细节进服务端日志 catch (Exception ex) { logger.LogError(ex, "Failed to process order {OrderId}", orderId); return Problem( title: "处理请求时发生错误", detail: "请稍后重试，或联系支持人员。", statusCode: StatusCodes.Status500InternalServerError); }

ASP.NET Core 的ProblemDetails（RFC 7807）机制天然适合这种"客户端拿到可读、可展示的错误结构，服务端保留完整异常"的分层设计。

七、与 ECC 安全审查生态的联动

这份规则文档不是孤立存在的——它处在 ECC 仓库"规则 → 代理 → 技能"三层安全体系中：

7.1 csharp-reviewer 的 CRITICAL 检查项

审查代理把安全与错误处理列为 CRITICAL 优先级的完整清单包括：

• SQL 注入：查询中的字符串拼接/插值 → 参数化或 EF Core；
• 命令注入：Process.Start中未验证的输入 → 校验与净化；
• 路径遍历：用户可控文件路径 →Path.GetFullPath+ 前缀检查；
• 不安全反序列化：BinaryFormatter、JsonSerializer配合TypeNameHandling.All；
• 硬编码密钥：源码中的 API 密钥、连接字符串 → 配置/机密管理器；
• CSRF/XSS：缺少[ValidateAntiForgeryToken]、Razor 未编码输出；
• 空 catch 块 / 吞掉异常：catch { }或catch { return null; }；
• 异步阻塞：.Result、.Wait()、.GetAwaiter().GetResult()。

批准标准清晰可执行：无 CRITICAL 或 HIGH 问题才 Approve；发现 CRITICAL/HIGH 直接 Block。这正是本规则文档在真实开发流程中的强制力来源。

7.2 可操作的验证命令

审查代理给出了配套诊断命令，可作为阅读本指南后的自查步骤：

dotnet build # 编译检查 dotnet format --verify-no-changes # 格式与静态分析检查 dotnet test --no-build # 运行测试 dotnet test --collect:"XPlat Code Coverage" # 覆盖率收集

安全相关的测试建议用WebApplicationFactory<TEntryPoint>走真实 HTTP 管线，验证认证 401、授权 403、非法输入 400、限流 429 等行为（详见 rules/csharp/testing.md），而不是绕过中间件直接调用内部方法。

八、落地建议：把规则变成日常习惯

综合本规则文档与仓库其他规则，给出以下可操作的落地顺序：

1. 密钥一律走配置系统：builder.Configuration读取 + 启动时?? throw校验；本地用dotnet user-secrets，生产用云机密管理器；提交前检查appsettings.*.json与git log是否混入凭据；
2. 查询全部参数化：Dapper/ADO.NET 用参数对象，EF Core 用 LINQ；动态排序与过滤字段先过白名单映射（参考 rules/csharp/patterns.md 的 Options 模式集中管理配置键与映射表）；
3. 边界验证：DTO + 数据注解/FluentValidation，[ApiController]自动拒绝无效模型状态，再进入业务逻辑；
4. 认证授权交给框架：JWT Bearer + 授权策略，端点处显式声明；日志与响应中绝不出现令牌、密码、堆栈与 SQL 文本；
5. 纳入自动化：让 csharp-reviewer 代理在代码审查时按 agents/csharp-reviewer.md 的 CRITICAL 清单逐项比对，用dotnet build+dotnet format --verify-no-changes+dotnet test作为进入合并前的质量门禁；
6. 发现泄露立即响应：一旦怀疑密钥暴露，按 rules/common/security.md 的安全响应协议处理——停止当前工作、通知安全审查、优先修复 CRITICAL、轮换所有可能暴露的密钥、并复查整个代码库是否存在同类问题。

九、适用范围与前提说明

本指南依据的是当前仓库 docs/ja-JP/rules/csharp/security.md 及其英文原版、通用基线、审查代理与安全技能的内容。文中框架 API（builder.Configuration、JwtBearerDefaults、[ApiController]、ProblemDetails等）属于 .NET 官方提供的通用能力，落地时请以你实际使用的 .NET 版本与 ASP.NET Core 模板为准；各 ORM 的参数化写法以 Dapper/EF Core 对应版本文档为准。仓库本身不包含可运行的 C# 示例工程，因此文中的完整代码片段属于可复制的落地示范，而非对仓库内既有代码的引用——若需进一步参考，可阅读 rules/csharp/coding-style.md、rules/csharp/patterns.md 与 skills/security-review/SKILL.md 获取配套模式与检查清单。

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