Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

I fatti di associazione che una policy di governance legge

Un plugin di governance associato al ruolo ir-verdict riceve l’intero grafo della build, e ogni associazione di Feature nella build arriva con esso. Ciascuna associazione porta un insieme fisso di fatti su sé stessa: quale Feature nomina, quale slot riempie, su quale connessione è stata scritta, quando è stata scritta su una connessione, quale FeatureRecipe la realizza, che cosa l’autore del catalogo ha dichiarato su di essa, che cosa un autore vi ha scritto, e se gestisce materiale che qualcuno ha dichiarato sensibile. Una cosa non arriva com’è scritta: un valore che un autore ha dichiarato sensibile arriva trattenuto — vedi I valori dichiarati sensibili arrivano trattenuti.

Questa pagina enumera quei fatti e dice che cosa ciascuno afferma e che cosa non afferma. Per il socket stesso — i quattro ruoli, le severità dei verdetti, il canale di input dell’operatore e i due motori di policy distribuiti all’interno del compilatore — vedi policy-socket.md. Per la tabella campo per campo con tipi e obbligatorietà, vedi il riferimento dello schema del grafo generato; questa pagina insegna come leggere i fatti, e quella pagina è il contratto.

Dove si trovano le associazioni nel payload

Le associazioni sono appese al grafo della build sotto feature_values_mapping, con come chiave l’id del nodo e poi il nome di istanza che l’autore ha dato a ciascuna associazione:

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

Il nome dell’associazione ha una funzione, non è decorativo. È la chiave con cui un autore riempie uno slot, quindi è anche ciò che il compilatore abbina agli slot dichiarati del Component ospitante.

Un’associazione scritta su una delle connessioni di un componente — sotto features: su una voce uses, nell’Aggregate o nella Release — è una delle associazioni del componente consumatore, quindi si trova nello stesso contenitore, sul nodo del componente consumatore. La sua chiave è il nome che le dà il compilatore, l’alias della connessione e lo slot uniti da un punto: gpt.credential per lo slot credential della connessione scritta sotto l’alias gpt. Il punto non compare mai in un nome che un autore scrive, quindi quella chiave non è mai uguale al nome di una delle associazioni proprie del nodo. Una policy però non legge la connessione dalla chiave: la voce la porta come dato, in connection più sotto.

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

Solo ir-verdict vede questi fatti. Una policy render-verdict riceve gli artefatti renderizzati e nessun grafo; una policy label-transform riceve una proiezione delle etichette e dei valori dei nodi, con i suoi valori dichiarati sensibili trattenuti come qui, che non porta affatto associazioni; una policy annotation-transform riceve i componenti che può annotare. Una regola che legge fatti di associazione va in ir-verdict, e spostarla in un altro ruolo produce una regola che non scatta mai anziché un errore, perché un percorso che non c’è è semplicemente non definito.

Un solo contenitore, ogni famiglia di associazioni

Ogni associazione su un nodo si trova nello stesso contenitore, qualunque cosa produca la sua Feature — una Feature operativa, una Feature di credenziali, una Feature di identità. Nessuna famiglia riceve una proiezione più ristretta di un’altra, quindi una policy che percorre il contenitore le vede tutte e non deve mai sapere quale famiglia sta guardando prima di poter leggere un fatto.

Identità: type e resolved_version

type è l’URI della Feature del catalogo che l’associazione nomina. resolved_version è la versione esatta su cui la risoluzione si è fermata per questa build. Entrambi sono sempre presenti.

Metadati del catalogo, portati testualmente: labels e catalog_annotations

labels sono i metadata.labels propri dell’entità Feature associata. catalog_annotations sono i metadata.annotations propri di quell’entità. Entrambi vengono portati nell’ordine in cui l’entità del catalogo li dichiara, e nessuno dei due viene filtrato, normalizzato o privato del prefisso — una chiave nel namespace proprio dell’autore del catalogo arriva esattamente com’è scritta, e il compilatore non ne legge nessuna.

