infra 變更走 code 流程

infra 變更的標準路徑是 PR → plan → review diff → 合併 → apply。這個順序的核心責任是把「執行前先看清楚要改什麼」變成強制步驟，而不是 apply 之後才從事故裡發現改錯了。每個環節各自承擔一段審查責任，少掉任一段，infra 就退回到不可審查的狀態。

plan 是整條鏈最關鍵的一環

terraform plan 把當前 state、雲端實際資源、與目標設定三方比對，產出一份「會新增 / 修改 / 刪除哪些資源」的 diff。這份 diff 是 review 的對象：reviewer 直接看 plan 算出來的實際變更，而非讀 HCL 自行想像結果。

plan 輸出裡最關鍵的判讀訊號是操作類型。+ 是新增，~ 是就地更新，- 是銷毀，-/+ 是先銷毀再重建。前兩者多數情境是安全的，後兩者需要逐行細看。改一個看似無害的欄位可能觸發整個資源重建（-/+），例如某些雲資源的 name 或 identifier 是 immutable 屬性，改它的唯一方式就是銷毀再建。對有狀態的服務（RDS、帶資料的 EBS volume），-/+ 代表資料遺失或停機。Review 階段抓到這個 -/+，比 apply 到一半才發現便宜太多。

 1# plan 輸出中要特別警惕的標記
 2# forces replacement  — 某個 immutable 屬性被修改，將觸發銷毀重建
 3# must be replaced    — 跟上面同義，Terraform 新版的表達方式
 4# will be destroyed   — 資源將被刪除
 5
 6  # aws_db_instance.primary must be replaced
 7  -/+ resource "aws_db_instance" "primary" {
 8      ~ identifier = "app-prod" -> "app-production"  # forces replacement
 9        ...
10    }

把 plan 結果貼回 PR

把 plan 結果貼回 PR 是讓 review 真正生效的做法。流程上，PR 觸發 CI 跑 plan，plan 輸出回貼成 PR comment，reviewer 連同程式碼 diff 一起看；approve 後才允許合併，合併才觸發 apply。

這裡有個取捨：plan 與 apply 之間若隔了很久，雲端實際狀態可能已經漂移（有人手動改了、或別的 PR 先 apply 了），導致 apply 時的 plan 跟 review 時看到的不一致。應對方式分保守與務實兩種。保守做法是 apply 前重跑一次 plan 並比對結果 — 一致才繼續，不一致就中斷。務實做法是在合併觸發 apply 時自動跑 plan 並只在無 destroy / replace 時自動執行，有 destroy / replace 就停下來要人確認。多數團隊從務實做法開始，到遇過一次 plan-apply 不一致的事故後才升級到保守做法。

apply 失敗的回退邊界

infra apply 不像程式碼部署可以直接 rollback 到上一版 image — 中途失敗時部分資源已經建立、state 可能處於半完成狀態。例如 apply 建了一個新 subnet 但在建 route table 時 timeout，此時 subnet 存在於雲端和 state 裡，route table 只在雲端不在 state 裡（或反過來），下一次 plan 的計算基礎就不精準。

應對的紀律是：apply 失敗後，先跑一次 terraform plan 確認 state 與現實的差距，再決定是修正 code 重新 apply 還是手動清理殘留資源後 terraform state rm。在清理之前不要再改 code、不要連發第二次 apply — 第二次 apply 在不確定的 state 上跑，可能把問題擴大。

PR 流程的價值在這裡不只是事前審查，也是事後可追溯：每次變更都對應一個 commit 與一個 PR，要回溯時知道是哪次改的、為什麼改、誰 review 的。

fmt 與 validate：最便宜的第一道檢查

fmt 與 validate 是進到任何安全掃描之前的基礎檢查，責任是擋掉格式不一致與語法 / 型別錯誤這類不需要動腦判斷的問題。它們跑得快（通常不到五秒）、沒有誤判空間，適合放在 CI 最前面當作快速 fail 的關卡。

