angie-in-the-cloud/circleci-aws-opa-terraform-lab

# CircleCI + AWS + OPA + Terraform 实验教程 一个演示如何使用 CircleCI、AWS OIDC、Open Policy Agent 和 Terraform 实现云安全自动化的动手实验。 ## 为什么这很重要 在大多数组织中，合规性审查发生在基础设施部署之后。审查人员手动检查资源是否符合策略，记录证据，并标记需要修复的问题。这个过程不仅缓慢、重复，而且常常会遗漏两次审查之间发生的配置漂移。 本实验将合规性检查左移。在任何 AWS 资源部署之前，流水线就会根据安全策略对其进行检查。如果资源未通过检查，流水线将阻止部署。这使得合规性成为自动化、持续的过程，并内置于部署流程中，而不是事后修补。 ## 本实验演示的内容 | 内容 | 方式 | |---|---| | 策略即代码 | 使用 OPA Rego 编写安全规则，可进行版本控制和测试 | | CI/CD 自动化 | CircleCI 流水线在每次推送时运行安全检查 | | 安全的 AWS 身份验证 | 基于 OIDC 的身份验证，不在任何地方存储长期凭证 | | 基础设施即代码 | Terraform 在 AWS 中配置合规的 S3 存储桶 | | 合规关卡 | 如果任何安全检查未通过，流水线会自动停止 | ## 仓库结构 | 文件 | 用途 | | --- | --- | | `.circleci/config.yml` | 流水线定义 | | `policies/s3.rego` | OPA 安全策略 | | `policies/s3_test.rego` | OPA 策略测试 | | `terraform/main.tf` | 基础设施蓝图 | | `compliant-s3.json` | 合规的 S3 资源示例 | | `non-compliant-s3.json` | 不合规的 S3 资源示例 | | `aws-configs/circleci-trust-policy.json` | AWS 信任策略 | | `aws-configs/circleci-policy.json` | AWS 权限策略 | ## 流水线作业 流水线运行在 `.circleci/config.yml` 中定义的五个作业： | 作业 | 功能 | |---|---| | `test-aws-oidc` | 验证 CircleCI 是否可以使用 OIDC 向 AWS 进行身份验证 | | `test-opa-policies` | 运行 `s3_test.rego` 中的三个 OPA 单元测试 | | `validate-compliant-resource` | 将 `compliant-s3.json` 传递给 OPA - 期望零违规 | | `validate-non-compliant-resource` | 将 `non-compliant-s3.json` 传递给 OPA - 期望出现违规 | | `validate-terraform` | 运行 `terraform init`、`validate` 和 `apply` 来配置基础设施 | **作业执行顺序：** `test-aws-oidc` 和 `test-opa-policies` 在流水线开始时并行运行。一旦 `test-opa-policies` 通过，两个 OPA 验证作业（`validate-compliant-resource` 和 `validate-non-compliant-resource`）将并行运行。当这两个 OPA 验证作业都通过后，`validate-terraform` 将运行并配置存储桶。 ## 逐步实验设置 ### 第 1 步：创建 GitHub 仓库 创建一个名为以下名称的新 GitHub 仓库： ``` circleci-aws-opa-terraform-lab ``` 将上面仓库结构中列出的所有项目文件添加进去，并将它们提交到 `main` 分支。 ### 第 2 步：将仓库连接到 CircleCI 1. 前往 CircleCI (https://app.circleci.com/login) 2. 点击 **Log in with GitHub** 3. 前往 **Projects** 并找到你的仓库：`circleci-aws-opa-terraform-lab` 4. 点击 **Set Up Project** 5. 如果出现提示，请选择 `main` 作为默认分支 CircleCI 现在将监视此仓库，并在每次推送时触发流水线。 ### 第 2A 步：授权 CircleCI 通过 SSH 访问 GitHub 如果不执行此步骤，每个作业都会在 checkout 阶段失败，并显示 `Permission denied (publickey)` 错误。 1. 前往你的 CircleCI 项目 **Settings** 2. 点击左侧面板中的 **SSH Keys** 3. 在 **User Key** 下，点击 **Authorize with GitHub** 4. 点击 **Add User Key** 5. 点击 **Confirm User** ### 第 3 步：获取你的 CircleCI ID 你将需要你的 **Organization ID** 和 **Project ID**，用于 AWS 信任策略。 **Organization ID：** 1. 在 CircleCI 中，点击左侧面板中的 **Org** 2. 从此页面复制 Organization ID **Project ID：** 1. 返回主页选项卡 2. 在你的项目卡片上，点击 **Overview**，然后点击 **Settings** 3. 从此页面复制 Project ID ### 第 4 步：创建 AWS OIDC 身份提供商 这会告诉 AWS 信任由 CircleCI 颁发的 token。 1. 前往 **AWS IAM → Identity providers** 2. 点击 **Add provider** 3. 对于 Provider type，选择 **OpenID Connect** 4. 对于 Provider URL，输入：`https://oidc.circleci.com/org/` 5. 对于 Audience，输入你的 **Organization ID**（必须完全匹配） 6. 点击 **Add provider** ### 第 5 步：创建 CircleCI 将要扮演的 IAM 角色 1. 前往 **AWS IAM → Roles → Create role** 2. 选择 **Web identity** 作为受信任的实体类型 3. 选择你刚刚创建的 OIDC 提供商 4. 选择你的 **Organization ID** 作为 Audience 5. 点击 **Next** 6. 搜索并附加 **AmazonS3FullAccess** 7. 命名角色：`CircleCI-OIDC-Lab-Role` 8. 点击 **Create role** ### 第 6 步：更新信任策略 信任策略限制了哪些 CircleCI 组织和项目可以扮演该角色。 打开 `aws-configs/circleci-trust-policy.json`，确认你的 **AWS Account ID**、**Org ID** 和 **Project ID** 在所有出现的位置都已正确设置： - **Federated ARN** - 包含你的 AWS 账户 ID 和组织 ID - **Condition key names** - 包含你的组织 ID - **`aud` value** - 你的组织 ID - **`sub` value** - 同时包含你的组织 ID 和项目 ID 然后前往 **AWS IAM → Roles → CircleCI-OIDC-Lab-Role → Trust relationships → Edit trust policy**，粘贴 `circleci-trust-policy.json` 的内容并保存。 ### 第 7 步：将角色 ARN 添加到 CircleCI 从你的 IAM 角色中复制 ARN。它看起来像这样： ``` arn:aws:iam::123456789012:role/CircleCI-OIDC-Lab-Role ``` 然后在 CircleCI 中： 1. 前往你的项目 **Settings → Environment Variables** 2. 点击 **Add Variable** 3. Name：`AWS_ROLE_ARN` - Value：你的角色 ARN ### 第 8 步：查看关键文件 **`policies/s3.rego`** OPA 策略文件。包含两条规则：S3 存储桶必须启用服务器端加密，以及 S3 存储桶不得使用 `public-read` ACL。 **`policies/s3_test.rego`** 在自动化运行之前测试策略逻辑。确认该策略能够正确允许合规的存储桶并捕获违规情况。 **`terraform/main.tf`** 基础设施蓝图。定义了一个启用了加密、版本控制和公共访问屏蔽的合规 S3 存储桶。 **`aws-configs/circleci-trust-policy.json`** 控制谁被允许扮演 IAM 角色 - 限定为你特定的 CircleCI 组织和项目。 **`aws-configs/circleci-policy.json`** 控制 CircleCI 在扮演该角色后在 AWS 中被允许执行的操作。 ### 第 9 步：触发流水线 向 GitHub 推送一次提交 - CircleCI 会检测到并自动触发流水线。 或者在 CircleCI 中手动触发： 1. 点击右上角的 **Trigger Pipeline** 2. 从 Config source 下拉菜单中选择 **main** 3. 点击 **Run Pipeline** ### 第 10 步：观察流水线运行 在 CircleCI 中你会看到全部五个作业。点击任何作业可查看其日志。 **需要注意的内容：** - **`test-aws-oidc`** - 查看显示为绿色的 `Test AWS authentication with OIDC` 步骤。这确认了 CircleCI 和 AWS 之间的秘密握手成功。 - **`test-opa-policies`** - 确认所有三个 OPA 单元测试均已通过。 - **`validate-compliant-resource`** - OPA 发现零违规。好的存储桶通过了检查。 - **`validate-non-compliant-resource`** - OPA 发现了违规。坏的存储桶被成功阻止。 - **`validate-terraform`** - Terraform 已初始化、验证并应用。一个真实的 S3 存储桶已在 AWS 中创建。 ### 第 11 步：清理 每次成功的 `terraform apply` 都会创建一个带有随机后缀的新 S3 存储桶。为了避免累积存储桶并产生存储费用，请在完成实验后销毁资源。 **方式 1：使用 Terraform 销毁（推荐）** 在 `terraform/` 文件夹中运行： ``` terraform destroy -auto-approve ``` 这将移除 Terraform 上次创建的存储桶并更新状态文件。 **方式 2：使用 AWS CLI 手动删除存储桶** 如果你多次运行流水线，Terraform 仅跟踪最新的存储桶。要查找并删除较旧的存储桶： ``` # 列出所有 lab bucket aws s3 ls --profile | grep circleci-lab-compliant # 删除特定 bucket（替换为实际的 bucket 名称） aws s3 rb s3://circleci-lab-compliant-xxxxxxxx --force --profile ``` ## 关于流水线设计的说明 `test-aws-oidc` 与流水线的其余部分并行运行，但它实际上并不阻止任何其他作业运行。这意味着，如果 AWS 身份验证失败，OPA 作业仍然会运行，并且流水线只会在最后当 Terraform 尝试部署时才会失败。 如果我要重新构建此流水线，我会将 `test-aws-oidc` 设为 `validate-terraform` 的必要依赖项。这样，身份验证失败会及早显示出来，而不是在几分钟的不必要工作之后才出现。 ## 这如何与 GRC 产生关联 本实验以代码形式实现了多项云治理概念： | GRC 概念 | 实施方式 | |---|---| | 安全控制 | `s3.rego` 中的 OPA 策略规则 | | 持续控制监控 | 流水线在每次提交时运行 | | 证据收集 | 带有时间戳的 CircleCI 作业日志 | | 漂移预防 | 不合规的资源在部署前被阻止 | | 审计跟踪 | Git 中的完整变更历史 | | 最小权限访问 | OIDC 临时凭证，限定范围的 IAM 角色 | **演示的控制模式：** 本实验实现了两个特定的 S3 控制（静态加密、公共访问屏蔽）。它们映射到常见框架中的以下控制领域： * **SOC 2**：CC6.1（逻辑访问与静态数据保护） * **NIST 800-53**：SC-28（静态信息保护），AC-3（访问执行/公共访问屏蔽） * **CIS AWS Benchmark**：2.1.2（S3 加密），2.1.4（S3 公共访问屏蔽） * **ISO 27001:2022**：A.8.24（密码学/静态加密），A.8.22（网络安全/技术性公共访问屏蔽） 生产环境的 GRC 计划将扩展此模式，以涵盖更多的资源类型和控制措施。 ## 视频系列 本实验配有 4 部分的 YouTube 系列：**Cloud Security Automation Series** | 视频 | 标题 | |---|---| | [第 1 部分](https://youtu.be/LkgudHL7gHg) | OPA 与策略即代码 - 数字化规则手册 | | [第 2 部分](https://youtu.be/duBk5lrBO2s) | CI/CD 流水线 - 自动化装配线 | | [第 3 部分](https://youtu.be/WlZjKe66MR0) | 使用 OIDC 进行 AWS 身份验证 - 秘密握手 | | [第 4 部分](https://youtu.be/Bfz62T2S6b4) | Terraform 配置 - 蓝图检查 |

标签：AWS, CI/CD 安全, CI/CD 流水线, CircleCI, DevSecOps, DPI, EC2, ECS, Groq API, IaC, Modbus, OIDC, OPA, Rego, S3 存储桶安全, Terraform, 上游代理, 云基础设施, 亚马逊云, 合规自动化, 合规门禁, 安全左移, 安全策略测试, 安全认证, 持续合规, 数据投毒防御, 无长期凭证, 漏洞利用检测, 漏洞探索, 策略即代码, 结构化提示词, 聊天机器人安全, 靶场