Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Die Anbindungsfakten, die eine Governance-Richtlinie liest

Ein Governance-Plugin, das an der Rolle ir-verdict angebunden ist, erhält den gesamten Build-Graphen, und jede Feature-Anbindung im Build kommt mit ihm an. Jede Anbindung trägt eine feste Menge von Fakten über sich selbst: welches Feature sie nennt, welchen Slot sie befüllt, auf welcher Verbindung sie geschrieben wurde, wenn sie auf einer geschrieben wurde, welches FeatureRecipe sie realisiert, was der Katalog-Autor über sie deklariert hat, was ein Autor in sie geschrieben hat und ob sie Material verarbeitet, das jemand als sensibel deklariert hat. Eines kommt nicht wie geschrieben an: Ein Wert, den ein Autor als sensibel deklariert hat, kommt zurückgehalten an — siehe Als sensibel deklarierte Werte kommen zurückgehalten an.

Diese Seite zählt diese Fakten auf und sagt, was jeder behauptet und was nicht. Zum Socket selbst — den vier Rollen, den Schweregraden der Verdikte, dem Eingabekanal des Betreibers und den zwei Richtlinien-Engines, die im Compiler ausgeliefert werden — siehe policy-socket.md. Für die feldweise Tabelle mit Typen und Pflichtangaben siehe die generierte Graph-Schema-Referenz; diese Seite lehrt, wie man die Fakten liest, und jene Seite ist der Vertrag.

Wo die Anbindungen in der Payload liegen

Anbindungen hängen im Build-Graphen unter feature_values_mapping, geschlüsselt nach Knoten-ID und dann nach dem Instanznamen, den der Autor jeder Anbindung gegeben hat:

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

Der Anbindungsname ist tragend und nicht dekorativ. Er ist der Schlüssel, über den ein Autor einen Slot befüllt, und daher auch das, was der Compiler mit den deklarierten Slots der Host-Component abgleicht.

Eine Anbindung, die auf einer der Verbindungen einer Komponente geschrieben ist — unter features: an einem Eintrag uses, im Aggregate oder im Release —, ist eine der Anbindungen der konsumierenden Komponente und liegt daher im selben Bucket, am Knoten der konsumierenden Komponente. Ihr Schlüssel ist der Name, den der Compiler ihr gibt, der Alias der Verbindung und der Slot durch einen Punkt verbunden: gpt.credential für den Slot credential der unter dem Alias gpt geschriebenen Verbindung. Der Punkt erscheint nie in einem Namen, den ein Autor schreibt, daher ist dieser Schlüssel nie gleich dem Namen einer der eigenen Anbindungen des Knotens. Eine Richtlinie liest die Verbindung jedoch nicht aus dem Schlüssel: Der Eintrag trägt sie als Daten, in connection weiter unten.

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])
}

Nur ir-verdict sieht diese Fakten. Eine Richtlinie render-verdict erhält die gerenderten Artefakte und keinen Graphen; eine Richtlinie label-transform erhält eine Projektion der Labels und Werte der Knoten, mit ihren wie hier zurückgehaltenen, als sensibel deklarierten Werten, die überhaupt keine Anbindungen trägt; eine Richtlinie annotation-transform erhält die Komponenten, die sie annotieren darf. Eine Regel, die Anbindungsfakten liest, gehört an ir-verdict, und sie an eine andere Rolle zu verschieben, ergibt statt eines Fehlers eine Regel, die nie auslöst, weil ein Pfad, der nicht da ist, schlicht undefiniert ist.

Ein Bucket, jede Anbindungsfamilie

Jede Anbindung an einem Knoten liegt im selben Bucket, was auch immer ihr Feature erzeugt — ein operatives Feature, ein Zugangsdaten-Feature, ein Identitäts-Feature. Keine Familie erhält eine engere Projektion als eine andere, daher sieht eine Richtlinie, die den Bucket durchläuft, alle und muss nie wissen, welche Familie sie gerade betrachtet, bevor sie einen Fakt lesen kann.

Identität: type und resolved_version

type ist die URI des Katalog-Features, das die Anbindung nennt. resolved_version ist die exakte Version, auf die sich die Auflösung für diesen Build festgelegt hat. Beide sind immer vorhanden.