terraform fmt -check 驗證程式碼是否符合標準排版。它本身不影響基礎設施行為，價值在於消除 diff 噪音：當每個人的編輯器縮排習慣不同，PR diff 會混入大量純排版變動，把真正的邏輯變更淹沒，reviewer 更容易看漏。統一格式後，diff 裡剩下的就是語意變更。在本地開發階段配合 editor plugin 或 pre-commit hook 在存檔時自動 fmt，讓 CI 的 fmt check 幾乎不會再 fail — 它存在的意義是攔住那些沒裝 plugin 的人。

validate 則檢查設定在語法與內部一致性上是否成立 — reference 到不存在的變數、型別不匹配、必填參數缺漏、module 呼叫的 source 解析不了，這些在 validate 階段就會報錯，不必等到 plan 連線雲端才發現。validate 需要先跑 terraform init，但可以用 -backend=false 跳過連線 state backend，這樣在 CI 裡不需要雲端憑證就能跑完。

 1# .github/workflows/terraform.yml — plan 前的基礎檢查
 2jobs:
 3  validate:
 4    runs-on: ubuntu-latest
 5    steps:
 6      - uses: actions/checkout@v4
 7      - uses: hashicorp/setup-terraform@v3
 8      - run: terraform fmt -check -recursive
 9      - run: terraform init -backend=false
10      - run: terraform validate

判讀上，fmt 與 validate 失敗代表的是「這份 code 還沒準備好被認真 review」，屬於作者自己該先修掉的問題，不該佔用 reviewer 注意力。把它們設成 CI 必過的 gate，作者在本地就會先跑、先修，PR 送出時已經是乾淨的。

tflint / checkov / tfsec：抓壞寫法與安全漏洞

fmt 與 validate 確認 code「語法正確」，但語法正確的設定仍然可能是危險的設定。tflint、checkov、tfsec 這類靜態掃描工具承擔的是「語意正確」這層：在不實際建立資源的前提下，從 HCL 裡比對已知的壞寫法與安全反模式，把問題擋在 plan 之前。它們補的是 reviewer 肉眼容易漏掉的盲區 — 人會看漏一個 0.0.0.0/0，規則不會。

三者的側重

checkov 與 tfsec 的覆蓋範圍有重疊（都會掃 S3 公開與 SG 全開），差別在規則來源與報告格式。checkov 的規則對標 CIS benchmark 和多雲合規框架（AWS、Azure、GCP、Kubernetes），tfsec 更專注在 Terraform HCL 結構。兩者跑在一起時，重複的命中可以用其中一個的 skip 標記豁免。

兩個最常攔下的反模式

S3 bucket 對外公開。一個漏設 block_public_access 或 ACL 寫成 public-read 的 bucket，會讓裡面的物件對整個網際網路可讀。這類設定在 HCL 裡只是一兩行，肉眼 review 時很容易因為「看起來像樣板」而放過，但後果是資料外洩。checkov 規則 CKV_AWS_19（S3 bucket 未啟用 server-side encryption）和 CKV_AWS_53（block public access 未全開）會標記這類漏洞：

 1# checkov 會攔下的寫法 — 缺少 block_public_access
 2resource "aws_s3_bucket" "data" {
 3  bucket = "acme-customer-data"
 4}
 5
 6# 正確寫法 — 顯式關閉公開存取
 7resource "aws_s3_bucket_public_access_block" "data" {
 8  bucket                  = aws_s3_bucket.data.id
 9  block_public_acls       = true
10  block_public_policy     = true
11  ignore_public_acls      = true
12  restrict_public_buckets = true
13}

Security group 對全世界開放。一條 ingress 寫成 cidr_blocks = ["0.0.0.0/0"] 加上 port 22 或 3306，等於把 SSH 或資料庫埠暴露給全網掃描器。tfsec 與 checkov 都會標記這種「敏感埠 + 全開 CIDR」的組合。這條規則跟模組三：網路地基講的 security group 收斂原則是同一件事的兩端 — 模組三教怎麼把規則寫對，本章用靜態掃描確保寫錯時擋得下來。

1# 三道掃描串在一起，任一 fail 就中斷
2tflint --recursive
3checkov -d . --quiet --compact
4tfsec . --soft-fail=false

命中是候選不是判決

判讀這些工具的命中時，要區分「真漏洞」與「情境合理的例外」。並非每個 0.0.0.0/0 都是錯 — 一個對外的 HTTPS load balancer 在 port 443 開全網是設計本意。所以掃描的命中是候選不是判決。