È questo trasporto testuale a permettere che una policy abbia come chiave un’etichetta della cui esistenza il compilatore non ha motivo di sapere. Un autore del catalogo che contrassegna le Features di credenziali con un’etichetta di sua invenzione può scrivere una regola direttamente su quell’etichetta.

Ciascuno è assente dall’associazione quando la Feature non ne dichiara alcuno, e quando il suo type non si risolve in alcuna entità del catalogo.

catalog_annotations descrive l’entità che l’associazione nomina. È una questione diversa da annotation_key e annotation_source più sotto, che descrivono come è nata l’associazione. Un’associazione scritta in un blocco features: porta annotazioni del catalogo senza portare nessuno degli altri due.

Quale slot riempie l’associazione: binding

binding ha tre risposte, e la terza non è una variante della seconda:

ValoreSignificato
un nome di slotL’associazione riempie lo slot di associazione dichiarato con quel nome.
freeL’associazione non riempie alcuno slot dichiarato. Si tratta di un riscontro positivo: l’insieme degli slot è stato risolto e nessuno slot dichiarato porta questo nome.
assenteNon è stato possibile risolvere l’insieme degli slot dichiarati del Component ospitante, quindi quale slot venga riempito è sconosciuto.

Da quale insieme di slot dichiarati provenga il nome dipende da dove è stata scritta l’associazione. Un’associazione del blocco proprio del nodo riempie uno slot che il Component ospitante dichiara nel proprio featuresSchema. Un’associazione scritta su una connessione — una che porta connection più sotto — riempie uno slot che il socket della connessione dichiara, nel featuresSchema di quel socket sul Component ospitante. Così lo stesso valore, credential, nomina uno slot del Component su un’associazione e uno slot di un socket su un’altra, ed è connection a distinguere le due.

L’abbinamento avviene per nome — un’associazione riempie uno slot quando la Feature è associata sotto il nome dello slot, sul blocco del componente o sulla connessione — quindi il valore è una chiave esatta dell’insieme di slot dichiarati. Nulla viene letto dalla chiave dell’associazione: l’associazione di una connessione ha come chiave gpt.credential e riporta credential. Viene portato il nome dello slot anziché un semplice flag perché quale slot è stato riempito è la metà più utile della risposta.

Un’associazione scritta su una connessione non riporta mai free. Gli slot di un socket sono gli unici nomi che una connessione attraverso di esso può portare, e una connessione che porta qualsiasi altro nome viene rifiutata quando la build viene caricata, quindi ogni associazione di questo tipo in un grafo che raggiunge una policy riempie uno slot dichiarato.

Una policy che tratta un binding assente come free riporterà un’incognita come riscontro. Verifica free esplicitamente.

Su quale connessione è stata scritta l’associazione: connection

connection è presente su ogni associazione scritta su una delle connessioni del nodo, e assente su ogni associazione del blocco proprio del nodo. Porta due campi, le coordinate di quella connessione sul nodo:

CampoSignificato
socketIl socket attraverso cui la connessione è collegata.
aliasL’alias sotto cui la connessione è scritta.

La coppia nomina uno degli archi del grafo: l’arco il cui source è il nodo che porta l’associazione e i cui socket e alias sono questi. Il target di quell’arco è il componente a cui l’associazione viene presentata. Così una policy unisce un’associazione a ciò che raggiunge — cosa che nessun fatto sulla sola associazione può dire, perché l’associazione si trova sul nodo consumatore:

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