Katalog-Metadaten, wörtlich übernommen: labels und catalog_annotations

labels sind die eigenen metadata.labels der angebundenen Feature-Entität. catalog_annotations sind die eigenen metadata.annotations dieser Entität. Beide werden in der Reihenfolge getragen, in der die Katalogentität sie deklariert, und keines wird gefiltert, normalisiert oder um ein Präfix gekürzt — ein Schlüssel im eigenen Namespace des Katalog-Autors kommt genau wie geschrieben an, und der Compiler liest keinen davon.

Diese wörtliche Übernahme ermöglicht es, eine Richtlinie an einem Label anzusetzen, von dessen Existenz der Compiler keinen Grund hat zu wissen. Ein Katalog-Autor, der Zugangsdaten-Features mit einem Label eigener Erfindung kennzeichnet, kann direkt gegen dieses Label eine Regel schreiben.

Jedes fehlt in der Anbindung, wenn das Feature keines deklariert und wenn sein type zu keiner Katalogentität aufgelöst wird.

catalog_annotations beschreibt die Entität, die die Anbindung nennt. Das ist eine andere Frage als annotation_key und annotation_source weiter unten, die beschreiben, wie die Anbindung entstanden ist. Eine Anbindung, die in einem Block features: geschrieben ist, trägt Katalog-Annotationen, ohne eines der beiden anderen zu tragen.

Welchen Slot die Anbindung befüllt: binding

binding hat drei Antworten, und die dritte ist keine Variante der zweiten:

WertBedeutung
ein Slot-NameDie Anbindung befüllt den deklarierten Anbindungs-Slot dieses Namens.
freeDie Anbindung befüllt keinen deklarierten Slot. Das ist ein positiver Befund: Die Slot-Menge wurde aufgelöst, und kein deklarierter Slot trägt diesen Namen.
fehlendDie deklarierte Slot-Menge der Host-Component konnte nicht aufgelöst werden, daher ist unbekannt, welcher Slot befüllt wird.

Aus welcher deklarierten Slot-Menge der Name stammt, hängt davon ab, wo die Anbindung geschrieben wurde. Eine Anbindung des eigenen Blocks des Knotens befüllt einen Slot, den die Host-Component in ihrem eigenen featuresSchema deklariert. Eine auf einer Verbindung geschriebene Anbindung — eine, die connection weiter unten trägt — befüllt einen Slot, den der Socket der Verbindung deklariert, im featuresSchema dieses Sockets an der Host-Component. Derselbe Wert, credential, nennt also bei einer Anbindung einen Slot der Component und bei einer anderen einen Slot eines Sockets, und connection ist das, was die beiden unterscheidet.

Die Paarung erfolgt über den Namen — eine Anbindung befüllt einen Slot, wenn das Feature unter dem Namen des Slots angebunden ist, am Block der Komponente oder an der Verbindung —, daher ist der Wert ein exakter Schlüssel aus der deklarierten Slot-Menge. Nichts wird aus dem Schlüssel der Anbindung gelesen: Die Anbindung einer Verbindung ist mit gpt.credential geschlüsselt und meldet credential. Der Slot-Name wird statt eines bloßen Flags getragen, weil welcher Slot befüllt wurde die nützlichere Hälfte der Antwort ist.

Eine auf einer Verbindung geschriebene Anbindung meldet nie free. Die Slots eines Sockets sind die einzigen Namen, die eine Verbindung über ihn tragen darf, und eine Verbindung, die einen anderen Namen trägt, wird beim Laden des Builds zurückgewiesen, daher befüllt jede solche Anbindung in einem Graphen, der eine Richtlinie erreicht, einen deklarierten Slot.

Eine Richtlinie, die ein fehlendes binding als free behandelt, meldet eine Unbekannte als Befund. Prüfen Sie explizit auf free.

Auf welcher Verbindung die Anbindung geschrieben wurde: connection

connection ist an jeder Anbindung vorhanden, die auf einer der Verbindungen des Knotens geschrieben ist, und fehlt an jeder Anbindung des eigenen Blocks des Knotens. Es trägt zwei Felder, die Koordinaten dieser Verbindung am Knoten:

FeldBedeutung
socketDer Socket, über den die Verbindung verbunden ist.
aliasDer Alias, unter dem die Verbindung geschrieben ist.

Das Paar nennt eine der Kanten des Graphen: die Kante, deren source der Knoten ist, der die Anbindung trägt, und deren socket und alias diese sind. Das target dieser Kante ist die Komponente, der die Anbindung vorgelegt wird. So verknüpft eine Richtlinie eine Anbindung mit dem, was sie erreicht — etwas, das kein Fakt an der Anbindung allein sagen kann, weil die Anbindung am konsumierenden Knoten liegt:

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])
}

Was connection behauptet und was nicht:

  • Es hält fest, wo der Autor die Anbindung geschrieben hat. Es wird aus der Verbindung befüllt, auf der die Anbindung geschrieben wurde, nie aus dem Schlüssel der Anbindung geparst, daher enthält es den Socket — den der Schlüssel nicht trägt — ebenso wie den Alias.
  • Es trägt den Slot nicht. Welchen Slot des Sockets die Anbindung befüllt, ist binding, gelesen wie bei jeder Anbindung; der Slot wird einmal gemeldet, dort.
  • Es beschreibt das Target nicht. Das Target, seine Labels und wer die Kante verbunden hat — der Entwickler, das Release oder ein Feature — sind Fakten der Kante und des Target-Knotens, die dort nach der Verknüpfung gelesen werden.
  • Eine Verbindung, die ein Feature zieht, trägt keine Anbindungen, daher trägt keine Anbindung eine connection, die eine solche Kante nennt. Zugangsdaten, die die eigene Verbindung eines Features benötigt, sind eine Anbindung, die einen Slot befüllt, den das Feature deklariert, und sie tragen keine connection.
  • Fehlend bedeutet der eigene Block des Knotens. Eine Anbindung ohne connection wurde in den eigenen features: der Komponente geschrieben (oder hat sie aus einem breiteren Geltungsbereich oder durch annotationsgesteuerte Erweiterung erreicht). Es ist kein Befund, dass die Anbindung keiner anderen Komponente vorgelegt wird: Was die eigenen Zugangsdaten einer Komponente erreichen, entscheidet sich daran, wie ihre Auslieferung verbunden ist, was dieses Feld nicht beschreibt.

Abgesehen davon, dass es entscheidet, aus welcher deklarierten Slot-Menge binding und die Slot-Hälfte von sensitive gelesen werden, ändert connection nichts an der Anbindung: Ihr FeatureRecipe, ihr provides-Vertrag, ihre übrigen Fakten und ihr Platz im Bucket sind die jeder Anbindung, die der Knoten trägt.

Welches FeatureRecipe die Anbindung realisiert: realization

realization nennt das FeatureRecipe, das das Manifest des Release an die Anbindung bindet, als <name>:<version>. Das Manifest bindet über den eigenen Namen der Anbindung, wo seine Ebene name diesen Namen abbildet — bei einer auf einer Verbindung geschriebenen Anbindung ihr qualifizierter Name, oben gpt.credential —, und andernfalls über den Feature-Typ, den die Anbindung nennt. Das genannte FeatureRecipe ist dasjenige, mit dem ein Build derselben Dokumente die Anbindung rendert: Der Graph hält die Bindung fest, bevor irgendetwas gerendert wird, und das Rendern bindet die Anbindung auf dieselbe Weise.

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])
}

