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

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

PropriedadeTipoObrigatóriaDescrição
pluginsobject[]nãoUm 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: []
versionconst 1simVersã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[]

PropriedadeTipoObrigatóriaDescrição
deprecationobjetonãoMarcador 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.
pluginstringsimA 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_versionstringsimVersã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: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringsimDigest 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}$.
signatureVerifiedSignaturenãoFacto 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.

PropriedadeTipoObrigatóriaDescrição
messagestringsimMensagem 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.
severitystring (enum)simSeveridade 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.

PropriedadeTipoObrigatóriaDescrição
bundle_digeststringsimDigest 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}$.
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.