Aggrega Plugin 신뢰 레코드 스키마
자동 생성된 레퍼런스입니다. 직접 편집하지 말고 게시된 JSON Schema에서 다시 생성하십시오.
스키마 id: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json
수락 또는 거부 판정을 반환하는 각 첨부(ir-verdict 또는 render-verdict 역할의 plugins.governance 첨부와 모든 plugins.linter 첨부)에 대해 신뢰되는 플러그인 식별 정보를 기계가 생성한 레코드입니다. lockfile 옆의 plugins-trust.yaml에 위치하며 lockfile과 함께 커밋됩니다. 버전 관리 밖에 보관된 레코드는 아무도 검토할 수 없고 무엇과도 비교할 수 없기 때문입니다. aggrega pull이 작성하며, 이 명령은 해당 첨부 중 하나를 처음 해석할 때 파일을 생성하고 첨부를 해석할 때마다 첨부별로 레코드를 추가합니다. 구성된 첨부 중 일부에 대해서만 레코드를 담은 파일은 손상된 상태가 아니라 유효한 중간 상태입니다. aggrega build, aggrega lint --release, aggrega validate --release, 그리고 aggrega serve와 aggrega mcp를 통해 도달하는 동일한 작업이 이 파일을 읽으며, 각 작업은 해당 첨부가 실행되기 전에 작업 공간 구성을 레코드와 대조합니다. 두 가지 불일치는 서로 다른 이유로 거부됩니다. 해석된 아티팩트 다이제스트가 기록된 다이제스트와 다른 플러그인은 실행되지 않고 거부됩니다. 실행될 플러그인이 레코드가 검토된 대상과 다르기 때문입니다. 또한 구성된 어떤 판정 첨부로도 설명되지 않는 레코드 항목은 실행을 중단시킵니다. 게이트를 제거해도 렌더링된 바이트는 전혀 바뀌지 않으므로, 검토된 게이트 없이 생성된 출력은 그 게이트가 승인한 출력과 구별할 수 없기 때문입니다. 빌드, 릴리스 범위 lint, 릴리스 범위 검증은 명령줄에서든 aggrega serve나 aggrega mcp를 통해서든, 콘텐츠 캐시에서 읽는 각 플러그인을 로드할 때 해당 레코드가 담은 signature와도 대조합니다. 이는 빌드가 모든 lockfile 항목을 그 항목이 담은 서명과 대조하는 것과 같습니다. 아래 signature를 참조하십시오. 반대 방향, 즉 레코드에 아직 없는 구성된 첨부는 앞서 설명한 중간 상태이며 어느 비교도 이를 거부하지 않습니다. 또한 레코드가 없으면 항목도 전혀 없으므로 아무것도 고정하지 않으며, 어느 비교도 이를 이유로 무언가를 거부하지 않습니다. 서명 요구 사항은 항목이 없어도 벗어날 수 없는 유일한 대조이며, 이는 아래 signature에서 설명합니다. 항목은 명시적 업그레이드로만 레코드에서 제거됩니다. 플러그인을 지정한 aggrega pull --upgrade는 더 이상 어떤 판정 첨부도 그 플러그인을 지정하지 않을 때 해당 플러그인의 항목을 제거하고, 인수 없는 aggrega pull --upgrade는 그러한 항목을 모두 제거합니다. 일반 aggrega pull은 항목의 식별 정보를 다시 해석하지도, 항목을 제거하지도 않으므로, 아무것도 설명하지 않는 항목으로 인한 중단은 다음 실행이 아니라 의도적으로 그렇게 지시해야 해소됩니다. 마지막 항목이 제거된 레코드는 삭제되지 않고 비워지며, 비워진 레코드는 유효합니다. 아무것도 담지 않으므로 아무것도 고정하지 않고, 레코드가 없을 때와 똑같이 어느 비교도 이를 이유로 무언가를 거부하지 않습니다. 각 레코드는 플러그인 자신의 식별 좌표로 주소가 지정되며 선택된 버전과 아티팩트 다이제스트를 필드로 담습니다. 따라서 버전 변경은 새 주소 아래의 새 레코드가 아니라 기존 레코드의 필드 변경이며, 이 덕분에 버전이 바뀐 플러그인을 처음 기록된 플러그인과 파일 및 그 diff에서 구별할 수 있습니다. 이 식별 정보 외에 레코드는 자신이 지정하는 아티팩트에 관한 두 가지 사실을 담으며, 각각 검증된 경우에만 기록됩니다. 하나는 게시자가 아티팩트에 첨부한 지원 중단 정보로, 발견되고 그 서명이 검증된 경우에 기록됩니다. 다른 하나는 aggrega pull이 플러그인 자체의 서명을 검증했을 때 기록한 검증된 서명 사실로, lockfile 항목이 담는 것과 같은 키 아래의 같은 사실입니다. 각각은 두 번째 식별 정보가 아니라 기록된 아티팩트에 관한 사실이며, 그래서 일반 pull이 대조 대상인 식별 정보를 건드리지 않고 이를 기록할 수 있습니다. 파일은 이 외에는 아무것도 기록하지 않습니다. 파일 자체에 대한 서명도, 규칙 입력도, 해석 출처(레지스트리 호스트나 파일을 작성한 머신의 경로)도, 시각 정보도 없으므로 동일한 해석은 언제 어디서 실행되든 동일한 바이트를 생성합니다. plugins.governance 판정 첨부의 외부 규칙 파일은 lockfile의 verdict_inputs에 다이제스트로 기록되며, plugins.linter 첨부의 규칙 입력은 어느 파일에도 기록되지 않습니다. 빌드가 바이트 단위로 재현하는 모든 것은 대신 lockfile에 고정됩니다. 판정 첨부는 렌더링된 출력에 아무 영향도 주지 않으므로 그 식별 정보는 lockfile이 아니라 여기에 기록됩니다. 스키마 진화 원칙: 새 최상위 섹션 추가는 SemVer-MINOR(추가적 변경)이고, 기존 섹션 안에 새 필드 추가는 SemVer-MINOR이며, 키 제거나 제약 강화는 SemVer-MAJOR입니다.
최상위 타입: object
속성
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
plugins | object[] | 아니요 | 판정을 반환하는 연결마다 신뢰되는 플러그인당 하나의 레코드이며, 플러그인의 식별 좌표로 주소가 지정됩니다. 두 판정 역할에 동시에 연결된 플러그인(ir-verdict와 render-verdict에 모두 바인딩된 동일한 거버넌스 플러그인)은 레코드 하나만 남깁니다. 기록되는 대상은 연결이 아니라 플러그인의 식별 정보이며, 두 연결은 같은 아티팩트를 읽기 때문입니다. 레코드는 좌표의 오름차순으로 출력됩니다. 기본값: [] |
version | const 1 | 예 | 신뢰 레코드 스키마 버전: 1. 스키마에 SemVer-MAJOR 변경이 있으면 이 값이 증가합니다. 상수: 1 |
추가 속성은 허용되지 않습니다.
plugins-trust.plugins[]
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
deprecation | object | 아니요 | digest가 가리키는 아티팩트에서 서명되고 신뢰되는 마커가 발견되었을 때 기록되는, 검증된 소급 지원 중단 마커입니다. 마커는 지원 중단 대상 아티팩트를 가리키는 서명된 OCI referrer로, 아티팩트를 다시 게시하지 않고 게시 후에 첨부됩니다. 따라서 이미 여기에 기록된 플러그인도 나중에 지원 중단될 수 있으며, 철회 등급인 retracted 심각도에서는 아티팩트가 단순히 권장되지 않는 데 그치지 않고 선택 대상에서 제외됩니다. 이는 두 번째 식별 정보가 아니라 이 레코드가 이미 가리키는 아티팩트에 관한 사실이며, 그렇기 때문에 aggrega pull은 resolved_version과 digest를 그대로 둔 채 마커를 추가할 수 있습니다. 마커를 기록해도 아무것도 채택되지 않습니다. 마커는 해석된 다이제스트가 이미 기록된 다이제스트와 같을 때만 기록됩니다. 다른 바이트를 보고하는 해석은 식별 정보의 변경이며, 이 레코드 자체의 규칙을 따르고 실행이 요청하지 않는 한 거부됩니다. 기록된 마커를 지우는 방법은 없습니다. 마커는 그것을 담은 레코드와 함께, 해당 레코드를 교체하거나 삭제하는 명시적 업그레이드 시에만 제거됩니다. aggrega build, aggrega lint --release, aggrega validate --release, 그리고 aggrega serve와 aggrega mcp를 통해 실행되는 동일한 작업은 마커가 있는 플러그인을 이름으로 알립니다. 그렇지 않으면 지원 중단된 게이트가 아무 안내 없이 가져와지고, 캐시되고, 실행되기 때문입니다. 빌드가 이 마커로 중단될지 단순히 안내만 받을지는 워크스페이스의 build.halt_on_deprecated_severity 설정이 결정합니다. |
plugin | string | 예 | 플러그인의 식별 좌표로, governance/aggrega-security-baseline처럼 소켓 세그먼트와 단순 이름을 슬래시로 연결한 것입니다. 단순 이름은 해당 소켓 안에서만 고유하므로, 서로 다른 소켓에 있는 같은 이름의 두 플러그인은 소켓 세그먼트로 구별됩니다. 좌표에는 의도적으로 버전이 포함되지 않습니다. 그렇기 때문에 버전 변경이 관련 없는 레코드가 아니라 아래 resolved_version의 수정으로 드러납니다. |
resolved_version | string | 예 | 레코드가 작성될 때 이 플러그인에 대해 선택된 구체적인 버전입니다(예: 1.2.3). 단일 경로 세그먼트로 기록되므로 /, \, ..를 포함하지 않습니다. 패턴: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | 예 | 해석된 플러그인 아티팩트의 콘텐츠 다이제스트로, sha256: 뒤에 소문자 16진수 64자가 오는 형식입니다. 이는 콘텐츠 주소가 비교되는 모든 곳에서 사용되는 형식입니다. 패턴: ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | 아니요 | aggrega pull이 digest가 가리키는 아티팩트에 대해 이 플러그인 자체의 서명을 해석 레지스트리의 신뢰 정책에 따라 검증했을 때 기록되는 검증된 서명 사실입니다. pull은 이러한 연결 중 하나를 위해 해석하는 모든 플러그인의 서명을 매 실행마다 검증하고, 발견한 내용을 여기에 기록합니다. 이때 레코드가 담고 있던 내용을 교체하며, 검증된 서명이 없으면 제거합니다. 이 과정에서 레코드가 검사 기준으로 삼는 식별 정보는 변경되지 않습니다. 빌드, 릴리스 범위 lint 또는 릴리스 범위 검증이 플러그인을 실행하기 전에, 이 사실이 가리키는 캐시된 서명 번들을 다시 해시하며 blob이 없거나 다르면 실행이 중단됩니다. 또한 콘텐츠 캐시에서 읽은 플러그인의 경우, 실행은 그 번들에서 서명이 어떤 아티팩트에 대해 만들어졌는지 읽고, 읽은 플러그인과 다른 아티팩트에 대해 만들어졌으면 중단됩니다. 따라서 다른 플러그인의 항목에서 복사한 signature는 서명 요구 사항과 관계없이 거부됩니다. 이 단계에서는 서명을 검증하지 않으므로, 이 플러그인 자체의 아티팩트에 맞추어 수동으로 캐시에 기록한 번들은 pull이 검증한 번들과 구별되지 않습니다. 그리고 워크스페이스의 신뢰 구성이 콘텐츠 캐시에서 읽은 플러그인에 서명을 요구하는 경우(aggrega pull이 플러그인을 검증할 때 적용하는 요구 사항이므로, pull이 서명을 기록하지 않아도 되게 하는 건너뛰기 설정과 advisory 레지스트리는 실행도 계속 진행되게 합니다), 해당 플러그인에 대한 signature가 없는 레코드나 해당 플러그인에 대한 항목이 아예 없는 레코드는 실행을 중단시키며, 플러그인과 서명을 요구하는 설정의 이름을 알립니다. 카탈로그 디렉터리나 컴파일러 바이너리 내부의 사본에서 읽은 플러그인에는 이 요구 사항이 적용되지 않습니다. |
추가 속성은 허용되지 않습니다.
plugins-trust.plugins[].deprecation
digest가 가리키는 아티팩트에서 서명되고 신뢰되는 마커가 발견되었을 때 기록되는, 검증된 소급 지원 중단 마커입니다. 마커는 지원 중단 대상 아티팩트를 가리키는 서명된 OCI referrer로, 아티팩트를 다시 게시하지 않고 게시 후에 첨부됩니다. 따라서 이미 여기에 기록된 플러그인도 나중에 지원 중단될 수 있으며, 철회 등급인 retracted 심각도에서는 아티팩트가 단순히 권장되지 않는 데 그치지 않고 선택 대상에서 제외됩니다. 이는 두 번째 식별 정보가 아니라 이 레코드가 이미 가리키는 아티팩트에 관한 사실이며, 그렇기 때문에 aggrega pull은 resolved_version과 digest를 그대로 둔 채 마커를 추가할 수 있습니다. 마커를 기록해도 아무것도 채택되지 않습니다. 마커는 해석된 다이제스트가 이미 기록된 다이제스트와 같을 때만 기록됩니다. 다른 바이트를 보고하는 해석은 식별 정보의 변경이며, 이 레코드 자체의 규칙을 따르고 실행이 요청하지 않는 한 거부됩니다. 기록된 마커를 지우는 방법은 없습니다. 마커는 그것을 담은 레코드와 함께, 해당 레코드를 교체하거나 삭제하는 명시적 업그레이드 시에만 제거됩니다. aggrega build, aggrega lint --release, aggrega validate --release, 그리고 aggrega serve와 aggrega mcp를 통해 실행되는 동일한 작업은 마커가 있는 플러그인을 이름으로 알립니다. 그렇지 않으면 지원 중단된 게이트가 아무 안내 없이 가져와지고, 캐시되고, 실행되기 때문입니다. 빌드가 이 마커로 중단될지 단순히 안내만 받을지는 워크스페이스의 build.halt_on_deprecated_severity 설정이 결정합니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
message | string | 예 | 마커에 담긴 사람이 읽을 수 있는 지원 중단 메시지로, 일반적으로 마이그레이션 안내입니다. 마커에 별도의 메시지가 없으면 대신 그 사유가 여기에 기록되므로, 보고되는 문장이 비어 있는 경우는 없습니다. |
severity | string (enum) | 예 | 마커 심각도로, warning < error < retracted 순서입니다. 이 심각도가 구성된 중단 임계값 이상이면 빌드가 중단되고, 그렇지 않으면 안내만 받습니다. 이는 다른 모든 지원 중단 보고가 읽는 것과 같은 규칙과 같은 설정입니다. retracted는 철회 등급으로, 이 심각도의 아티팩트는 선택 대상에서 제외되며 두 안내 심각도는 아티팩트를 선택 가능한 상태로 둡니다. 허용 값: "warning", "error", "retracted" |
추가 속성은 허용되지 않습니다.
정의
VerifiedSignature
pull이 확인 중인 레지스트리의 신뢰 정책에 대해 아티팩트의 서명을 검증할 때 기록하는 검증된 서명 정보입니다. 두 레코드, 즉 lockfile의 각 항목과 이 레코드의 각 플러그인이 이 정보에 사용하는 단 하나의 형태이므로, 검증된 서명은 어느 파일에서든 동일하게 읽힙니다. 검증 모드, 일치한 keyless 아이덴티티/발급자(keyless인 경우) 또는 고정된 키의 지문(keyed인 경우), 그리고 pull이 캐시한 서명 번들의 콘텐츠 주소 다이제스트를 기록합니다.
| 속성 | 타입 | 필수 | 설명 |
|---|---|---|---|
bundle_digest | string | 예 | 캐시된 서명 번들 blob의 SHA-256 다이제스트로, sha256: 뒤에 소문자 16진수 64자가 오는 형식입니다. 이 값은 캐시 blob의 이름이 되어 경로를 구성하므로 /, \, ..를 포함하지 않으며(sha256: 형식이 이미 이를 배제합니다), 빌드, 릴리스 범위의 lint, 릴리스 범위의 validation이 해당 blob을 다시 해시하여 비교하는 기준이 됩니다. 패턴: ^sha256:[a-f0-9]{64}$. |
identity | string | 아니요 | 서명의 검증된 서명자입니다. keyless 서명의 경우 서명 인증서의 subject이고, keyed 서명의 경우 keyed:sha256: 뒤에 고정된 공개 키 PEM 텍스트의 SHA-256이 오는 값입니다. |
issuer | string | 아니요 | keyless 서명에 대해 검증된 OIDC 발급자입니다. keyed 서명의 경우 비어 있습니다. |
mode | string (enum) | 예 | 서명을 허용한 검증 모드입니다. 허용되는 값: "keyless", "keyed" |
추가 속성은 허용되지 않습니다.