Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Fakty o dołączeniach odczytywane przez politykę nadzoru

Plugin nadzoru dołączony w roli ir-verdict otrzymuje cały graf budowania, a wraz z nim każde dołączenie encji Feature w budowaniu. Każde dołączenie niesie ustalony zestaw faktów o sobie: którą encję Feature wskazuje, który slot wypełnia, na którym połączeniu zostało zapisane, jeśli zapisano je na połączeniu, która encja FeatureRecipe je realizuje, co zadeklarował o nim autor katalogu, co wpisał do niego autor oraz czy obsługuje materiał, który ktoś zadeklarował jako wrażliwy. Jedna rzecz nie dociera w postaci, w jakiej ją zapisano: wartość, którą autor zadeklarował jako wrażliwą, dociera zatajona — zob. Wartości zadeklarowane jako wrażliwe docierają zatajone.

Ta strona wylicza te fakty i opisuje, co każdy z nich stwierdza, a czego nie stwierdza. Opis samego gniazda — czterech ról, poziomów ważności werdyktów, kanału danych wejściowych operatora oraz dwóch silników polityk dostarczanych w kompilatorze — znajduje się w policy-socket.md. Tabelę pole po polu z typami i informacją o wymagalności zawiera wygenerowana dokumentacja schematu grafu; ta strona uczy, jak odczytywać fakty, a tamta strona stanowi kontrakt.

Gdzie w ładunku znajdują się dołączenia

Dołączenia są zawieszone w grafie kompilacji pod kluczem feature_values_mapping, indeksowane identyfikatorem węzła, a następnie nazwą instancji, którą autor nadał każdemu dołączeniu:

input.graph.spec.feature_values_mapping[<node id>][<attachment name>]

Nazwa dołączenia pełni funkcję nośną, a nie dekoracyjną. Jest to klucz, za pomocą którego autor wypełnia slot, a więc także to, co kompilator dopasowuje do slotów zadeklarowanych przez encję Component, która jest gospodarzem.

Dołączenie zapisane na jednym z połączeń komponentu — pod features: we wpisie uses, w encji Aggregate lub w encji Release — jest jednym z dołączeń komponentu konsumującego, więc znajduje się w tym samym zbiorze, na węźle komponentu konsumującego. Jego kluczem jest nazwa nadana przez kompilator: alias połączenia i slot połączone kropką: gpt.credential dla slotu credential połączenia zapisanego pod aliasem gpt. Kropka nigdy nie pojawia się w nazwie zapisanej przez autora, więc taki klucz nigdy nie jest równy nazwie jednego z własnych dołączeń węzła. Polityka nie odczytuje jednak połączenia z klucza: wpis przenosi je jako dane, w polu connection opisanym poniżej.

package security
import rego.v1
deny contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some name, attachment in attachments
attachment.binding == "free"
msg := sprintf("%v carries attachment %v, which fills no declared slot.", [node_id, name])
}

Tylko ir-verdict widzi te fakty. Polityka render-verdict otrzymuje wyrenderowane artefakty i żadnego grafu; polityka label-transform otrzymuje projekcję etykiet i wartości węzłów, z wartościami zadeklarowanymi jako wrażliwe zatajonymi tak jak tutaj, która nie przenosi żadnych dołączeń; polityka annotation-transform otrzymuje komponenty, które może opatrzyć adnotacjami. Reguła odczytująca fakty o dołączeniach należy do roli ir-verdict, a przeniesienie jej do innej roli daje regułę, która nigdy się nie uruchamia, zamiast błędu, ponieważ ścieżka, której nie ma, jest po prostu niezdefiniowana.

Jeden kubełek dla każdej rodziny dołączeń

Każde dołączenie w węźle trafia do tego samego kubełka, niezależnie od tego, co wytwarza jego encja Feature — operacyjna encja Feature, encja Feature poświadczeń, encja Feature tożsamości. Żadna rodzina nie otrzymuje węższej projekcji niż inna, więc polityka, która przechodzi przez kubełek, widzi je wszystkie i nigdy nie musi wiedzieć, z jaką rodziną ma do czynienia, zanim odczyta fakt.

