Schema bản ghi tin cậy Plugin của Aggrega
Tài liệu tham khảo được sinh tự động. Không chỉnh sửa thủ công — hãy sinh lại từ JSON Schema đã xuất bản.
Id lược đồ: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json
Bản ghi do máy sinh ra về danh tính plugin được tin cậy cho mỗi attachment trả về phán quyết chấp nhận hoặc từ chối — một attachment plugins.governance ở vai trò ir-verdict hoặc render-verdict, và mọi attachment plugins.linter. Nằm tại plugins-trust.yaml bên cạnh lockfile và được commit cùng với nó, vì một bản ghi nằm ngoài hệ thống quản lý phiên bản là bản ghi không ai có thể xem xét và không gì có thể đối chiếu. Được ghi bởi aggrega pull, lệnh này tạo tệp vào lần đầu tiên nó phân giải một trong các attachment đó và thêm một bản ghi cho mỗi attachment khi phân giải nó. Một tệp chỉ chứa bản ghi cho một số attachment đã cấu hình là một trạng thái trung gian hợp lệ chứ không phải trạng thái hỏng. Được đọc bởi aggrega build, bởi aggrega lint --release và bởi aggrega validate --release, và bởi cùng các thao tác đó khi gọi qua aggrega serve và aggrega mcp; mỗi thao tác đối chiếu cấu hình workspace với bản ghi trước khi bất kỳ attachment nào trong số đó chạy. Hai loại bất đồng bị từ chối, vì những lý do khác nhau: một plugin có digest artifact đã phân giải không phải là digest được ghi cho nó sẽ bị từ chối thay vì được chạy, vì plugin sắp chạy không phải là plugin mà bản ghi đã được xem xét; và một mục bản ghi không được attachment phán quyết nào đã cấu hình giải thích sẽ dừng lần chạy, vì việc bỏ một cổng kiểm soát không thay đổi byte nào được render, nên đầu ra tạo ra mà thiếu một cổng đã được xem xét không thể phân biệt với đầu ra mà cổng đó đã chấp thuận. Một lần build, một lần lint theo phạm vi release và một lần validate theo phạm vi release — từ dòng lệnh, qua aggrega serve hoặc qua aggrega mcp — cũng đối chiếu mỗi plugin trong số đó mà chúng đọc từ bộ nhớ đệm nội dung với signature mà bản ghi của nó mang, khi nạp plugin, giống như một lần build đối chiếu mọi mục lockfile với chữ ký mà mục đó mang: xem signature bên dưới. Chiều ngược lại — một attachment đã cấu hình mà bản ghi chưa chứa — là trạng thái trung gian vừa mô tả và không phép so sánh nào từ chối nó, và một bản ghi không tồn tại thì không chứa mục nào, nên nó không ghim gì và không phép so sánh nào từ chối điều gì vì nó; yêu cầu chữ ký là ràng buộc duy nhất mà một mục bị thiếu không tránh được, như signature bên dưới mô tả. Một mục chỉ rời khỏi bản ghi khi nâng cấp tường minh: aggrega pull --upgrade nêu tên một plugin sẽ bỏ mục của plugin đó khi không còn attachment phán quyết nào nêu tên nó, và aggrega pull --upgrade không kèm đối số sẽ bỏ mọi mục như vậy. Một lệnh aggrega pull thông thường không phân giải lại danh tính của một mục cũng không xóa mục đó, nên việc dừng do một mục không được gì giải thích chỉ được gỡ bỏ bằng cách chủ ý tuyên bố như vậy chứ không phải bởi lần chạy tiếp theo. Một bản ghi có mục cuối cùng bị bỏ sẽ được làm rỗng chứ không bị xóa, và một bản ghi rỗng là hợp lệ: nó không chứa gì, nên không ghim gì và không phép so sánh nào từ chối điều gì vì nó, giống hệt một bản ghi không tồn tại. Mỗi bản ghi được định địa chỉ bằng tọa độ danh tính riêng của plugin và mang phiên bản đã chọn cùng digest artifact dưới dạng trường, nên một thay đổi phiên bản là thay đổi một trường của bản ghi hiện có chứ không phải một bản ghi mới dưới địa chỉ mới — đó là điều giúp một plugin được đổi phiên bản phân biệt được, trong tệp và trong diff của nó, với một plugin được ghi lần đầu. Ngoài danh tính đó, một bản ghi mang hai thông tin về artifact mà nó nêu tên, mỗi thông tin chỉ được ghi khi đã được xác minh: thông báo ngừng hỗ trợ mà nhà phát hành đã gắn vào artifact, khi tìm thấy và chữ ký của nó đã được xác minh, và thông tin chữ ký đã xác minh mà aggrega pull ghi lại khi xác minh chữ ký riêng của plugin — cùng thông tin đó, dưới cùng khóa đó, mà một mục lockfile mang. Mỗi thông tin là một sự thật về artifact được ghi chứ không phải một danh tính thứ hai, đó là lý do một lần pull thông thường ghi lại nó mà không làm xáo trộn danh tính mà bản ghi được đối chiếu. Ngoài những thứ đó, tệp không ghi gì khác: không có chữ ký trên chính tệp, không có đầu vào quy tắc, không có nguồn gốc phân giải — không có máy chủ registry, không có đường dẫn trên máy đã ghi nó — và không có dấu thời gian, nên cùng một lần phân giải tạo ra cùng các byte ở bất cứ đâu và bất cứ khi nào nó chạy. Các tệp quy tắc bên ngoài của một attachment phán quyết plugins.governance được ghi dưới dạng digest trong verdict_inputs của lockfile; đầu vào quy tắc của một attachment plugins.linter không được ghi trong tệp nào. Mọi thứ mà một lần build tái tạo y nguyên từng byte được ghim trong lockfile; một attachment phán quyết không định hình phần nào của đầu ra được render, đó là lý do danh tính của nó được ghi ở đây thay vì ở đó. Nguyên tắc tiến hóa lược đồ: thêm một phần cấp cao nhất mới là SemVer-MINOR (bổ sung); thêm một trường mới bên trong một phần hiện có là SemVer-MINOR; xóa một khóa hoặc thắt chặt một ràng buộc là SemVer-MAJOR.
Kiểu cấp cao nhất: object
Thuộc tính
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
plugins | object[] | không | Mỗi plugin được tin cậy cho một attachment trả về phán quyết có một bản ghi, được định địa chỉ bằng tọa độ định danh của plugin. Một plugin được gắn ở hai vai trò phán quyết cùng lúc — cùng một plugin governance được gắn với cả ir-verdict và render-verdict — chỉ đóng góp một bản ghi duy nhất, vì đối tượng được ghi nhận là định danh của plugin chứ không phải attachment: hai attachment đọc cùng một artifact. Các bản ghi được xuất theo thứ tự tọa độ tăng dần. Mặc định: [] |
version | const 1 | có | Phiên bản schema của bản ghi tin cậy: 1. Một thay đổi SemVer-MAJOR đối với schema sẽ tăng giá trị này. Hằng số: 1 |
Không cho phép thuộc tính bổ sung.
plugins-trust.plugins[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
deprecation | object | không | Dấu hiệu ngừng hỗ trợ hồi tố đã được xác minh, được ghi lại khi phát hiện một dấu hiệu đã ký và đáng tin cậy trên artifact mà digest chỉ định. Một dấu hiệu là một OCI referrer đã ký của artifact mà nó ngừng hỗ trợ, được gắn sau khi xuất bản mà không cần xuất bản lại artifact, nên một plugin đã được ghi lại ở đây vẫn có thể bị ngừng hỗ trợ về sau — ở mức độ retracted, tức là cấp thu hồi, điều đó có nghĩa là artifact bị loại khỏi việc lựa chọn chứ không chỉ đơn thuần là không được khuyến khích. Đây là một dữ kiện về artifact mà bản ghi này đã định địa chỉ chứ không phải một định danh thứ hai, và đó là điều cho phép aggrega pull thêm nó trong khi vẫn giữ nguyên resolved_version và digest: việc ghi lại nó không chấp nhận thêm gì. Nó chỉ được ghi lại khi digest đã phân giải bằng với digest đã được ghi — một lần phân giải báo cáo các byte khác là một thay đổi về định danh, chịu sự điều chỉnh của quy định riêng của bản ghi này và bị từ chối trừ khi lần chạy yêu cầu điều đó. Không gì xóa được một dấu hiệu đã ghi; nó chỉ rời đi cùng với bản ghi chứa nó, trong lần nâng cấp tường minh thay thế hoặc loại bỏ bản ghi đó. aggrega build, aggrega lint --release và aggrega validate --release, cùng các thao tác tương tự được gọi qua aggrega serve và aggrega mcp, nêu tên một plugin mang dấu hiệu như vậy, vì nếu không, một cổng đã ngừng hỗ trợ sẽ được tải về, lưu vào bộ nhớ đệm và chạy mà không có thông báo nào, và tùy chọn build.halt_on_deprecated_severity của workspace quyết định liệu một bản build dừng lại vì nó hay chỉ nhận cảnh báo. |
plugin | string | có | Tọa độ định danh của plugin: phân đoạn socket và tên trần của nó được nối bằng dấu gạch chéo, như trong governance/aggrega-security-baseline. Một tên trần chỉ là duy nhất trong socket của nó, nên phân đoạn socket là thứ phân biệt hai plugin cùng tên ở các socket khác nhau. Tọa độ cố ý không mang phiên bản — đó là điều khiến một thay đổi phiên bản hiển thị như một chỉnh sửa đối với resolved_version bên dưới chứ không phải như một bản ghi không liên quan. |
resolved_version | string | có | Phiên bản cụ thể được chọn cho plugin này khi bản ghi được viết (ví dụ 1.2.3). Được ghi dưới dạng một phân đoạn đường dẫn duy nhất, nên nó không chứa /, \ hay ... Mẫu: ^([^/\\.]|\.[^/\\.])*\.?$. |
digest | string | có | Digest nội dung của artifact plugin đã phân giải, ở dạng sha256: theo sau là 64 ký tự hex chữ thường — dạng mà địa chỉ nội dung được viết ở mọi nơi nó được so sánh. Mẫu: ^sha256:[a-f0-9]{64}$. |
signature | VerifiedSignature | không | Dữ kiện chữ ký đã xác minh, được ghi lại khi aggrega pull xác minh chữ ký riêng của plugin này theo chính sách tin cậy của registry phân giải, cho artifact mà digest chỉ định. Một lần pull xác minh chữ ký của mọi plugin mà nó phân giải cho một trong các attachment này, ở mọi lần chạy, và ghi lại những gì tìm thấy ở đây — thay thế những gì bản ghi đang giữ, và xóa nó khi lần pull không xác minh được chữ ký nào — mà không làm xáo trộn định danh mà bản ghi được đối chiếu. Trước khi một bản build, một lần lint theo phạm vi release hoặc một lần xác thực theo phạm vi release chạy plugin, gói chữ ký trong bộ nhớ đệm mà dữ kiện này chỉ định được băm lại, và lần chạy dừng lại nếu blob bị thiếu hoặc khác biệt; và với một plugin được đọc từ bộ nhớ đệm nội dung, lần chạy đọc từ gói đó xem chữ ký được tạo cho artifact nào, và dừng lại nếu nó được tạo cho một artifact khác với plugin đã đọc — nên một signature được sao chép từ mục của plugin khác sẽ bị từ chối, bất kể yêu cầu ký nói gì. Không có chữ ký nào được xác minh ở đó, nên một gói được ghi thủ công vào bộ nhớ đệm, được lập cho chính artifact của plugin này, không được phân biệt với một gói mà lần pull đã xác minh. Và khi cấu hình tin cậy của workspace yêu cầu chữ ký cho một plugin được đọc từ bộ nhớ đệm nội dung — yêu cầu mà aggrega pull áp dụng khi xác minh plugin, nên các trường hợp bỏ qua và một registry advisory cho phép lần pull không ghi lại chữ ký nào cũng cho phép lần chạy tiếp tục — một bản ghi không mang signature cho plugin đó, hoặc hoàn toàn không có mục nào cho nó, sẽ dừng lần chạy, nêu tên plugin và các thiết lập yêu cầu chữ ký. Một plugin được đọc từ thư mục catalog hoặc từ bản sao bên trong tệp nhị phân của trình biên dịch không bao giờ phải tuân theo yêu cầu đó. |
Không cho phép thuộc tính bổ sung.
plugins-trust.plugins[].deprecation
Dấu hiệu ngừng hỗ trợ hồi tố đã được xác minh, được ghi lại khi phát hiện một dấu hiệu đã ký và đáng tin cậy trên artifact mà digest chỉ định. Một dấu hiệu là một OCI referrer đã ký của artifact mà nó ngừng hỗ trợ, được gắn sau khi xuất bản mà không cần xuất bản lại artifact, nên một plugin đã được ghi lại ở đây vẫn có thể bị ngừng hỗ trợ về sau — ở mức độ retracted, tức là cấp thu hồi, điều đó có nghĩa là artifact bị loại khỏi việc lựa chọn chứ không chỉ đơn thuần là không được khuyến khích. Đây là một dữ kiện về artifact mà bản ghi này đã định địa chỉ chứ không phải một định danh thứ hai, và đó là điều cho phép aggrega pull thêm nó trong khi vẫn giữ nguyên resolved_version và digest: việc ghi lại nó không chấp nhận thêm gì. Nó chỉ được ghi lại khi digest đã phân giải bằng với digest đã được ghi — một lần phân giải báo cáo các byte khác là một thay đổi về định danh, chịu sự điều chỉnh của quy định riêng của bản ghi này và bị từ chối trừ khi lần chạy yêu cầu điều đó. Không gì xóa được một dấu hiệu đã ghi; nó chỉ rời đi cùng với bản ghi chứa nó, trong lần nâng cấp tường minh thay thế hoặc loại bỏ bản ghi đó. aggrega build, aggrega lint --release và aggrega validate --release, cùng các thao tác tương tự được gọi qua aggrega serve và aggrega mcp, nêu tên một plugin mang dấu hiệu như vậy, vì nếu không, một cổng đã ngừng hỗ trợ sẽ được tải về, lưu vào bộ nhớ đệm và chạy mà không có thông báo nào, và tùy chọn build.halt_on_deprecated_severity của workspace quyết định liệu một bản build dừng lại vì nó hay chỉ nhận cảnh báo.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
message | string | có | Thông điệp ngừng hỗ trợ dễ đọc do dấu hiệu mang theo — thường là một chỉ dẫn di chuyển. Khi dấu hiệu không mang thông điệp riêng, lý do của nó được ghi ở đây thay thế, nên câu được báo cáo không bao giờ trống. |
severity | string (enum) | có | Mức độ của dấu hiệu, theo thứ tự warning < error < retracted. Một bản build dừng lại khi mức độ này bằng hoặc vượt ngưỡng dừng đã cấu hình, và chỉ nhận cảnh báo trong trường hợp ngược lại — cùng quy định và cùng tùy chọn mà mọi báo cáo ngừng hỗ trợ khác đọc. retracted là cấp thu hồi: một artifact ở mức độ đó bị loại khỏi việc lựa chọn, trong khi hai mức độ cảnh báo vẫn để nó có thể được chọn. Giá trị cho phép: "warning", "error", "retracted" |
Không cho phép thuộc tính bổ sung.
Định nghĩa
VerifiedSignature
Dữ kiện chữ ký đã xác minh mà một lần pull ghi lại khi nó xác minh chữ ký của một artifact theo chính sách tin cậy của registry phân giải. Đây là cấu trúc duy nhất mà cả hai bản ghi dùng cho dữ kiện này — lockfile, trên từng mục của nó, và bản ghi này, trên từng plugin — nên một chữ ký đã xác minh được đọc giống nhau trong cả hai tệp. Ghi lại chế độ xác minh, danh tính/issuer keyless đã khớp (khi là keyless) hoặc dấu vân tay của khóa được ghim (khi dùng khóa), và digest định địa chỉ theo nội dung của gói chữ ký mà lần pull đã lưu vào bộ nhớ đệm.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
bundle_digest | string | có | Digest SHA-256 của blob gói chữ ký đã lưu trong bộ nhớ đệm, ở dạng sha256: theo sau là 64 ký tự hex chữ thường. Nó đặt tên cho blob trong bộ nhớ đệm, nên nó tạo nên một đường dẫn và không chứa /, \ hay .. — những thứ mà dạng sha256: vốn đã loại trừ — và đây là giá trị mà một bản build, một lần lint theo phạm vi release và một lần xác thực theo phạm vi release dùng để băm lại blob đó và đối chiếu. Mẫu: ^sha256:[a-f0-9]{64}$. |
identity | string | không | Bên ký đã được xác minh của chữ ký: subject của chứng chỉ ký đối với chữ ký keyless, hoặc keyed:sha256: theo sau là SHA-256 của văn bản PEM của khóa công khai đã ghim đối với chữ ký keyed. |
issuer | string | không | Bên phát hành OIDC đã được xác minh đối với chữ ký keyless. Để trống đối với chữ ký keyed. |
mode | string (enum) | có | Chế độ xác minh đã chấp nhận chữ ký. Giá trị cho phép: "keyless", "keyed" |
Không cho phép thuộc tính bổ sung.