使用 OPA 進行部署門控

在 DevSecOps 架構中，於 CI 流程中收集的證據必須在部署前經過驗證，以確保資產符合合規要求。此驗證流程扮演著品質把關的角色，可防止不符合規範的資產被部署至測試或生產環境。

有關證據篩選的更多資訊，請參閱「證據驗證」。

介紹 Open Policy Agent (OPA)

為了提供更大的靈活性，此建置流程現已支援透過 Open Policy Agent (OPA) 進行部署閘控。 OPA 是一個開源、通用的政策引擎，它將政策決策與處理管線的執行解耦。它讓您能夠以程式碼形式定義合規規則，使評估過程高度可自訂且完全透明。 OPA 採用 Rego 作為其查詢語言，使政策撰寫與維護變得輕鬆。

如需有關 Open Policy Agent 的更多資訊，請參閱 Open Policy Agent。

什麼是 Rego？

Rego 是 OPA 所採用的原生、宣告式查詢語言。它讓您能夠編寫「政策即代碼」與其依賴硬編碼的管線邏輯，不如評估管線的證據載荷，並回傳一個決策。

在部署門控的背景下，您可以將 Rego 視為您所蒐集的證據與目標環境之間的過濾器。 Rego 並不會依賴僵化的管線邏輯，而是會擷取管線中的證據資料（格式為 JSON），並根據您的自訂規則進行評估，進而回傳明確的部署決策。

有關 Rego 的更多資訊，請參閱《Rego 政策條款》。

`allow` 規則標準

根據慣例，您的 Rego 保單檔案必須包含一項「allow」條款。就這條流程而言，這不僅僅是一項建議——而是一項嚴格的要求。

管道引擎會特別查詢 allow 這個布林值，以做出最終的「進行」或「不進行」部署決定。若您提供自訂的 Rego 政策，則必須明確定義此規則。如果缺少 allow 規則，或者該規則的評估結果為 false``，則管線將立即停止，阻斷部署，並輸出您所定義的拒絕訊息。

為確保最高安全性，OPA 採用嚴格的「故障關閉」運作模式。您的政策應始終預設為「false」，僅在所有必要的合規條件均已滿足時，才評估為「true」。

package one_pipeline.config
# Default deny
default allow := false
# Allow only if your custom checks pass
allow {
    check_sast_scans_passed
    check_secrets_scans_passed
}

在您的處理流程中啟用 OPA

若要開始使用 OPA 進行部署閘控，您需要在管道設定中配置特定的屬性（環境變數）。請參考下表，以確定您的特定管線類型需要哪些屬性：

需求	管線物業	目的
啟用閘控（推廣）	`opt-in-evidence-checks`	啟用「推廣驗證」管線中的合規性檢查閘門。
啟用 OPA（CD 與 CC）	`opt-in-rego-translation`	指示持續部署（CD）與持續合規（CC）管道採用新的 OPA 邏輯。
定義邏輯（規則）	`policy-path`	將管道引擎指向您的自訂 `.rego` 政策檔案。
提供數據（事實）	`evidence-checks-config-path`	指向您的靜態資料驗證檔案 `.json`。

政策檔案與資料驗證檔案

政策檔案 (.rego) — 邏輯

請在此處撰寫實際的規則與條件。舉例來說，您的政策可能會規定：「除非已完成漏洞掃描，且結果顯示沒有任何嚴重問題，否則不得進行此部署。」 您可以透過使用 policy-path 管線環境屬性，提供自訂的政策檔案。若未提供政策檔案，管線將使用預設的政策檔案。

資料驗證檔案（.json）—— 事實概述

此檔案用作您的靜態參考清單。與其將資料直接硬編碼到 Rego 規則中，您應使用此檔案來維護已核准變數的清單——例如允許使用的影像註冊表（us.icr.io 或 eu.icr.io ），或是豁免特定檢查的特定儲存庫。您可以透過使用「evidence-checks-config-path」管線環境屬性來提供您的資料驗證檔案。若未提供資料驗證檔案，此流程將使用預設的資料驗證檔案。

資料驗證檔案範例：

        package one_pipeline.config
        pre_deployment := {
            "com.ibm.prod_change_request": {
                "asset_type": [
                "*",
                "image"
                ],
                "source": [
                "prod",
                "stage"
                ],
                "target": [
                "prod",
                "stage"
                ],
                "recommended": [
                "*"
                ]
            }
        }
        post_deployment := {
            "com.ibm.prod_change_request": {
                "asset_type": [
                "*",
                "image"
                ],
                "source": [
                "prod",
                "stage"
                ],
                "target": [
                "prod",
                "stage"
                ],
                "recommended": [
                "*"
                ]
            }
        }

配置中的每個區塊都會精確定義預期所需的證據、其來源，以及應以何種嚴格程度加以執行。