Tożsamość: type i resolved_version

type to URI katalogowej encji Feature, którą wskazuje załącznik. resolved_version to dokładna wersja, na której rozwiązywanie zależności zatrzymało się dla tej kompilacji. Oba pola są zawsze obecne.

Metadane katalogu przenoszone dosłownie: labels i catalog_annotations

labels to własne metadata.labels dołączonej encji Feature. catalog_annotations to własne metadata.annotations tej encji. Oba są przenoszone w kolejności, w jakiej deklaruje je encja katalogu, i żadne z nich nie jest filtrowane, normalizowane ani pozbawiane prefiksu — klucz we własnej przestrzeni nazw autora katalogu dociera dokładnie tak, jak został zapisany, a kompilator nie odczytuje żadnego z nich.

To dosłowne przenoszenie pozwala oprzeć politykę na etykiecie, o której istnieniu kompilator nie ma powodu wiedzieć. Autor katalogu, który oznacza encje Features z poświadczeniami wymyśloną przez siebie etykietą, może napisać regułę bezpośrednio wobec tej etykiety.

Każde z nich jest nieobecne w dołączeniu, gdy encja Feature nie deklaruje żadnych, oraz gdy jej type nie wskazuje żadnej encji katalogu.

catalog_annotations opisuje encję, którą wskazuje dołączenie. To inne pytanie niż annotation_key i annotation_source poniżej, które opisują, jak dołączenie powstało. Dołączenie zapisane w bloku features: przenosi adnotacje katalogu, nie przenosząc żadnego z pozostałych dwóch.

Który slot wypełnia załącznik: binding

binding ma trzy możliwe odpowiedzi, a trzecia nie jest wariantem drugiej:

WartośćZnaczenie
nazwa slotuZałącznik wypełnia zadeklarowany slot załącznika o tej nazwie.
freeZałącznik nie wypełnia żadnego zadeklarowanego slotu. Jest to ustalenie pozytywne: zbiór slotów został rozwiązany i żaden zadeklarowany slot nie nosi tej nazwy.
brakNie udało się rozwiązać zadeklarowanego zbioru slotów encji Component będącej hostem, więc nie wiadomo, który slot jest wypełniony.

To, z którego zadeklarowanego zbioru slotów pochodzi nazwa, zależy od miejsca, w którym zapisano załącznik. Załącznik z własnego bloku węzła wypełnia slot, który encja Component będąca hostem deklaruje we własnym featuresSchema. Załącznik zapisany na połączeniu — taki, który niesie opisane niżej connection — wypełnia slot zadeklarowany przez gniazdo połączenia, w featuresSchema tego gniazda w encji Component będącej hostem. Ta sama wartość, credential, wskazuje więc w jednym załączniku slot encji Component, a w innym slot gniazda, i to connection pozwala je rozróżnić.

Dopasowanie odbywa się po nazwie — załącznik wypełnia slot, gdy Feature jest dołączony pod nazwą slotu, w bloku komponentu lub na połączeniu — więc wartość jest dokładnym kluczem z zadeklarowanego zbioru slotów. Nic nie jest odczytywane z klucza załącznika: załącznik połączenia ma klucz gpt.credential i zgłasza credential. Przekazywana jest nazwa slotu zamiast samej flagi, ponieważ to, który slot został wypełniony, jest bardziej przydatną połową odpowiedzi.

Załącznik zapisany na połączeniu nigdy nie zgłasza free. Sloty gniazda są jedynymi nazwami, jakie może nieść przechodzące przez nie połączenie, a połączenie niosące inną nazwę jest odrzucane przy ładowaniu kompilacji, więc każdy taki załącznik w grafie, który dociera do polityki, wypełnia zadeklarowany slot.

Polityka, która traktuje brak binding jak free, zgłosi niewiadomą jako ustalenie. Należy jawnie sprawdzać wartość free.

Na którym połączeniu zapisano dołączenie: connection

connection występuje w każdym dołączeniu zapisanym na jednym z połączeń węzła i nie występuje w żadnym dołączeniu z własnego bloku węzła. Zawiera dwa pola, współrzędne tego połączenia w węźle:

