From 169c93876c62d2fc0d92f7c7a874d4d6e1a5ffdc Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 27 Oct 2026 22:37:43 +0100 Subject: [PATCH] NK-WP-0055-T11: proposed Audit Correlation Contract v0.1; owner scoping recorded Co-Authored-By: Claude Opus 5.5 Assistant: claude-code Assistant-Model: opus Assistant-Process: 4515@bnt-lap001 Assistant-Session: 0bf96127-6e04-41be-bfda-d11717c3f354 --- WORK-RECORDS.md | 2 +- canon/standards/audit-correlation_v0.1.md | 86 +++++++++++++++++++ ...-security-platform-production-readiness.md | 4 +- 3 files changed, 90 insertions(+), 2 deletions(-) create mode 100644 canon/standards/audit-correlation_v0.1.md diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index beee9d6..8be5a3f 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -328,7 +328,7 @@ | task | NK-WP-0055-T08 | todo | — | workplans/NK-WP-0055-security-platform-production-readiness.md | | task | NK-WP-0055-T09 | wait | — | workplans/NK-WP-0055-security-platform-production-readiness.md | | task | NK-WP-0055-T10 | done | — | workplans/NK-WP-0055-security-platform-production-readiness.md | -| task | NK-WP-0055-T11 | todo | — | workplans/NK-WP-0055-security-platform-production-readiness.md | +| task | NK-WP-0055-T11 | progress | — | workplans/NK-WP-0055-security-platform-production-readiness.md | | task | NK-WP-0055-T12 | todo | — | workplans/NK-WP-0055-security-platform-production-readiness.md | | task | NK-WP-0055-T13 | todo | — | workplans/NK-WP-0055-security-platform-production-readiness.md | | task | NK-WP-0055-T14 | todo | — | workplans/NK-WP-0055-security-platform-production-readiness.md | diff --git a/canon/standards/audit-correlation_v0.1.md b/canon/standards/audit-correlation_v0.1.md new file mode 100644 index 0000000..5159ad1 --- /dev/null +++ b/canon/standards/audit-correlation_v0.1.md @@ -0,0 +1,86 @@ +--- +id: NK-STD-AUDIT-CORRELATION +title: "Audit Correlation Contract" +version: "0.1" +status: proposed +owner: net-kingdom +created: "2026-10-27" +work: NK-WP-0055-T11 +--- + +# Audit Correlation Contract v0.1 (proposed) + +## Purpose + +This contract defines one correlation id that links the audit records of a single unit of work across all of these: + +- identity issuance; +- the authorization decision; +- secret access; +- workload enforcement. + +Without it, the architecture's onboarding audit-readiness step (`docs/platform-identity-security-architecture.md`, step 7) +cannot be tested. + +Owners: + +- **NetKingdom** owns this contract. +- **audit-core** owns the `correlation_id` envelope field (AUDIT-WP-0017-T05). +- **Each emitting service** owns its own propagation. + +## Rules + +**AC-1. Format.** `correlation_id` is the 32-character lowercase hex trace id of +[W3C Trace Context](https://www.w3.org/TR/trace-context/). An all-zero id is invalid. The value is opaque and carries no +personal data, tenant name or secret. Receivers may store other ids of up to 128 characters, but those do not satisfy this +contract. + +**AC-2. Transport.** On HTTP, the id travels in the standard `traceparent` header. The `correlation_id` is the trace-id +part of that header. There is no custom header. For non-HTTP calls (LDAP, internal queues), the emitting service records +the id it received on its inbound HTTP leg. + +**AC-3. Not a token claim.** The id is never placed in an access token, ID token or other credential. A token outlives a +unit of work, so a claim would wrongly link unrelated requests. + +**AC-4. Who sets it.** + +- The **originator of the unit of work** sets the id: the workload or the user-facing application, at the start of the + request it is serving. +- Every downstream component copies the inbound id unchanged into its audit record and into its own outbound calls. +- A component that receives no valid `traceparent` starts a new trace. It records that fact as + `correlation_origin: generated`; propagated ids are recorded as `correlation_origin: propagated`. +- `parent_event_id` is optional, and is used only when one record directly causes another. + +**AC-5. Trust.** The id is a claim made by the caller and nothing more: + +- It never influences an authentication, authorization or secret decision. +- It is not evidence of who acted. The record's authenticated subject is that evidence. +- Where a decision record is signed (access-engine FLEX-WP-0024), the signature covers the id, so the record cannot be + relinked afterwards. + +**AC-6. Per emitter.** + +| Emitter | Where it reads the id | Owner task | +|---|---|---| +| Workload / application | Generates the id, or takes it from its own inbound request | each workload owner | +| KeyCape | Inbound `traceparent` on the token and authorize endpoints | key-cape (via NK-WP-0055-T11) | +| access-engine | Inbound `traceparent` on the check APIs; copied into the decision record | FLEX-WP-0031-T11 | +| OpenBao | Audits the `traceparent` request header in plain text via `sys/config/auditing/request-headers` (`hmac: false`) and maps it on shipping | RPF-WP-0066-T02 | +| Authelia, LLDAP, privacyIDEA | Inbound `traceparent` where the service exposes it; otherwise `correlation_origin: generated` | NK-WP-0055-T11 identity intake | +| Kubernetes API audit | Not part of the chain. It keeps its own `auditID`, and k3s does not carry the id | RCLUSTER-WP-0021 | + +**AC-7. End-to-end test.** The tenant onboarding completion test (NK-WP-0055-T12) passes only when a single +`correlation_id` set by a test workload can be found in audit-core in all of these records: + +- the KeyCape issuance record; +- the access-engine decision record; +- the OpenBao audit record; +- the workload enforcement record. + +The test uses synthetic subjects only. + +## Open for owners + +- audit-core: confirm the `correlation_origin` field name and the validation for the new sources (AUDIT-WP-0017-T05). +- railiance-platform: confirm that the OpenBao version in use supports audited request headers (RPF-WP-0066-T01). +- key-cape: accept the propagation task. diff --git a/workplans/NK-WP-0055-security-platform-production-readiness.md b/workplans/NK-WP-0055-security-platform-production-readiness.md index 94117b4..16f6bf4 100644 --- a/workplans/NK-WP-0055-security-platform-production-readiness.md +++ b/workplans/NK-WP-0055-security-platform-production-readiness.md @@ -256,7 +256,7 @@ Decide what production requires: ```task id: NK-WP-0055-T11 -status: todo +status: progress priority: high assignee: claude-code state_hub_task_id: "93caa9e0-3d28-58ac-808a-47e15fe6d6ab" @@ -270,6 +270,8 @@ Topaz is not a source (ADR-0018). durably; one correlation id is defined and tested across the onboarding chain; audit-core has a recurring restore drill and AUDIT-WP-0015-T01's offsite chain head. + +2026-10-27 owner scoping (proposed workplans, unpushed in the owner repos): audit-core AUDIT-WP-0017 (`ead0f09`: intake package per sender, correlation field, quarterly restore drill, offsite chain head); railiance-platform RPF-WP-0066 (`87a488c`: file audit device plus async sidecar shipper, snapshots, live conformance); railiance-cluster RCLUSTER-WP-0021 (`3ed1ac1`: k3s audit policy, node buffer, shipper, founder-run restart); access-engine FLEX-WP-0031-T10/T11 and FLEX-WP-0039 (`7cbd4e5`). NetKingdom's part: the [Audit Correlation Contract v0.1](../canon/standards/audit-correlation_v0.1.md) (proposed) and the four identity-provider intake packages (still to draft). Noted: audit-core lists six access-engine pins, the registry has nine. ## Record live conformance receipts ```task