多數工具支援用行內註解標記豁免。checkov 用 #checkov:skip=CKV_AWS_260:ALB 443 對外是設計本意，tfsec 用 #tfsec:ignore:aws-elb-alb-not-public。豁免的紀律是：每個 skip 都要寫理由、要在 PR 裡可見。沒有理由的 skip 跟關掉整條規則沒有差別 — review 時看到無理由的 skip 應該當成跟看到裸 0.0.0.0/0 一樣的警報。

把例外顯式化、留下為什麼豁免的紀錄，比關掉整條規則安全。隨時間累積的 skip 也要定期盤點：某個當初合理的例外，在架構演進後可能已經不再合理。

Atlantis 與 GitHub Actions：自動化 plan 與 apply

把上述流程自動化，需要一個能監聽 PR 事件、在對的時機跑 plan 與 apply 的執行層。兩種常見做法是直接用 CI 平台（如 GitHub Actions）寫 workflow，或用 Atlantis 這類專為 Terraform PR 流程設計的工具。

Atlantis

Atlantis 是一個常駐服務，掛在 git 平台的 webhook 上。PR 開啟時它自動跑 plan 並把結果貼回 PR comment，reviewer approve 後在 PR 留言 atlantis apply，它才執行 apply 並回報結果。它的價值在於把「誰能 apply、apply 前要不要 approve、plan 結果在哪看」這些規則收斂成一致的、可設定的流程。

Atlantis 內建的 state lock 語意在多 PR 並行時特別有用：當兩個 PR 都改到同一個 Terraform project，第二個 PR 的 plan 會被 lock 擋住，直到第一個 apply 完成或 PR 關閉。這避免了兩個 PR 各自拿到的 plan 基於不同的 state 快照、apply 時互相覆蓋的問題。用 GitHub Actions 要自己實作這個 lock 邏輯（通常靠 Terraform 自己的 state lock + workflow concurrency group），複雜度高得多。

Atlantis 的代價是它本身是一個要部署、要升級、要保護的常駐服務 — 它持有對雲端的寫入權限，所以它的部署環境必須嚴格控制存取。

GitHub Actions

GitHub Actions workflow 的優點是不必額外維運服務、跟既有 CI 共用同一套 runner。缺點是 apply 的 gating 邏輯要自己用 workflow 條件拼出來。一個完整的 workflow 通常分成兩個 job：PR 觸發 plan job（跑 fmt / validate / scan / plan、把結果貼回 PR），合併到 main 才觸發 apply job。

無論哪種執行層，自動化的 apply 都需要對雲端的寫入權限，而這個權限怎麼來是整條管線的安全根基。這裡正是模組二：身分與憑證地基鋪設的 OIDC 兌現的地方 — 管線不該存放長期的 access key，而是在 runner 執行時用 OIDC 向雲端換取短期 token。

 1# 合併到主幹後，用 OIDC 換短期憑證再 apply（呼應模組二）
 2jobs:
 3  apply:
 4    if: github.ref == 'refs/heads/main'
 5    runs-on: ubuntu-latest
 6    permissions:
 7      id-token: write   # 允許 runner 取得 OIDC token
 8      contents: read
 9    steps:
10      - uses: actions/checkout@v4
11      - uses: aws-actions/configure-aws-credentials@v4
12        with:
13          role-to-assume: arn:aws:iam::123456789012:role/infra-apply
14          aws-region: ap-northeast-1
15      - uses: hashicorp/setup-terraform@v3
16      - run: terraform init
17      - run: terraform apply -auto-approve

選型判準

判讀自動 apply 的邊界：對會觸發資源重建或刪除的高風險 plan，多數團隊會保留人工 apply 的關卡（Atlantis 的手動 atlantis apply、或 workflow 加 environment protection rule 要人按確認），不讓這類變更在合併瞬間無人看管地執行。自動化的目的是消除重複勞動與人為遺漏，不是把判斷也一起省掉。

知識留在 code，而不是留在個人腦中