PoleZnaczenie
socketGniazdo, przez które poprowadzono połączenie.
aliasAlias, pod którym zapisano połączenie.

Ta para wskazuje jedną z krawędzi grafu: krawędź, której source jest węzłem zawierającym dołączenie, a socket i alias mają te wartości. target tej krawędzi to komponent, któremu dołączenie jest przedstawiane. Dzięki temu polityka łączy dołączenie z tym, do czego ono sięga — czego nie może wyrazić żaden fakt samego dołączenia, ponieważ dołączenie znajduje się w węźle konsumującym:

package security
import rego.v1
deny contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some name, attachment in attachments
attachment.labels["feature.aggrega.ai/kind"] == "secret"
some edge in input.graph.spec.edges
edge.source == node_id
edge.socket == attachment.connection.socket
edge.alias == attachment.connection.alias
input.graph.spec.nodes[edge.target].labels["example.com/trust-zone"] == "external"
msg := sprintf("%v presents the credential %v to %v, outside the trust zone.", [node_id, name, edge.target])
}

Co connection stwierdza, a czego nie:

  • Zapisuje, gdzie autor umieścił dołączenie. Jest wypełniane na podstawie połączenia, na którym zapisano dołączenie, nigdy nie jest odczytywane z klucza dołączenia, więc zawiera gniazdo — którego klucz nie zawiera — a także alias.
  • Nie zawiera slotu. To, który slot gniazda wypełnia dołączenie, określa binding, odczytywane tak samo jak dla każdego dołączenia; slot jest podawany tylko raz, właśnie tam.
  • Nie opisuje celu. Cel, jego etykiety oraz to, kto poprowadził krawędź — programista, encja Release czy Feature — są faktami krawędzi i węzła docelowego, odczytywanymi tam po złączeniu.
  • Połączenie rysowane przez Feature nie zawiera dołączeń, więc żadne dołączenie nie zawiera connection wskazującego taką krawędź. Poświadczenie potrzebne własnemu połączeniu encji Feature jest dołączeniem wypełniającym slot deklarowany przez Feature i nie zawiera connection.
  • Brak oznacza własny blok węzła. Dołączenie bez connection zapisano we własnym features: komponentu (albo trafiło tam z szerszego zakresu lub przez rozwinięcie sterowane adnotacjami). Nie jest to ustalenie, że dołączenie nie jest przedstawiane żadnemu innemu komponentowi: do czego sięga własne poświadczenie komponentu, zależy od sposobu poprowadzenia jego dostarczania, którego to pole nie opisuje.

Poza tym, że rozstrzyga, z którego zadeklarowanego zbioru slotów odczytywane są binding i część sensitive dotycząca slotu, connection niczego nie zmienia w dołączeniu: jego FeatureRecipe, kontrakt provides, pozostałe fakty i miejsce w kubełku są takie same jak w przypadku każdego innego dołączenia węzła.

Która FeatureRecipe realizuje przyłączenie: realization

realization wskazuje FeatureRecipe, którą Manifest encji Release wiąże z przyłączeniem, w postaci <name>:<version>. Manifest wiąże po własnej nazwie przyłączenia, jeśli jego poziom name mapuje tę nazwę — dla przyłączenia zapisanego na połączeniu jest to jego nazwa kwalifikowana, powyżej gpt.credential — a w przeciwnym razie po typie encji Feature, który przyłączenie wskazuje. Wskazana FeatureRecipe to ta, za pomocą której kompilacja tych samych dokumentów renderuje przyłączenie: graf zapisuje powiązanie, zanim cokolwiek zostanie wyrenderowane, a renderowanie wiąże przyłączenie w ten sam sposób.

package security
import rego.v1
approved_realizations := {"approved-credential:1.0.0"}
deny contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some name, attachment in attachments
attachment.labels["feature.aggrega.ai/kind"] == "secret"
realization := attachment.realization
not realization in approved_realizations
msg := sprintf("%v realizes the credential %v with %v, which is not an approved FeatureRecipe.",
[node_id, name, realization])
}