Was realization behauptet und was nicht:

  • Es ist überall, wo es erscheint, dasselbe Paar. aggrega inspect gibt es als die Realisierung der Anbindung aus, und wo ein Target Herkunftsangaben auf das stempelt, was es rendert, tragen die Dokumente, die dieses FeatureRecipe rendert, es als ihren Wert aggrega.ai/recipe-uri, sodass eine Richtlinie eine Anbindung mit dem verknüpft, was sie rendert, ohne zwischen Formen zu übersetzen.
  • Es nennt das FeatureRecipe nach Name und Version, nicht nach Fähigkeit. Zwei Fähigkeiten können jeweils ein FeatureRecipe unter demselben Namen und derselben Version veröffentlichen. Welches davon gebunden ist, legt die Abbildung des Manifest fest, die die Fähigkeit überall dort nennt, wo der Name allein mehrdeutig wäre; dieses Feld wiederholt das nicht.
  • Auch die eigenen Anbindungen einer Release-Boundary tragen es, unter boundary_features, auf dieselbe Weise gelesen. Eine Anbindung auf Boundary-Ebene erreicht außerdem jede Komponente, die die Boundary enthält, und trägt dort dieselbe Realisierung.
  • Fehlend bedeutet an nichts gebunden. Eine Anbindung, die das Manifest an kein FeatureRecipe bindet, das der Katalog enthält, trägt keine realization. Ein Build einer solchen Komposition bricht ab, bevor er rendert, und nennt die unabgebildete Anbindung — doch eine Richtlinie an dieser Rolle wird vor diesem Abbruch befragt, daher kann sie auf eine Anbindung treffen, die keine trägt. Die Regel oben lässt eine solche Anbindung passieren, weil ihr Rumpf zuerst realization bindet; eine Regel, die sie melden will, prüft explizit auf den fehlenden Schlüssel.

Wie die Anbindung entstanden ist: origin und seine zwei Begleiter

origin unterscheidet eine Anbindung, die ein Entwickler getippt hat, von einer, die die annotationsgesteuerte Erweiterung erzeugt hat:

WertBedeutung
explicitIn einem Block features: verfasst.
annotationDurch annotationsgesteuerte Erweiterung erzeugt.
mixedDie Wert- oder Infra-Blätter der Anbindung tragen eine Mischung aus beidem; das Detail pro Blatt steht in den Herkunfts-Maps.

annotation_key nennt die Annotation, die eine synthetische Anbindung ausgelöst hat, und annotation_source verortet ihre Deklaration als <release-file-path>:<dotted-yaml-key-path>. Beide fehlen, wenn origin explicit ist.

Die verfassten Payloads: values, infra und inject

values ist die operative Konfiguration der Anbindung — die Domäne des Entwicklers. infra ist ihre physische Dimensionierung pro Instanz — die des Betreibers. inject ist das agnostische Injektions-Routing, das Auslieferungsschlüssel den Schlüsseln provides zuordnet, aus denen sie befüllt werden, zuerst nach Auslieferungsmechanismus geschlüsselt.

Was values einer Zugangsdaten-Anbindung trägt, ist die Wahl des Autors, und der Compiler trägt, was auch immer geschrieben wurde, ohne eines von beiden aufzulösen: Zugangsdaten per Referenz tragen einen Zeiger in einen Secret-Speicher, und solche per Wert tragen das Material selbst. Was auch immer es ist, ein Blatt, das das angebundene Feature als sensibel deklariert, erreicht eine Richtlinie zurückgehalten, wie der nächste Abschnitt beschreibt; ein Blatt, das es undeklariert lässt, etwa ein veröffentlichter Lokator, kommt wie geschrieben an.

Als sensibel deklarierte Werte kommen zurückgehalten an

Jedes Blatt, das der Graph als sensibel deklariert markiert, kommt an diesem Socket als Zurückhaltungsmarkierung an statt als der Wert, den ein Autor geschrieben hat. Die Markierung ist ein Objekt mit einem einzigen Schlüssel, das den Grund trägt, aus dem der Wert fehlt:

{ "aggrega_withheld": "declared" }

declared bedeutet, dass eine Deklaration das Blatt abdeckt. Eine Payload, die überhaupt nicht gelesen werden konnte, wird als Ganzes zurückgehalten, mit dem Grund unreadable, weil kein Blatt darin beurteilt werden konnte.

