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

Schemat rekordu zaufania Aggrega Plugin Trust Record

Dokumentacja wygenerowana automatycznie. Nie należy jej edytować ręcznie — należy ją wygenerować ponownie z opublikowanego JSON Schema.

Identyfikator schematu: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json

Generowany maszynowo rekord tożsamości wtyczki zaufanej dla każdego podpięcia zwracającego werdykt „akceptuj albo odrzuć” — podpięcia plugins.governance w roli ir-verdict lub render-verdict oraz każdego podpięcia plugins.linter. Znajduje się w plugins-trust.yaml obok pliku blokady i jest zatwierdzany razem z nim, ponieważ rekordu przechowywanego poza kontrolą wersji nikt nie może przejrzeć i nie można się do niego odnieść przy porównaniu. Zapisuje go aggrega pull, które tworzy plik przy pierwszym rozwiązaniu jednego z tych podpięć i dodaje po jednym rekordzie na podpięcie w miarę ich rozwiązywania. Plik zawierający rekordy tylko dla części skonfigurowanych podpięć jest poprawnym stanem pośrednim, a nie uszkodzonym. Odczytują go aggrega build, aggrega lint --release i aggrega validate --release, a także te same operacje wywoływane przez aggrega serve i aggrega mcp; każda z nich sprawdza konfigurację obszaru roboczego względem rekordu, zanim którekolwiek z tych podpięć zostanie uruchomione. Odrzucane są dwie niezgodności, z różnych powodów: wtyczka, której rozwiązany skrót artefaktu nie jest skrótem dla niej zapisanym, zostaje odrzucona zamiast uruchomiona, ponieważ wtyczka, która by się uruchomiła, nie jest tą, dla której rekord przejrzano; a wpis rekordu, któremu nie odpowiada żadne skonfigurowane podpięcie werdyktu, zatrzymuje przebieg, ponieważ usunięcie bramki nie zmienia żadnego wyrenderowanego bajtu, więc wyniku wytworzonego bez przejrzanej bramki nie da się odróżnić od wyniku, który ta bramka zatwierdziła. Kompilacja, lintowanie w zakresie wydania i walidacja w zakresie wydania — z wiersza poleceń, przez aggrega serve lub przez aggrega mcp — przy ładowaniu każdej z tych wtyczek odczytanej z pamięci podręcznej treści sprawdzają ją również względem signature zapisanego w jej rekordzie, tak jak kompilacja sprawdza każdy wpis pliku blokady względem tego, który ten wpis zawiera: zob. signature poniżej. Kierunek przeciwny — skonfigurowane podpięcie, którego rekord jeszcze nie zawiera — jest opisanym właśnie stanem pośrednim i żadne z porównań go nie odrzuca, a nieobecny rekord nie zawiera żadnych wpisów, więc niczego nie przypina i żadne z porównań niczego z jego powodu nie odrzuca; wymóg podpisu jest jedynym sprawdzeniem, którego brak wpisu nie pozwala uniknąć, jak opisuje signature poniżej. Wpis opuszcza rekord wyłącznie przy jawnej aktualizacji: aggrega pull --upgrade wskazujące wtyczkę usuwa jej wpis, gdy żadne podpięcie werdyktu już jej nie wskazuje, a samo aggrega pull --upgrade usuwa każdy taki wpis. Zwykłe aggrega pull ani nie rozwiązuje ponownie tożsamości wpisu, ani go nie usuwa, więc zatrzymanie z powodu wpisu, któremu nic nie odpowiada, usuwa się świadomą decyzją, a nie przy kolejnym przebiegu. Rekord, z którego usunięto ostatni wpis, jest opróżniany, a nie kasowany, a opróżniony rekord jest poprawny: nic nie zawiera, więc niczego nie przypina i żadne z porównań niczego z jego powodu nie odrzuca, dokładnie tak jak w przypadku nieobecnego rekordu. Każdy rekord jest adresowany własną współrzędną tożsamości wtyczki i zawiera wybraną wersję oraz skrót artefaktu jako pola, więc zmiana wersji jest zmianą pola istniejącego rekordu, a nie nowym rekordem pod nowym adresem — dzięki temu wtyczkę o zmienionej wersji można odróżnić, w pliku i w jego różnicach, od wtyczki zapisanej po raz pierwszy. Poza tą tożsamością rekord zawiera dwa fakty o artefakcie, który wskazuje, każdy zapisywany tylko wtedy, gdy został zweryfikowany: wycofanie dołączone do niego przez wydawcę, gdy je znaleziono i zweryfikowano jego podpis, oraz fakt zweryfikowanego podpisu zapisany przez aggrega pull po zweryfikowaniu własnego podpisu wtyczki — ten sam fakt, pod tym samym kluczem, który zawiera wpis pliku blokady. Każdy z nich jest faktem o zapisanym artefakcie, a nie drugą tożsamością, dlatego zwykłe pobranie zapisuje go bez naruszania tożsamości, względem której rekord jest sprawdzany. Poza nimi plik nie zapisuje niczego: żadnego podpisu samego pliku, żadnych danych wejściowych reguł, żadnego pochodzenia rozwiązania — żadnego hosta rejestru, żadnej ścieżki na maszynie, która go zapisała — ani żadnego odczytu zegara, więc to samo rozwiązanie daje te same bajty, gdziekolwiek i kiedykolwiek jest wykonywane. Zewnętrzne pliki reguł podpięcia werdyktu plugins.governance są zapisywane jako skróty w verdict_inputs pliku blokady; dane wejściowe reguł podpięcia plugins.linter nie są zapisywane w żadnym z plików. Wszystko, co kompilacja odtwarza bajt w bajt, jest przypięte w pliku blokady; podpięcie werdyktu nie kształtuje żadnej części wyrenderowanego wyniku, dlatego jego tożsamość jest zapisywana tutaj, a nie tam. Dyscyplina ewolucji schematu: dodanie nowej sekcji najwyższego poziomu jest zmianą SemVer-MINOR (addytywną); dodanie nowego pola w istniejącej sekcji jest zmianą SemVer-MINOR; usunięcie klucza lub zaostrzenie ograniczenia jest zmianą SemVer-MAJOR.