Co realization stwierdza, a czego nie:

  • Jest to ta sama para wszędzie, gdzie się pojawia. aggrega inspect wypisuje ją jako realizację przyłączenia, a tam, gdzie target oznacza pochodzeniem to, co renderuje, dokumenty renderowane przez tę FeatureRecipe zawierają ją jako wartość aggrega.ai/recipe-uri, dzięki czemu polityka łączy przyłączenie z tym, co ono renderuje, bez przekładania między formami.
  • Wskazuje FeatureRecipe po nazwie i wersji, nie po możliwości. Dwie możliwości mogą każda opublikować FeatureRecipe pod jedną nazwą i wersją. To, która z nich zostaje powiązana, rozstrzyga mapowanie w encji Manifest, które wskazuje możliwość wszędzie tam, gdzie sama nazwa byłaby niejednoznaczna; to pole tego nie powtarza.
  • Własne przyłączenia granicy encji Release również je zawierają, w boundary_features, odczytywane w ten sam sposób. Przyłączenie na poziomie granicy dociera także do każdego komponentu, który granica obejmuje, i zawiera tam tę samą realizację.
  • Brak oznacza powiązanie z niczym. Przyłączenie, którego Manifest nie wiąże z żadną FeatureRecipe zawartą w katalogu, nie zawiera realization. Kompilacja takiej kompozycji zatrzymuje się przed renderowaniem, wskazując niezmapowane przyłączenie — jednak polityka w tej roli jest odpytywana przed tym zatrzymaniem, więc może napotkać przyłączenie bez tego pola. Powyższa reguła pomija takie przyłączenie, ponieważ jej treść najpierw wiąże realization; reguła, która ma je zgłosić, jawnie sprawdza brakujący klucz.

Jak powstało powiązanie: origin i dwa towarzyszące mu pola

origin odróżnia powiązanie wpisane przez programistę od powiązania wytworzonego przez rozwijanie sterowane adnotacjami:

WartośćZnaczenie
explicitZapisane w bloku features:.
annotationWytworzone przez rozwijanie sterowane adnotacjami.
mixedLiście wartości lub infra powiązania mają mieszane pochodzenie; szczegóły dla poszczególnych liści znajdują się w mapach pochodzenia.

annotation_key wskazuje adnotację, która wywołała syntetyczne powiązanie, a annotation_source lokalizuje jej deklarację w postaci <release-file-path>:<dotted-yaml-key-path>. Oba pola są nieobecne, gdy origin ma wartość explicit.

Autorskie ładunki: values, infra i inject

values to konfiguracja operacyjna dołączenia — domena dewelopera. infra to jego fizyczne wymiarowanie dla każdej instancji — domena operatora. inject to agnostyczne trasowanie wstrzykiwania, mapujące klucze dostarczania na klucze provides, z których są wypełniane, indeksowane najpierw według mechanizmu dostarczania.

To, co zawiera values dołączenia poświadczeń, zależy od wyboru autora, a kompilator przenosi to, co zapisano, nie rozwiązując żadnego z wariantów: poświadczenie przez referencję zawiera wskaźnik do magazynu sekretów, a poświadczenie przez wartość zawiera sam materiał. Niezależnie od wariantu liść, który dołączona encja Feature deklaruje jako wrażliwy, dociera do polityki jako wstrzymany, jak opisuje następna sekcja; liść, którego nie deklaruje, na przykład opublikowany lokalizator, dociera w postaci, w jakiej go zapisano.

Wartości zadeklarowane jako wrażliwe docierają wstrzymane

Każdy liść, który graf oznacza jako zadeklarowany jako wrażliwy, dociera do tego gniazda jako znacznik wstrzymania, a nie jako wartość zapisana przez autora. Znacznik jest obiektem z jednym kluczem, niosącym powód braku wartości:

{ "aggrega_withheld": "declared" }

declared oznacza, że liść jest objęty deklaracją. Ładunek, którego w ogóle nie dało się odczytać, jest wstrzymywany w całości z powodem unreadable, ponieważ żadnego liścia w nim nie dało się ocenić.