走完整套 PR 流程後，infra 的真正收穫是知識從個人的記憶移到了 repo 裡。每一次「為什麼這個 security group 開這個埠」「為什麼這台機器選這個 instance type」的決策，都以 code + PR 描述 + review 討論的形式留下，新人讀 repo 就能還原當初的判斷，不必去問那個「只有他懂 infra」的人。基礎設施可被閱讀，等於它可被交接。PR 流程上線後，管理層可以從 repo 的 PR merge 歷史與 plan comment 確認所有 infra 變更都經過提案與審查——這本身就是稽核要求的變更紀錄證據，不需要額外產出。

git revert 的能力與邊界

可 revert 是 PR 流程最直接的兌現。當某次變更引發問題，回退手段是 git revert 那個 commit 再走一次 PR 流程，讓基礎設施回到變更前的設定 — 跟回退一段壞掉的程式碼是同一個動作。對照手動操作的舊狀態：回退靠的是當事人記得自己改了什麼、手動在 Console 改回去，記錯或人不在就無從回退。把變更歷史留在 git，回退就從「依賴某人的記憶」變成「依賴版本紀錄」。

這份 revert 能力的邊界要講清楚。revert code 救得回的是「設定」，救不回已經被銷毀的狀態與資料：

• revert 掉一個刪除 RDS 的 commit，只是讓設定回到「該資源應該存在」。apply 時 Terraform 會試圖建一個新的空資料庫 — 但被刪掉的資料庫裡的資料不會跟著回來。
• rename 或 replace 類的變更 revert 後，可能再觸發一次資源重建 — 因為 identifier 又改回去了，而 identifier 是 immutable 屬性。
• apply 到一半失敗的 state 不能直接 revert code 修復，得先處理 state 與雲端現實的不一致。

stateful 變更的真正回退仍然靠備份與快照，這正是模組五：核心服務上 IaC stateful 處理與模組八：治理好習慣 secret / state 保護要顧的事。把 git revert 當「設定層回退」就誠實，把它當「資料層回退」就會在事故裡踩空。

知識共享的判讀訊號

判讀一個團隊是否確實把知識留在 code 的訊號：當主要負責 infra 的人請假，其他人能不能只靠讀 repo 就理解現狀並安全地改一個小設定。如果答案是「得等他回來」，那不論工具鏈多完整，知識還在個人腦中，PR 流程只是形式。這個訊號比任何工具設定都更能反映 infra 的成熟度。

讓知識真正從個人腦中搬進 repo 的方式，除了 PR 流程本身，還需要組織層的配合 — 刻意的 review 輪替、on-call 輪值、配對操作。這條路線在模組九：怎麼把 infra 推動起來展開到組織層。本章解決的是技術機制 — code 留得住知識；模組九解決的是怎麼讓團隊實際願意走這套流程、把知識交出來。

跨分類引用

• → CI/CD 教學：infra 管線用的就是這套驗證 / 發布 gate，plan / apply 對應 build / deploy 階段
• → 模組二：身分與憑證地基：管線用 OIDC 取得 apply 權限，本章是該章 OIDC 設計的回報兌現處
• → 模組三：網路地基：security group 收斂原則，本章用 tfsec / checkov 在 CI 攔下寫錯的全開規則
• → 模組五：核心服務上 IaC：stateful 資源的保護策略，git revert 救不回資料層
• → 模組八：治理好習慣：secret / state 保護
• → 模組九：怎麼把 infra 推動起來：本章把知識留在 code 的技術機制，在該章展開成組織層的採用與知識共享
• → backend 模組七：資安與資料保護：S3 公開、敏感埠全開這類掃描攔截的反模式，對應的資料保護原則
• → 團隊權限分級：權限變更走 PR 流程，讓 policy 調整有審查紀錄
• → 職務交接設計：PR 歷史是交接時的知識載體
• → Terraform CI Pipeline 設定指南：GitHub Actions 完整 workflow
• → checkov 與 tfsec 規則配置：規則選擇、豁免管理、CI 整合

Pipeline 的兩個階段

整條 pipeline 分成兩個觸發時機，各自承擔不同責任：

兩個階段用不同的 IAM role：plan role 只有唯讀權限（能跑 terraform plan 但不能改任何資源），apply role 有寫入權限。這個分離確保 PR 階段的任何 code 都沒辦法偷偷改動雲端資源。

