企业官网建设流程全解析

• 应用安全
• SAST
• IaC

导读：aws-documentdb-encryption-customer-key是 tfsec 内置的 AWS 静态检查规则，用于在 Terraform 配置中识别未指定kms_key_id的aws_docdb_cluster资源，从而强制 DocumentDB 底层存储使用客户管理密钥（Customer Managed Key，CMK）加密。本文将围绕该检查的判定逻辑、默认严重级别、不安全/安全示例展开，并结合 tfsec 源码说明如何运行、过滤与定制该检查，帮助读者在 CI 流水线中落地更细粒度的 KMS 加密控制。

一、检查项概览

该检查隶属于 tfsec 的 AWS DocumentDB 检查组。同一组的其他检查还包括：

• aws-documentdb-enable-log-export：DocumentDB 日志导出应开启（文档）；
• aws-documentdb-enable-storage-encryption：DocumentDB 存储必须加密（文档）。

三个检查的完整目录索引见 docs/checks/aws/documentdb/index.md，mkdocs 站点导航中的组织方式见 mkdocs.yml。

二、检查原理：AWS 托管密钥 vs 客户管理密钥

检查文档的 Explanation 明确阐述了规则背后的安全动机：

Encryption using AWS keys provides protection for your DocumentDB underlying storage. To increase control of the encryption and manage factors like rotation use customer managed keys.

AWS DocumentDB 对底层存储（含备份与快照）的静态加密默认由 AWS 托管的 KMS 密钥完成，这能提供基础的数据保护；但若需要更细粒度的控制——例如自定义密钥生命周期、独立审计、按组织规范管理密钥轮换（rotation）策略——则应改用客户管理密钥（CMK），并在 Terraform 资源中通过kms_key_id显式指定。

对应地，Possible Impact 指出不满足要求时的风险：

Using AWS managed keys does not allow for fine grained control

即：仅使用 AWS 托管密钥时，密钥的创建、轮换、禁用与删除均由 AWS 全权管理，无法满足合规或审计上对"加密密钥自主可控"的诉求。Suggested Resolution 给出的修复方向是 "Enable encryption using customer managed keys"。

值得注意的是，aws-documentdb-encryption-customer-key关注的是密钥归属与控制权，而姊妹检查aws-documentdb-enable-storage-encryption关注的是存储加密开关本身是否开启（通过storage_encrypted参数判定，见 enable-storage-encryption/index.md）。两者可以组合使用：先保证storage_encrypted = true，再进一步要求kms_key_id指向客户管理密钥，构成"加密已启用 + 密钥可自主管理"的完整防线。

三、不安全示例：未指定 kms_key_id 将触发告警

以下 Terraform 配置无法通过aws-documentdb-encryption-customer-key检查（判定为 FAIL）：

resource "aws_docdb_cluster" "docdb" { cluster_identifier = "my-docdb-cluster" engine = "docdb" master_username = "foo" master_password = "mustbeeightchars" backup_retention_period = 5 preferred_backup_window = "07:00-09:00" skip_final_snapshot = true }

逐项解读：

• engine = "docdb"指明这是 Amazon DocumentDB 集群；
• master_username/master_password用于初始化管理员账号；
• backup_retention_period与preferred_backup_window定义备份保留与时间窗口；
• skip_final_snapshot = true表示删除集群时跳过最终快照（生产环境通常不建议）；
• 关键缺陷：整个资源块中没有kms_key_id参数。tfsec 扫描器解析到aws_docdb_cluster资源后，若发现缺少该参数（或该参数为空值），即判定本次检查失败——这意味着集群将回退到 AWS 托管密钥加密，失去密钥控制权。

四、修复方案：显式引用客户管理密钥

以下配置可以通过该检查（判定为 PASS）：

resource "aws_kms_key" "docdb_encryption" { enable_key_rotation = true } resource "aws_docdb_cluster" "docdb" { cluster_identifier = "my-docdb-cluster" engine = "docdb" master_username = "foo" master_password = "mustbeeightchars" backup_retention_period = 5 preferred_backup_window = "07:00-09:00" skip_final_snapshot = true kms_key_id = aws_kms_key.docdb_encryption.arn }

修复要点：

