islamelkadi/terraform-aws-apigateway

GitHub: islamelkadi/terraform-aws-apigateway

一个生产就绪的 Terraform 模块,用于在 AWS 上快速部署符合多框架安全合规标准的 API Gateway REST API。

Stars: 0 | Forks: 0

# Terraform AWS API Gateway REST API 模块 [![Terraform Security](https://static.pigsec.cn/wp-content/uploads/repos/2026/03/dd8e973204004825.svg)](https://github.com/islamelkadi/terraform-aws-apigateway/actions/workflows/terraform-security.yaml) [![Terraform Lint & Validation](https://static.pigsec.cn/wp-content/uploads/repos/2026/03/34835fe1a7004827.svg)](https://github.com/islamelkadi/terraform-aws-apigateway/actions/workflows/terraform-lint.yaml) [![Terraform Docs](https://static.pigsec.cn/wp-content/uploads/repos/2026/03/5c01155649004828.svg)](https://github.com/islamelkadi/terraform-aws-apigateway/actions/workflows/terraform-docs.yaml) 此模块用于创建具有 Lambda 集成、Mock 集成、CORS 支持及安全最佳实践的 AWS API Gateway REST API。 ## 目录 - [前置条件](#prerequisites) - [安全](#security) - [功能](#features) - [用法](#usage) - [要求](#requirements) - [MCP 服务器](#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 基础安全最佳实践 (FSBP) - CIS AWS 基础基准 - NIST 800-53 Rev 5 - NIST 800-171 Rev 2 - PCI DSS v4.0 ### 已实施的控制 - [x] **访问日志记录**:用于 API 访问监控的 CloudWatch Logs - [x] **X-Ray 追踪**:用于可观测性的分布式追踪 - [x] **KMS 加密**:用于日志加密的客户托管密钥 - [x] **日志保留**:可配置的保留策略(建议 365 天) - [x] **限流**:速率限制以防止滥用 - [x] **授权**:IAM、Cognito 或 Lambda 授权方 - [x] **WAF 保护**:Web Application Firewall 集成(必需) - [x] **安全控制覆盖**:具有审计理由的可扩展覆盖系统 ### 安全最佳实践 **生产环境 API:** - 启用访问日志记录并保留 365 天 - 启用 X-Ray 追踪以实现可观测性 - 使用 KMS 客户托管密钥进行日志加密 - 配置限流限制 - 使用 IAM 或 Cognito 授权方进行身份验证 - **关联 WAF Web ACL 以防止常见的 Web 攻击** - 仅为受信任的来源启用 CORS - 尽可能使用私有或区域端点 **开发环境 API:** - 访问日志记录可选,以节省成本 - X-Ray 追踪可选 - 可接受较短的日志保留期 有关完整的安全标准和实施细节,请参阅 [AWS 安全标准](../../../.kiro/steering/aws/aws-security-standards.md)。 ### 基于环境的安全控制 安全控制通过 [terraform-aws-metadata](https://github.com/islamelkadi/terraform-aws-metadata?tab=readme-ov-file#security-profiles) 模块的安全配置文件,根据环境自动应用: | 控制项 | Dev | Staging | Prod | |---------|-----|---------|------| | KMS 客户托管密钥 | 可选 | 必需 | 必需 | | 访问日志记录 | 可选 | 必需 | 必需 | | X-Ray 追踪 | 可选 | 必需 | 必需 | | 日志保留期 | 7 天 | 90 天 | 365 天 | | 限流 | 宽松 | 类生产环境 | 强制执行 | 有关安全配置文件及控制如何随环境变化的完整详细信息,请参阅 [安全配置文件](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)** - 在示例代码中被抑制,其中 KMS 模块使用灵活的 IAM 策略用于演示目的 - 生产部署应根据特定安全要求自定义 KMS 策略并应用最小权限原则 **API Gateway 可选功能** - **缓存 (CKV_AWS_120, CKV_AWS_225)**:增加成本的可选功能;根据性能要求启用 - **客户端证书 (CKV2_AWS_51)**:增加复杂性的可选安全功能;根据安全要求启用 - **请求验证 (CKV2_AWS_53)**:需要特定于用例的请求模型;根据 API 要求实施 - **WAF 保护 (CKV2_AWS_29)**:增加显著成本的可选安全功能;根据安全和预算要求启用 ## 功能 - 具有可配置端点类型(EDGE、REGIONAL、PRIVATE)的 REST API - 具有自动权限管理的 Lambda 代理集成 - 用于无后端服务测试的 Mock 集成 - 支持 preflight OPTIONS 的 CORS 配置 - 用于访问日志记录的 CloudWatch Logs 集成 - 用于可观测性的 X-Ray 追踪 - 用于 CloudWatch Logs 的 IAM 角色 - 限流和缓存配置 - **WAF Web ACL 集成(安全必需)** - 具有覆盖能力的安全控制 ### WAF 保护 该模块需要 WAF Web ACL ARN 以防止常见的 Web 攻击。示例包含完整的 WAF 配置(`waf.tf`),具有: - 针对 OWASP Top 10 保护的 AWS 托管规则 - 已知恶意输入阻止 - IP 信誉过滤 - 速率限制(可配置) - 具有敏感字段修订的 CloudWatch 日志记录 ## MCP 服务器 此模块包含两个在 `.kiro/settings/mcp.json` 中配置的 [模型上下文协议 (MCP)](https://modelcontextprotocol.io/) 服务器,用于 Kiro: | 服务器 | 包 | 描述 | |--------|---------|-------------| | `aws-docs` | `awslabs.aws-documentation-mcp-server@latest` | 提供对 AWS 文档的访问,用于服务功能、API 参考和最佳实践的上下文查找。 | | `terraform` | `awslabs.terraform-mcp-server@latest` | 允许直接从 IDE 执行 Terraform 操作(init、validate、plan、fmt、tflint),并为常见工作流提供自动批准的命令。 | 两个服务器都通过 `uvx` 运行,除了 [引导](#prerequisites) 步骤外,不需要额外的安装。 ## 用法 ``` # 主模块示例 - 此演示了 terraform-aws-apigateway 模块 # 支持基础设施 (KMS) 定义在单独的文件中 # 以保持此示例专注于模块的核心功能。 # # API Gateway 模块示例 # 演示带有 mock 集成的 API Gateway module "api_gateway" { source = "../" namespace = var.namespace environment = var.environment name = var.name region = var.region description = var.description # Endpoint configuration endpoint_types = var.endpoint_types disable_execute_api_endpoint = var.disable_execute_api_endpoint # Lambda integration (optional) lambda_integration = var.lambda_integration # Mock integrations mock_integrations = var.mock_integrations # CORS configuration enable_cors = var.enable_cors cors_allow_origin = var.cors_allow_origin cors_allow_methods = var.cors_allow_methods cors_allow_headers = var.cors_allow_headers # Logging configuration enable_access_logging = var.enable_access_logging log_retention_days = var.log_retention_days logging_level = var.logging_level enable_data_trace = var.enable_data_trace # Monitoring enable_xray_tracing = var.enable_xray_tracing enable_metrics = var.enable_metrics # Throttling throttling_burst_limit = var.throttling_burst_limit throttling_rate_limit = var.throttling_rate_limit # Caching enable_caching = var.enable_caching cache_ttl_seconds = var.cache_ttl_seconds cache_data_encrypted = var.cache_data_encrypted # Direct reference to kms.tf module output kms_key_arn = module.kms_key.key_arn # WAF Web ACL ARN (from local WAF resource) waf_acl_arn = aws_wafv2_web_acl.api_gateway.arn # Stage configuration stage_name = var.stage_name stage_description = var.stage_description stage_variables = var.stage_variables tags = var.tags } ``` ## 要求 | 名称 | 版本 | |------|---------| | [terraform](#requirement\_terraform) | >= 1.14.3 | | [aws](#requirement\_aws) | >= 6.34 | ## 提供者 | 名称 | 版本 | |------|---------| | [aws](#provider\_aws) | >= 6.34 | ## 模块 | 名称 | 来源 | 版本 | |------|--------|---------| | [metadata](#module\_metadata) | github.com/islamelkadi/terraform-aws-metadata | v1.0.0 | ## 资源 | 名称 | 类型 | |------|------| | [aws_api_gateway_account.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_account) | resource | | [aws_api_gateway_deployment.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_deployment) | resource | | [aws_api_gateway_integration.cors_options](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_integration) | resource | | [aws_api_gateway_integration.lambda_proxy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_integration) | resource | | [aws_api_gateway_integration.mock](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_integration) | resource | | [aws_api_gateway_integration_response.cors_options](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_integration_response) | resource | | [aws_api_gateway_integration_response.lambda_proxy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_integration_response) | resource | | [aws_api_gateway_integration_response.mock](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_integration_response) | resource | | [aws_api_gateway_method.cors_options](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_method) | resource | | [aws_api_gateway_method.lambda_proxy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_method) | resource | | [aws_api_gateway_method.mock](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_method) | resource | | [aws_api_gateway_method_response.cors_options](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_method_response) | resource | | [aws_api_gateway_method_response.lambda_proxy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_method_response) | resource | | [aws_api_gateway_method_response.mock](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_method_response) | resource | | [aws_api_gateway_method_settings.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_method_settings) | resource | | [aws_api_gateway_resource.mock](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_resource) | resource | | [aws_api_gateway_rest_api.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_rest_api) | resource | | [aws_api_gateway_stage.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/api_gateway_stage) | resource | | [aws_cloudwatch_log_group.api_gateway](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_group) | resource | | [aws_iam_role.cloudwatch](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource | | [aws_iam_role_policy_attachment.cloudwatch](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource | | [aws_lambda_permission.api_gateway](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_permission) | resource | | [aws_wafv2_web_acl_association.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/wafv2_web_acl_association) | resource | | [aws_iam_policy_document.cloudwatch_assume_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source | ## 输入 | 名称 | 描述 | 类型 | 默认值 | 必需 | |------|-------------|------|---------|:--------:| | [access\_log\_format](#input\_access\_log\_format) | 访问日志的格式(建议使用 JSON 格式) | `string` | `"$context.requestId $context.extendedRequestId $context.identity.sourceIp $context.requestTime $context.httpMethod $context.routeKey $context.status $context.protocol $context.responseLength"` | no | | [attributes](#input\_attributes) | 用于命名的额外属性 | `list(string)` | `[]` | no | | [cache\_data\_encrypted](#input\_cache\_data\_encrypted) | 是否加密缓存数据 | `bool` | `true` | no | | [cache\_ttl\_seconds](#input\_cache\_ttl\_seconds) | 缓存 TTL(秒) | `number` | `300` | no | | [cloudwatch\_log\_group\_arn](#input\_cloudwatch\_log\_group\_arn) | 用于访问日志的 CloudWatch Log Group ARN。如果未提供且 create\_log\_group 为 true,将创建一个日志组 | `string` | `null` | no | | [cloudwatch\_role\_arn](#input\_cloudwatch\_role\_arn) | CloudWatch Logs 的 IAM 角色 ARN。仅当 create\_cloudwatch\_role 为 false 时使用 | `string` | `null` | no | | [cors\_allow\_headers](#input\_cors\_allow\_headers) | CORS 允许的标头 | `list(string)` |
[
"Content-Type",
"X-Amz-Date",
"Authorization",
"X-Api-Key",
"X-Amz-Security-Token"
]
| no | | [cors\_allow\_methods](#input\_cors\_allow\_methods) | CORS 允许的方法 | `list(string)` |
[
"GET",
"POST",
"PUT",
"DELETE",
"OPTIONS"
]
| no | | [cors\_allow\_origin](#input\_cors\_allow\_origin) | CORS 允许的来源(例如 '*' 或 'https://example.com') | `string` | `"*"` | no | | [create\_cloudwatch\_role](#input\_create\_cloudwatch\_role) | 是否为 CloudWatch Logs 创建 IAM 角色 | `bool` | `true` | no | | [create\_log\_](#input\_create\_log\_group) | 是否为 API Gateway 创建 CloudWatch Log Group | `bool` | `true` | no | | [delimiter](#input\_delimiter) | 名称组件之间使用的分隔符 | `string` | `"-"` | no | | [description](#input\_description) | API Gateway REST API 的描述 | `string` | `""` | no | | [disable\_execute\_api\_endpoint](#input\_disable\_execute\_api\_endpoint) | 是否禁用默认的 execute-api 端点 | `bool` | `false` | no | | [enable\_access\_logging](#input\_enable\_access\_logging) | 启用访问日志记录到 CloudWatch Logs | `bool` | `true` | no | | [enable\_caching](#input\_enable\_caching) | 启用 API Gateway 缓存 | `bool` | `false` | no | | [enable\_cors](#input\_enable\_cors) | 启用 CORS 配置 | `bool` | `false` | no | | [enable\_data\_trace](#input\_enable\_data\_trace) | 启用数据追踪日志记录(记录完整的请求/响应数据) | `bool` | `false` | no | | [enable\_metrics](#input\_enable\_metrics) | 启用 CloudWatch 指标 | `bool` | `true` | no | | [enable\_xray\_tracing](#input\_enable\_xray\_tracing) | 启用 AWS X-Ray 追踪 | `bool` | `true` | no | | [endpoint\_types](#input\_endpoint\_types) | 端点类型列表(EDGE、REGIONAL 或 PRIVATE) | `list(string)` |
[
"REGIONAL"
]
| no | | [environment](#input\_environment) | 环境名称(dev、staging、prod) | `string` | n/a | yes | | [kms\_key\_arn](#input\_kms\_key\_arn) | 用于加密的 KMS 密钥 ARN。如果未提供,则使用 AWS 托管密钥 | `string` | `null` | no | | [lambda\_integration](#input\_lambda\_integration) | Lambda 集成配置。设置为 null 以禁用 Lambda 集成。

字段:
- lambda\_function\_name:要集成的 Lambda 函数名称
- lambda\_invoke\_arn:Lambda 函数的调用 ARN
- http\_methods:要集成的 HTTP 方法列表(例如 ["GET", "POST"])
- resource\_id:API Gateway 资源 ID(可选,默认为根资源)
- authorization\_type:授权类型(NONE、AWS\_IAM、CUSTOM、COGNITO\_USER\_POOLS)
- authorizer\_id:授权方 ID(可选)
- request\_validator\_id:请求验证器 ID(可选)
- api\_key\_required:是否需要 API 密钥(默认:false)
- timeout\_milliseconds:集成超时时间(毫秒)(默认:29000) |
object({
lambda_function_name = string
lambda_invoke_arn = string
http_methods = list(string)
resource_id = optional(string, null)
authorization_type = optional(string, "NONE")
authorizer_id = optional(string, null)
request_validator_id = optional(string, null)
api_key_required = optional(bool, false)
timeout_milliseconds = optional(number, 29000)
})
| `null` | no | | [log\_retention\_days](#input\_log\_retention\_days) | CloudWatch 日志保留天数 | `number` | `365` | no | | [logging\_level](#input\_logging\_level) | API Gateway 日志级别(OFF、ERROR、INFO) | `string` | `"INFO"` | no | | [mock\_integrations](#input\_mock\_integrations) | 用于无后端服务测试的 Mock API 集成列表。
每个集成包括:
- path:API 路径(例如 "/health"、"/status")
- http\_method:HTTP 方法(GET、POST 等)
- status\_code:响应状态码(默认:200)
- response\_body:Mock 响应体(默认:{"message": "OK"})
- authorization\_type:授权类型(默认:NONE) |
list(object({
path = string
http_method = string
status_code = optional(number, 200)
response_body = optional(string, "{\"message\": \"OK\"}")
authorization_type = optional(string, "NONE")
}))
| `[]` | no | | [name](#input\_name) | API Gateway REST API 的名称 | `string` | n/a | yes | | [namespace](#input\_namespace) | 命名空间(组织/团队名称) | `string` | n/a | yes | | [region](#input\_region) | 创建资源的 AWS 区域 | `string` | n/a | yes | | [security\_control\_overrides](#input\_security\_control\_overrides) | 覆盖此 API Gateway 的特定安全控制。
仅在有书面业务理由时使用。

示例用例:
- disable\_access\_logging:无敏感数据的开发环境 API
- disable\_xray\_tracing:低价值 API 的成本优化
- disable\_kms\_requirement:无敏感数据的公共 API

重要:出于审计目的,请在 'justification' 字段中记录原因。 |
object({
disable_access_logging = optional(bool, false)
disable_xray_tracing = optional(bool, false)
disable_kms_requirement = optional(bool, false)
disable_cloudwatch_logs = optional(bool, false)
disable_log_retention_validation = optional(bool, false)

# Audit trail - document why controls are disabled
justification = optional(string, "")
})
|
{
"disable_access_logging": false,
"disable_cloudwatch_logs": false,
"disable_kms_requirement": false,
"disable_log_retention_validation": false,
"disable_xray_tracing": 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
})
network = object({
require_private_subnets = bool
require_vpc_endpoints = bool
block_public_ingress = bool
require_imdsv2 = bool
})
compliance = object({
enable_point_in_time_recovery = bool
require_reserved_concurrency = bool
enable_deletion_protection = bool
})
})
| `null` | no | | [stage\_description](#input\_stage\_description) | API Gateway 阶段的描述 | `string` | `""` | no | | [stage\_name](#input\_stage\_name) | API Gateway 阶段的名称 | `string` | `"prod"` | no | | [stage\_variables](#input\_stage\_variables) | 阶段变量映射 | `map(string)` | `{}` | no | | [tags](#input\_tags) | 应用于资源的额外标签 | `map(string)` | `{}` | no | | [throttling\_burst\_limit](#input\_throttling\_burst\_limit) | API Gateway 限流突发限制 | `number` | `5000` | no | | [throttling\_rate\_limit](#input\_throttling\_rate\_limit) | API Gateway 限流速率限制(每秒请求数) | `number` | `10000` | no | | [waf\_acl\_arn](#input\_waf\_acl\_arn) | 要与 API Gateway 阶段关联的 WAF Web ACL ARN。生产环境必需,以防止常见的 Web 攻击 | `string` | n/a | yes | ## 输出 | 名称 | 描述 | |------|-------------| | [api\_endpoint](#output\_api\_endpoint) | 完整的 API 端点 URL(调用 URL) | | [cloudwatch\_role\_arn](#output\_cloudwatch\_role\_arn) | CloudWatch Logs IAM 角色的 ARN | | [deployment\_id](#output\_deployment\_id) | API Gateway 部署的 ID | | [log\_group\_arn](#output\_log\_group\_arn) | CloudWatch Log Group 的 ARN | | [log\_group\_name](#output\_log\_group\_name) | CloudWatch Log Group 的名称 | | [mock\_endpoints](#output\_mock\_endpoints) | Mock 端点 URL 列表 | | [mock\_resource\_ids](#output\_mock\_resource\_ids) | Mock 集成资源 ID 的映射 | | [rest\_api\_arn](#output\_rest\_api\_arn) | REST API 的 ARN | | [rest\_api\_execution\_arn](#output\_rest\_api\_execution\_arn) | REST API 的执行 ARN | | [rest\_api\_id](#output\_rest\_api\_id) | REST API 的 ID | | [rest\_api\_name](#output\_rest\_api\_name) | REST API 的名称 | | [rest\_api\_root\_resource\_id](#output\_rest\_api\_root\_resource\_id) | REST API 的根资源 ID | | [stage\_arn](#output\_stage\_arn) | API Gateway 阶段的 ARN | | [stage\_id](#output\_stage\_id) | API Gateway 阶段的 ID | | [stage\_invoke\_url](#output\_stage\_invoke\_url) | API Gateway 阶段的调用 URL | | [stage\_name](#output\_stage\_name) | API Gateway 阶段的名称 | | [tags](#output\_tags) | 应用于 API Gateway 的标签 | ## 示例 有关包含所有功能的完整工作示例,请参阅 [example/](example/)。 ## 许可证 MIT 许可。有关完整详细信息,请参阅 [LICENSE](LICENSE)。 END_TF_DOCS -->
标签:API Gateway, AWS, CIS, CISA项目, CloudWatch, CORS, DPI, EC2, ECS, FSBP, IaC, KMS, Lambda, NIST, PCI DSS, Python, REST API, Streamlit, StruQ, Terraform, Tflint, X-Ray, 云安全监控, 人工智能安全, 代码复用, 企业级, 加密, 合规性, 无后门, 无服务器, 漏洞扫描器, 特权提升, 自动化部署, 访问控制, 逆向工具, 静态分析