Wstrzymanie podąża za oznaczeniami samego grafu, więc obejmuje dokładnie te liście, które one wskazują, gdziekolwiek się znajdują:

  • values i infra każdego dołączenia, niezależnie od zakresu, który je zapisał — własny blok komponentu, podsystem, granica lub encja Release, rozwinięcie sterowane adnotacją — oraz niezależnie od tego, czy zapisano je we własnym bloku węzła, czy na jednym z jego połączeń, według liści wskazanych przez jego sensitive_payload_leaves;
  • infra dołączenia na poziomie granicy, w boundary_features, według jego własnego oznaczenia;
  • własne values i infra węzła, w values_mapping i infra_mapping, według własnego sensitive_payload_leaves węzła;
  • własne values i infra połączenia, na krawędzi i we wpisie uses węzła konsumującego, według sensitive_payload_leaves krawędzi, które wskazuje liście zadeklarowane jako wrażliwe przez gniazdo komponentu konsumującego.

To, na podstawie czego rozumuje polityka, pozostaje nienaruszone. Typ, rozwiązana wersja, etykiety, adnotacje katalogu, binding, connection, realization, origin i jego mapy pochodzenia, wszystkie trzy fakty dotyczące wrażliwości oraz każdy liść nieoznaczony żadną deklaracją docierają w postaci, w jakiej je zapisano. Klucz wstrzymanego liścia również zostaje zachowany, więc polityka nadal widzi, jakie liście zawiera ładunek i które z nich niosą zadeklarowany materiał — brakuje jedynie wartości. Regułę dotyczącą tego, dokąd i którą drogą przemieszcza się materiał zadeklarowany jako wrażliwy, można więc w pełni wyrazić; regułę dotyczącą treści tego materiału — celowo nie.

Autorski blok uses węzła, przenoszony na węźle obok jego krawędzi, zachowuje każde dołączenie zapisane na połączeniu w postaci jego type i description. Wartości dołączenia są przenoszone raz, na samym dołączeniu, gdzie obejmuje je wstrzymanie.

Polityka, która chce odróżnić liść wstrzymany od zapisanego przez autora, sprawdza obecność klucza znacznika:

package security
import rego.v1
audit contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some name, attachment in attachments
some key, value in attachment.values
is_object(value)
value.aggrega_withheld
msg := sprintf("%v/%v writes a declared-sensitive value at values.%v.", [node_id, name, key])
}

Jest to to samo wstrzymanie, które stosuje --ir-graph, gdy polecenie wypisuje graf, oraz aggrega/irGraph demona, gdy odpowiada klientowi, więc polityka i osoba czytająca graf widzą te same wstrzymane liście. Te powierzchnie zwracają wartości osobie, która poprosi o nie za pomocą --unredacted; ładunek otrzymywany przez politykę nie przewiduje takiej prośby, a zadeklarowane własne wartości węzła są przed nią wstrzymywane na tych samych zasadach co wartości dołączenia. Dotyczy to wyłącznie ładunku otrzymywanego przez politykę i niczego więcej: graf, z którego renderuje kompilacja, pozostaje nietknięty, więc wstrzymanie nie zmienia żadnego wyrenderowanego bajtu. Z tego, co otrzymuje polityka render-verdict, nie wstrzymuje się niczego, ponieważ to właśnie wyrenderowane artefakty ocenia ta rola.

Skąd pochodzi każdy liść: values_provenance i infra_provenance

Każda z tych map jest kluczowana kropkowaną ścieżką liścia w obrębie jego filaru, a każdy wpis zapisuje origin danego liścia — to samo rozróżnienie explicit / annotation, stosowane do jednego liścia naraz. Liść wniesiony przez adnotację dodatkowo niesie powierzchnię autorską, na której został zadeklarowany, klucz adnotacji, który go wniósł, oraz lokalizację tej deklaracji w źródle. Tam, gdzie jawny liść nadpisał liść wniesiony przez adnotację, wpis niesie też pominięty wkład, który zastąpił, dzięki czemu polityka widzi, co zostało nadpisane, a nie tylko to, co zwyciężyło.

Trzy jednostki wrażliwości

Ładunek zawiera trzy fakty dotyczące wrażliwości, a każdy z nich odnosi się do innej jednostki: całego dołączenia, pojedynczego klucza dostarczania lub pojedynczego liścia ładunku.

