NK-WP-0055-T11: proposed Audit Correlation Contract v0.1; owner scoping recorded
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Assistant: claude-code Assistant-Model: opus Assistant-Process: 4515@bnt-lap001 Assistant-Session: 0bf96127-6e04-41be-bfda-d11717c3f354
This commit is contained in:
parent
e15b61c074
commit
169c93876c
3 changed files with 90 additions and 2 deletions
|
|
@ -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 |
|
||||
|
|
|
|||
86
canon/standards/audit-correlation_v0.1.md
Normal file
86
canon/standards/audit-correlation_v0.1.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue