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
}

ポリシーファイルとデータ検証ファイル

ポリシーファイル（.rego） - ロジック

ここには、実際のルールや条件を記述します。 たとえば、ポリシーでは次のように規定されている場合があります*。「脆弱性スキャンが完了し、その結果に重大な問題が1件も見つからなかった場合を除き、このデプロイを許可してはならない。」* 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": [
                "*"
                ]
            }
        }

構成内の各ブロックでは、どのような証拠が求められるか、その出所はどこか、そしてどの程度厳格に適用されるべきかが明確に定義されています。

• 証拠タイプID（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からRegoへの変換スクリプト

このパイプラインは、従来のJSON形式のデータ検証ファイルをネイティブでサポートしていますが、将来的には、「ポリシー・アズ・コード」の標準を完全に採用するために、設定をネイティブのRego形式に刷新したいと考えるかもしれません。

これを支援するため、既存のJSONデータ検証ファイルを新しいRego形式に自動的に変換するスタンドアロンのユーティリティスクリプトをご用意しています。

スクリプトの場所: /opt/one-pipeline/polyglot/polyglot/translate-pipeline-config.sh

コンバータスクリプトの使用方法

このスクリプトは、ローカルで、またはパイプラインの実行内で実行できます。 スクリプトをローカルで実行する場合は、ターゲット環境とソース環境を明示的に指定する必要があります。

# 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

柔軟な設定：複数の検証ファイル

複雑な環境では、モジュール式のルールセットが必要となる場合が多い。 これを支援するため、プロモーション検証パイプラインでは、複数の構成に対して証拠を同時に評価することができます。

evidence-checks-config-path パラメータに、複数のデータ検証ファイルのパスをカンマ区切りのリストとして指定することで、複数のデータ検証ファイルを提供することができます。 この場合、パイプラインは各設定ファイルに対してエビデンス・ペイロードを評価し、ファイルごとに個別の評価テーブルを生成します。 また、PRのコメント欄には、各ファイルの評価表が個別のコメントとして表示されます。

PRフィードバックの自動化

可視性を最大限に高めるため、パイプラインは、提供された各設定ファイルに対して、現在のエビデンス・ペイロードを評価します。 評価が完了すると、パイプラインが自動的に詳細な要約と評価表を生成し、それらをプルリクエストに直接追加します。

複数のデータ検証ファイルを設定した場合、パイプラインは各ファイルの結果を個別のプルリクエストのコメントとして投稿します。 これにより、レビュー担当者は、出力結果を混同することなく、さまざまな状況におけるコンプライアンス状況を明確かつ包括的に把握することができます。

各PRコメントの中には、以下の内容が含まれています：

• 3つの評価表 ：検証結果の完全な内訳。 これらの表の見方に関する詳細については、「 エビデンス確認表の理解 」を参照してください。
• 設定リンク ：その評価の実施に使用された特定のデータ検証ファイルおよびポリシーファイルへの直接リンク。これにより、ルールの監査やトラブルシューティングが容易になります。

プロモーション検証フェーズにおいて、このOPA準拠チェックは、可視化とフィードバックを目的として設計されています。 ルールに違反する問題が検出された場合でも、パイプラインは停止したり失敗したりすることはありません。 その代わりに、パイプラインは処理を完了し、詳細な結果をPRに投稿します。 これにより、開発者はすべてのコンプライアンス上の不備に関する完全なレポートを受け取ることができ、ビルドの途中でクラッシュすることなく、それらの不備を修正することができます。

table_results オブジェクト（PRに関するフィードバック用）

PRのコメント内に詳細な Markdown テーブルを生成するために、パイプラインは「 table_results 」という名前の特定のデータ構造を検索します。

ポリシーが、 table_results 内で、まさにこれら 8 つのフィールドを含む 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 ルール（パイプライン実行用）

前述の通り、本契約の2つ目の必須条項は、「 allow 」という規定です。

なぜこれが必要なのですか？

table_results はコンプライアンスチェックの結果報告を担当しますが、 allow ルールこそが、パイプラインの実際のキルスイッチとなります。 パイプラインエンジンは、 allow というブール値を照会して最終的な「Go」または「No-Go」の決定を下すよう、ハードコーディングされています。

カスタムポリシーファイルを提供しても、「 allow 」ルールを含めるのを忘れると、パイプラインは処理の進め方がわからなくなります。 厳格な「フェイルクローズド」セキュリティモデルに基づいて動作するため、デフォルトではパイプラインの実行を失敗させ、デプロイをブロックします。

OPAの有効化

CDおよびCCパイプラインでOPAベースのコンプライアンス・ゲーティングを有効にするには、 opt-in-rego-translation フラグを明示的に有効にする必要があります（ true または 1 に設定してください）。

構成上の制約

プロモーション・パイプラインと同様に、ポリシー・ファイル（ロジック）とデータ検証ファイル（事実）の両方を指定することができます。 ただし、1つ重要な違いがあります。CDおよびCCパイプラインは、現在、カンマ区切りのリストではなく、一度に1つのデータ検証ファイルのみを受け付けるようになっています。

変更依頼（CR）の添付ファイルとパイプラインの完了ステップ

CDパイプラインを実行すると、エンジンはデータ検証ファイルを処理し、監査の目的でそれを変更リクエストに添付します。 ファイルの添付方法は、指定した形式によって異なります：

• 従来のJSONデータ検証ファイルを提供する場合 ：パイプラインはバックグラウンドで自動的にそれを変換します。 元のJSONファイルと生成されたRego設定ファイルの両方が、「変更依頼」ステップに添付されています。
• ネイティブのRegoデータ検証ファイルを提供する場合 ：パイプラインは、提供されたRegoファイルのみを直接接続します。

このまったく同じアタッチメントの挙動は、パイプラインの最終段階である「CD Finish」ステップで行われる構成の再構築プロセスにも適用されます。