Esquema do registo de confiança de Plugin do Aggrega
Referência gerada. Não editar à mão — gerar novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json
Registo gerado automaticamente da identidade de plugin considerada fidedigna para cada anexo que devolve um veredicto de aceitação ou rejeição — um anexo plugins.governance num papel ir-verdict ou render-verdict, e cada anexo plugins.linter. Encontra-se em plugins-trust.yaml junto ao ficheiro de bloqueio e é incluído em commit juntamente com ele, porque um registo mantido fora do controlo de versões é um registo que ninguém pode rever e com o qual nada pode ser comparado. É escrito por aggrega pull, que cria o ficheiro na primeira vez que resolve um desses anexos e adiciona um registo por anexo à medida que o resolve. Um ficheiro que contém registos apenas para alguns dos anexos configurados é um estado intermédio válido e não um estado danificado. É lido por aggrega build, por aggrega lint --release e por aggrega validate --release, e pelas mesmas operações alcançadas através de aggrega serve e aggrega mcp; cada uma confronta a configuração do espaço de trabalho com o registo antes de qualquer um desses anexos ser executado. Duas divergências são recusadas, por motivos diferentes: um plugin cujo digest de artefacto resolvido não é o digest registado para ele é recusado em vez de executado, porque o plugin que seria executado não é aquele para o qual o registo foi revisto; e uma entrada do registo pela qual nenhum anexo de veredicto configurado responde interrompe a execução, porque remover um controlo não altera nenhum byte renderizado, pelo que uma saída produzida sem um controlo que tinha sido revisto é indistinguível de uma saída que esse controlo aprovou. Uma compilação, um lint com âmbito de release e uma validação com âmbito de release — a partir da linha de comandos, através de aggrega serve ou através de aggrega mcp — também sujeitam cada um desses plugins que leem da cache de conteúdo à signature que o seu registo transporta, quando o carregam, tal como uma compilação sujeita cada entrada do ficheiro de bloqueio àquela que essa entrada transporta: ver signature abaixo. A direção oposta — um anexo configurado que o registo ainda não contém — é o estado intermédio acabado de descrever e nenhuma das duas comparações o recusa, e um registo ausente não contém nenhuma entrada, pelo que não fixa nada e nenhuma das duas comparações recusa nada por causa dele; o requisito de assinatura é a única restrição à qual uma entrada em falta não escapa, como signature abaixo descreve. Uma entrada só sai do registo numa atualização explícita: aggrega pull --upgrade a nomear um plugin remove a entrada desse plugin quando nenhum anexo de veredicto o nomeia mais, e um aggrega pull --upgrade sem argumentos remove todas essas entradas. Um aggrega pull simples nem volta a resolver a identidade de uma entrada nem remove a entrada, pelo que uma interrupção devida a uma entrada pela qual nada responde é resolvida declarando-o deliberadamente, e não pela execução seguinte. Um registo cuja última entrada é removida é esvaziado em vez de eliminado, e um registo esvaziado é um registo válido: não contém nada, pelo que não fixa nada e nenhuma das duas comparações recusa nada por causa dele, exatamente como um registo ausente. Cada registo é endereçado pela coordenada de identidade própria do plugin e transporta a versão selecionada e o digest do artefacto como campos, pelo que uma mudança de versão é uma alteração a um campo de um registo existente em vez de um novo registo sob um novo endereço — e é isso que torna um plugin com nova versão distinguível, no ficheiro e no seu diff, de um registado pela primeira vez. Além dessa identidade, um registo transporta dois factos sobre o artefacto que nomeia, cada um registado apenas quando foi verificado: a descontinuação que um publicador lhe anexou, quando foi encontrada uma e a sua assinatura verificada, e o facto de assinatura verificada que aggrega pull registou quando verificou a assinatura própria do plugin — o mesmo facto, sob a mesma chave, que uma entrada do ficheiro de bloqueio transporta. Cada um é um facto sobre o artefacto registado e não uma segunda identidade, e é por isso que um pull comum regista um sem perturbar a identidade à qual está vinculado. Além destes, o ficheiro não regista nada: nenhuma assinatura sobre o próprio ficheiro, nenhuma entrada de regras, nenhuma proveniência da resolução — nenhum host de registo, nenhum caminho na máquina que o escreveu — e nenhuma leitura de relógio, pelo que a mesma resolução produz os mesmos bytes onde e quando quer que seja executada. Os ficheiros de regras externos de um anexo de veredicto plugins.governance são registados como digests em verdict_inputs do ficheiro de bloqueio; as entradas de regras de um anexo plugins.linter não são registadas em nenhum dos dois ficheiros. Tudo aquilo que uma compilação reproduz byte a byte é antes fixado no ficheiro de bloqueio; um anexo de veredicto não molda nada da saída renderizada, e é por isso que a sua identidade é registada aqui e não lá. Disciplina de evolução do esquema: adicionar uma nova secção de nível superior é SemVer-MINOR (aditivo); adicionar um novo campo dentro de uma secção existente é SemVer-MINOR; remover uma chave ou tornar uma restrição mais rígida é SemVer-MAJOR.
Tipo de nível superior: object
Propriedades
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
plugins | object[] | não | Um registo por plugin de confiança para um anexo que devolve um veredicto, endereçado pela coordenada de identidade do plugin. Um plugin anexado a dois papéis de veredicto em simultâneo — o mesmo plugin de governação associado tanto a ir-verdict como a render-verdict — contribui com um único registo, porque o sujeito registado é a identidade do plugin e não o anexo: os dois anexos leem o mesmo artefacto. Os registos são emitidos por ordem crescente de coordenada. Predefinição: [] |
version | const 1 | sim | Versão do esquema do registo de confiança: 1. Uma alteração SemVer-MAJOR ao esquema incrementa-a. Constante: 1 |
Não são permitidas propriedades adicionais.
plugins-trust.plugins[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
deprecation | objeto | não | Marcador de descontinuação retroativo verificado, registado quando um marcador assinado e de confiança foi descoberto no artefacto que digest nomeia. Um marcador é um referrer OCI assinado do artefacto que descontinua, anexado após a publicação sem voltar a publicar o artefacto, pelo que um plugin já registado aqui pode ser descontinuado posteriormente — na severidade retracted, que é o nível de retirada, isso significa que o artefacto é excluído da seleção em vez de apenas desaconselhado. É um facto sobre o artefacto que este registo já endereça e não uma segunda identidade, o que permite a aggrega pull acrescentar um deixando ainda assim intactos resolved_version e digest: registá-lo não adota nada. Só é registado quando o digest resolvido é igual ao digest já registado — uma resolução que reporta bytes diferentes é uma mudança de identidade, regida pela regra própria deste registo e recusada a menos que a execução a tenha pedido. Nada apaga um marcador registado; só sai juntamente com o registo que o contém, na atualização explícita que substitui ou remove esse registo. aggrega build, aggrega lint --release e aggrega validate --release, e as mesmas operações alcançadas através de aggrega serve e aggrega mcp, nomeiam um plugin que tenha um, porque de outro modo um controlo descontinuado é obtido, colocado em cache e executado sem que nada seja dito, e o ajuste build.halt_on_deprecated_severity do espaço de trabalho decide se uma compilação para por causa dele ou apenas recebe um aviso. |
plugin | string | sim | A coordenada de identidade do plugin: o seu segmento de socket e o seu nome simples unidos por uma barra, como em governance/aggrega-security-baseline. Um nome simples só é único dentro do seu socket, pelo que é o segmento de socket que distingue dois plugins com o mesmo nome em sockets diferentes. A coordenada não contém deliberadamente nenhuma versão — é isso que torna uma mudança de versão visível como uma edição de resolved_version abaixo e não como um registo sem relação. |
resolved_version | string | sim | Versão concreta selecionada para este plugin quando o registo foi escrito (por exemplo 1.2.3). Registada como um único segmento de caminho, pelo que não contém /, nem \, nem ... Padrão: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | sim | Digest de conteúdo do artefacto de plugin resolvido, na forma sha256: seguido de 64 caracteres hexadecimais minúsculos — a forma em que o endereço de conteúdo é escrito em todos os locais onde é comparado. Padrão: ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | não | Facto de assinatura verificada registado quando aggrega pull verificou a assinatura própria deste plugin face à política de confiança do registo que o resolveu, para o artefacto que digest nomeia. Um pull verifica a assinatura de cada plugin que resolve para um destes anexos, em cada execução, e regista aqui o que encontrou — substituindo o que o registo continha, e removendo-o quando o pull não verificou nenhuma — sem alterar a identidade à qual o registo está sujeito. Antes de uma compilação, um lint com âmbito de release ou uma validação com âmbito de release executar o plugin, é calculado de novo o hash do bundle de assinatura em cache que este facto nomeia, e a execução para quando o blob está em falta ou é diferente; e, para um plugin lido a partir da cache de conteúdo, a execução lê nesse bundle para que artefacto a assinatura foi feita, e para quando foi feita para um artefacto diferente do plugin que leu — pelo que uma signature copiada da entrada de outro plugin é recusada, independentemente do que diga o requisito de assinatura. Aí não é verificada nenhuma assinatura, pelo que um bundle escrito à mão na cache, emitido para o artefacto próprio deste plugin, não é distinguido de um que um pull verificou. E quando a configuração de confiança do espaço de trabalho exige uma assinatura para um plugin lido a partir da cache de conteúdo — o requisito que aggrega pull aplica quando verifica o plugin, pelo que as isenções e um registo advisory que permitem a um pull não registar nenhuma também deixam a execução prosseguir — um registo que não contém nenhuma signature para ele, ou nenhuma entrada para ele, faz parar a execução, nomeando o plugin e as definições que exigem a assinatura. Um plugin lido a partir de um diretório de catálogo ou da cópia incluída no binário do compilador nunca fica sujeito a esse requisito. |
Não são permitidas propriedades adicionais.
plugins-trust.plugins[].deprecation
Marcador de descontinuação retroativo verificado, registado quando um marcador assinado e de confiança foi descoberto no artefacto que digest nomeia. Um marcador é um referrer OCI assinado do artefacto que descontinua, anexado após a publicação sem voltar a publicar o artefacto, pelo que um plugin já registado aqui pode ser descontinuado posteriormente — na severidade retracted, que é o nível de retirada, isso significa que o artefacto é excluído da seleção em vez de apenas desaconselhado. É um facto sobre o artefacto que este registo já endereça e não uma segunda identidade, o que permite a aggrega pull acrescentar um deixando ainda assim intactos resolved_version e digest: registá-lo não adota nada. Só é registado quando o digest resolvido é igual ao digest já registado — uma resolução que reporta bytes diferentes é uma mudança de identidade, regida pela regra própria deste registo e recusada a menos que a execução a tenha pedido. Nada apaga um marcador registado; só sai juntamente com o registo que o contém, na atualização explícita que substitui ou remove esse registo. aggrega build, aggrega lint --release e aggrega validate --release, e as mesmas operações alcançadas através de aggrega serve e aggrega mcp, nomeiam um plugin que tenha um, porque de outro modo um controlo descontinuado é obtido, colocado em cache e executado sem que nada seja dito, e o ajuste build.halt_on_deprecated_severity do espaço de trabalho decide se uma compilação para por causa dele ou apenas recebe um aviso.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
message | string | sim | Mensagem de descontinuação legível por humanos contida no marcador — tipicamente uma indicação de migração. Quando o marcador não continha uma mensagem separada, o seu motivo é registado aqui em vez disso, pelo que a frase reportada nunca fica em branco. |
severity | string (enum) | sim | Severidade do marcador, ordenada warning < error < retracted. Uma compilação para quando esta severidade atinge ou excede o limiar de interrupção configurado, e emite um aviso caso contrário — a mesma regra e o mesmo ajuste que qualquer outro relatório de descontinuação lê. retracted é o nível de retirada: um artefacto com essa severidade é excluído da seleção, ao passo que as duas severidades consultivas o deixam selecionável. Valores permitidos: "warning", "error", "retracted" |
Não são permitidas propriedades adicionais.
Definições
VerifiedSignature
Facto de assinatura verificada que um pull regista quando verifica a assinatura de um artefacto face à política de confiança do registo que o resolve. É a forma única que ambos os registos usam para ele — o ficheiro de bloqueio, em cada uma das suas entradas, e este registo, em cada plugin — pelo que uma assinatura verificada se lê da mesma forma em qualquer um dos ficheiros. Regista o modo de verificação, a identidade/o emissor keyless que correspondeu (quando keyless) ou a impressão digital da chave fixada (quando com chave), e o digest endereçado por conteúdo do bundle de assinatura que o pull colocou em cache.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
bundle_digest | string | sim | Digest SHA-256 do blob do bundle de assinatura em cache, na forma sha256: seguido de 64 caracteres hexadecimais minúsculos. Nomeia o blob da cache, pelo que forma um caminho e não contém /, nem \, nem .. — o que a forma sha256: já exclui — e é face a ele que uma compilação, um lint com âmbito de release e uma validação com âmbito de release voltam a calcular o hash desse blob. Padrão: ^sha256:[a-f0-9]{64}$. |
identity | string | não | Signatário verificado da assinatura: o sujeito do certificado de assinatura para uma assinatura keyless, ou keyed:sha256: seguido do SHA-256 do texto PEM da chave pública fixada para uma assinatura com chave. |
issuer | string | não | Emissor OIDC verificado para uma assinatura keyless. Vazio para uma assinatura com chave. |
mode | string (enum) | sim | Modo de verificação que admitiu a assinatura. Valores permitidos: "keyless", "keyed" |
Não são permitidas propriedades adicionais.