Każdy z nich jest obliczany z własnych danych wejściowych. Żaden nie jest wyprowadzany z innego, a w szczególności odpowiedź dla całego dołączenia nigdy nie jest przenoszona na węższe jednostki. Pomylenie dowolnych dwóch z nich daje politykę błędną w sposób, który zawodzi po cichu, dlatego warto przeczytać opis każdego z trzech osobno przed napisaniem reguły opartej na którymkolwiek z nich.

Każdy z nich wynika z tego, co autor zadeklarował — sensitive: true na liściu schematu encji Feature lub sensitive: true na slocie dołączenia deklarowanym przez encję Component, dla jej własnych dołączeń albo na jednym z jej gniazd. Treść żadnej wartości nie jest sprawdzana i z nazwy pola nie jest odczytywane żadne znaczenie.

sensitive — jedna odpowiedź dla całego dołączenia

Prawda, gdy dołączona encja Feature deklaruje wrażliwy liść w values, infra lub provides albo gdy slot wypełniany przez dołączenie deklaruje, że wszystko, co go wiąże, obsługuje materiał tajny — slot dołączenia o tej samej nazwie w encji Component będącej hostem lub, dla dołączenia zawierającego connection, slot o tej nazwie deklarowany przez gniazdo połączenia. Nieustawione, gdy żadna z tych deklaracji nie występuje.

Odpowiada to na pytanie, czym jest encja, więc celowo nie zależy od tego, co napisał konkretny autor. Odczytywane są deklaracje encji Feature, a nie podzbiór wrażliwych liści, który akurat wypełniło to dołączenie, ponieważ pole wrażliwe w jednej encji Release, a niewrażliwe w innej, byłoby bezużyteczne dla polityki rozumującej o encji katalogu.

Obie połowy są niezależne i każda obowiązuje samodzielnie. Encja Feature, która nie deklaruje żadnego wrażliwego liścia, nadal wiąże wrażliwy slot jako wrażliwe dołączenie, ponieważ tak stwierdził slot. Wypełnienie deklarujące wrażliwy liść jest wrażliwym dołączeniem nawet wtedy, gdy slot nie złożył takiej deklaracji, a nawet gdy jest to wolne dołączenie niewiążące żadnego slotu.

sensitive_inject — jedna odpowiedź na klucz dostarczania

Podzbiór inject, którego przywoływany klucz provides dołączona encja Feature deklaruje jako wrażliwy, w kształcie samego inject: mechanizm, następnie klucz dostarczania, z przywoływanym kluczem provides jako wartością.

Klucz dostarczania wypełniany z klucza provides, który encja Feature oznaczyła jako wrażliwy, pojawia się tutaj; klucz wypełniany z nieoznaczonego klucza — nie, nawet w tym samym dołączeniu i przy tym samym mechanizmie. Nieobecne, gdy dołączenie nie deklaruje żadnego mechanizmu dostarczania lub nie przywołuje żadnego wrażliwego klucza provides.

sensitive_payload_leaves — jedna odpowiedź na liść ładunku

Liście zawarte w ładunku tego dołączenia, których ścieżkę dołączona encja Feature deklaruje jako wrażliwą, każdy jako ścieżka kropkowa z prefiksem filaru, którą zajmuje dana: values.<path> lub infra.<path>.

Odczytywany jest tu ładunek, który dołączenie ostatecznie zawiera, a nie blok napisany przez autora. Liść mający wartość, którą schemat encji Feature deklaruje jako default, jest wymieniany na równi z liściem zapisanym przez autora: wypełniona wartość domyślna jest daną zawartą w ładunku, a oznaczenie odczytane wyłącznie z zapisanego bloku pozostawiłoby ją niewymienioną.

Liść pojawia się tam, gdzie obejmuje go ścieżka zadeklarowana jako wrażliwa w schemacie encji Feature — deklaracja wskazuje ten liść lub obiekt, który go zawiera. Dopasowanie odbywa się segment po segmencie po ścieżce kropkowej, więc deklaracja na db obejmuje db.password i nie sięga sąsiedniego liścia o nazwie dbPassword. Z tekstu samej ścieżki nic nie jest odczytywane i żadna wartość nie jest sprawdzana — czy autor zapisał w oznaczonym liściu sam materiał, czy wskaźnik do niego, nie jest tu możliwe do ustalenia i nie jest tym, co stwierdza oznaczenie.