Das Zurückhalten folgt den eigenen Markierungen des Graphen, sodass es genau die Blätter erreicht, die sie benennen, wo auch immer sie liegen:

  • die values und das infra jeder Anbindung, gleich welcher Geltungsbereich die Anbindung geschrieben hat — der eigene Block der Komponente, ein Subsystem, eine Boundary oder das Release, eine annotationsgesteuerte Erweiterung — und gleich, ob sie am eigenen Block des Knotens oder an einer seiner Verbindungen geschrieben wurde, anhand der Blätter, die ihr sensitive_payload_leaves benennt;
  • das infra einer Anbindung auf Boundary-Ebene, unter boundary_features, anhand ihrer eigenen Markierung;
  • die eigenen values und das eigene infra eines Knotens, unter values_mapping und infra_mapping, anhand des eigenen sensitive_payload_leaves des Knotens;
  • die eigenen values und das eigene infra einer Verbindung, an der Kante und im Eintrag uses des konsumierenden Knotens, anhand des sensitive_payload_leaves der Kante, das die Blätter benennt, die der Socket der konsumierenden Komponente als sensibel deklariert.

Worauf sich eine Richtlinie stützt, bleibt intakt. Der Typ, die aufgelöste Version, die Labels, die Katalog-Annotationen, binding, connection, realization, origin und seine Herkunfts-Maps, alle drei Fakten zur Sensibilität und jedes Blatt, das keine Deklaration markiert, kommen wie geschrieben an. Auch der Schlüssel eines zurückgehaltenen Blatts bleibt erhalten, sodass eine Richtlinie weiterhin sieht, welche Blätter eine Payload trägt und welche davon deklariertes Material tragen — nur der Wert fehlt. Eine Regel darüber, wohin als sensibel deklariertes Material wandert und auf welchem Weg, ist daher vollständig ausdrückbar; eine Regel über den Inhalt des Materials ist es nicht, und zwar bewusst.

Der vom Autor geschriebene Block uses eines Knotens, der am Knoten neben seinen Kanten getragen wird, behält von jeder an einer Verbindung geschriebenen Anbindung nur deren type und description. Die Werte der Anbindung werden einmal getragen, an der Anbindung selbst, wo das Zurückhalten sie erreicht.

Eine Richtlinie, die ein zurückgehaltenes Blatt von einem vom Autor geschriebenen unterscheiden will, prüft auf den Schlüssel der Markierung:

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])
}

Es ist dasselbe Zurückhalten, das --ir-graph anwendet, wenn ein Befehl den Graphen ausgibt, und das aggrega/irGraph des Daemons anwendet, wenn er einem Client antwortet, sodass eine Richtlinie und eine Person, die den Graphen liest, dieselben Blätter zurückgehalten sehen. Diese Oberflächen geben die Werte an eine Person zurück, die mit --unredacted danach fragt; die Payload, die eine Richtlinie erhält, kennt keine solche Anfrage, und die eigenen deklarierten Werte eines Knotens werden darin zu denselben Bedingungen zurückgehalten wie die einer Anbindung. Es gilt für die Payload, die eine Richtlinie erhält, und für nichts anderes: Der Graph, aus dem der Build rendert, bleibt unberührt, sodass das Zurückhalten kein gerendertes Byte ändert. Aus dem, was eine Richtlinie render-verdict erhält, wird nichts zurückgehalten, weil die gerenderten Artefakte das sind, was diese Rolle beurteilt.

Woher jedes Blatt stammt: values_provenance und infra_provenance

Jede ist nach dem gepunkteten Blattpfad innerhalb ihrer Säule geschlüsselt, und jeder Eintrag hält den origin dieses Blatts fest — dieselbe Unterscheidung explicit / annotation, Blatt für Blatt angewandt. Ein durch eine Annotation beigesteuertes Blatt trägt zusätzlich die Authoring-Oberfläche, an der es deklariert wurde, den Annotationsschlüssel, der es beigesteuert hat, und die Quellposition dieser Deklaration. Wo ein explizites Blatt ein durch eine Annotation beigesteuertes überschrieben hat, trägt der Eintrag auch den unterdrückten Beitrag, den es ersetzt hat, sodass eine Richtlinie sehen kann, was überschrieben wurde, und nicht nur, was sich durchgesetzt hat.

Die drei Sensibilitätseinheiten

Die Payload trägt drei Fakten zur Sensibilität, und sie liegen auf drei verschiedenen Einheiten: eine ganze Anbindung, ein Auslieferungsschlüssel, ein Blatt der Payload.

