Polityka oparta na jedynym liściu, który napisał autor
Ten przykład uczy jednej reguły domowej i faktu, który pozwala ją wyrazić:
Slot poświadczeń może zostać wypełniony. Nie może zostać wypełniony przez wpisanie materiału do własnego źródła obszaru roboczego.
Dwa wydania różniące się jedną zmienną: ta sama zarządzana baza danych, ten sam wymagany slot poświadczeń, wypełniony przez dwie różne encje Features — jedną dołącza programista w encji Aggregate, drugą operator w encji Release. Polityka napisana przez operatora odrzuca jedną i dopuszcza drugą. Uruchomienie tej pary ma sens dlatego, że oba dołączenia obsługują materiał tajny — reguły nie można więc sformułować wokół pytania „czy to dołączenie jest wrażliwe?”, a polityka kontrolna poniżej pokazuje, co się dzieje przy takiej próbie.
Wszystko poza dwoma plikami polityk pochodzi z katalogu biblioteki standardowej, łącznie z encją Plugin do zarządzania (governance).
Slot i dwie encje Features, które mogą go wypełnić
core/datastore/mariadb deklaruje jeden wymagany slot na poświadczenia:
featuresSchema: root_password: required: true sensitive: true inject: [] description: Root database password. Recipe controls delivery (Black-Box).sensitive: true jest tu stwierdzeniem dotyczącym punktu powiązania, a nie konkretnego wypełnienia: cokolwiek wiąże ten slot, obsługuje materiał tajny. inject: [] zamyka dostarczanie — to encja Recipe decyduje, dokąd trafia poświadczenie, a programista tego nie narzuca.
Ten slot wiążą dwie encje Features z biblioteki standardowej, które modelują przeciwstawne cykle życia poświadczeń:
| Feature | kto jest właścicielem materiału | co definiuje dołączenie |
|---|---|---|
core/secret-value | dostarcza go autor | dwa liście values — zob. poniżej |
core/generated-secret | docelowy silnik go tworzy i rotuje | nic; nie deklaruje żadnych values |
core/secret-value deklaruje swoje dwa liście asymetrycznie, a ta asymetria jest osią całego przykładu:
values: origin: { type: string, sensitive: true } key: { type: string, required: true, default: "value" }origin przenosi materiał i jest zadeklarowany jako wrażliwy. key jest nazwą dostarczenia i celowo pozostaje nieoznaczony — klucz wskazuje, gdzie znajduje się materiał, a nie jest samym materiałem, i każda encja Recipe implementująca tę encję Feature renderuje go jawnie.
core/generated-secret nie deklaruje żadnych values, więc dołączenie nie ma czego definiować. Jest to odpowiednik zarządzany przez silnik, a nie słabsza wersja tego samego: nosi tę samą etykietę rodziny poświadczeń, wiąże ten sam slot, a jego encje Recipes niczego nie renderują, ponieważ poświadczenie należy do silnika, którym zarządza własna encja Recipe komponentu.
Dwa wydania
aggregate-authored.yaml wiąże slot w sposób, w którym materiał dostarcza autor: deweloper
dołącza poświadczenie w encji Aggregate, a dołączenie definiuje oba
liście:
features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: root-password-in-the-clearGałąź delegowana wiąże go w sposób zarządzany przez silnik, a to wiązanie należy do
operatora: to, czy poświadczenie należy do silnika, wynika z encji Recipe, którą
wybiera encja Manifest, dlatego release-delegated.yaml dołącza core/generated-secret we
swoim wpisie dla db, a aggregate-delegated.yaml to napisana przez autora encja Aggregate
bez bloku features::
components: db: features: root_password: type: core/generated-secretOba wydania współdzielą plik manifest.yaml, który wiąże wszystkie trzy typy dla
celu Terraform, więc to nie encja Manifest jest miejscem, w którym się różnią:
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.0Polityka
policy.rego, dołączona do grafu budowania:
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 wymienia te liście niesione przez ładunek tego dołączenia, których ścieżkę dołączona encja Feature deklaruje jako wrażliwą, każdy jako ścieżkę kropkową poprzedzoną nazwą filaru. Odczytywany jest ładunek, który dołączenie ostatecznie niesie, więc liść o wartości zadeklarowanej w schemacie encji Feature jako default jest wymieniany na równi z liściem, którego wartość zapisał autor. Wynikają z tego dwie konsekwencje, a przykład opiera się na obu:
- Liść pojawia się tylko tam, gdzie obejmuje go deklaracja — deklaracja wskazuje ten liść albo obiekt, który go zawiera, przy dopasowaniu ścieżki kropkowej segment po segmencie. Nic nie jest odczytywane z samego tekstu ścieżki i żadna wartość nie jest badana. Dlatego
key, zapisany obokoriginw tym samym dołączeniu, nigdy się nie pojawia: jego encja Feature nic o nim nie deklaruje. - Dołączenie, którego ładunek nie niesie niczego w zadeklarowanym liściu, nie wnosi niczego do listy. Dołączenie w wydaniu delegowanym niesie odpowiedź dotyczącą całego dołączenia i w ogóle nie ma listy dla poszczególnych liści, ponieważ klucz jest pomijany w przesyłanych danych, gdy byłby pusty.
Dołączenie znajduje się w .aggrega-config.yaml w roli ir-verdict, czyli w roli, która otrzymuje graf budowania:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policy.regoRola werdyktu zwraca akceptację albo odrzucenie i nic więcej. Może zatrzymać to budowanie; nie może przepisać encji Aggregate tak, by stała się zgodna, ponieważ ścieżka przekazująca werdykt nie ma możliwości zastosowania go jako zmiany. Encja Release, która chce formy delegowanej, uzyskuje ją przez dołączenie delegowanej encji Feature — nigdy przez politykę, która po cichu ją podstawia.
Budowanie obu
aggrega build --release release-negative-authored.yaml --auto-pull # expected to failaggrega build --release release-delegated.yaml --auto-pull--auto-pull wypełnia plik blokady podczas budowania; jednorazowe uruchomienie aggrega pull --release release-<arm>.yaml wcześniej robi to samo i pozwala uruchamiać późniejsze budowania bez tej flagi. Wyrenderowane wyjście i pliki blokady są generowane, a nie dostarczane:
ten przykład zatwierdza swoje dane wejściowe i generuje wszystko inne na nowo.
Co zwraca kompilacja
Release napisany przez autora zostaje odrzucony, a kompilacja kończy się kodem 1. E0005 to
diagnostyka, którą niesie odmowa polityki — zob.
dokumentację diagnostyk:
[… 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 violationWarto odczytać ścieżkę liścia. Ładunek dołączenia niesie dwie wartości; odmowa
wskazuje values.origin i nie wspomina o values.key. To jedno zdanie to
znakowanie per liść w działaniu — jedno dołączenie, dwa liście ładunku, jedna
deklaracja, jedna odmowa.
Odmowa następuje też, zanim cokolwiek zostanie wyrenderowane. Katalog dist/infra-authored/
nie jest w ogóle tworzony, więc nie ma częściowego drzewa artefaktów do sprzątania
ani niczego na dysku, co późniejszy krok mógłby wziąć za wynik.
Release delegowany kompiluje się, kończy kodem 0 i zapisuje dwa pliki.
dist/infra-delegated/terraform/aggrega.modules.tf, główną konfigurację
granicy:
# 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"}oraz dist/infra-delegated/terraform/modules/db/main.tf, który zaczyna się
blokiem komentarzy # identyfikującym kompilację, a następnie zawiera ograniczenie
providerа AWS, zasób oraz wyjście adresu publikowane przez 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 to forma delegowana docierająca do wyniku: poświadczenie przechowuje silnik, a encja Release nigdzie nie wskazuje żadnego materiału. Dozwolony release wyrenderował rzeczywisty artefakt, zamiast przejść, nie renderując niczego.
Próba kontrolna: pytanie o całe powiązanie
Należy podmienić dołączone źródło w .aggrega-config.yaml:
sources: - policy-attachment-wide.regopolicy-attachment-wide.rego to to samo przejście, oparte jednak na attachment.sensitive
— jednej wartości logicznej dla całego powiązania — zamiast na liście dla poszczególnych liści:
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])}Należy ponownie zbudować oba wydania — a potem przywrócić policy.rego, ponieważ dalsza część
tej strony zakłada jego obecność. Teraz oba są odrzucane, z tym samym komunikatem:
[… 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 violationTo nie jest błędne zadziałanie reguły — reguła otrzymuje bardziej ogólne pytanie
i odpowiada na nie poprawnie. sensitive odczytuje to, co deklarują encje: jest
tu prawdą, ponieważ slot deklaruje, że cokolwiek się z nim wiąże, obsługuje materiał
tajny, i slot mówi to niezależnie od tego, kto go wypełnia. Delegowane powiązanie
niczego nie definiuje, a mimo to jest wrażliwe, więc reguła oparta na tej odpowiedzi w ogóle
nie potrafi rozróżnić obu wydań. Wydanie delegowane to build, na który reguła dla poszczególnych liści
pozwala, a reguła dla całego powiązania nie ma żadnej możliwości, by na niego pozwolić.
Trzeci fakt dotyczący wrażliwości, sensitive_inject, również nie pomaga: wskazuje
klucze dostarczania, których przywoływany klucz provides jest zadeklarowany jako wrażliwy. Tutaj
slot jest zamknięty na dostarczanie, a dostarczana przez autora encja Feature nie publikuje
filaru provides, więc w tym obszarze roboczym nie wskazuje niczego. Z trzech faktów
tylko lista dla poszczególnych liści odpowiada na pytanie „gdzie ładunek tego powiązania przenosi dane”,
a właśnie tego dotyczy reguła wewnętrzna.
Zestawienie wszystkich trzech faktów, z kształtami ładunków i przypadkami, w których każdy z nich jest właściwym pytaniem, zawiera strona fakty o powiązaniach odczytywane przez politykę nadzoru. O samym gnieździe — rolach, poziomach ważności werdyktów, kanale danych wejściowych operatora — mówi strona gniazdo polityki, a o miejscu polityk w produkcie — Nadzór i zgodność.
Co ten cel pokazuje na temat formy autorskiej
Recipe zarządzanej bazy danych bezwarunkowo ustawia własną dyrektywę silnika dotyczącą zarządzanego hasła i nie odczytuje żadnego wstrzykniętego poświadczenia, więc na tym celu zatrzymuje budowanie na samym autorskim załączniku, wskazując gniazdo, zamiast przyjąć materiał, który nie ma gdzie trafić. Polityka odrzuca go wcześniej, tam, gdzie faktycznie się znajduje: w pliku, który obszar roboczy przechowuje w systemie kontroli wersji. To jest kwestia zarządzania (governance) i jest to sprawa odrębna od tego, co wyrenderowałby jakikolwiek Recipe.
Dlatego też obie encje Features są równorzędne, a nie alternatywami o równej pozycji na każdym celu. Encję Feature dostarczaną przez autora należy wiązać tam, gdzie rzeczywiście posiada się poświadczenie, a tę zarządzaną przez silnik — tam, gdzie poświadczenie należy do celu. Autorskie wydanie z tego przykładu jest niedopasowaniem, które reguła wewnętrzna może wychwycić mechanicznie.
Skąd pochodzi plugin
Każda encja, z której korzysta ten obszar roboczy, pochodzi z opublikowanego katalogu biblioteki standardowej: encja Component, dwie encje Features, encja Recipe, dwie encje FeatureRecipes oraz encja Plugin zarządzania — odczytywane z rejestru hub wskazanego w .aggrega-config.yaml lub z checkoutu katalogu (skąd go wziąć) wskazanego za pomocą --catalog.
uri: governance/rego:0.9.0 wskazuje tę encję Plugin. Jest to tożsamość: współrzędna <pluginType>/<name> wraz z wersją, a obie części należą do formy. Wersja to ta, pod którą plugin został opublikowany — hub publikuje ją jako oci://hub.aggrega.ai/plugin/governance/rego:0.9.0. Wersja bierze udział w rozwiązywaniu: dołączenie wskazujące wersję, której nie zawiera żaden katalog, żaden rejestr ani sam plik binarny aggrega, zatrzymuje kompilację. Plik binarny zawiera encję silnika wyłącznie w wersji własnego wydania.
Kompilowany z --catalog wskazującym checkout katalogu przykład nie potrzebuje niczego więcej: z plikiem binarnym aggrega wydania wskazanego przez dołączenie, który sam zawiera encję Plugin, każda encja jest rozwiązywana bez sieci, a uruchamiany silnik to ten wkompilowany w plik binarny aggrega. Bez tej flagi encje są odczytywane z hub.aggrega.ai.
Silnik Rego jest wkompilowany w plik binarny CLI, a jego wersją jest wydanie kompilatora, które go dostarcza. Kompilator innego wydania odczytuje z hubu encję Plugin wskazaną przez dołączenie i uruchamia wkompilowany w siebie silnik: wersja w dołączeniu identyfikuje encję i nie wybiera silnika.
Pliki
aggregate-authored.yaml— slotroot_passwordpowiązany przezcore/secret-valuew encji Aggregate, który definiuje klucz dostarczenia i materiał.aggregate-delegated.yaml— ta sama baza danych bez dołączenia: deweloper niczego nie wiąże.manifest.yaml— wiąże typ komponentu i oba typy encji Feature z ich encjami Recipes dla Terraform. Wspólny dla obu wydań.release-negative-authored.yaml,release-delegated.yaml— po jednym na wariant, każdy z własnym katalogiem granicznymdirectory:. Nie ma flagi określającej lokalizację wyjścia, więc gdyby dwa wydania współdzieliły jeden katalog, drugie nadpisałoby pierwsze.release-delegated.yamlwiąże też slot, we wpisie dladb, za pomocącore/generated-secret, niczego nie definiując. Jedyną różnicą między oboma wariantami jest to, która encja Feature wypełnia slot i w którym dokumencie.policy.rego— reguła organizacji, oparta na oznaczeniu poszczególnych liści.policy-attachment-wide.rego— wariant kontrolny, oparty na odpowiedzi dotyczącej całego dołączenia. Domyślnie niedołączony..aggrega-config.yaml— domyślny rejestr i dołączenie ładu (governance).
Generowanie przykładu
Ten przykład można zbudować za pomocą poniższych poleceń albo zlecić jego zbudowanie asystentowi AI.
Należy zapisać przykład w nowym folderze nazwanym tak jak on:
aggrega scaffold --example policy-payload-leaf-sensitivityNastępnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu:
cd policy-payload-leaf-sensitivityKompilacja
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1aggrega build --release release-delegated.yaml --auto-pull # buildsZ asystentem AI
Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić mu ten prompt.
Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder Workspace nie zawiera jeszcze folderu `policy-payload-leaf-sensitivity`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `policy-payload-leaf-sensitivity` i bez `dir`: zapisuje ono przykład w nowym folderze `policy-payload-leaf-sensitivity`. Następnie wywołaj narzędzie `build` z `workspace_root` ustawionym na `policy-payload-leaf-sensitivity`, `release` ustawionym na `release-negative-authored.yaml`, `auto_pull` ustawionym na true i `write` ustawionym na true: ta kompilacja ma zostać odrzucona, więc odczytaj mi odmowę. Potem wywołaj narzędzie `build` w ten sam sposób z `release` ustawionym na `release-delegated.yaml`. Powiedz mi, jakie pliki zapisała ta druga kompilacja; znajdują się w `policy-payload-leaf-sensitivity/dist/`.