Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Esquema do registro de confiança de Plugin do Aggrega

Referência gerada. Não edite à mão — gere novamente a partir do JSON Schema publicado.

ID do esquema: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json

Registro gerado automaticamente da identidade de plugin considerada confiável para cada vinculação que retorna um veredito de aceitação ou rejeição — uma vinculação plugins.governance em um papel ir-verdict ou render-verdict, e toda vinculação plugins.linter. Fica em plugins-trust.yaml ao lado do arquivo de bloqueio e é incluído em commit junto com ele, porque um registro mantido fora do controle de versão é um registro que ninguém pode revisar e com o qual nada pode ser comparado. Escrito por aggrega pull, que cria o arquivo na primeira vez que resolve uma dessas vinculações e adiciona um registro por vinculação à medida que a resolve. Um arquivo que contém registros apenas para algumas das vinculações configuradas é um estado intermediário 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 por meio de aggrega serve e aggrega mcp; cada uma confronta a configuração do espaço de trabalho com o registro antes que qualquer uma dessas vinculações seja executada. Duas divergências são recusadas, por motivos diferentes: um plugin cujo digest de artefato resolvido não é o digest registrado para ele é recusado em vez de executado, porque o plugin que seria executado não é aquele para o qual o registro foi revisado; e uma entrada do registro pela qual nenhuma vinculação de veredito configurada responde interrompe a execução, porque remover um controle não altera nenhum byte renderizado, de modo que uma saída produzida sem um controle que foi revisado é indistinguível de uma saída que esse controle aprovou. Um build, um lint com escopo de release e uma validação com escopo de release — pela linha de comando, por meio de aggrega serve ou por meio de aggrega mcp — também submetem cada um desses plugins que leem do cache de conteúdo à signature que seu registro traz, quando o carregam, assim como um build submete cada entrada do arquivo de bloqueio àquela que essa entrada traz: veja signature abaixo. A direção oposta — uma vinculação configurada que o registro ainda não contém — é o estado intermediário que acabou de ser descrito e nenhuma das duas comparações a recusa, e um registro ausente não contém nenhuma entrada, então não fixa nada e nenhuma das duas comparações recusa nada por causa dele; o requisito de assinatura é a única restrição da qual uma entrada ausente não escapa, como signature abaixo descreve. Uma entrada só sai do registro em uma atualização explícita: aggrega pull --upgrade nomeando um plugin remove a entrada desse plugin quando nenhuma vinculação de veredito o nomeia mais, e um aggrega pull --upgrade sem argumentos remove todas essas entradas. Um aggrega pull simples nem resolve novamente a identidade de uma entrada nem remove a entrada, de modo que uma interrupção por causa de uma entrada pela qual nada responde é resolvida declarando isso deliberadamente, e não pela próxima execução. Um registro cuja última entrada é removida é esvaziado em vez de excluído, e um registro esvaziado é um registro válido: não contém nada, então não fixa nada e nenhuma das duas comparações recusa nada por causa dele, exatamente como um registro ausente. Cada registro é endereçado pela coordenada de identidade própria do plugin e traz a versão selecionada e o digest do artefato como campos, de modo que uma mudança de versão é uma alteração em um campo de um registro existente em vez de um novo registro sob um novo endereço — o que torna um plugin com nova versão distinguível, no arquivo e em seu diff, de um registrado pela primeira vez. Além dessa identidade, um registro traz dois fatos sobre o artefato que nomeia, cada um registrado apenas quando foi verificado: a descontinuação que um publicador anexou a ele, quando uma foi encontrada e sua assinatura verificada, e o fato de assinatura verificada que aggrega pull registrou quando verificou a assinatura própria do plugin — o mesmo fato, sob a mesma chave, que uma entrada do arquivo de bloqueio traz. Cada um é um fato sobre o artefato registrado, e não uma segunda identidade, e é por isso que um pull comum registra um sem perturbar a identidade à qual ele está vinculado. Além desses, o arquivo não registra nada: nenhuma assinatura sobre o próprio arquivo, nenhuma entrada de regras, nenhuma procedência de resolução — nenhum host de registro, nenhum caminho na máquina que o escreveu — e nenhuma leitura de relógio, de modo que a mesma resolução produz os mesmos bytes onde e quando quer que seja executada. Os arquivos de regras externos de uma vinculação de veredito plugins.governance são registrados como digests em verdict_inputs do arquivo de bloqueio; as entradas de regras de uma vinculação plugins.linter não são registradas em nenhum dos dois arquivos. Tudo o que um build reproduz byte a byte é fixado no arquivo de bloqueio em vez disso; uma vinculação de veredito não molda nada da saída renderizada, e é por isso que sua identidade é registrada aqui, e não lá. Disciplina de evolução do esquema: adicionar uma nova seção de nível superior é SemVer-MINOR (aditivo); adicionar um novo campo dentro de uma seção existente é SemVer-MINOR; remover uma chave ou tornar uma restrição mais rígida é SemVer-MAJOR.