證據類型識別碼（com.ibm.prod_change_request ）： 此頂層鍵決定了正在評估的證據所屬的具體類別。常見的例子包括 com.ibm.static-scan、com.ibm.unit-tests 或 com.ibm.image_signing。
asset_type: 定義此規則所適用的工件類型。例如，這可能僅適用於 image 或 repo。使用 ["*"] 會將此規則套用至所有資產類型。
source （來源環境）： 定義證據的來源。這可能是某個特定分支，也可能是某個管道環境（例如：ci-pipeline、stage、prod ）。
target (目標環境)： 定義此證據正在進行部署驗證的目的地環境（例如：stage、prod ）。有關來源與目標的更多詳細資訊，請參閱此處。
gating mode: 最後幾個欄位用於指定您要對該證據類型套用的閘控模式。有關支援的觸發模式的更多資訊，請參閱此處。

注意：所有部署前檢查都必須定義在 pre_deployment :{} 陣列中，而所有部署後檢查則必須定義在 post_deployment :{} 陣列中。此外，若您使用預設的政策路徑，則必須在資料驗證登錄檔中加入 one_pipeline.config 套件的匯入指令。

現有 JSON 資料驗證的無縫遷移

對於已經在使用此建置流程的團隊來說，最常被問到的問題通常是：「我是否必須手動將所有現有的 JSON 設定檔重新寫成 Rego 格式？」

答案是否定的。 為了讓遷移過程完全無縫接軌，您可以將現有的 JSON 資料驗證檔案直接整合到處理流程中。此處理流程能原生識別您的舊版 JSON 檔案，並會與新的 OPA 功能無縫整合進行評估。

注意： 此向後相容性特別適用於資料驗證檔案。若您希望實作自訂評估邏輯，必須撰寫一個 Rego 政策檔案。

JSON 轉 Rego 轉換腳本

雖然此處理流程原生支援舊版 JSON 資料驗證檔案，但您最終可能希望將配置現代化為原生 Rego，以全面採用「政策即代碼」標準。

為協助您完成此項工作，我們提供了一個獨立的實用程式腳本，可自動將您現有的 JSON 資料驗證檔案轉換為新的 Rego 格式。

Script \u4f4d\u7f6e\uff1a /opt/one-pipeline/polyglot/polyglot/translate-pipeline-config.sh

如何使用轉換腳本

您可以於本地端或於管線執行過程中執行此腳本。在本地執行此腳本時，必須明確指定目標環境與來源環境。

腳本參數

參數	必要？	說明
`--input`	是	您現有舊版 JSON 設定檔的檔案路徑。
`--target-env`	是	驗證的目標環境（例如：`prod`、`stage` ）。注意：若在管線內執行，此參數會透過 `get_env` 自動解析。
`--source-env`	是	證據的來源環境（例如：`master`、`stage` ）。注意：若在管線內執行，此參數會透過 `get_env` 自動解析。
`--output`	否	將生成的 `.rego` 檔案儲存到的目標路徑。若未指定，則會根據 Python 腳本的邏輯，將輸出寫入標準輸出，或與輸入檔案一同產生。

範例用法

# Convert a JSON config to Rego using named parameters
/opt/one-pipeline/polyglot/polyglot/translate-pipeline-config.sh \
  --input ./legacy-evidence-config.json \
  --output ./new-evidence-config.rego \
  --target-env prod \
  --source-env master

注意： 若您在 --config-path 屬性中直接指定 .json 檔案，則還需提供 source-environment 及 target-environment 這兩項管道環境屬性。

發布驗證流程：左移合規性審查

將 Open Policy Agent (OPA) 整合至「推廣驗證」流程中，可讓合規性檢查直接納入拉取請求 (PR) 階段。這種 「左移」 方法能讓開發人員驗證其證據載荷，並在之前程式碼合併前發現合規性缺口。透過在開發生命週期的早期階段就發現缺失或失效的證據，團隊便能避免在後期階段遭遇部署障礙，並大幅減少返工。

彈性配置：多個驗證檔案

複雜的環境往往需要模組化的規則集。為此，促銷驗證流程可讓您同時針對多種設定來評估您的證據。

您可以透過將多個資料驗證檔案的路徑以逗號分隔的清單形式傳遞給 evidence-checks-config-path 參數，來提供多個資料驗證檔案。在此情況下，處理流程會根據每個設定檔來評估證據載荷，並針對每個檔案分別產生一份評估表。此外，在 PR 的留言區中，您會看到每個檔案的評估表格，它們以獨立留言的形式呈現。

自動化公關回饋

為了確保最大透明度，此流程會將當前的證據資料包與您提供的每個設定檔進行比對。評估完成後，處理流程會自動產生詳細的摘要與評估表格，並直接附加至拉取請求中。

若您設定了多個資料驗證檔案，管道會將每個檔案的結果分別以獨立的 PR 留言形式發布。這能讓審查人員清楚且全面地了解不同情境下的合規狀況，同時避免將各項結果混為一談。

在每則 PR 評論中，您可以找到：