Typ najwyższego poziomu: object

Właściwości

WłaściwośćTypWymaganaOpis
pluginsobject[]nieJeden rekord na każdą wtyczkę zaufaną dla dołączenia zwracającego werdykt, adresowany współrzędną tożsamości wtyczki. Wtyczka dołączona jednocześnie w dwóch rolach werdyktu — ta sama wtyczka zarządcza powiązana zarówno z ir-verdict, jak i z render-verdict — daje jeden rekord, ponieważ rejestrowanym podmiotem jest tożsamość wtyczki, a nie dołączenie: oba dołączenia odczytują ten sam artefakt. Rekordy są emitowane w rosnącej kolejności współrzędnych. Wartość domyślna: []
versionconst 1takWersja schematu rekordu zaufania: 1. Zmiana schematu typu SemVer-MAJOR ją zwiększa. Stała: 1

Dodatkowe właściwości są niedozwolone.

plugins-trust.plugins[]

WłaściwośćTypWymaganaOpis
deprecationobjectnieZweryfikowany wsteczny znacznik wycofania, rejestrowany, gdy na artefakcie wskazanym przez digest wykryto podpisany, zaufany znacznik. Znacznik to podpisany referrer OCI artefaktu, który wycofuje, dołączany po publikacji bez ponownego publikowania artefaktu, dzięki czemu wtyczkę już tu zarejestrowaną można wycofać później — przy poziomie retracted, który jest poziomem wycofania z użycia, oznacza to, że artefakt jest wykluczony z wyboru, a nie jedynie odradzany. Jest to fakt dotyczący artefaktu, który ten rekord już adresuje, a nie druga tożsamość, i właśnie dlatego aggrega pull może go dodać, pozostawiając resolved_version i digest bez zmian: jego zarejestrowanie niczego nie przyjmuje. Jest rejestrowany tylko wtedy, gdy rozwiązany skrót jest równy skrótowi już zarejestrowanemu — rozwiązanie zgłaszające inne bajty jest zmianą tożsamości, podlega własnej regule tego rekordu i jest odrzucane, chyba że uruchomienie o nie poprosiło. Nic nie usuwa zarejestrowanego znacznika; znika on tylko razem z rekordem, który go zawiera, przy jawnej aktualizacji, która ten rekord zastępuje lub usuwa. aggrega build, aggrega lint --release i aggrega validate --release, a także te same operacje wywoływane przez aggrega serve i aggrega mcp, wskazują wtyczkę z takim znacznikiem, ponieważ w przeciwnym razie wycofana bramka byłaby pobierana, buforowana i uruchamiana bez żadnej informacji, a ustawienie obszaru roboczego build.halt_on_deprecated_severity decyduje, czy kompilacja zostaje z tego powodu zatrzymana, czy tylko wyświetla ostrzeżenie.
pluginstringtakWspółrzędna tożsamości wtyczki: jej segment gniazda i jej sama nazwa połączone ukośnikiem, jak w governance/aggrega-security-baseline. Sama nazwa jest unikalna tylko w obrębie swojego gniazda, więc to segment gniazda odróżnia dwie wtyczki o tej samej nazwie w różnych gniazdach. Współrzędna celowo nie zawiera wersji — dzięki temu zmiana wersji jest widoczna jako edycja resolved_version poniżej, a nie jako niepowiązany rekord.
resolved_versionstringtakKonkretna wersja wybrana dla tej wtyczki w chwili zapisania rekordu (np. 1.2.3). Zapisywana jako pojedynczy segment ścieżki, więc nie zawiera /, \ ani ... Wzorzec: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringtakSkrót treści rozwiązanego artefaktu wtyczki w postaci sha256:, po którym następują 64 małe znaki szesnastkowe — w tej postaci adres treści jest zapisywany wszędzie, gdzie jest porównywany. Wzorzec: ^sha256:[a-f0-9]{64}$.
signatureVerifiedSignaturenieFakt zweryfikowanego podpisu, rejestrowany, gdy aggrega pull zweryfikowało własny podpis tej wtyczki względem polityki zaufania rozwiązującego rejestru, dla artefaktu wskazanego przez digest. Pull weryfikuje podpis każdej wtyczki rozwiązywanej dla jednego z tych dołączeń, przy każdym uruchomieniu, i zapisuje tu wynik — zastępując to, co zawierał rekord, i usuwając to, gdy nie zweryfikowano żadnego podpisu — bez naruszania tożsamości, względem której rekord jest sprawdzany. Zanim kompilacja, lint w zakresie wydania lub walidacja w zakresie wydania uruchomi wtyczkę, buforowany pakiet podpisu wskazany przez ten fakt jest ponownie haszowany, a uruchomienie zostaje zatrzymane, jeśli obiektu brakuje lub się różni; ponadto dla wtyczki odczytanej z pamięci podręcznej treści uruchomienie odczytuje z tego pakietu, dla którego artefaktu złożono podpis, i zatrzymuje się, jeśli złożono go dla innego artefaktu niż odczytana wtyczka — więc signature skopiowany z wpisu innej wtyczki jest odrzucany, niezależnie od wymogu podpisu. Na tym etapie żaden podpis nie jest weryfikowany, więc pakiet zapisany ręcznie w pamięci podręcznej, wystawiony dla własnego artefaktu tej wtyczki, jest nieodróżnialny od pakietu zweryfikowanego przez pull. Gdy zaś konfiguracja zaufania obszaru roboczego wymaga podpisu dla wtyczki odczytanej z pamięci podręcznej treści — jest to wymóg, który aggrega pull stosuje przy weryfikacji wtyczki, więc pominięcia i rejestr advisory, które pozwalają pull nie zapisać podpisu, pozwalają również kontynuować uruchomienie — rekord bez signature dla tej wtyczki lub w ogóle bez wpisu dla niej zatrzymuje uruchomienie, wskazując wtyczkę i ustawienia wymagające podpisu. Wtyczka odczytana z katalogu lub z kopii wbudowanej w plik binarny kompilatora nigdy nie podlega temu wymogowi.