Tipo de nível superior: object

Propriedades

PropriedadeTipoObrigatóriaDescrição
pluginsobject[]nãoUm registro por plugin confiável para uma vinculação que retorna um veredito, endereçado pela coordenada de identidade do plugin. Um plugin vinculado a dois papéis de veredito ao mesmo tempo — o mesmo plugin de governança associado tanto a ir-verdict quanto a render-verdict — contribui com um único registro, porque o sujeito registrado é a identidade do plugin e não a vinculação: as duas vinculações leem o mesmo artefato. Os registros são emitidos em ordem crescente de coordenada. Valor padrão: []
versionconst 1simVersão do esquema do registro de confiança: 1. Uma alteração SemVer-MAJOR no esquema a incrementa. Constante: 1

Não são permitidas propriedades adicionais.

plugins-trust.plugins[]

PropriedadeTipoObrigatóriaDescrição
deprecationobjectnãoMarcador de descontinuação retroativo verificado, registrado quando um marcador assinado e confiável foi descoberto no artefato que digest nomeia. Um marcador é um referrer OCI assinado do artefato que ele descontinua, anexado após a publicação sem republicar o artefato, de modo que um plugin já registrado aqui pode ser descontinuado depois — na severidade retracted, que é o nível de retirada, isso significa que o artefato é excluído da seleção em vez de apenas desaconselhado. É um fato sobre o artefato que este registro já endereça e não uma segunda identidade, o que permite que o aggrega pull adicione um e ainda assim deixe intactos resolved_version e digest: registrá-lo não adota nada. Ele é registrado apenas quando o digest resolvido é igual ao digest já registrado — uma resolução que informa bytes diferentes é uma mudança de identidade, regida pela regra própria deste registro e recusada a menos que a execução a tenha pedido. Nada limpa um marcador registrado; ele sai apenas junto com o registro que o traz, na atualização explícita que substitui ou remove esse registro. aggrega build, aggrega lint --release e aggrega validate --release, e as mesmas operações alcançadas por meio de aggrega serve e aggrega mcp, nomeiam um plugin que traz um, porque de outra forma um controle descontinuado é obtido, armazenado em cache e executado sem que nada seja dito, e o ajuste build.halt_on_deprecated_severity do espaço de trabalho decide se um build é interrompido por ele ou apenas recebe um aviso.
pluginstringsimA coordenada de identidade do plugin: seu segmento de socket e seu nome simples unidos por uma barra, como em governance/aggrega-security-baseline. Um nome simples é único apenas dentro do seu socket, então é o segmento de socket que distingue dois plugins de mesmo nome em sockets diferentes. A coordenada deliberadamente não traz 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 registro não relacionado.
resolved_versionstringsimVersão concreta selecionada para este plugin quando o registro foi escrito (por exemplo 1.2.3). Registrada como um único segmento de caminho, então não contém /, nem \, nem ... Padrão: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringsimDigest de conteúdo do artefato de plugin resolvido, no formato sha256: seguido de 64 caracteres hexadecimais minúsculos — a forma em que o endereço de conteúdo é escrito em todos os lugares onde é comparado. Padrão: ^sha256:[a-f0-9]{64}$.
signatureVerifiedSignaturenãoFato de assinatura verificada registrado quando o aggrega pull verificou a assinatura própria deste plugin em relação à política de confiança do registro que o resolveu, para o artefato que digest nomeia. Um pull verifica a assinatura de cada plugin que resolve para uma dessas vinculações, em cada execução, e registra aqui o que encontrou — substituindo o que o registro continha, e removendo-o onde o pull não verificou nenhuma — sem alterar a identidade à qual o registro está sujeito. Antes que um build, um lint com escopo de release ou uma validação com escopo de release execute o plugin, o bundle de assinatura em cache que esse fato nomeia passa novamente por hash, e a execução é interrompida quando o blob está ausente ou é diferente; e, para um plugin lido do cache de conteúdo, a execução lê nesse bundle para qual artefato a assinatura foi feita, e é interrompida quando ela foi feita para um artefato diferente do plugin que leu — de modo que uma signature copiada da entrada de outro plugin é recusada, independentemente do que diga o requisito de assinatura. Ali nenhuma assinatura é verificada, então um bundle escrito à mão no cache, emitido para o artefato próprio deste plugin, não é distinguido de um que um pull verificou. E onde a configuração de confiança do espaço de trabalho exige uma assinatura para um plugin lido do cache de conteúdo — o requisito que o aggrega pull aplica quando verifica o plugin, de modo que as isenções e um registro advisory que permitem a um pull não registrar nenhuma também deixam a execução prosseguir — um registro que não traz nenhuma signature para ele, ou nenhuma entrada para ele, interrompe a execução, nomeando o plugin e as configurações que exigem a assinatura. Um plugin lido 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, registrado quando um marcador assinado e confiável foi descoberto no artefato que digest nomeia. Um marcador é um referrer OCI assinado do artefato que ele descontinua, anexado após a publicação sem republicar o artefato, de modo que um plugin já registrado aqui pode ser descontinuado depois — na severidade retracted, que é o nível de retirada, isso significa que o artefato é excluído da seleção em vez de apenas desaconselhado. É um fato sobre o artefato que este registro já endereça e não uma segunda identidade, o que permite que o aggrega pull adicione um e ainda assim deixe intactos resolved_version e digest: registrá-lo não adota nada. Ele é registrado apenas quando o digest resolvido é igual ao digest já registrado — uma resolução que informa bytes diferentes é uma mudança de identidade, regida pela regra própria deste registro e recusada a menos que a execução a tenha pedido. Nada limpa um marcador registrado; ele sai apenas junto com o registro que o traz, na atualização explícita que substitui ou remove esse registro. aggrega build, aggrega lint --release e aggrega validate --release, e as mesmas operações alcançadas por meio de aggrega serve e aggrega mcp, nomeiam um plugin que traz um, porque de outra forma um controle descontinuado é obtido, armazenado em cache e executado sem que nada seja dito, e o ajuste build.halt_on_deprecated_severity do espaço de trabalho decide se um build é interrompido por ele ou apenas recebe um aviso.

