作成者が記述した 1 つのリーフをキーとするポリシー
この例では、1 つのハウスルールと、それを表現可能にしている事実を説明します。
credential スロットは埋めてもかまいません。ただし、その素材をワークスペース自身のソースに書き込むことで埋めてはなりません。
変数が 1 つだけ異なる 2 つのリリースがあります。同じマネージドデータベース、同じ必須クレデンシャルスロットを、2 つの異なる Features が埋めます。一方は開発者が Aggregate でアタッチし、もう一方はオペレーターが Release でアタッチします。オペレーターが作成したポリシーは、一方を拒否し、もう一方を許可します。このペアを実行する価値があるのは、どちらのアタッチメントもシークレットマテリアルを扱う点です。そのため、このルールは「このアタッチメントはセンシティブか?」という問いに対しては記述できません。そうしようとすると何が起こるかは、後述のコントロールポリシーで示します。
2 つのポリシーファイルを除くすべては、ガバナンス用の Plugin エンティティも含め、標準ライブラリのカタログから提供されます。
スロットと、それを埋められる 2 つの Features
core/datastore/mariadb は、必須のクレデンシャルスロットを 1 つ宣言しています。
featuresSchema: root_password: required: true sensitive: true inject: [] description: Root database password. Recipe controls delivery (Black-Box).ここでの sensitive: true は、特定の埋め方ではなくバインディングポイントについての記述です。このスロットをバインドするものは、何であれ秘密情報を扱います。inject: [] は配信先を閉じます。クレデンシャルの行き先は Recipe が決め、開発者が指定することはありません。
このスロットをバインドする標準ライブラリの Features は 2 つあり、それぞれ正反対のクレデンシャルのライフサイクルをモデル化しています。
| Feature | 秘密情報の所有者 | アタッチメントが記述するもの |
|---|---|---|
core/secret-value | 作成者が提供する | 2 つの values リーフ(後述) |
core/generated-secret | ターゲットエンジンがプロビジョニングとローテーションを行う | なし。values を宣言しない |
core/secret-value は 2 つのリーフを非対称に宣言しており、この非対称性こそがこの例の要です。
values: origin: { type: string, sensitive: true } key: { type: string, required: true, default: "value" }origin は秘密情報そのものを保持し、sensitive として宣言されています。key は配信用の名前であり、意図的にマークされていません。キーは秘密情報そのものではなく、秘密情報がどこにあるかを示す名前であり、この Feature を実装するすべての Recipe はこれを平文でレンダリングします。
core/generated-secret は values をまったく宣言しないため、アタッチメントが記述するものは何もありません。これは同じものの弱いバージョンではなく、エンジン管理型の対となるものです。同じクレデンシャルファミリーのラベルを持ち、同じスロットをバインドし、その Recipes は何もレンダリングしません。クレデンシャルは、コンポーネント自身の Recipe が管理するエンジンに属するからです。
2 つのリリース
aggregate-authored.yaml は、作成者が供給する方式でスロットをバインドします。開発者は Aggregate で認証情報をアタッチし、そのアタッチメントは両方のリーフを記述します。
features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: root-password-in-the-clear委任側はエンジン管理の方式でスロットをバインドし、そのバインドはオペレーターが行います。エンジンが認証情報を所有するかどうかは Manifest が選ぶ Recipe から決まるため、release-delegated.yaml は db のエントリで core/generated-secret をアタッチし、aggregate-delegated.yaml は記述された Aggregate から features: ブロックを除いたものになります。
components: db: features: root_password: type: core/generated-secret両方のリリースは manifest.yaml を共有します。これは Terraform ターゲット向けに 3 つの型すべてをバインドするため、2 つの違いは Manifest にはありません。
components: type: core/datastore/mariadb:1.0.0: terraform/mariadb-rds:1.0.0 features: type: core/secret-value:1.0.0: terraform/variable-secret:1.0.0 core/generated-secret:1.0.0: terraform/generated-secret:1.0.0ポリシー
ビルドグラフに対してアタッチされた policy.rego:
package house.governance
import rego.v1
deny contains msg if { some node_id, attachments in input.graph.spec.feature_values_mapping some attachment_name, attachment in attachments some leaf in attachment.sensitive_payload_leaves msg := sprintf("%v: the %v credential carries declared-sensitive material in its payload at %v", [node_id, attachment_name, leaf])}sensitive_payload_leaves は、このアタッチメントのペイロードが保持するリーフのうち、アタッチされた Feature がそのパスを機密と宣言しているものを、それぞれピラー接頭辞付きのドット区切りパスとして列挙します。読み取られるペイロードは、アタッチメントが最終的に保持するものです。そのため、Feature のスキーマが
default として宣言した値にあるリーフも、作成者がそこに書いたリーフと並んで名前が挙がります。ここから 2 つの帰結があり、この例はその両方に基づいています。
- リーフが現れるのは、宣言がそれをカバーする場合だけです。つまり、宣言がそのリーフを指定しているか、そのリーフを含むオブジェクトを指定している場合で、ドット区切りのパスに対してセグメント単位で照合されます。パス自体のテキストからは何も読み取られず、値も検査されません。そのため、同じアタッチメントで
originの隣に書かれたkeyは決して現れません。その Feature はそれについて何も宣言していないためです。 - 宣言されたリーフに何も保持しないペイロードを持つアタッチメントは、リストに何も加えません。delegated の release のアタッチメントは、アタッチメント全体に対する回答を保持し、リーフごとのリストはまったく保持しません。このキーは、空になる場合にはワイヤ上から省略されるためです。
アタッチメントは .aggrega-config.yaml の ir-verdict ロールに置かれます。これはビルドグラフを受け取るロールです。
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policy.regoverdict ロールは受理か拒否かだけを返し、それ以外は何も返しません。このビルドを停止することはできますが、Aggregate を書き換えて準拠させることはできません。verdict をディスパッチするパスには、それを変更として適用する手段がないためです。delegated の形式を求める Release は、delegated の Feature をアタッチすることでそれを得ます。ポリシーが黙って差し替えることは決してありません。
両方をビルドする
aggrega build --release release-negative-authored.yaml --auto-pull # expected to failaggrega build --release release-delegated.yaml --auto-pull--auto-pull はビルド中にロックファイルを埋めます。事前に一度 aggrega pull --release release-<arm>.yaml を実行しても同じことが行われ、以降のビルドはフラグなしで実行できます。レンダリングされた出力とロックファイルは生成されるものであり、同梱はされません。
この例は入力をコミットし、それ以外はすべて再生成します。
返される結果
authored の release は拒否され、ビルドは 1 で終了します。E0005 はポリシーによる拒否が持つ診断です。
診断リファレンスを参照してください:
[… omitted: the pull's lines — the same refusal among them — and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: db: the root_password credential carries declared-sensitive material in its payload at values.origin caused by: policy violationリーフパスを読んでください。アタッチメントのペイロードは 2 つの値を持ちますが、拒否は values.origin を挙げ、values.key には触れません。この 1 文こそが、リーフ単位のマーキングが機能している証です。1 つのアタッチメント、2 つのペイロードリーフ、1 つの宣言、1 つの拒否です。
拒否は、何かがレンダリングされる前に届きます。dist/infra-authored/
ディレクトリはまったく作成されないため、後片付けが必要な部分的な成果物ツリーはなく、後続のステップが出力と誤認しうるものもディスク上に残りません。
delegated の release はビルドされ、0 で終了し、2 つのファイルを書き出します。
境界のルート設定である dist/infra-delegated/terraform/aggrega.modules.tf:
# Root configuration for this boundary. Each component rendered here is one# module block below, and the directory that block points at holds that# component's own files. One configuration means one dependency graph, which is# what lets a reference or a depends_on reach from one component to another.
module "db" { source = "./modules/db"}そして dist/infra-delegated/terraform/modules/db/main.tf です。これはビルドを識別する
# コメントブロックで始まり、続いて AWS provider の制約、リソース、そして Recipe が公開するアドレス出力を含みます:
terraform { required_providers { aws = { source = "hashicorp/aws" version = "~> 6.69" } }}
resource "aws_db_instance" "db" { identifier = "db" engine = "mariadb" engine_version = "11.4" port = 3306
## ── Compute ────────────────────────────────────────────── instance_class = "db.t3.small"
## ── Storage ────────────────────────────────────────────── allocated_storage = 100 storage_type = "gp3"
## ── Database ───────────────────────────────────────────── db_name = "appdb" username = "admin"
## Black-Box: RDS manages the password via Secrets Manager. manage_master_user_password = true
## ── HA ─────────────────────────────────────────────────── multi_az = false
## ── Backup ─────────────────────────────────────────────── backup_retention_period = 7
## ── Provider-specific overrides ──────────────────────────}
output "address" { value = aws_db_instance.db.address}manage_master_user_password = true は、委譲された形が出力に現れたものです。認証情報はエンジンが保持し、Release はどこにも機密素材を記述しません。許可された release は、何もレンダリングしないことで通過したのではなく、実際の成果物をレンダリングしました。
対照実験:代わりにアタッチメント全体についての問いを立てる
.aggrega-config.yaml でアタッチするソースを差し替えます:
sources: - policy-attachment-wide.regopolicy-attachment-wide.rego は同じ走査を、リーフごとのリストではなく attachment.sensitive
(アタッチメント全体に対する 1 つの真偽値)をキーにして行います:
deny contains msg if { some node_id, attachments in input.graph.spec.feature_values_mapping some attachment_name, attachment in attachments attachment.sensitive msg := sprintf("%v: the %v credential handles sensitive material", [node_id, attachment_name])}両方のリリースを再ビルドします。このページの以降の内容は policy.rego を前提とするため、終わったら元に戻してください。今度は両方とも拒否されます。文言も同じです:
[… omitted: the pull's lines — the same refusal among them — and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: db: the root_password credential handles sensitive material caused by: policy violationこれはルールの誤動作ではありません。ルールがより粗い問いを投げかけられ、それに正しく答えているのです。sensitive は エンティティ が宣言する内容を読み取ります。ここで真になるのは、スロットがそれにバインドされるものは何であれ秘密のマテリアルを扱うと宣言しており、スロットを誰が埋めてもそう宣言するからです。委譲されたアタッチメントは何も記述していなくても sensitive であるため、この答えをキーにしたルールでは 2 つのリリースをまったく区別できません。委譲されたリリースは、リーフごとのルールなら許可し、アタッチメント全体のルールでは許可しようがないビルドです。
3 つ目の機密性に関するファクトである sensitive_inject も役に立ちません。これは、参照先の provides キーが sensitive と宣言されている配信キーを挙げるものです。ここではスロットが配信クローズドであり、作成者が提供する Feature は provides の柱を公開しないため、このワークスペースでは何も挙げません。3 つのファクトのうち、「このアタッチメントのペイロード はどこにデータを持つか」に答えるのはリーフごとのリストだけであり、それこそがハウスルールが扱う内容です。
3 つのファクトを、ペイロードの形や、それぞれが適切な問いとなるケースとあわせて並べたものは、 ガバナンスポリシーが読み取るアタッチメントのファクトを参照してください。 ソケットそのもの(ロール、判定の重大度、オペレーター入力チャネル)については ポリシーソケットを、製品内でのポリシーの位置付けについては ガバナンスとコンプライアンスを参照してください。
このターゲットが明らかにする、作成された形式について
マネージドデータベースの Recipe は、エンジン独自のマネージドパスワードディレクティブを無条件に設定し、注入された認証情報を一切読み取りません。そのため、このターゲットでは、行き場のない機密情報を受け入れる代わりに、作成された添付そのものに対してスロット名を示してビルドを停止します。ポリシーはそれより先に、実際に存在する場所、つまりワークスペースがバージョン管理下に置くファイルの中でそれを拒否します。それがガバナンス上の関心事であり、どの Recipe が何をレンダリングしたかとは別の問題です。
これは、2 つの Features がすべてのターゲットで同等の立場にある代替手段ではなく、対等な存在である理由でもあります。認証情報を実際に保持している場合は作成者提供の Feature をバインドし、ターゲットが認証情報を所有している場合はエンジン管理の Feature をバインドします。この例の作成されたリリースは、社内ルールが機械的に検出できる不整合です。
プラグインの入手元
このワークスペースが使用するエンティティはすべて、公開されている標準ライブラリのカタログから取得されます。Component、2 つの Features、Recipe、2 つの FeatureRecipes、そしてガバナンス用の Plugin エンティティです。これらは .aggrega-config.yaml が指定する hub レジストリ、または --catalog で指定したカタログのチェックアウト(入手方法)から読み込まれます。
uri: governance/rego:0.9.0 はその Plugin エンティティを指します。これは識別子であり、<pluginType>/<name> の座標とバージョンから成り、その両方が形式の一部です。バージョンはプラグインが公開されているバージョンです。hub はこれを oci://hub.aggrega.ai/plugin/governance/rego:0.9.0 として公開しています。バージョンは解決に関与します。どのカタログディレクトリにも、どのレジストリにも、aggrega バイナリ自体にも存在しないバージョンを指定したアタッチメントは、ビルドを停止させます。バイナリが持つのは、自身のリリースのバージョンのエンジンのエンティティだけです。
--catalog でカタログのチェックアウトを指定してビルドする場合、この例は他に何も必要としません。アタッチメントが指定するリリースの aggrega バイナリは Plugin エンティティ自体を含んでいるため、すべてのエンティティはネットワークなしで解決され、実行されるエンジンは aggrega バイナリに組み込まれてコンパイルされたものです。指定しない場合、エンティティは hub.aggrega.ai から読み込まれます。
Rego エンジンは CLI バイナリに組み込まれてコンパイルされており、そのバージョンはそれを同梱するコンパイラのリリースです。別のリリースのコンパイラは、アタッチメントが指定する Plugin エンティティを hub から読み込み、自身に組み込まれたエンジンを実行します。アタッチメントのバージョンはエンティティを識別するものであり、エンジンを選ぶものではありません。
ファイル
aggregate-authored.yaml— Aggregate 内でcore/secret-valueによって束縛されるroot_passwordスロット。配信キーとマテリアルを記述します。aggregate-delegated.yaml— アタッチメントを持たない同じデータベース。開発者は何も束縛しません。manifest.yaml— コンポーネント型と両方の Feature 型を、それぞれの Terraform Recipes に束縛します。両方のリリースで共有されます。release-negative-authored.yaml、release-delegated.yaml— アームごとに 1 つずつあり、 それぞれ独自の境界directory:を持ちます。出力先を指定するフラグはないため、 2 つのリリースが 1 つのディレクトリを共有すると、2 つ目が 1 つ目を上書きします。release-delegated.yamlは、dbのエントリでスロットをcore/generated-secretによって束縛し、 何も記述しません。どの Feature がスロットを埋めるか、そしてどのドキュメントで埋めるかが、2 つのアームの唯一の違いです。policy.rego— リーフごとのマーキングをキーとするハウスルール。policy-attachment-wide.rego— アタッチメント全体の回答をキーとする対照。 デフォルトではアタッチされません。.aggrega-config.yaml— デフォルトのレジストリとガバナンスアタッチメント。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example policy-payload-leaf-sensitivityその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd policy-payload-leaf-sensitivityビルド
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1aggrega build --release release-delegated.yaml --auto-pull # buildsAI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールのみを使用し、フォルダーは自分で作成しないでください。Workspace フォルダーにまだ `policy-payload-leaf-sensitivity` フォルダーがない場合は、`example` を `policy-payload-leaf-sensitivity` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、新しい `policy-payload-leaf-sensitivity` フォルダーに例が書き込まれます。次に、`workspace_root` を `policy-payload-leaf-sensitivity`、`release` を `release-negative-authored.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。これは拒否されることを意図しているので、拒否内容を読み上げてください。続いて、同じ方法で `release` を `release-delegated.yaml` に設定して `build` ツールを呼び出してください。その 2 回目のビルドが書き込んだファイルを教えてください。それらは `policy-payload-leaf-sensitivity/dist/` の下にあります。