Porównanie odbywa się na ładunku spłaszczonym do liści, a nie na kluczach najwyższego poziomu filaru, więc liść zagnieżdżony w zagnieżdżonej mapie jest porównywany jak każdy inny.

Liście przychodzą w kolejności, w jakiej przechowuje je ładunek, liście filaru values przed liśćmi filaru infra — w tej samej kolejności, w jakiej zawierają je same ładunki, co zapewnia identyczność bajtową danych przesyłanych między uruchomieniami na identycznym wejściu.

Ta jednostka odpowiada na pytanie, gdzie to dołączenie umieściło dane, co z konieczności zależy od encji Release. Dlatego uwzględnia ona to, co zostało napisane, a sensitive nie: są to odpowiedzi na różne pytania, a zastosowanie reguły jednego pola do drugiego by je zepsuło.

Odczytywanie wszystkich trzech razem

Autor dołącza encję Feature z poświadczeniami, która deklaruje jako wrażliwe swój liść wartości literalPassword i swój klucz provides password, wypełnia zadeklarowany slot credentials i zapisuje hasło bezpośrednio w kodzie:

{
"type": "example/db-credential",
"resolved_version": "1.0.0",
"binding": "credentials",
"values": {
"secretName": "db-creds",
"literalPassword": { "aggrega_withheld": "declared" }
},
"inject": {
"env": { "DATABASE_PASSWORD": "password" }
},
"sensitive": true,
"sensitive_inject": {
"env": { "DATABASE_PASSWORD": "password" }
},
"sensitive_payload_leaves": ["values.literalPassword"]
}

Trzy różne pytania, trzy różne odpowiedzi. Dołączenie w ogóle obsługuje materiał zadeklarowany jako wrażliwy (sensitive). Klucz środowiskowy DATABASE_PASSWORD jest tym, który go przenosi (sensitive_inject). A ładunek tego dołączenia zawiera wartość konkretnie w values.literalPassword (sensitive_payload_leaves) — natomiast values.secretName, lokalizator, który encja Feature celowo pozostawia nieoznaczony, nie występuje na tej liście, choć ładunek również go zawiera. Hasło zapisane przez autora przychodzi wstrzymane, a lokalizator obok niego przychodzi w postaci zapisanej: oznaczenie informuje politykę, że wartość istnieje, ale sama wartość nigdy do niej nie dociera.

Reguła zabraniająca dosłownego sekretu w wyrenderowanym artefakcie potrzebuje trzeciego faktu. Reguła wymagająca, by każde dołączenie obsługujące poświadczenia miało etykietę właściciela, potrzebuje pierwszego. Zastąpienie jednego drugim zmienia to, które kompilacje zostają zatrzymane.

Brak nie oznacza zezwolenia

Liść jest wymieniany tylko tam, gdzie obejmuje go deklaracja. Brak sensitive_payload_leaves oznacza więc, że to dołączenie nie wymienia żadnego liścia, który jego encja Feature deklaruje jako wrażliwy — nigdy, że ładunek nie jest wrażliwy. Nie odróżnia też dołączenia, które nie ma takiego liścia do wymienienia, od producenta, który w ogóle nie raportuje tej osi: te dwa przypadki pozostają nierozróżnialne, a odbiorca brakującego klucza dowiaduje się tego i niczego więcej.

Gość, który odczytuje brak listy liści jako zezwolenie na wyświetlenie lub wyemitowanie wartości jawnym tekstem, odczytał oznaczenie na odwrót.

Klucz jest całkowicie pomijany w przesyłanych danych, gdy byłby pusty, więc dołączenie, którego encja Feature i slot niczego nie deklarują, zawiera dokładnie te bajty, które zawierałoby, gdyby oznaczenie nie istniało. To pominięcie ułatwia błędne odczytanie i dlatego warto jasno określić kierunek.

