운영 provenance 검증 계약과 audit checkout 증거 무결성

Objective

trex-core가 운영 lifecycle을 실행하거나 특정 runtime을 선택하지 않으면서도 운영 계층이 제공한 observed target/image evidence, audit checkout 검증, PRE/POST 상태 capture와 dirty isolation 결과를 재현 가능한 형식으로 검증하게 한다. 개별 gate record는 caller evidence와 gate 직접 관측값을 구분하고 fail-closed하며, 명시적인 PRE/POST pair validator는 같은 operation의 성공 record 두 개만 immutable manifest로 결합한다. Dirty checkout 보존본은 path뿐 아니라 type·size·SHA-256 일치 여부로 무결성을 증명한다.

Scope

release_provenance_gate.py는 versioned observed evidence JSON을 입력받아 strict schema·secret 검사를 수행하고, target/image evidence를 operator_observed source로 기록한다.
Gate가 직접 관측하는 audit checkout HEAD/detached/dirty 상태, revision blob과 working-tree runtime file hash, read-only capture 결과는 caller evidence와 별도 namespace에 기록한다.
개별 record는 versioned schema, operation metadata, observed evidence, checkout/runtime/capture 결과와 gate verdict를 포함하고 checkout 밖에 exclusive-create read-only file로 저장한다.
Gate CLI는 record를 생성한 직후 raw file bytes의 SHA-256과 canonical path를 machine-readable receipt로 출력한다. 신규 pair verification CLI는 운영 계층이 보존한 PRE/POST canonical path와 expected SHA-256을 명시적으로 받아 검증한다.
Pair validator는 두 record가 같은 schema version, operation ID, instance, target kind/ID를 가지며 각각 성공한 pre/post record이고 current raw bytes가 expected SHA-256과 같을 때만 versioned immutable manifest를 생성한다.
Pair manifest는 두 input의 canonical path·verified SHA-256·phase·command class·observed image identity와 검증 시각을 저장한다. Image 변경과 command-class transition의 운영 정책은 판정하지 않는다.
Dirty isolation은 modified/untracked regular file과 symlink를 checkout 밖에 보존하고 source/copied type·size·hash와 matches를 versioned manifest에 기록한다. Source bytes를 삭제·reset·checkout하지 않는다.
Existing read-only capture allowlist, broker log 원문 비저장, actor/reason secret-like material 거부와 audit checkout 밖 output 원칙을 유지한다.
docs/operations.md는 trex-core gate가 runtime inspect나 lifecycle command를 수행하지 않으며 운영 계층이 observed evidence 생성과 non-zero 결과의 enforcement를 소유한다고 명시한다.
Repository-local tests는 정상·실패·collision·tamper 경계를 검증한다.

Constraints

모든 schema object는 아래에 명시된 key만 허용하고 unknown/duplicate key를 거부한다. sha256은 prefix 없는 lowercase 64-hex, image_id와 image_digest는 sha256:<64 lowercase hex>, revision은 lowercase 40-hex, 모든 timestamp는 UTC RFC 3339다. Record·manifest hash는 JSON 재직렬화 값이 아니라 저장된 raw file bytes를 대상으로 한다.

Observed evidence v1

Exact keys: schema_version(integer 1), target_id(non-empty string), target_kind(non-empty string), image_id, image_digest, oci_revision, observed_at.

Gate record v1

Exact top-level keys: schema_version(integer 1), timestamp_utc, actor, reason, instance, command_class, operation_id, phase(pre|post), observed_evidence, checkout, runtime_file_verification, state_capture, gate; dirty checkout이면 dirty_checkout_isolation을 추가로 허용한다.
observed_evidence: observed evidence v1 exact object에 source=operator_observed만 추가한다.
checkout: exact keys path, head_revision, detached_head, git_status_porcelain, git_clean, dirty_paths. Pair success에는 head_revision == observed_evidence.oci_revision, detached_head=true, git_clean=true, empty dirty_paths가 필요하다.
runtime_file_verification: non-empty list이며 각 item exact keys는 path, path_within_checkout, exists, current_sha256, expected_revision, expected_sha256, matches_expected_revision이다. Pair success에는 모든 boolean이 true이고 expected_revision == observed_evidence.oci_revision, 두 SHA-256이 같아야 한다.
state_capture.command_outputs: exact keys pending_slots, reconciliation_slots, queue_consumers; 각 output의 exact keys는 command, returncode, stdout, stdout_format, stderr이며 pair success에는 returncode=0이 필요하다. stdout payload의 application-owned nested key는 schema 통제 대상이 아니지만 secret sanitization 대상이다.
state_capture.broker_side_effect_logs: capture_status=captured|captured_empty이면 exact keys path, exists, capture_status, file_sha256, scanned_lines, matches; unavailable이면 exact keys path, exists, capture_status, matches; error이면 exact keys path, exists, capture_status, error_type, matches다. Pair success에는 success variant가 필요하고 matches item exact keys는 event, line_number, line_sha256이다.
gate: exact keys passed, deployment_blocked, runtime_files_verified, state_captures_succeeded, broker_log_captured. Pair success에는 각각 true,false,true,true,true가 필요하다.
Gate receipt stdout: exact JSON object schema_version(integer 1), record_path(canonical absolute path), record_sha256(raw record bytes SHA-256), gate_passed(boolean). Failure record를 정상적으로 쓴 경우에도 receipt를 출력하되 CLI는 non-zero다.