Plan 階段的完整 workflow

 1name: Terraform Plan
 2on:
 3  pull_request:
 4    paths:
 5      - 'infra/**'
 6
 7permissions:
 8  id-token: write
 9  contents: read
10  pull-requests: write
11
12jobs:
13  plan:
14    runs-on: ubuntu-latest
15    defaults:
16      run:
17        working-directory: infra/environments/prod
18
19    steps:
20      - uses: actions/checkout@v4
21
22      - uses: aws-actions/configure-aws-credentials@v4
23        with:
24          role-to-assume: arn:aws:iam::123456789012:role/infra-plan
25          aws-region: ap-northeast-1
26
27      - uses: hashicorp/setup-terraform@v3
28        with:
29          terraform_version: 1.9.0
30
31      - name: Format check
32        run: terraform fmt -check -recursive -diff
33
34      - name: Init
35        run: terraform init -input=false
36
37      - name: Validate
38        run: terraform validate
39
40      - name: TFLint
41        uses: terraform-linters/setup-tflint@v4
42        with:
43          tflint_version: latest
44      - run: tflint --recursive --format compact
45
46      - name: Plan
47        id: plan
48        run: |
49          terraform plan -no-color -input=false -out=tfplan \
50            -detailed-exitcode 2>&1 | tee plan-output.txt
51        continue-on-error: true
52
53      - name: Comment plan on PR
54        uses: actions/github-script@v7
55        with:
56          script: |
57            const fs = require('fs');
58            const plan = fs.readFileSync('infra/environments/prod/plan-output.txt', 'utf8');
59            const truncated = plan.length > 60000
60              ? plan.substring(0, 60000) + '\n\n... (truncated)'
61              : plan;
62            await github.rest.issues.createComment({
63              owner: context.repo.owner,
64              repo: context.repo.repo,
65              issue_number: context.issue.number,
66              body: `### Terraform Plan\n\`\`\`\n${truncated}\n\`\`\``
67            });
68
69      - name: Fail if plan errored
70        if: steps.plan.outcome == 'failure'
71        run: exit 1

各步驟的職責

Format check 驗證 HCL 是否符合標準排版。它不影響功能，但消除 diff 噪音——排版不一致時 PR diff 會混入純格式變更，reviewer 分不清哪些是邏輯改動。-diff flag 讓 CI 輸出具體哪幾行不符合，作者在本地跑 terraform fmt 就能修。

Init 初始化 provider 和 backend。-input=false 避免 CI 卡在等待互動式輸入。如果 backend 設定錯了（bucket 不存在、權限不足），這一步就會失敗，不會跑到後面浪費時間。

Validate 檢查 HCL 的語法和內部一致性——變數沒宣告、型別不匹配、必填參數缺漏。它不連線雲端，只讀 code，所以不需要 AWS credential 也能跑（但放在 init 之後是因為 validate 需要 provider schema）。

TFLint 做 provider 層的正確性檢查：instance type 在該 region 不存在、已棄用的參數、命名不符規範。它補的是 validate 抓不到的「語法對但值不對」的問題。

Plan 是整條 pipeline 的核心產出。-detailed-exitcode 讓 exit code 區分三種狀態：0 = 無差異、1 = 錯誤、2 = 有差異。-out=tfplan 把 plan 結果存成二進位檔，apply 階段可以直接用這份 plan 執行，避免 plan 和 apply 之間的時間差導致不一致。

Comment 把 plan 輸出貼回 PR，reviewer 看 code diff 的同時看到 plan 的實際變更。plan 輸出可能很長（幾百行），超過 GitHub comment 上限時截斷，但保留開頭（通常包含 add/change/destroy 的摘要行）。

Apply 階段

 1name: Terraform Apply
 2on:
 3  push:
 4    branches: [main]
 5    paths:
 6      - 'infra/**'
 7
 8permissions:
 9  id-token: write