1. 新建 KMS 密钥资源：aws_kms_key "docdb_encryption"即客户管理密钥，建议同时设置enable_key_rotation = true，让 KMS 自动按年度轮换密钥材料——这正是文档中"manage factors like rotation"的直接落地；
2. 建立引用：在aws_docdb_cluster中通过kms_key_id = aws_kms_key.docdb_encryption.arn把集群加密绑定到该 CMK；
3. 实践建议：在真实生产代码中，通常通过data "aws_kms_key"引用既有密钥，或把 KMS ARN 收敛为变量（如kms_key_id = var.docdb_kms_key_arn）以便多环境复用；同时建议结合aws_docdb_cluster的参数别名（parameter group）与备份配置统一治理。

参数名、取值范围与行为细节以 Terraform AWS Provider 的aws_docdb_cluster资源文档（kms_key_id字段）和 AWS DocumentDB 加密相关官方文档为准。

五、在 tfsec 中运行与验证该检查

1. 基础扫描

在当前目录（或指定目录）运行扫描：

tfsec . # 或指定路径 tfsec ./path/to/terraform

入口流程见 internal/app/tfsec/cmd/root.go：命令解析目录后，通过scanner.New(options...)构建 defsec 的 Terraform 扫描器，再调用ScanFSWithMetrics完成资源解析与规则匹配。

2. 只保留本条检查

使用--filter-results仅输出指定检查（源码实现见 internal/app/tfsec/cmd/flags.go，内部转换为ScannerWithIncludedRules）：

tfsec . --filter-results aws-documentdb-encryption-customer-key

3. 按严重级别过滤

默认严重级别为low，可使用--minimum-severity提高门槛（合法值为CRITICAL/HIGH/MEDIUM/LOW，校验逻辑见 internal/app/tfsec/cmd/flags.go）：

# 只报告 MEDIUM 及以上，此时 low 级别的本检查将被忽略 tfsec . --minimum-severity MEDIUM

4. 在配置文件中覆盖严重级别

tfsec 支持在项目.tfsec/config.yml（或config.json/config.yaml）中通过severity_overrides提升或降低该检查的严重级别，例如把低风险的 CMK 缺失提升为MEDIUM以便纳入准入控制。配置加载与覆盖逻辑见 internal/app/tfsec/cmd/flags.go。

5. 与退出码联动

tfsec 依据结果计算退出码（internal/app/tfsec/cmd/root.go）：

• 全部通过 →0；
• 存在失败但全部为 LOW 级别→ 特殊失败码2；
• 存在任何 CRITICAL/HIGH/MEDIUM 失败 → 失败码1。

由于本检查默认是 LOW，单独触发时通常得到退出码2；若通过severity_overrides提升为 MEDIUM 及以上，则会使流水线以1失败。这一机制使团队可以按风险偏好决定"低风险项仅告警"还是"强制阻断"。

六、源码视角：该检查在 tfsec 体系中的定位

• 文档组织：每条检查的说明页位于docs/checks/aws/documentdb/目录，由 mkdocs.yml 的documentdb小节统一渲染成站点导航，形成"检查目录页 + 单条检查页"的文档结构；
• ID 映射：在 internal/pkg/legacy/map.go 的旧版 ID 映射表（如AWS061→aws-api-gateway-enable-access-logging）中未出现documentdb 相关条目，可以推断该检查属于较新加入的规则集合，不存在旧版短 ID，因此排障/忽略时应直接使用长 IDaws-documentdb-encryption-customer-key；
• 扫描管线：检查规则本身由底层 defsec 的嵌入式策略集提供（options.ScannerWithEmbeddedPolicies(true)，见 internal/app/tfsec/cmd/flags.go），tfsec CLI 负责目录发现、HCL 解析、结果过滤与多格式输出；
• 项目状态：tfsec 现已并入 Trivy 生态，迁移路径与差异说明见仓库根目录的 tfsec-to-trivy-migration-guide.md，在 Trivy 中使用时请注意检查 ID 与输出格式的对应关系。

七、快速自查清单

在提交 DocumentDB 相关 Terraform 变更前，建议对照以下清单：

• aws_docdb_cluster已设置storage_encrypted = true（对应aws-documentdb-enable-storage-encryption）；
• 已创建或引用客户管理 KMS 密钥，并通过kms_key_id显式绑定到集群；
• KMS 密钥已开启enable_key_rotation，符合轮换管理要求；
• 已在 CI 中运行tfsec（或 Trivy），确认aws-documentdb-encryption-customer-key通过；
• 若暂无法修复，已通过.tfsec/config.yml的exclude或注释tfsec:ignore显式登记例外，并评估了风险等级。

通过以上配置，即可在 IaC 阶段提前拦截"DocumentDB 加密密钥不可控"的配置漂移，将加密控制权牢牢掌握在团队手中。

• 应用安全
• SAST
• IaC