Jeder wird aus seinen eigenen Eingaben berechnet. Keiner wird aus einem anderen abgeleitet, und insbesondere wird die Antwort pro Anbindung nie auf die engeren Einheiten heruntergebrochen. Wer zwei davon vermengt, erhält eine Richtlinie, die in einer Richtung falsch ist, die still scheitert; daher lohnt es sich, die drei getrennt zu lesen, bevor man eine Regel gegen einen davon schreibt.

Jeder davon wird aus dem abgeleitet, was ein Autor deklariert hat — sensitive: true an einem Blatt des Feature-Schemas oder sensitive: true an einem Anbindungs-Slot, den eine Component deklariert, für ihre eigenen Anbindungen oder an einem ihrer Sockets. Der Inhalt keines Werts wird untersucht, und aus dem Namen eines Felds wird keine Bedeutung herausgelesen.

sensitive — eine Antwort für die gesamte Anbindung

Wahr, wenn entweder das angebundene Feature in seinen values, infra oder provides ein sensibles Blatt deklariert oder der Slot, den die Anbindung füllt, deklariert, dass alles, was ihn bindet, geheimes Material verarbeitet — der gleichnamige Anbindungs-Slot der Host-Component oder, für eine Anbindung, die connection trägt, der Slot dieses Namens, den der Socket der Verbindung deklariert. Nicht gesetzt, wenn keine der beiden Deklarationen vorhanden ist.

Dies beantwortet, was die Entität ist, und variiert daher bewusst nicht mit dem, was ein bestimmter Autor geschrieben hat. Es liest die Deklarationen des Feature statt der Teilmenge sensibler Blätter, die diese Anbindung zufällig gefüllt hat, weil ein Feld, das in einem Release sensibel war und in einem anderen nicht, für eine Richtlinie, die über die Katalogentität urteilt, unbrauchbar wäre.

Die beiden Hälften sind unabhängig, und jede gilt für sich. Ein Feature, das überhaupt kein sensibles Blatt deklariert, bindet einen sensiblen Slot dennoch als sensible Anbindung, weil der Slot es so festgelegt hat. Eine Füllung, die ein sensibles Blatt deklariert, ist eine sensible Anbindung, auch wenn der Slot keine solche Deklaration getroffen hat, und auch wenn sie eine freie Anbindung ist, die keinen Slot bindet.

sensitive_inject — eine Antwort pro Auslieferungsschlüssel

Die Teilmenge von inject, deren referenzierten Schlüssel provides das angebundene Feature als sensibel deklariert, getragen in der eigenen Form von inject: Mechanismus, dann Auslieferungsschlüssel, mit dem referenzierten Schlüssel provides als Wert.

Ein Auslieferungsschlüssel, der aus einem Schlüssel provides befüllt wird, den das Feature als sensibel markiert hat, erscheint hier; einer, der aus einem nicht markierten Schlüssel befüllt wird, nicht, selbst an derselben Anbindung und mit demselben Mechanismus. Fehlt, wenn die Anbindung keinen Auslieferungsmechanismus deklariert oder keinen sensiblen Schlüssel provides referenziert.

sensitive_payload_leaves — eine Antwort pro Blatt der Payload

Die Blätter, die die Payload dieser Anbindung trägt, deren Pfad das angebundene Feature als sensibel deklariert, jeweils als der mit der Säule präfixierte gepunktete Pfad, den das Datum belegt: values.<path> oder infra.<path>.

Die hier gelesene Payload ist diejenige, die die Anbindung am Ende trägt, nicht der Block, den ein Autor geschrieben hat. Ein Blatt, das auf einem Wert steht, den das Feature-Schema als default deklariert, wird ebenso benannt wie eines, auf das ein Autor diesen Wert geschrieben hat: Ein befüllter Standardwert ist ein Datum, das die Payload trägt, und eine allein aus dem geschriebenen Block gelesene Markierung ließe es unbenannt.