PropriedadeTipoObrigatóriaDescrição
messagestringsimMensagem de descontinuação legível por humanos trazida pelo marcador — normalmente uma indicação de migração. Onde o marcador não trazia uma mensagem separada, o seu motivo é registrado aqui no lugar dela, de modo que a frase relatada nunca fica em branco.
severitystring (enum)simSeveridade do marcador, ordenada warning < error < retracted. Um build é interrompido quando essa 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 todo outro relatório de descontinuação lê. retracted é o nível de retirada: um artefato com essa severidade é excluído da seleção, enquanto as duas severidades consultivas o deixam selecionável. Valores permitidos: "warning", "error", "retracted"

Não são permitidas propriedades adicionais.

Definições

VerifiedSignature

Fato de assinatura verificada que um pull registra quando verifica a assinatura de um artefato em relação à política de confiança do registro que o resolve. É a forma única que ambos os registros usam para ele — o arquivo de bloqueio, em cada uma das suas entradas, e este registro, em cada plugin — de modo que uma assinatura verificada é lida da mesma forma em qualquer um dos arquivos. Registra 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 armazenou em cache.

PropriedadeTipoObrigatóriaDescrição
bundle_digeststringsimDigest SHA-256 do blob do bundle de assinatura em cache, no formato sha256: seguido de 64 caracteres hexadecimais minúsculos. Ele nomeia o blob do cache, então forma um caminho e não contém /, nem \, nem .. — o que o formato sha256: já exclui — e é em relação a ele que um build, um lint com escopo de release e uma validação com escopo de release refazem o hash desse blob. Padrão: ^sha256:[a-f0-9]{64}$.
identitystringnãoSignatá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.
issuerstringnãoEmissor OIDC verificado para uma assinatura keyless. Vazio para uma assinatura com chave.
modestring (enum)simModo de verificação que admitiu a assinatura. Valores permitidos: "keyless", "keyed"

Não são permitidas propriedades adicionais.