Che cosa afferma connection, e che cosa non afferma:

  • Registra dove l’autore ha scritto l’associazione. Viene compilato a partire dalla connessione su cui l’associazione è stata scritta, mai estratto dalla chiave dell’associazione, quindi contiene il socket — che la chiave non porta — oltre all’alias.
  • Non porta lo slot. Quale slot del socket l’associazione riempie è binding, letto allo stesso modo che per qualsiasi associazione; lo slot viene riportato una sola volta, lì.
  • Non descrive il target. Il target, le sue etichette e chi ha collegato l’arco — lo sviluppatore, la Release o una Feature — sono fatti dell’arco e del nodo target, letti lì dopo l’unione.
  • Una connessione che una Feature crea non porta associazioni, quindi nessuna associazione porta una connection che nomini un arco di questo tipo. Una credenziale di cui ha bisogno la connessione propria di una Feature è un’associazione che riempie uno slot che la Feature dichiara, e non porta alcuna connection.
  • Assente significa il blocco proprio del nodo. Un’associazione senza connection è stata scritta nei features: propri del componente (o lo ha raggiunto da un ambito più ampio o tramite l’espansione guidata dalle annotazioni). Non è un riscontro che l’associazione non venga presentata ad alcun altro componente: ciò che una credenziale propria di un componente raggiunge è deciso da come è collegata la sua consegna, che questo campo non descrive.

Oltre a decidere da quale insieme di slot dichiarati vengono letti binding e la metà relativa allo slot di sensitive, connection non cambia nulla dell’associazione: la sua FeatureRecipe, il suo contratto provides, il resto dei suoi fatti e il suo posto nel contenitore sono quelli di qualsiasi associazione che il nodo porta.

Quale FeatureRecipe realizza l’associazione: realization

realization nomina la FeatureRecipe che il Manifest della Release lega all’associazione, come <name>:<version>. Il Manifest lega in base al nome proprio dell’associazione dove il suo livello name mappa quel nome — per un’associazione scritta su una connessione, il suo nome qualificato, gpt.credential sopra — e altrimenti in base al tipo di Feature che l’associazione nomina. La FeatureRecipe nominata è quella con cui una build degli stessi documenti renderizza l’associazione: il grafo registra il legame prima che venga renderizzato qualsiasi cosa, e il rendering lega l’associazione allo stesso modo.

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

Che cosa afferma realization, e che cosa non afferma:

  • È la stessa coppia ovunque compaia. aggrega inspect la stampa come la realizzazione dell’associazione, e dove un target appone la provenienza su ciò che renderizza, i documenti che quella FeatureRecipe renderizza la portano come valore di aggrega.ai/recipe-uri, così una policy unisce un’associazione a ciò che renderizza senza tradurre tra forme diverse.
  • Nomina la FeatureRecipe per nome e versione, non per capacità. Due capacità possono ciascuna pubblicare una FeatureRecipe con uno stesso nome e una stessa versione. Quale delle due sia legata è stabilito dalla mappatura del Manifest, che nomina la capacità ovunque il solo nome sarebbe ambiguo; questo campo non lo ripete.
  • Anche le associazioni proprie di un confine di una Release la portano, sotto boundary_features, lette allo stesso modo. Un’associazione a livello di confine raggiunge anche ciascun componente che il confine contiene, e lì porta la stessa realizzazione.
  • Assente significa legata a nulla. Un’associazione che il Manifest non lega ad alcuna FeatureRecipe contenuta nel catalogo non porta alcuna realization. Una build di una tale composizione si arresta prima di renderizzare, nominando l’associazione non mappata — ma a una policy in questo ruolo viene chiesto prima di quell’arresto, quindi può incontrare un’associazione che non ne porta alcuna. La regola sopra lascia passare una tale associazione, perché il suo corpo lega per prima realization; una regola che vuole riportarla verifica esplicitamente la chiave mancante.

Come è nata l’associazione: origin e i suoi due compagni

origin distingue un’associazione digitata da uno sviluppatore da una prodotta dall’espansione guidata dalle annotazioni:

ValoreSignificato
explicitScritta in un blocco features:.
annotationProdotta dall’espansione guidata dalle annotazioni.
mixedLe foglie dei valori o dell’infra dell’associazione portano un misto di entrambe; il dettaglio per foglia si trova nelle mappe di provenienza.