Pair manifest v1

Exact top-level keys: schema_version(integer 1), verified_at, operation_id, instance, target_kind, target_id, pre, post.
pre/post exact keys: record_path, record_sha256, phase, command_class, image_id, image_digest, oci_revision, observed_at; phase는 각 object 이름과 일치해야 한다.

Isolation manifest v1

Exact top-level keys: schema_version(integer 1), timestamp_utc, checkout_dir, isolate_dir, entries.
각 entry exact keys: path, source_type, source_size, source_sha256, copied_path, copied_type, copied_size, copied_sha256, matches. Type은 regular|symlink; symlink size/hash는 target text의 UTF-8 bytes 기준이다.
Observed evidence schema의 필수 field는 schema_version, target_id, target_kind, image_id, image_digest, oci_revision, observed_at이다. Unknown/duplicate key, 누락, 잘못된 type/형식과 secret-like material은 fail-closed한다.
schema_version은 integer 1, target field는 non-empty string, image_id와 image_digest는 lowercase sha256:<64 hex>, oci_revision은 lowercase 40-hex Git commit, observed_at은 timezone을 가진 UTC RFC 3339 timestamp다.
target_kind의 의미와 target/runtime 실재 여부는 운영 계층이 소유한다. Core는 Docker·Compose·host runtime을 선택하거나 inspect하지 않고 caller evidence를 직접 관측했다고 표시하지 않는다.
Gate는 observed oci_revision과 audit checkout HEAD가 같아야 하고 runtime file working bytes가 해당 revision Git blob과 같아야 성공한다.
Observed evidence JSON 자체의 schema·duplicate key·secret validation이 실패하면 해당 입력을 record에 복사하지 않고 record/receipt 없이 non-zero로 종료한다. Evidence validation을 통과한 뒤 checkout/runtime/capture gate가 실패하면 immutable failure record와 receipt를 남긴다.
Pair validator는 filesystem scan이나 latest-file 선택을 하지 않는다. PRE/POST canonical path와 gate receipt에서 보존한 expected SHA-256은 필수 명시 입력이며, input raw bytes를 다시 hash해 일치해야 한다.
Pair validator는 실제 deploy/restart가 수행됐는지, image 변경이 허용되는지 또는 command-class transition이 운영 정책에 맞는지 주장하지 않는다.
Legacy unversioned record를 새 pair success로 암묵 승격하지 않는다. Unsupported schema는 fail-closed한다.
Record와 manifest는 overwrite하지 않고 exclusive-create하며 성공한 write 뒤 read-only mode로 전환한다.
Dirty isolation의 hash manifest는 file content를 포함하지 않는다. Unsupported special file, checkout/symlink escape, copy/hash mismatch와 output collision은 성공으로 기록하지 않는다.
Normative Design Documents: 없음. 이 REQ와 AC-0035~AC-0037이 이번 specification의 normative behavior를 소유한다.

Non-Goals

Docker Compose/container 또는 host process 중 canonical production runtime 선택
Runtime/container/process inspect, 실제 stop/start/recreate/deploy/recovery command 실행
Lifecycle wrapper, global operation lock, stale-lock 처리와 maintenance orchestration
Audit checkout worktree 생성·교체·reset, dirty source 삭제 또는 recovery branch commit
Image transition과 command-class transition의 운영 정책 판정
Trading/domain contract, 주문 lifecycle, database schema·migration 또는 daemon composition 변경
자동 주문·취소, DB recovery, sync --live, verify --live
Production deployment, restart 또는 runtime validation 완료 주장
Registry publication, image signing, SBOM, package visibility 또는 release workflow 변경

9.4 KiB Raw Blame History

운영 provenance 검증 계약과 audit checkout 증거 무결성

Objective

Scope

Constraints

Non-Goals

9.4 KiB

Raw Blame History