10  contents: read
11
12jobs:
13  apply:
14    runs-on: ubuntu-latest
15    environment: production
16    defaults:
17      run:
18        working-directory: infra/environments/prod
19
20    steps:
21      - uses: actions/checkout@v4
22
23      - uses: aws-actions/configure-aws-credentials@v4
24        with:
25          role-to-assume: arn:aws:iam::123456789012:role/infra-apply
26          aws-region: ap-northeast-1
27
28      - uses: hashicorp/setup-terraform@v3
29        with:
30          terraform_version: 1.9.0
31
32      - name: Init
33        run: terraform init -input=false
34
35      - name: Plan (verify)
36        run: terraform plan -no-color -input=false -detailed-exitcode
37
38      - name: Apply
39        run: terraform apply -auto-approve -input=false

environment protection rule

environment: production 這一行啟用 GitHub 的環境保護功能。在 repo 的 Settings → Environments → production 設定：

• Required reviewers：指定至少一個人 approve 才能執行 apply job
• Wait timer：合併後等 N 分鐘才開始 apply（給人反應時間）
• Deployment branches：限定只有 main branch 能觸發

這層保護讓高風險的變更（plan 顯示 destroy 或 replace）在 apply 前多一道人工確認。日常低風險變更（加一個 tag、調一個參數）可以直接通過。取捨點是：每次 apply 都要人按確認會拖慢頻繁的小變更，可以用 deployment rule 的條件只攔 production 環境。

Apply 階段重跑 plan 的理由

apply 之前重跑一次 plan，是為了驗證合併後的現實跟 PR review 時看到的一致。PR 從開啟到合併可能隔了幾小時或幾天，期間有人可能手動改了雲端資源（drift）或別的 PR 先 apply 了。重跑 plan 確認差異跟預期一致，不一致就停下來而非盲目 apply。

如果使用了 plan 階段的 -out=tfplan 保存 plan 檔，apply 可以改為 terraform apply tfplan 直接執行已 review 過的 plan。代價是 plan 檔需要跨 job 傳遞（GitHub Actions 的 artifact），且 plan 檔有時效——state 在 plan 之後被修改，apply 會拒絕執行。

多環境的 pipeline 設計

管理 dev / staging / prod 三個環境時，pipeline 有兩種常見結構：

單 workflow 加 matrix：一份 YAML 用 strategy.matrix 跑三個環境，每個環境有自己的 working directory 和 IAM role。好處是維護一份 YAML；代價是三個環境的 plan 都在同一次 PR run 裡，reviewer 要看三份 plan 輸出。

每環境獨立 workflow：三份 YAML 各自觸發在對應環境目錄的變更上（paths: ['infra/environments/dev/**']）。好處是只有改到的環境才跑、PR comment 乾淨；代價是三份 YAML 有重複。

多數團隊起步時用單 workflow + matrix，環境數量超過三個或各環境的 apply 策略不同（dev 自動、prod 要 approval）時切到獨立 workflow。

安全邊界

CI pipeline 是 infra 變更的自動化執行者，它的安全性等同於 apply role 的權限。幾個邊界要守住：

OIDC claim 收斂：apply role 的 trust policy 只允許特定 repo 的 main branch 假扮（見 OIDC Trust Policy 設定）。如果 claim 只驗 repo 不驗 branch，任何人在 feature branch 推一個修改過的 workflow 就能觸發 apply。

Workflow 修改的 review：.github/workflows/ 底下的 YAML 變更應該跟 infra code 一樣走 PR review。修改 workflow 等於修改 pipeline 的行為——加一個 terraform destroy step 就能在合併時清掉整個環境。GitHub 的 CODEOWNERS 功能可以強制特定人 review workflow 變更。

Secret 與 environment variable：OIDC 取代了存在 repo secrets 裡的 access key，但 workflow 可能還用到其他 secret（Terraform Cloud token、Slack webhook URL）。這些 secret 要限定在特定 environment 才能存取，不開放給所有 branch。

本篇聚焦 GitHub Actions。如果團隊選擇 Atlantis（常駐服務、內建 state lock 與 apply 語意），見主文章的 Atlantis 段的選型討論。

跨分類引用

• → OIDC Trust Policy 設定：pipeline 的 credential 來源
• → checkov / tfsec 規則配置：pipeline 裡的靜態安全掃描怎麼配
• → infra 走 PR 流程與自動化護欄：pipeline 背後的審查原則
• → 模組四：環境分離與模組化：多環境的目錄結構決定 pipeline 的 working directory

規則選擇策略