annotation_key nomina l’annotazione che ha attivato un’associazione sintetica, e annotation_source individua la sua dichiarazione come <release-file-path>:<dotted-yaml-key-path>. Entrambi sono assenti quando origin è explicit.

I payload scritti dall’autore: values, infra e inject

values è la configurazione operativa dell’associazione — il dominio dello sviluppatore. infra è il suo dimensionamento fisico per istanza — quello dell’operatore. inject è l’instradamento agnostico dell’iniezione, che mappa le chiavi di consegna sulle chiavi provides da cui si riempiono, con come prima chiave il meccanismo di consegna.

Che cosa porti il values di un’associazione di credenziali è una scelta dell’autore, e il compilatore porta qualunque cosa sia stata scritta senza risolvere né l’una né l’altra: una credenziale per riferimento porta un puntatore in un archivio di segreti, e una per valore porta il materiale stesso. In entrambi i casi, una foglia che la Feature associata dichiara sensibile raggiunge una policy trattenuta, come descrive la sezione successiva; una foglia che lascia non dichiarata, come un localizzatore pubblicato, arriva com’è scritta.

I valori dichiarati sensibili arrivano trattenuti

Ogni foglia che il grafo marca come dichiarata sensibile arriva a questo socket come un marcatore di trattenimento anziché come il valore scritto da un autore. Il marcatore è un oggetto a chiave singola che porta il motivo per cui il valore è assente:

{ "aggrega_withheld": "declared" }

declared significa che una dichiarazione copre la foglia. Un payload che non è stato possibile leggere affatto viene trattenuto per intero, con il motivo unreadable, perché nessuna foglia al suo interno ha potuto essere giudicata.

Il trattenimento segue le marcature del grafo stesso, quindi raggiunge esattamente le foglie che esse nominano, ovunque si trovino:

  • i values e l’infra di ogni associazione, qualunque ambito abbia scritto l’associazione — il blocco proprio del componente, un sottosistema, un confine o la Release, un’espansione guidata dalle annotazioni — e che sia stata scritta sul blocco proprio del nodo o su una delle sue connessioni, in base alle foglie nominate dal suo sensitive_payload_leaves;
  • l’infra di un’associazione a livello di confine, sotto boundary_features, in base alla sua marcatura;
  • i values e l’infra propri di un nodo, sotto values_mapping e infra_mapping, in base al sensitive_payload_leaves proprio del nodo;
  • i values e l’infra propri di una connessione, sull’arco e nella voce uses del nodo consumatore, in base al sensitive_payload_leaves dell’arco, che nomina le foglie che il socket del componente consumatore dichiara sensibili.

Ciò su cui una policy ragiona resta intatto. Il tipo, la versione risolta, le etichette, le annotazioni di catalogo, binding, connection, realization, origin e le sue mappe di provenienza, tutti e tre i fatti di sensibilità e ogni foglia che nessuna dichiarazione marca arrivano come sono stati scritti. Sopravvive anche la chiave di una foglia trattenuta, così una policy vede ancora quali foglie porta un payload e quali di esse portano materiale dichiarato — manca solo il valore. Una regola su dove viaggia il materiale dichiarato sensibile, e per quale percorso, è quindi pienamente esprimibile; una regola sul contenuto del materiale non lo è, per progettazione.

Il blocco uses scritto dall’autore di un nodo, portato sul nodo accanto ai suoi archi, riduce ogni associazione scritta su una connessione al suo type e alla sua description. I valori dell’associazione sono portati una sola volta, sull’associazione stessa, dove il trattenimento li raggiunge.

Una policy che vuole distinguere una foglia trattenuta da una scritta dall’autore verifica la presenza della chiave del marcatore:

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

