Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Một chính sách dựa trên đúng một lá mà tác giả đã viết

Ví dụ này dạy một quy định nội bộ và sự thật khiến nó có thể diễn đạt được:

Một khe thông tin xác thực có thể được điền. Nó không được điền bằng cách viết dữ liệu bí mật vào chính mã nguồn của workspace.

Hai bản phát hành, chỉ khác nhau một biến: cùng một cơ sở dữ liệu được quản lý, cùng một khe thông tin xác thực bắt buộc, được điền bởi hai Features khác nhau — một do nhà phát triển gắn trong Aggregate, một do người vận hành gắn trong Release. Một chính sách do người vận hành viết từ chối cái này và cho phép cái kia. Điều khiến cặp này đáng chạy là cả hai lần gắn đều xử lý dữ liệu bí mật — vì vậy quy định không thể được viết dựa trên câu hỏi “lần gắn này có nhạy cảm không?”, và chính sách đối chứng bên dưới cho thấy điều gì xảy ra khi bạn thử làm vậy.

Mọi thứ, trừ hai tệp chính sách, đều đến từ catalog thư viện chuẩn, kể cả thực thể Plugin quản trị.

Slot, và hai Features có thể lấp đầy nó

core/datastore/mariadb khai báo một slot thông tin xác thực bắt buộc:

featuresSchema:
root_password:
required: true
sensitive: true
inject: []
description: Root database password. Recipe controls delivery (Black-Box).

sensitive: true ở đó là một khẳng định về điểm liên kết chứ không về một cách lấp đầy cụ thể nào: bất cứ thứ gì liên kết với slot này đều xử lý dữ liệu bí mật. inject: [] đóng việc phân phối — Recipe quyết định thông tin xác thực đi đến đâu, và nhà phát triển không áp đặt điều đó.

Hai Features của thư viện chuẩn liên kết với slot đó, và chúng mô hình hóa hai vòng đời thông tin xác thực trái ngược nhau:

Featureai sở hữu dữ liệu bí mậtmột attachment viết những gì
core/secret-valuemột tác giả cung cấp nóhai leaf values — xem bên dưới
core/generated-secretengine đích cấp phát và xoay vòng nókhông gì cả; nó không khai báo values nào

core/secret-value khai báo hai leaf của nó một cách bất đối xứng, và sự bất đối xứng đó chính là điểm then chốt của toàn bộ ví dụ này:

values:
origin: { type: string, sensitive: true }
key: { type: string, required: true, default: "value" }

origin mang dữ liệu bí mật và được khai báo là nhạy cảm. key là một tên phân phối và được cố ý để không đánh dấu — một key đặt tên cho nơi dữ liệu bí mật nằm chứ không phải bản thân dữ liệu đó, và mọi Recipe triển khai Feature này đều kết xuất nó ở dạng rõ.

core/generated-secret hoàn toàn không khai báo values, nên không có gì để một attachment viết. Nó là đối tác do engine quản lý chứ không phải một phiên bản yếu hơn của cùng một thứ: nó mang cùng nhãn họ thông tin xác thực, nó liên kết với cùng slot, và các Recipes của nó không kết xuất gì, vì thông tin xác thực thuộc về engine mà chính Recipe của component quản lý.

Hai bản phát hành

aggregate-authored.yaml ràng buộc slot theo cách do tác giả cung cấp: nhà phát triển gắn thông tin xác thực trong Aggregate, và phần gắn kèm viết cả hai lá:

features:
root_password:
type: core/secret-value
values:
key: MARIADB_ROOT_PASSWORD
origin: root-password-in-the-clear

Nhánh ủy quyền ràng buộc slot theo cách do engine quản lý, và việc ràng buộc đó thuộc về người vận hành: engine có sở hữu thông tin xác thực hay không là do Recipe mà Manifest chọn quyết định, vì vậy release-delegated.yaml gắn core/generated-secret vào mục của nó cho db, và aggregate-delegated.yaml là Aggregate đã viết nhưng không có khối features::

components:
db:
features:
root_password:
type: core/generated-secret

Cả hai bản phát hành dùng chung manifest.yaml, tệp ràng buộc cả ba kiểu cho target Terraform, nên Manifest không phải là chỗ hai bản khác nhau:

components:
type:
core/datastore/mariadb:1.0.0: terraform/mariadb-rds:1.0.0
features:
type:
core/secret-value:1.0.0: terraform/variable-secret:1.0.0
core/generated-secret:1.0.0: terraform/generated-secret:1.0.0

Chính sách

policy.rego, được gắn trên đồ thị build:

package house.governance
import rego.v1
deny contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some attachment_name, attachment in attachments
some leaf in attachment.sensitive_payload_leaves
msg := sprintf("%v: the %v credential carries declared-sensitive material in its payload at %v", [node_id, attachment_name, leaf])
}

sensitive_payload_leaves liệt kê các lá mà payload của lần gắn này mang có đường dẫn được Feature được gắn khai báo là nhạy cảm, mỗi lá dưới dạng một đường dẫn phân cách bằng dấu chấm có tiền tố trụ cột. Payload được đọc là payload mà lần gắn rốt cuộc mang, nên một lá nằm ở một giá trị mà schema của Feature khai báo là default cũng được nêu tên cùng với một lá do tác giả viết tại đó. Có hai hệ quả, và ví dụ xoay quanh cả hai:

  • Một lá chỉ xuất hiện ở nơi có một khai báo bao phủ nó — khai báo nêu tên lá đó, hoặc nêu tên một đối tượng chứa nó, được so khớp theo từng đoạn trên đường dẫn phân cách bằng dấu chấm. Không có gì được đọc từ chính văn bản của đường dẫn và không giá trị nào được kiểm tra. Vì vậy key, được viết bên cạnh origin trong cùng lần gắn, không bao giờ xuất hiện: Feature của nó không khai báo gì về nó.
  • Một lần gắn có payload không mang gì tại một lá đã khai báo thì không đóng góp gì vào danh sách. Lần gắn của release ủy quyền mang câu trả lời cho toàn bộ lần gắn và hoàn toàn không có danh sách theo từng lá, vì khóa bị lược khỏi dữ liệu truyền đi khi nó rỗng.

Lần gắn nằm trong .aggrega-config.yaml ở vai trò ir-verdict, là vai trò nhận đồ thị build:

plugins:
governance:
- uri: governance/rego:0.9.0
role: ir-verdict
with:
sources:
- policy.rego

Một vai trò phán quyết chỉ trả về chấp nhận hoặc từ chối và không gì khác. Nó có thể dừng lần build này; nó không thể viết lại Aggregate cho tuân thủ, vì đường thực thi phát đi một phán quyết không có cách nào áp dụng phán quyết đó như một thay đổi. Một Release muốn có dạng ủy quyền thì có được nó bằng cách gắn Feature ủy quyền — không bao giờ bằng việc một chính sách âm thầm thay thế.

Build cả hai

Terminal window
aggrega build --release release-negative-authored.yaml --auto-pull # expected to fail
aggrega build --release release-delegated.yaml --auto-pull

--auto-pull điền lockfile trong quá trình build; chạy aggrega pull --release release-<arm>.yaml một lần trước đó cũng làm điều tương tự và cho phép các lần build sau chạy mà không cần cờ. Đầu ra được render và các lockfile là được sinh ra, không được phát hành kèm: ví dụ này commit các đầu vào của nó và sinh lại mọi thứ còn lại.

Kết quả trả về

Release do tác giả viết bị từ chối và bản build thoát với mã 1. E0005 là chẩn đoán mà một lần từ chối của policy mang theo — xem tài liệu tham khảo chẩn đoán:

[… omitted: the pull's lines — the same refusal among them — and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db: the root_password credential carries declared-sensitive material in its payload at values.origin
caused by: policy violation

Hãy đọc đường dẫn leaf. Payload của attachment mang hai giá trị; lời từ chối nêu tên values.origin và không nhắc đến values.key. Chỉ một câu đó là việc đánh dấu theo từng leaf đang làm đúng nhiệm vụ — một attachment, hai leaf của payload, một khai báo, một lần từ chối.

Lời từ chối cũng đến trước khi bất cứ thứ gì được render. Thư mục dist/infra-authored/ hoàn toàn không được tạo ra, nên không có cây artifact dở dang nào phải dọn dẹp và không có gì trên đĩa mà một bước sau có thể nhầm là output.

Release ủy quyền build thành công, thoát với mã 0 và ghi ra hai tệp. dist/infra-delegated/terraform/aggrega.modules.tf, cấu hình gốc của ranh giới:

# Root configuration for this boundary. Each component rendered here is one
# module block below, and the directory that block points at holds that
# component's own files. One configuration means one dependency graph, which is
# what lets a reference or a depends_on reach from one component to another.
module "db" {
source = "./modules/db"
}

và dist/infra-delegated/terraform/modules/db/main.tf, tệp mở đầu bằng một khối chú thích # xác định bản build, rồi chứa ràng buộc provider AWS, resource và output địa chỉ mà Recipe công bố:

terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.69"
}
}
}
resource "aws_db_instance" "db" {
identifier = "db"
engine = "mariadb"
engine_version = "11.4"
port = 3306
## ── Compute ──────────────────────────────────────────────
instance_class = "db.t3.small"
## ── Storage ──────────────────────────────────────────────
allocated_storage = 100
storage_type = "gp3"
## ── Database ─────────────────────────────────────────────
db_name = "appdb"
username = "admin"
## Black-Box: RDS manages the password via Secrets Manager.
manage_master_user_password = true
## ── HA ───────────────────────────────────────────────────
multi_az = false
## ── Backup ───────────────────────────────────────────────
backup_retention_period = 7
## ── Provider-specific overrides ──────────────────────────
}
output "address" {
value = aws_db_instance.db.address
}