三張評估表：驗證結果的完整細項分析。有關如何解讀這些表格的更多資訊，請參閱《了解證據核對表》。
設定連結：直接連結至用於執行該次具體評估的特定資料驗證檔案與政策檔案，讓您能輕鬆審核規則並排除問題。

在「促銷驗證」階段，此 OPA 合規性檢查旨在提升透明度並提供回饋。若偵測到違反您所設定規則的合規問題，處理流程並不會因此中斷或失敗。相反地，該流程會執行完畢，並將詳細的結果發佈至 PR 中。這可確保開發人員能收到一份完整報告，列出所有合規缺口，並能在不致讓建置過程中途當機的情況下進行修正。

OPA 資料合約：與處理流程的通訊

當您撰寫自訂政策時，OPA 會在後台精準地評估您的規則。然而，該處理流程需要一種標準化的方式來解讀這些結果，以便能向開發人員精確說明究竟發生了什麼事。這正是資料合約派上用場的地方。

請將此合約視為您的自訂 Rego 檔案與管線引擎之間的一種「握手」。您可以完全自由地編寫任何複雜的邏輯，以做出決策。但在政策的最末端，您必須將調查結果對應至兩項具體產出：table_results 物件以及 allow 規則。

`table_results` 物件（用於 PR 回饋）

為了在您的 PR 評論中產生詳細的 Markdown 表格，此流程會搜尋一個名為 table_results 的特定資料結構。

如果您的政策在 table_results 中輸出一個包含這八個確切欄位的 res 物件，則管線將接手處理。它會安全地解析您的輸出結果，並自動將其轉換為您在 PR 中所見的、結構清晰且詳盡的 Markdown 表格：

table_results contains res if {
    # ... your custom evaluation logic goes here ...
    
    # Map your findings to the contract structure
    res := {
        "RuleType":       "Required",       
        "AssetType":      "image",          
        "AssetId":        "12345678",      
        "EvidenceTypeId": "com.ibm.scan",   
        "Tool":           "zap",         
        "Status":         "failure",        
        "Source":         "ci-pipeline",    
        "Target":         "prod",           
    }
}

`allow` 規則（適用於管線執行）

如前所述，本合約的第二項強制性條款是「allow」規則。

為什麼有這項要求？

雖然 table_results 負責處理合規檢查的報告，但 allow 規則才是該管線的實際「緊急關機開關」。管線引擎已透過硬編碼設定，會查詢 allow 這個布林值，以決定最終的「繼續」或「中止」決策。

如果您提供了自訂政策檔案，卻忘記加入「allow」這項規則，管道將無法繼續執行。該系統採用嚴格的「失敗即關閉」安全模型，預設會使管道執行失敗並阻斷部署。

持續部署（CD）與持續合規（CC）管道

雖然「推廣驗證」流程主要著重於 PR 層級的檢查，但您也可以在「持續部署」（CD）和「持續合規」（CC）流程中，利用 OPA 進行部署門控。

啟用 OPA

若要在您的 CD 和 CC 管道中啟用基於 OPA 的合規性檢查，您必須明確啟用 opt-in-rego-translation 標誌（將其設定為 true 或 1 ）。

配置限制

就像「推廣」流程一樣，您可以同時提供「政策」檔案（您的邏輯）和「資料驗證」檔案（您的事實）。然而，有一項關鍵差異：CD 和 CC 處理流程目前每次僅能接受一個資料驗證檔案，而非以逗號分隔的清單。

變更請求 (CR) 附件與流程完成步驟

當您執行 CD 管線時，引擎會處理您的資料驗證檔案，並將其附加至您的變更請求中，以供稽核之用。檔案附件的行為完全取決於您提供的格式：

若您提供舊版 JSON 資料驗證檔案：管線會在後台自動進行轉換。原始的 JSON 檔案與生成的 Rego 設定檔均已附加至「變更請求」步驟中。
若您提供原生 Rego 資料驗證檔案：該管線將僅直接附加您所提供的 Rego 檔案。

這種完全相同的附加行為，同樣適用於在管線最末端的「CD 完成」步驟中進行的配置重建過程。

使用 OPA 進行部署門控

使用 OPA 進行部署門控

介紹 Open Policy Agent (OPA)

什麼是 Rego？

allow 規則標準

在您的處理流程中啟用 OPA

政策檔案與資料驗證檔案

現有 JSON 資料驗證的無縫遷移

JSON 轉 Rego 轉換腳本

如何使用轉換腳本

腳本參數

範例用法

發布驗證流程：左移合規性審查

彈性配置：多個驗證檔案

自動化公關回饋

OPA 資料合約：與處理流程的通訊

table_results 物件（用於 PR 回饋）

allow 規則（適用於管線執行）

持續部署（CD）與持續合規（CC）管道

啟用 OPA

配置限制

變更請求 (CR) 附件與流程完成步驟

`allow` 規則標準

`table_results` 物件（用於 PR 回饋）

`allow` 規則（適用於管線執行）