È lo stesso trattenimento che --ir-graph applica quando un comando stampa il grafo e che aggrega/irGraph del daemon applica quando risponde a un client, così una policy e una persona che legge il grafo vedono trattenute le stesse foglie. Quelle superfici restituiscono i valori a una persona che li chiede con --unredacted; il payload che una policy riceve non offre una richiesta del genere, e da esso i valori dichiarati propri di un nodo vengono trattenuti alle stesse condizioni di quelli di un’associazione. Si applica al payload che una policy riceve e a nient’altro: il grafo da cui la build esegue il rendering resta intatto, quindi il trattenimento non cambia alcun byte renderizzato. Nulla viene trattenuto da ciò che riceve una policy render-verdict, perché gli artefatti renderizzati sono ciò che quel ruolo giudica.

Da dove proviene ciascuna foglia: values_provenance e infra_provenance

Ciascuna è indicizzata dal percorso puntato della foglia all’interno del suo pilastro, e ogni voce registra l’origin di quella foglia — la stessa distinzione explicit / annotation, applicata una foglia alla volta. Una foglia apportata da un’annotazione porta inoltre la superficie di authoring su cui è stata dichiarata, la chiave di annotazione che l’ha apportata e la posizione nel sorgente di quella dichiarazione. Dove una foglia esplicita ha sovrascritto una foglia apportata da un’annotazione, la voce porta anche il contributo soppresso che ha sostituito, così una policy può vedere che cosa è stato sovrascritto e non solo che cosa ha prevalso.

Le tre unità di sensibilità

Il payload porta tre fatti di sensibilità, che si collocano a tre unità diverse: un’intera associazione, una chiave di consegna, una foglia del payload.

Ciascuno è calcolato dai propri input. Nessuno è derivato da un altro, e in particolare la risposta per associazione non viene mai propagata verso le unità più ristrette. Confondere due qualsiasi di essi produce una policy sbagliata in una direzione che fallisce silenziosamente, quindi conviene leggere i tre separatamente prima di scrivere una regola su uno qualsiasi di essi.

Ognuno di essi è derivato da ciò che un autore ha dichiarato — sensitive: true su una foglia dello schema di una Feature, oppure sensitive: true su uno slot di associazione che un Component dichiara, per le proprie associazioni o su uno dei suoi socket. Il contenuto di nessun valore viene ispezionato, e nessun significato viene ricavato dal nome di un campo.

sensitive — una risposta per l’intera associazione

Vero quando la Feature associata dichiara una foglia sensibile nei suoi values, infra o provides, oppure quando lo slot che l’associazione riempie dichiara che qualunque cosa lo leghi gestisce materiale segreto — lo slot di associazione omonimo del Component ospitante oppure, per un’associazione che porta connection, lo slot con quel nome dichiarato dal socket della connessione. Non impostato quando nessuna delle due dichiarazioni è presente.

Questo risponde a che cos’è l’entità, quindi deliberatamente non varia con ciò che un particolare autore ha scritto. Legge le dichiarazioni della Feature anziché il sottoinsieme di foglie sensibili che questa associazione si è trovata a riempire, perché un campo sensibile in una Release e non in un’altra sarebbe inutilizzabile per una policy che ragiona sull’entità di catalogo.

Le due metà sono indipendenti, e ciascuna vale da sola. Una Feature che non dichiara alcuna foglia sensibile lega comunque uno slot sensibile come associazione sensibile, perché lo slot lo ha detto. Un riempimento che dichiara una foglia sensibile è un’associazione sensibile anche quando lo slot non ha fatto alcuna dichiarazione del genere, e anche quando è un’associazione libera che non lega alcuno slot.

sensitive_inject — una risposta per chiave di consegna

Il sottoinsieme di inject la cui chiave provides referenziata è dichiarata sensibile dalla Feature associata, portato nella forma propria di inject: meccanismo, poi chiave di consegna, con la chiave provides referenziata come valore.

