islamelkadi/terraform-aws-kms
GitHub: islamelkadi/terraform-aws-kms
生产级 AWS KMS Terraform 模块，提供开箱即用的多框架合规支持和自动化安全控制。
Stars: 0 | Forks: 0
# Terraform AWS KMS 模块
[](https://github.com/islamelkadi/terraform-aws-kms/actions/workflows/terraform-security.yaml)
[](https://github.com/islamelkadi/terraform-aws-kms/actions/workflows/terraform-lint.yaml)
[](https://github.com/islamelkadi/terraform-aws-kms/actions/workflows/terraform-docs.yaml)
一个可复用的 Terraform 模块，用于创建符合 AWS Security Hub 合规性 (FSBP, CIS, NIST 800-53, NIST 800-171, PCI DSS) 要求的 AWS KMS Customer Managed Keys (CMK)，支持自动密钥轮换和灵活的安全控制覆盖。
## 目录
- [前置条件](#prerequisites)
- [安全](#security)
- [功能](#features)
- [用法](#usage)
- [要求](#requirements)
- [MCP Servers](#mcp-servers)
## 前置条件
本模块专为 macOS 设计。您的机器上必须已安装以下软件：
- Python 3 和 pip
- [Kiro](https://kiro.dev) 和 Kiro CLI
- [Homebrew](https://brew.sh)
要安装其余的开发工具，请运行：
```
make bootstrap
```
这将安装/升级：tfenv、Terraform (通过 tfenv)、tflint、terraform-docs、checkov 和 pre-commit。
## 安全
### 安全控制
本模块实现了 AWS Security Hub 合规性，并配备了一个可扩展的覆盖系统。
### 可用的安全控制覆盖
| 覆盖标志 | 描述 | 常见理由 |
|--------------|-------------|---------------------|
| `disable_key_rotation_requirement` | 禁用自动密钥轮换 | “导入的密钥材料，手动轮换流程” |
| `disable_deletion_window_validation` | 允许较短的删除窗口 | “开发密钥，需要更快地拆除” |
### 安全最佳实践
**生产环境密钥：**
- 启用自动密钥轮换（365 天）
- 将删除窗口设置为 30 天（最大值）
- 明确定义密钥管理员和用户
- 启用 CloudWatch Logs 访问权限以用于日志加密
- 使用多区域密钥以实现灾难恢复
**开发环境密钥：**
- 仍然建议进行密钥轮换
- 可以接受较短的删除窗口（7-14 天）
### 基于环境的安全控制
安全控制通过 [terraform-aws-metadata](https://github.com/islamelkadi/terraform-aws-metadata?tab=readme-ov-file#security-profiles) 模块的安全配置文件，根据环境自动应用：
| 控制 | Dev | Staging | Prod |
|---------|-----|---------|------|
| KMS customer-managed keys | 可选 | 必需 | 必需 |
| 密钥轮换 | 建议 | 必需 | 必需 |
| 删除窗口 | 7 天 | 14-30 天 | 30 天 |
| CloudWatch Logs 访问 | 可选 | 建议 | 必需 |
有关安全配置文件以及控制如何随环境变化的完整详细信息，请参阅 [安全配置文件](https://github.com/islamelkadi/terraform-aws-metadata?tab=readme-ov-file#security-profiles) 文档。
### 安全扫描抑制
本模块抑制了某些 Checkov 安全检查，这些检查要么不适用于示例/演示代码，要么代表了有意的设计选择。以下检查在 `.checkov.yaml` 中被抑制：
**模块源版本控制 (CKV_TF_1, CKV_TF_2)**
- 被抑制是因为我们使用语义版本标签 (`?ref=v1.0.0`) 而不是提交哈希，以提高可维护性和可读性
- 语义版本控制是稳定版本的有效且广泛接受的版本控制策略
**KMS IAM 策略 (CKV_AWS_111, CKV_AWS_356, CKV_AWS_109)**
- 被抑制是因为本模块有意使用灵活的 IAM 策略进行演示
- 该模块生成的 IAM 策略文档允许广泛的权限，以演示 KMS 密钥使用模式
- 生产部署应根据具体的安全要求自定义这些策略，并应用最小权限原则
- 用户应根据其组织的安全策略限制资源访问和操作
## 功能
- KMS customer-managed key (CMK)
- 自动密钥轮换
- 可配置的删除窗口（7-30 天）
- 密钥策略管理
- 多区域密钥支持
- CloudWatch Logs 集成
- 安全控制集成
## 使用示例
### 基本示例
```
module "kms_key" {
source = "github.com/islamelkadi/terraform-aws-kms"
namespace = "example"
environment = "prod"
name = "data-encryption"
region = "us-east-1"
description = "KMS key for encrypting sensitive data"
key_administrators = [
"arn:aws:iam::123456789012:role/admin"
]
key_users = [
module.lambda.role_arn,
module.s3.role_arn
]
tags = {
Project = "CorporateActions"
}
}
```
### 带安全控制的生产环境密钥
```
module "kms_key" {
source = "github.com/islamelkadi/terraform-aws-kms"
security_controls = module.metadata.security_controls
namespace = "example"
environment = "prod"
name = "corporate-actions-encryption"
region = "us-east-1"
description = "KMS key for Corporate Actions application encryption"
# Automatic key rotation enabled
enable_key_rotation = true
# Maximum deletion window for production
deletion_window_in_days = 30
# Key administrators
key_administrators = [
"arn:aws:iam::123456789012:role/SecurityAdmin",
"arn:aws:iam::123456789012:role/InfraAdmin"
]
# Key users (services that encrypt/decrypt)
key_users = [
module.lambda.role_arn,
module.rds.role_arn,
module.s3.role_arn,
module.dynamodb.role_arn
]
# Allow CloudWatch Logs to use key
enable_cloudwatch_logs_access = true
# Service principals
service_principals = [
"lambda.amazonaws.com",
"s3.amazonaws.com",
"dynamodb.amazonaws.com"
]
tags = {
Project = "CorporateActions"
DataClass = "Confidential"
Compliance = "PCI-DSS"
}
}
```
### 用于灾难恢复的多区域密钥
```
module "kms_key_primary" {
source = "github.com/islamelkadi/terraform-aws-kms"
security_controls = module.metadata.security_controls
namespace = "example"
environment = "prod"
name = "multi-region-encryption"
region = "us-east-1"
description = "Multi-region KMS key for disaster recovery"
# Enable multi-region
multi_region = true
enable_key_rotation = true
deletion_window_in_days = 30
key_administrators = [
"arn:aws:iam::123456789012:role/SecurityAdmin"
]
key_users = [
module.lambda.role_arn
]
tags = {
Project = "CorporateActions"
DR = "Enabled"
}
}
# 次要区域中的 Replica
module "kms_key_replica" {
source = "github.com/islamelkadi/terraform-aws-kms"
providers = {
aws = aws.us-east-1
}
namespace = "example"
environment = "prod"
name = "multi-region-encryption-replica"
region = "us-east-1"
description = "Replica of multi-region KMS key"
# Reference primary key
primary_key_arn = module.kms_key_primary.key_arn
tags = {
Project = "CorporateActions"
DR = "Replica"
}
}
```
## MCP Servers
本模块包含两个在 `.kiro/settings/mcp.json` 中配置的 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，以便与 Kiro 配合使用：
| Server | Package | 描述 |
|--------|---------|-------------|
| `aws-docs` | `awslabs.aws-documentation-mcp-server@latest` | 提供对 AWS 文档的访问，用于服务功能、API 参考和最佳实践的上下文查找。 |
| `terraform` | `awslabs.terraform-mcp-server@latest` | 支持直接从 IDE 执行 Terraform 操作（init、validate、plan、fmt、tflint），并为常见工作流提供自动批准的命令。 |
这两个服务器都通过 `uvx` 运行，除了 [bootstrap](#prerequisites) 步骤外，不需要额外的安装。
## 用法
```
# 基础 KMS 模块示例
module "kms" {
source = "github.com/islamelkadi/terraform-aws-kms"
namespace = var.namespace
environment = var.environment
name = var.name
description = var.description
region = var.region
# Use default settings (rotation enabled, 30-day deletion window)
tags = var.tags
}
```
## 要求
| Name | Version |
|------|---------|
| [terraform](#requirement\_terraform) | >= 1.14.3 |
| [aws](#requirement\_aws) | >= 6.34 |
## Providers
| Name | Version |
|------|---------|
| [aws](#provider\_aws) | >= 6.34 |
## 模块
| Name | Source | Version |
|------|--------|---------|
| [metadata](#module\_metadata) | github.com/islamelkadi/terraform-aws-metadata | v1.1.0 |
## 资源
| Name | Type |
|------|------|
| [aws_kms_alias.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_alias) | resource |
| [aws_kms_key.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_key) | resource |
| [aws_iam_policy_document.default](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
## 输入
| Name | Description | Type | Default | Required |
|------|-------------|------|---------|:--------:|
| [attributes](#input\_attributes) | 用于命名的额外属性 | `list(string)` | `[]` | no |
| [deletion\_window\_in\_days](#input\_deletion\_window\_in\_days) | 销毁后删除密钥前的天数（7-30 天） | `number` | `30` | no |
| [delimiter](#input\_delimiter) | 名称组件之间使用的分隔符 | `string` | `"-"` | no |
| [description](#input\_description) | KMS 密钥的描述 | `string` | n/a | yes |
| [enable\_cloudwatch\_logs\_access](#input\_enable\_cloudwatch\_logs\_access) | 允许 CloudWatch Logs 使用该密钥进行日志组加密 | `bool` | `false` | no |
| [enable\_key\_rotation](#input\_enable\_key\_rotation) | 启用自动密钥轮换 | `bool` | `true` | no |
| [environment](#input\_environment) | 环境名称 (dev, staging, prod) | `string` | n/a | yes |
| [key\_administrators](#input\_key\_administrators) | 可以管理密钥的 IAM role/user ARN 列表 | `list(string)` | `[]` | no |
| [key\_policy](#input\_key\_policy) | 自定义密钥策略 JSON。如果未提供，将创建默认策略 | `string` | `null` | no |
| [key\_users](#input\_key\_users) | 可以使用密钥进行加密/解密的 IAM role/user ARN 列表 | `list(string)` | `[]` | no |
| [multi\_region](#input\_multi\_region) | 创建多区域密钥 | `bool` | `false` | no |
| [name](#input\_name) | KMS 密钥的名称 | `string` | n/a | yes |
| [namespace](#input\_namespace) | Namespace（组织/团队名称） | `string` | n/a | yes |
| [region](#input\_region) | 创建资源的 AWS 区域 | `string` | n/a | yes |
| [security\_control\_overrides](#input\_security\_control\_overrides) | 通过书面理由覆盖特定的安全控制 |
object({
disable_key_rotation_requirement = optional(bool, false)
disable_deletion_window_validation = optional(bool, false)
justification = optional(string, "")
}) | {
"disable_deletion_window_validation": false,
"disable_key_rotation_requirement": false,
"justification": ""
} | no |
| [security\_controls](#input\_security\_controls) | 来自 metadata 模块的安全控制配置 | object({
encryption = object({
require_kms_customer_managed = bool
require_encryption_at_rest = bool
require_encryption_in_transit = bool
enable_kms_key_rotation = bool
})
logging = object({
require_cloudwatch_logs = bool
min_log_retention_days = number
require_access_logging = bool
require_flow_logs = bool
})
monitoring = object({
enable_xray_tracing = bool
enable_enhanced_monitoring = bool
enable_performance_insights = bool
require_cloudtrail = bool
})
compliance = object({
enable_point_in_time_recovery = bool
require_reserved_concurrency = bool
enable_deletion_protection = bool
})
}) | `null` | no |
| [service\_principals](#input\_service\_principals) | 可以使用密钥的 AWS service principals 列表（例如 lambda.amazonaws.com, s3.amazonaws.com） | `list(string)` | `[]` | no |
| [tags](#input\_tags) | 应用到资源的额外标签 | `map(string)` | `{}` | no |
## 输出
| Name | Description |
|------|-------------|
| [alias\_arn](#output\_alias\_arn) | KMS 密钥别名 ARN |
| [alias\_name](#output\_alias\_name) | KMS 密钥别名名称 |
| [key\_arn](#output\_key\_arn) | KMS 密钥 ARN |
| [key\_id](#output\_key\_id) | KMS 密钥 ID |
| [key\_policy](#output\_key\_policy) | KMS 密钥策略 |
| [tags](#output\_tags) | 应用到 KMS 密钥的标签 |
## 示例
有关包含密钥策略配置的完整工作示例，请参阅 [example/](example/)。
标签：Amazon Web Services, AWS KMS, CIS, CMK, EC2, ECS, FSBP, IaC, NIST, PCI DSS, Python, Security Hub, Terraform, Terraform Module, 企业级, 安全合规, 密钥轮换, 数据加密, 无后门, 模块, 特权提升, 网络代理, 自动化部署, 身份与访问管理, 预生产