Dodatkowe właściwości są niedozwolone.

plugins-trust.plugins[].deprecation

Zweryfikowany wsteczny znacznik wycofania, rejestrowany, gdy na artefakcie wskazanym przez digest wykryto podpisany, zaufany znacznik. Znacznik to podpisany referrer OCI artefaktu, który wycofuje, dołączany po publikacji bez ponownego publikowania artefaktu, dzięki czemu wtyczkę już tu zarejestrowaną można wycofać później — przy poziomie retracted, który jest poziomem wycofania z użycia, oznacza to, że artefakt jest wykluczony z wyboru, a nie jedynie odradzany. Jest to fakt dotyczący artefaktu, który ten rekord już adresuje, a nie druga tożsamość, i właśnie dlatego aggrega pull może go dodać, pozostawiając resolved_version i digest bez zmian: jego zarejestrowanie niczego nie przyjmuje. Jest rejestrowany tylko wtedy, gdy rozwiązany skrót jest równy skrótowi już zarejestrowanemu — rozwiązanie zgłaszające inne bajty jest zmianą tożsamości, podlega własnej regule tego rekordu i jest odrzucane, chyba że uruchomienie o nie poprosiło. Nic nie usuwa zarejestrowanego znacznika; znika on tylko razem z rekordem, który go zawiera, przy jawnej aktualizacji, która ten rekord zastępuje lub usuwa. aggrega build, aggrega lint --release i aggrega validate --release, a także te same operacje wywoływane przez aggrega serve i aggrega mcp, wskazują wtyczkę z takim znacznikiem, ponieważ w przeciwnym razie wycofana bramka byłaby pobierana, buforowana i uruchamiana bez żadnej informacji, a ustawienie obszaru roboczego build.halt_on_deprecated_severity decyduje, czy kompilacja zostaje z tego powodu zatrzymana, czy tylko wyświetla ostrzeżenie.