Ein Blatt erscheint dort, wo ein Pfad, den das Feature-Schema als sensibel deklariert, es abdeckt — die Deklaration benennt dieses Blatt oder ein Objekt, das es enthält. Der Abgleich erfolgt segmentweise über den gepunkteten Pfad, sodass eine Deklaration an db das Blatt db.password abdeckt und ein Geschwisterblatt namens dbPassword nicht erreicht. Aus dem Text des Pfads selbst wird nichts herausgelesen, und kein Wert wird untersucht — ob der Autor an einem markierten Blatt das Material selbst oder einen Verweis darauf geschrieben hat, ist hier nicht feststellbar und ist nicht das, was die Markierung behauptet.

Der Vergleich läuft über die auf ihre Blätter abgeflachte Payload, nicht über die Schlüssel der obersten Ebene der Säule, sodass ein in einer verschachtelten Map verschachteltes Blatt wie jedes andere verglichen wird.

Die Blätter kommen in der Reihenfolge an, in der die Payload sie enthält, die der Säule values vor denen der Säule infra — dieselbe Reihenfolge, die die Payloads selbst tragen, und genau das hält die übertragenen Daten über Läufe mit identischer Eingabe hinweg byte-identisch.

Diese Einheit beantwortet, wohin diese Anbindung Daten gelegt hat, was notwendigerweise je nach Release variiert. Deshalb überschneidet sie sich mit dem Geschriebenen, während sensitive das nicht tut: Die beiden sind Antworten auf verschiedene Fragen, und die Regel des einen auf das Feld des anderen anzuwenden, würde es unbrauchbar machen.

Die drei zusammen lesen

Ein Autor bindet ein Zugangsdaten-Feature an, das sein values-Blatt literalPassword und seinen provides-Schlüssel password als sensibel deklariert, füllt einen deklarierten Slot credentials und schreibt ein literales Passwort inline:

{
"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"]
}

Drei verschiedene Fragen, drei verschiedene Antworten. Die Anbindung verarbeitet überhaupt als sensibel deklariertes Material (sensitive). Der Umgebungsschlüssel DATABASE_PASSWORD ist einer, der es trägt (sensitive_inject). Und die Payload dieser Anbindung trägt speziell einen Wert unter values.literalPassword (sensitive_payload_leaves) — während values.secretName, ein Lokator, den das Feature bewusst unmarkiert lässt, in dieser Liste fehlt, obwohl die Payload auch ihn trägt. Das Passwort, das der Autor geschrieben hat, kommt zurückgehalten an, während der Lokator daneben wie geschrieben ankommt: Die Markierung sagt einer Richtlinie, dass dort ein Wert ist, und der Wert selbst erreicht sie nie.

Eine Regel, die ein literales Geheimnis in einem gerenderten Artefakt verbietet, braucht den dritten. Eine Regel, die verlangt, dass jede Anbindung, die Zugangsdaten verarbeitet, ein Eigentümer-Label trägt, braucht den ersten. Den einen durch den anderen zu ersetzen, ändert, welche Builds anhalten.

Abwesenheit ist keine Erlaubnis

Ein Blatt wird nur dort aufgeführt, wo eine Deklaration es abdeckt. Ein fehlendes sensitive_payload_leaves besagt also, dass diese Anbindung kein Blatt benennt, das ihr Feature als sensibel deklariert — niemals, dass die Payload nicht sensibel ist. Es unterscheidet auch nicht eine Anbindung, die kein solches Blatt zu benennen hat, von einem Erzeuger, der diese Achse gar nicht meldet: Diese beiden bleiben ununterscheidbar, und wer einen fehlenden Schlüssel liest, erfährt genau das und nicht mehr.

Ein Guest, der eine fehlende Blattliste als Erlaubnis liest, einen Wert im Klartext anzuzeigen oder auszugeben, hat die Markierung verkehrt herum gelesen.

Der Schlüssel wird vollständig aus den übertragenen Daten weggelassen, wenn er leer wäre, sodass eine Anbindung, deren Feature und Slot nichts deklarieren, genau die Bytes trägt, die sie tragen würde, wenn es die Markierung nicht gäbe. Diese Auslassung macht das Fehllesen leicht, und deshalb lohnt es sich, die Richtung klar auszusprechen.