manage_master_user_password = true là dạng ủy quyền xuất hiện trong output: engine giữ thông tin xác thực, và Release không nêu tên dữ liệu bí mật nào ở bất cứ đâu. Release được cho phép đã render một artifact thực sự chứ không phải vượt qua nhờ không render gì cả.

Đối chứng: thay vào đó đặt câu hỏi ở mức toàn bộ attachment

Hoán đổi nguồn được gắn trong .aggrega-config.yaml:

sources:
- policy-attachment-wide.rego

policy-attachment-wide.rego là cùng một phép duyệt nhưng dựa trên attachment.sensitive — một giá trị boolean cho toàn bộ attachment — thay vì dựa trên danh sách theo từng leaf:

deny contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some attachment_name, attachment in attachments
attachment.sensitive
msg := sprintf("%v: the %v credential handles sensitive material", [node_id, attachment_name])
}

Build lại cả hai release — và đặt lại policy.rego sau đó, vì phần còn lại của trang này giả định có nó. Giờ cả hai đều bị từ chối, với cùng một câu:

[… omitted: the pull's lines — the same refusal among them — and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db: the root_password credential handles sensitive material
caused by: policy violation

Đó không phải là quy tắc hoạt động sai — mà là quy tắc được hỏi một câu hỏi thô hơn và trả lời nó một cách chính xác. sensitive đọc những gì các thực thể khai báo: ở đây nó là true vì slot khai báo rằng bất cứ thứ gì gắn vào nó đều xử lý dữ liệu bí mật, và slot nói vậy bất kể ai lấp đầy nó. Attachment được ủy quyền không tự viết gì nhưng vẫn là sensitive, nên một quy tắc dựa trên câu trả lời đó hoàn toàn không thể phân biệt hai release. Release được ủy quyền là một bản build mà quy tắc theo từng leaf cho phép còn quy tắc ở mức toàn bộ attachment không có cách nào cho phép.

Sự kiện độ nhạy cảm thứ ba, sensitive_inject, cũng không giúp được gì: nó nêu tên các khóa phân phối có khóa provides được tham chiếu được khai báo là nhạy cảm. Ở đây slot đóng về phân phối và Feature do tác giả cung cấp không công bố trụ cột provides nào, nên trên workspace này nó không nêu tên gì cả. Trong ba sự kiện, chỉ danh sách theo từng leaf trả lời được “payload của attachment này mang dữ liệu ở đâu”, đó chính là điều mà quy tắc nội bộ quan tâm.

Để xem cả ba sự kiện cạnh nhau, cùng với dạng payload và các trường hợp mà mỗi sự kiện là câu hỏi đúng, xem các sự kiện về attachment mà một chính sách quản trị đọc. Về bản thân socket — các vai trò, mức độ nghiêm trọng của phán quyết, kênh đầu vào của người vận hành — xem socket chính sách, và về vị trí của chính sách trong sản phẩm, Quản trị và Tuân thủ.

Mục tiêu này làm lộ ra điều gì về dạng do tác giả viết

Recipe cơ sở dữ liệu được quản lý đặt chỉ thị mật khẩu được quản lý riêng của engine một cách vô điều kiện và không đọc thông tin xác thực nào được tiêm vào, nên trên mục tiêu này, nó dừng bản build ngay tại chính phần đính kèm do tác giả viết, nêu tên slot, thay vì chấp nhận dữ liệu không có chỗ nào để đưa vào. Chính sách từ chối nó trước, ở nơi nó thực sự nằm: trong một tệp mà workspace giữ dưới hệ thống quản lý phiên bản. Đó là mối quan tâm về quản trị, và đó là một vấn đề tách biệt với những gì bất kỳ Recipe nào lẽ ra đã render.

Đó cũng là lý do vì sao hai Features là ngang hàng chứ không phải các lựa chọn thay thế có vị thế ngang nhau trên mọi mục tiêu. Hãy bind Feature do tác giả cung cấp ở nơi bạn thực sự nắm giữ thông tin xác thực, và Feature do engine quản lý ở nơi mục tiêu sở hữu nó. Release do tác giả viết trong ví dụ này chính là sự không khớp mà một quy tắc nội bộ có thể phát hiện một cách máy móc.

Plugin đến từ đâu

Mọi thực thể mà workspace này sử dụng đều đến từ catalog thư viện chuẩn đã được công bố: Component, hai Features, Recipe, hai FeatureRecipes và thực thể Plugin quản trị — được đọc từ registry hub mà .aggrega-config.yaml nêu tên, hoặc từ một bản checkout của catalog (lấy ở đâu) được chỉ định bằng --catalog.

uri: governance/rego:0.9.0 gọi tên thực thể Plugin đó. Đó là một định danh: một tọa độ <pluginType>/<name> cộng với một phiên bản, và cả hai nửa đều là một phần của dạng thức. Phiên bản là phiên bản mà plugin được công bố — hub công bố nó dưới dạng oci://hub.aggrega.ai/plugin/governance/rego:0.9.0. Phiên bản tham gia vào quá trình phân giải: một attachment gọi tên một phiên bản mà không thư mục catalog nào, không registry nào và cả chính binary aggrega cũng không chứa sẽ làm dừng bản build. Binary chỉ chứa thực thể của engine ở phiên bản thuộc bản phát hành của chính nó.

Khi được build với --catalog chỉ tới một bản checkout của catalog, ví dụ này không cần gì khác: với binary aggrega của bản phát hành mà attachment nêu, vốn tự chứa thực thể Plugin, mọi thực thể được phân giải mà không cần mạng, và engine chạy là engine được biên dịch vào binary aggrega. Khi không có nó, các thực thể được đọc từ hub.aggrega.ai.

Engine Rego được biên dịch vào binary của CLI, và phiên bản của nó là bản phát hành trình biên dịch đi kèm nó. Một trình biên dịch của bản phát hành khác đọc thực thể Plugin mà attachment nêu từ hub và chạy engine được biên dịch vào chính nó: phiên bản trong attachment định danh thực thể, chứ không chọn engine.

Các tệp

  • aggregate-authored.yaml — slot root_password được gắn bằng core/secret-value trong Aggregate, với khóa phân phối và tài liệu bí mật do tác giả viết.
  • aggregate-delegated.yaml — cùng cơ sở dữ liệu đó nhưng không có attachment nào: nhà phát triển không gắn gì cả.
  • manifest.yaml — gắn kiểu component và cả hai kiểu Feature với các Recipes Terraform tương ứng. Được dùng chung cho cả hai release.
  • release-negative-authored.yaml, release-delegated.yaml — mỗi nhánh một tệp, mỗi tệp có directory: ranh giới riêng. Không có flag nào cho vị trí đầu ra, nên nếu hai release dùng chung một thư mục thì release thứ hai sẽ ghi đè release thứ nhất. release-delegated.yaml cũng gắn slot, trên mục của nó cho db, bằng core/generated-secret, không viết gì cả. Feature nào lấp slot, và trong tài liệu nào, là khác biệt duy nhất giữa hai nhánh.
  • policy.rego — quy định nội bộ, dựa trên việc đánh dấu theo từng leaf.
  • policy-attachment-wide.rego — phương án đối chứng, dựa trên câu trả lời cho toàn bộ attachment. Không được gắn theo mặc định.
  • .aggrega-config.yaml — registry mặc định và attachment governance.

Tạo ví dụ

Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.

Ghi ví dụ vào một thư mục mới đặt theo tên của nó:

Terminal window
aggrega scaffold --example policy-payload-leaf-sensitivity

Sau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:

Terminal window
cd policy-payload-leaf-sensitivity

Build

Terminal window
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1
aggrega build --release release-delegated.yaml --auto-pull # builds

Với trợ lý AI

Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.

Chỉ dùng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục Workspace chưa có thư mục `policy-payload-leaf-sensitivity`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `policy-payload-leaf-sensitivity` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `policy-payload-leaf-sensitivity` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `policy-payload-leaf-sensitivity`, `release` đặt thành `release-negative-authored.yaml`, `auto_pull` đặt thành true và `write` đặt thành true: bản dựng này được dự định là sẽ bị từ chối, vì vậy hãy đọc cho tôi lời từ chối. Tiếp theo gọi công cụ `build` theo cùng cách với `release` đặt thành `release-delegated.yaml`. Cho tôi biết bản dựng thứ hai đó đã ghi những tệp nào; chúng nằm trong `policy-payload-leaf-sensitivity/dist/`.