WłaściwośćTypWymaganaOpis
messagestringtakCzytelny dla człowieka komunikat o wycofaniu zawarty w znaczniku — zazwyczaj wskazówka migracji. Jeśli znacznik nie zawierał osobnego komunikatu, zapisywany jest tu jego powód, więc zgłaszane zdanie nigdy nie jest puste.
severitystring (enum)takPoziom znacznika, uporządkowany jako warning < error < retracted. Kompilacja zostaje zatrzymana, gdy ten poziom osiąga lub przekracza skonfigurowany próg zatrzymania, a w przeciwnym razie wyświetla ostrzeżenie — to ta sama reguła i to samo ustawienie, które odczytuje każdy inny raport o wycofaniu. retracted to poziom wycofania z użycia: artefakt o tym poziomie jest wykluczony z wyboru, podczas gdy dwa poziomy ostrzegawcze pozostawiają go do wyboru. Dozwolone wartości: "warning", "error", "retracted"

Dodatkowe właściwości są niedozwolone.

Definicje

VerifiedSignature

Fakt zweryfikowanego podpisu, który operacja pull zapisuje, gdy weryfikuje podpis artefaktu względem polityki zaufania rejestru, z którego rozwiązuje artefakt. Jest to jedyny kształt, którego używają do tego oba rekordy — plik blokady, w każdym ze swoich wpisów, i ten rekord, przy każdym pluginie — dzięki czemu zweryfikowany podpis wygląda tak samo w obu plikach. Zapisuje tryb weryfikacji, dopasowaną tożsamość/wystawcę (w trybie bezkluczowym) lub odcisk przypiętego klucza (w trybie z kluczem) oraz adresowany treścią skrót pakietu podpisu zapisanego przez pull w pamięci podręcznej.

WłaściwośćTypWymaganaOpis
bundle_digeststringtakSkrót SHA-256 obiektu blob pakietu podpisu w pamięci podręcznej, w postaci sha256:, po którym następuje 64 małych znaków szesnastkowych. Nazywa on obiekt blob w pamięci podręcznej, więc tworzy ścieżkę i nie zawiera /, \ ani .. — co postać sha256: już wyklucza — i to względem niego kompilacja, lint w zakresie wydania oraz walidacja w zakresie wydania ponownie obliczają skrót tego obiektu blob. Wzorzec: ^sha256:[a-f0-9]{64}$.
identitystringnieZweryfikowany podpisujący: podmiot certyfikatu podpisującego dla podpisu bezkluczowego lub keyed:sha256:, po którym następuje SHA-256 tekstu PEM przypiętego klucza publicznego, dla podpisu kluczowego.
issuerstringnieZweryfikowany wystawca OIDC dla podpisu bezkluczowego. Pusty dla podpisu kluczowego.
modestring (enum)takTryb weryfikacji, który dopuścił podpis. Dozwolone wartości: "keyless", "keyed"

Dodatkowe właściwości są niedozwolone.