Una chiave di consegna che si riempie da una chiave provides che la Feature ha marcato come sensibile compare qui; una che si riempie da una chiave non marcata no, anche sulla stessa associazione e con lo stesso meccanismo. Assente quando l’associazione non dichiara alcun meccanismo di consegna, o non referenzia alcuna chiave provides sensibile.

sensitive_payload_leaves — una risposta per foglia del payload

Le foglie che il payload di questa associazione porta il cui percorso è dichiarato sensibile dalla Feature associata, ciascuna come il percorso puntato, prefissato dal pilastro, che il dato occupa: values.<path> o infra.<path>.

Il payload letto qui è quello che l’associazione finisce per portare, non il blocco scritto da un autore. Una foglia che si trova a un valore che lo schema della Feature dichiara come default viene nominata allo stesso modo di una in cui un autore ha scritto quel valore: un default riempito è un dato che il payload porta, e una marcatura ricavata dal solo blocco scritto lo lascerebbe senza nome.

Una foglia compare dove un percorso che lo schema della Feature dichiara sensibile la copre — la dichiarazione nomina quella foglia, oppure nomina un oggetto che la contiene. Il confronto avviene segmento per segmento sul percorso puntato, quindi una dichiarazione su db copre db.password e non raggiunge una foglia sorella chiamata dbPassword. Nulla viene ricavato dal testo del percorso stesso e nessun valore viene ispezionato — se l’autore abbia scritto il materiale stesso in una foglia marcata, o un puntatore a esso, non è conoscibile qui e non è ciò che la marcatura afferma.

Il confronto avviene sul payload appiattito nelle sue foglie, non sulle chiavi di primo livello del pilastro, quindi una foglia annidata dentro una mappa annidata viene confrontata come qualsiasi altra.

Le foglie arrivano nell’ordine in cui il payload le contiene, quelle del pilastro values prima di quelle del pilastro infra — lo stesso ordine che portano i payload stessi, ed è ciò che mantiene i dati trasmessi identici byte per byte tra esecuzioni con input identico.

Questa unità risponde a dove questa associazione ha messo dei dati, il che varia necessariamente a seconda della Release. È per questo che si interseca con ciò che è stato scritto, mentre sensitive no: i due sono risposte a domande diverse, e applicare la regola dell’uno al campo dell’altro lo romperebbe.

Leggere i tre insieme

Un autore che associa una Feature di credenziali che dichiara sensibili la sua foglia values literalPassword e la sua chiave provides password, riempiendo uno slot credentials dichiarato, e che scrive in linea una password letterale:

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

Tre domande diverse, tre risposte diverse. L’associazione gestisce in qualche modo materiale dichiarato sensibile (sensitive). La chiave d’ambiente DATABASE_PASSWORD è una di quelle che lo portano (sensitive_inject). E il payload di questa associazione porta un valore proprio in values.literalPassword (sensitive_payload_leaves) — mentre values.secretName, un localizzatore che la Feature lascia deliberatamente non marcato, è assente da quell’elenco anche se il payload porta anche quello. La password scritta dall’autore arriva trattenuta, mentre il localizzatore accanto a essa arriva come è stato scritto: la marcatura dice a una policy che lì c’è un valore, e il valore stesso non la raggiunge mai.

Una regola che nega un segreto letterale in un artefatto renderizzato vuole il terzo. Una regola che richiede che ogni associazione che gestisce credenziali porti un’etichetta di proprietà vuole il primo. Sostituire l’uno con l’altro cambia quali build si arrestano.

L’assenza non è un permesso

Una foglia è elencata solo dove una dichiarazione la copre. Quindi un sensitive_payload_leaves assente afferma che questa associazione non nomina alcuna foglia che la sua Feature dichiara sensibile — mai che il payload non è sensibile. Inoltre non distingue un’associazione che non ha alcuna foglia del genere da nominare da un produttore che non riporta affatto questo asse: i due restano indistinguibili, e chi legge una chiave assente apprende questo e nient’altro.