Najwyraźniejszym przypadkiem jest dołączenie, które jest wrażliwe i nie wymienia żadnego liścia. Weźmy powyższe dołączenie i zmieńmy dwie rzeczy — autor zapisuje tylko lokalizator, pozostawiając liść zadeklarowany jako wrażliwy niewypełniony, i wypełnia klucz środowiskowy z nieoznaczonego klucza provides name encji Feature zamiast z password:

{
"type": "example/db-credential",
"resolved_version": "1.0.0",
"binding": "credentials",
"values": { "secretName": "db-creds" },
"inject": {
"env": { "DATABASE_PASSWORD": "name" }
},
"sensitive": true
}

sensitive nadal jest prawdą — deklaracje encji Feature się nie zmieniły — natomiast obie węższe jednostki zniknęły. Dołączenie nadal obsługuje materiał tajny; po prostu nie robi tego przez liść ani klucz dostarczania zawarty w tym dołączeniu. Polityka oparta na zbiorczej odpowiedzi odrzuca tę kompilację, a polityka oparta na oznaczeniu na poziomie liścia ją przepuszcza. Obie reguły są uzasadnione, a wybór tej, której potrzebuje polityka, jest świadomą decyzją autora polityki.

Ta sama asymetria działa w drugą stronę dla sensitive_inject: dołączenie może zapisywać wrażliwy liść, nie kierując niczego wrażliwego przez klucz dostarczania, albo kierować wrażliwy klucz provides, nie zapisując żadnej wartości.

Czego nie robi deklaracja wrażliwości

Oznaczenie jest adnotacją, a nie mechanizmem kontroli. Zadeklarowanie liścia lub slotu jako wrażliwego niczego nie szyfruje, nie waliduje ani nie odrzuca wartości i nie wymusza mechanizmu dostarczania. Obecność deklaracji nie zmienia wyniku żadnej kompilacji.

W przypadku większości celów nie zmienia też żadnego wyrenderowanego bajtu: zadeklarowana jako wrażliwa wartość, podana przez autora inline, jest renderowana dokładnie tak samo jak wartość niezadeklarowana. Terraform jest wyjątkiem wśród celów biblioteki standardowej, ponieważ ma natywny prymityw wrażliwości na poziomie pojedynczej wartości, na który deklaracja może trafić — zob. providers/terraform.md „Declared-sensitive module inputs”. Cel bez własnego pojęcia wrażliwości nie ma niczego, co deklaracja mogłaby zmienić.

Wszędzie natomiast deklaracje sprawiają, że fakt staje się czytelny — dla własnego wyjścia diagnostycznego kompilatora oraz dla polityki w tym gnieździe, która decyduje, co z nim zrobić. Przekształcenie oznaczenia w wynik kompilacji jest zadaniem polityki i właśnie do tego służy to gniazdo. Polityka dowiaduje się przy tym o materiale zadeklarowanym jako wrażliwy, nie otrzymując go: oznaczenie dociera, a wartość dociera wstrzymana.

Odsyłacze

  • policy-socket.md — gniazdo governance: cztery role, poziomy ważności werdyktów, kanał danych wejściowych operatora, silniki polityk dostarczane wraz z kompilatorem oraz podłączanie wtyczki do obszaru roboczego.
  • plugin-contract.md — miejsce gniazda w potoku i jego typowane kształty danych przesyłanych.
  • dokumentacja schematu grafu — kontrakt pole po polu dla grafu budowania, w tym każde pole załącznika.
  • entities/component.md „Attachment Slots” (Sloty załączników) — deklarowanie slotu i deklarowanie slotu jako wrażliwego oraz featuresSchema deklarowany przez gniazdo dla połączeń przez nie poprowadzonych.
  • entities/aggregate.md „A connection’s own attachments” (Własne załączniki połączenia) — zapisywanie załącznika na połączeniu i nazwa, jaką przyjmuje.
  • vocabulary/compact-form-authoring.md „Declaring a leaf sensitive” (Deklarowanie liścia jako wrażliwego) — słowo kluczowe sensitive: i granica tego, co daje jego zadeklarowanie.
  • vocabulary/labels-and-annotations.md — powierzchnie etykiet i adnotacji odczytywane przez politykę.