Der klarste Fall ist eine Anbindung, die sensibel ist und überhaupt kein Blatt aufführt. Nehmen Sie die Anbindung oben und ändern Sie zwei Dinge — der Autor schreibt nur den Lokator und lässt das als sensibel deklarierte Blatt unbefüllt, und er befüllt den Umgebungsschlüssel aus dem nicht markierten provides-Schlüssel name des Feature statt aus password:

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

sensitive ist weiterhin wahr — die Deklarationen des Feature haben sich nicht geändert —, während beide engeren Einheiten verschwunden sind. Die Anbindung verarbeitet weiterhin geheimes Material; sie tut es nur nicht über ein Blatt oder einen Auslieferungsschlüssel, den diese Anbindung trägt. Eine Richtlinie, die am zusammengefassten Wert ansetzt, weist diesen Build zurück, und eine Richtlinie, die an der Markierung pro Blatt ansetzt, lässt ihn durch. Beide sind vertretbare Regeln, und welche eine Richtlinie will, ist eine Entscheidung, die der Autor der Richtlinie bewusst trifft.

Dieselbe Asymmetrie gilt in der anderen Richtung für sensitive_inject: Eine Anbindung kann ein sensibles Blatt schreiben und dabei nichts Sensibles über einen Auslieferungsschlüssel leiten, oder einen sensiblen Schlüssel provides leiten und dabei überhaupt keinen Wert schreiben.

Was eine Sensibilitätsdeklaration nicht bewirkt

Die Markierung annotiert; sie ist keine Kontrolle. Ein Blatt oder einen Slot als sensibel zu deklarieren, verschlüsselt nichts, validiert oder verwirft keinen Wert und erzwingt keinen Auslieferungsmechanismus. Kein Build-Ergebnis ändert sich, weil eine Deklaration vorhanden ist.

Auf den meisten Targets ändert sie auch kein gerendertes Byte: Ein als sensibel deklarierter Wert, den ein Autor inline angegeben hat, wird genau so gerendert wie ein nicht deklarierter. Terraform ist unter den Targets der Standardbibliothek die Ausnahme, weil es ein natives Sensibilitätsprimitiv pro Wert besitzt, auf dem die Deklaration landen kann — siehe providers/terraform.md „Als sensibel deklarierte Moduleingaben“. Ein Target ohne eigenen Sensibilitätsbegriff bietet einer Deklaration nichts, was sie ändern könnte.

Was die Deklarationen überall bewirken, ist, den Sachverhalt lesbar zu machen — für die eigene Debug-Ausgabe des Compilers und für eine Richtlinie an diesem Socket, die entscheidet, was damit zu tun ist. Eine Markierung in ein Build-Ergebnis zu verwandeln, ist die Aufgabe der Richtlinie, und genau dafür existiert dieser Socket. Und einer Richtlinie wird von als sensibel deklariertem Material berichtet, ohne dass es ihr übergeben wird: Die Markierung kommt an, der Wert kommt zurückgehalten an.

Querverweise

  • policy-socket.md — der Governance-Socket: die vier Rollen, die Schweregrade der Verdikte, der Eingabekanal des Betreibers, die Richtlinien-Engines, die im Compiler mitgeliefert werden, und das Anbinden eines Plugins an einen Workspace.
  • plugin-contract.md — die Platzierung des Sockets in der Pipeline und seine typisierten Übertragungsformen.
  • Graph-Schema-Referenz — der Vertrag Feld für Feld für den Build-Graphen, einschließlich jedes Felds einer Anbindung.
  • entities/component.md „Anbindungs-Slots“ — einen Slot deklarieren und einen Slot als sensibel deklarieren; sowie das featuresSchema, das ein Socket für die über ihn geführten Verbindungen deklariert.
  • entities/aggregate.md „Die eigenen Anbindungen einer Verbindung“ — eine Anbindung an einer Verbindung schreiben, und der Name, den sie erhält.
  • vocabulary/compact-form-authoring.md „Ein Blatt als sensibel deklarieren“ — das Schlüsselwort sensitive: und die Obergrenze dessen, was seine Deklaration bewirkt.
  • vocabulary/labels-and-annotations.md — die Label- und Annotationsoberflächen, die eine Richtlinie liest.