Un guest che legge un elenco di foglie assente come il permesso di mostrare o emettere un valore in chiaro ha letto la marcatura al contrario.

La chiave viene omessa del tutto dai dati trasmessi quando sarebbe vuota, quindi un’associazione la cui Feature e il cui slot non dichiarano nulla porta esattamente i byte che porterebbe se la marcatura non esistesse. È quell’omissione che rende facile la lettura errata, ed è per questo che vale la pena dichiarare chiaramente la direzione.

Il caso più chiaro è un’associazione che è sensibile e non elenca alcuna foglia. Si prenda l’associazione sopra e si cambino due cose — l’autore scrive solo il localizzatore, lasciando non riempita la foglia dichiarata sensibile, e riempie la chiave d’ambiente dalla chiave provides name non marcata della Feature anziché da password:

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

sensitive è ancora vero — le dichiarazioni della Feature non sono cambiate — mentre entrambe le unità più ristrette sono sparite. L’associazione gestisce ancora materiale segreto; semplicemente non lo fa tramite una foglia o una chiave di consegna che questa associazione porta. Una policy basata sul valore aggregato nega questa build, e una policy basata sulla marcatura per foglia la lascia passare. Sono entrambe regole difendibili, e quale delle due una policy vuole è una decisione che l’autore della policy prende deliberatamente.

La stessa asimmetria vale nell’altro senso per sensitive_inject: un’associazione può scrivere una foglia sensibile senza instradare nulla di sensibile attraverso una chiave di consegna, oppure instradare una chiave provides sensibile senza scrivere alcun valore.

Cosa non fa una dichiarazione di sensibilità

La marcatura annota; non è un controllo. Dichiarare sensibile una foglia o uno slot non cifra nulla, non convalida né rifiuta un valore e non impone un meccanismo di consegna. Nessun esito di build cambia perché è presente una dichiarazione.

Sulla maggior parte dei target non cambia nemmeno alcun byte renderizzato: un valore dichiarato sensibile che un autore ha fornito in linea viene renderizzato esattamente come uno non dichiarato. Terraform è l’eccezione tra i target della libreria standard, perché dispone di una primitiva nativa di sensibilità per valore su cui la dichiarazione può poggiare — vedi providers/terraform.md «Input di modulo dichiarati sensibili». Un target privo di una propria nozione di sensibilità non ha nulla che una dichiarazione possa cambiare.

Ciò che le dichiarazioni fanno ovunque è rendere il fatto leggibile — per l’output di debug del compilatore stesso, e per una policy su questo socket che decide che cosa farne. Trasformare una marcatura in un esito di build è il compito della policy, ed è ciò per cui esiste questo socket. E a una policy viene detto del materiale dichiarato sensibile senza che le venga consegnato: la marcatura arriva, il valore arriva trattenuto.

Riferimenti incrociati

  • policy-socket.md — il socket di governance: i quattro ruoli, le severità dei verdetti, il canale di input dell’operatore, i motori di policy che vengono distribuiti all’interno del compilatore e l’associazione di un plugin a un workspace.
  • plugin-contract.md — la collocazione del socket nella pipeline e le sue forme di trasmissione tipizzate.
  • riferimento dello schema del grafo — il contratto campo per campo del grafo di build, inclusi tutti i campi di un’associazione.
  • entities/component.md «Slot di associazione» — dichiarare uno slot, e dichiarare sensibile uno slot; e il featuresSchema che un socket dichiara per le connessioni che passano attraverso di esso.
  • entities/aggregate.md «Le associazioni proprie di una connessione» — scrivere un’associazione su una connessione, e il nome che assume.
  • vocabulary/compact-form-authoring.md «Dichiarare sensibile una foglia» — la parola chiave sensitive: e il limite di ciò che dichiararla ottiene.
  • vocabulary/labels-and-annotations.md — le superfici di etichette e annotazioni che una policy legge.