兩個工具的內建規則集都超過數百條，涵蓋從加密設定到命名慣例。全開跑會讓命中清單長到沒人看。規則選擇的判準是「這條規則命中後，團隊會不會真的去修」——答案是不會的規則，開著只是製造噪音。

分層啟用

把規則分成三層逐步啟用，而非一次全開：

地基層是即使其他規則都關掉也要開的——S3 bucket 對外公開（CKV_AWS_19、CKV_AWS_53）和 security group 全開（CKV_AWS_24、CKV_AWS_25）這類規則命中就是真問題。營運層在 IaC 覆蓋率夠高時啟用，否則會掃到大量不在 IaC 管理內的資源。規範層等團隊有能力消化命中量再開。

checkov 的規則過濾

1# 只跑地基層規則
2checkov -d . --check CKV_AWS_19,CKV_AWS_53,CKV_AWS_24,CKV_AWS_25,CKV_AWS_40,CKV_AWS_145
3
4# 或者用 framework 過濾（只掃 Terraform）
5checkov -d . --framework terraform --compact --quiet

checkov 支援 --check（白名單，只跑這些）和 --skip-check（黑名單，跳過這些）。初期用 --check 白名單比較可控——明確列出要跑的規則，而非從全集去扣。隨著團隊消化能力提升再擴大白名單。

tfsec 的嚴重度過濾

1# 只報 CRITICAL 和 HIGH
2tfsec . --minimum-severity HIGH
3
4# 排除特定規則
5tfsec . --exclude aws-s3-specify-public-access-block

tfsec 的嚴重度分 CRITICAL / HIGH / MEDIUM / LOW。初期設 --minimum-severity HIGH 把低嚴重度的過濾掉，減少噪音量。降低閾值的時機是 HIGH 以上的命中清零後。

豁免管理

不是每個命中都是錯——對外的 ALB 在 port 443 開 0.0.0.0/0 是設計意圖、不是漏洞。豁免的重點是讓例外顯式化、有理由、可被 review。

行內豁免

1resource "aws_security_group_rule" "alb_https" {
2  type        = "ingress"
3  from_port   = 443
4  to_port     = 443
5  protocol    = "tcp"
6  cidr_blocks = ["0.0.0.0/0"]
7  #checkov:skip=CKV_AWS_24:ALB 的 HTTPS 入站需要對外開放
8}

tfsec 的行內豁免：

1resource "aws_security_group_rule" "alb_https" {
2  #tfsec:ignore:aws-ec2-no-public-ingress-sgr -- ALB HTTPS listener requires public access
3  cidr_blocks = ["0.0.0.0/0"]
4}

行內豁免的好處是理由跟程式碼在一起，review 時一眼可見。壞處是散落在各檔案裡，盤點所有豁免要 grep。

集中式豁免

checkov 支援 .checkov.yaml 集中管理豁免：

1# .checkov.yaml
2skip-check:
3  - CKV_AWS_24  # ALB public-facing SG rules
4  - CKV_AWS_19  # Legacy S3 buckets pending migration

集中式的好處是一個地方看到所有豁免，適合全域性的例外（如「這批 legacy S3 bucket 還沒遷完、暫時跳過 public access 檢查」）。壞處是理由離程式碼太遠，三個月後沒人記得為什麼跳過。

豁免紀律

每個豁免都要寫理由（-- 之後的文字）。沒有理由的豁免等於靜默跳過——review 時看不出是故意的還是為了讓 CI 過而隨手加的。定期（每季度）跑一次豁免盤點：

1# 盤點所有 checkov 豁免
2grep -rn "checkov:skip" --include="*.tf" .
3
4# 盤點所有 tfsec 豁免
5grep -rn "tfsec:ignore" --include="*.tf" .

每個命中問一句：當初跳過的原因還成立嗎？legacy 遷移完了嗎？臨時的例外變成永久的了嗎？

自訂規則

內建規則覆蓋通用安全實踐，但專案特有的規範（如「所有 RDS 必須有 cost-center tag」「所有 S3 bucket 名稱必須以公司前綴開頭」）需要自訂。

checkov 自訂規則（Python）

 1# custom_checks/require_cost_center_tag.py
 2from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck
 3from checkov.common.models.enums import CheckResult, CheckCategories
 4
 5class CostCenterTagRequired(BaseResourceCheck):
 6    def __init__(self):
 7        name = "Ensure cost-center tag is present"
 8        id = "CUSTOM_001"
 9        supported_resources = ["aws_instance", "aws_db_instance", "aws_s3_bucket"]
10        categories = [CheckCategories.GENERAL_SECURITY]
11        super().__init__(name=name, id=id, categories=categories,
12                         supported_resources=supported_resources)
13
14    def scan_resource_conf(self, conf):
15        tags = conf.get("tags", [{}])[0]
16        if isinstance(tags, dict) and "cost-center" in tags:
17            return CheckResult.PASSED
18        return CheckResult.FAILED
19
20check = CostCenterTagRequired()

1# 跑自訂規則
2checkov -d . --external-checks-dir ./custom_checks

tfsec 自訂規則（YAML）

 1# .tfsec/custom_rules.yaml
 2- id: CUSTOM_001
 3  description: S3 bucket name must start with company prefix
 4  impact: Non-standard naming breaks cross-account policies
 5  resolution: Add company prefix to bucket name
 6  requiredTypes:
 7    - resource
 8  requiredLabels:
 9    - aws_s3_bucket
10  severity: MEDIUM
11  matchSpec:
12    name: bucket
13    action: startsWith
14    value: acme-

自訂規則的數量保持精簡——每條規則都是維護成本。只有「違反後會在後續流程造成問題」的規範值得寫成自動化規則，純粹的風格偏好留給 review 時口頭提醒。

CI 整合

把掃描接進 CI 的目標是「PR 合併前就攔下問題」，而非 apply 之後才發現。

GitHub Actions 範例

 1jobs:
 2  security-scan:
 3    runs-on: ubuntu-latest
 4    steps:
 5      - uses: actions/checkout@v4
 6
 7      - name: Run checkov
 8        uses: bridgecrewio/checkov-action@v12
 9        with:
10          directory: .
11          check: CKV_AWS_19,CKV_AWS_53,CKV_AWS_24,CKV_AWS_25
12          quiet: true
13          compact: true
14          soft_fail: false
15
16      - name: Run tfsec
17        uses: aquasecurity/tfsec-action@v1
18        with:
19          minimum_severity: HIGH
20          soft_fail: false

soft_fail: false 讓掃描命中時 CI 失敗、阻擋合併。初期可以先設 soft_fail: true（掃描報告但不阻擋），讓團隊觀察命中量，確認規則集合理後再切成強制。

掃描結果回貼 PR

checkov 和 tfsec 的 GitHub Actions 都支援把結果以 PR comment 回貼。讓 reviewer 在 PR 頁面直接看到掃描結果，不用去翻 CI log。checkov-action 預設會回貼；tfsec-action 需要額外的 github_token 設定。

漸進式導入

1Week 1-2：soft_fail=true，觀察命中量和 false positive 率
2Week 3：修完所有真問題，豁免所有合理的 false positive
3Week 4：切 soft_fail=false，掃描變成強制 gate

這個節奏讓團隊在掃描變成強制之前就清理完存量，避免「一開 hard fail 所有 PR 都過不了」的窘境。

False positive 處理

false positive 的處理有三條路，依復發頻率選：

最常見的 false positive 是 ALB 的 public-facing security group（設計就是要開 443）和開發環境的寬鬆設定（dev 允許、prod 不允許）。後者可以用 checkov 的 --var-file 搭配環境變數區分——dev 跑寬鬆規則集、prod 跑嚴格規則集。

處理 false positive 時要抵抗「加 skip 讓 CI 過」的捷徑衝動。每個 skip 都要問：這是設計意圖（ALB 要開放）還是技術債（dev 環境暫時放寬）？前者寫永久豁免加理由，後者寫臨時豁免加 TODO 和預計修復時間。

跨分類引用

• → infra 走 PR 流程與自動化護欄：掃描在 PR 流程裡的定位與 plan/apply 的關係
• → Terraform CI Pipeline 設定：掃描步驟怎麼嵌入完整的 CI workflow
• → 模組三：Security Group 稽核與清理：掃描命中 0.0.0.0/0 後的處理流程