audit-core/INTENT.md

---
# NetKingdom Security Layer Model v0.7 (accepted) — §11 / companion §2.
# Declared by audit-core, in audit-core's own voice. Machine-readable form
# and the full conformance map: layer.yaml
layer: Engine
role: Evidence
standard: canon/standards/security-layer-model_v0.7.md
standard_version: "0.7"
declared_by: intakes/intakes.md AUDIT-IN-0001
declared_at: "2026-08-29"
---

# Audit Core Intent

## Purpose

Audit Core is the independent audit fabric for collecting, normalizing,
retaining, searching, exporting, and proving the integrity of audit events
across multi-tenant infrastructure and applications.

It exists so platforms can treat audit as a first-class product capability
rather than as an incidental log-forwarding detail. Audit Core should support
small installations that only need durable audit retention, while also scaling
toward enterprise and critical-infrastructure requirements such as tenant
isolation, immutable archive, tamper evidence, searchable investigation
workflows, retention policy, and controlled export.

Audit Core must integrate cleanly with NetKingdom, Railiance, OpenBao,
Kubernetes, identity providers, and application runtimes, but it must not depend
on NetKingdom to exist or operate.

## Layer

Audit Core is **Engine layer, role Evidence** under the NetKingdom Security
Layer Model v0.7 (`net-kingdom/canon/standards/security-layer-model_v0.7.md`,
accepted; working form `net-kingdom/SECURITY-COMPANION.md`). It exposes a
deterministic API contract over a modeled concept — the audit event — and holds
operational custody of what it accepts. Same authoritative input, same result.

**Evidence is a role, and it carries obligations the other engine roles do not:**

- Audit Core is explicitly **not a decision point** (§6). It answers what was
  recorded; it never answers whether an action is permitted, and exposes no
  surface returning such a verdict.
- An Audit Core outage **must not block the operation being recorded** (§3.3).
  v0.7 states this as a deliberate estate trade — availability of the recorded
  operation over independence of its recorder — not as a property of evidence
  engines. The consequence is accepted knowingly: a compromised source can
  suppress, and detection rather than prevention is the answer (§9.6).
  An operation whose control requirement is *independent recording before
  effect* remains raisable as a declared exception; the estate has not needed
  one, and Audit Core would want it raised rather than assumed.
- What Audit Core may **never claim** is fixed by §9.6 and restated in
  `## Evidence Bound` below.

Machine-readable declaration and the conformance map: `layer.yaml`.
Reviews: `history/2026-08-28-approval-evidence-assent.md`,
`history/2026-08-29-security-layer-model-v0.6-review.md`.

## Problem

Modern platforms generate audit-relevant events in many places:

- identity systems;
- secret managers;
- orchestration layers;
- administrative control surfaces;
- workload runtimes;
- tenant-facing applications;
- policy engines;
- backup, restore, and break-glass operations.

If these events remain scattered across local pod logs, PVCs, application
databases, shell histories, or ad hoc State Hub notes, they cannot satisfy
serious operational, forensic, or compliance needs.

The platform needs an audit system that can answer:

- who did what, when, from where, and under which authority;
- which tenant, scope, workload, system, or asset was affected;
- whether the event stream is complete enough for the configured policy;
- where the event is retained;
- who can search or export it;
- whether retained records were altered, deleted, or withheld;
- how long each class of event must be kept;
- whether a tenant has purchased or enabled each audit capability tier.

## Independence

Audit Core is a standalone product and repository.

It must not import NetKingdom internals, assume NetKingdom deployment paths, or
require NetKingdom identity in order to function. A small installation should be
able to deploy Audit Core with local configuration, static tenants, and a basic
OIDC provider.

NetKingdom integration is important, but it must happen through public,
documented contracts:

- tenant and scope registration APIs;
- issuer and identity mapping APIs;
- audit event ingestion APIs;
- retention and entitlement APIs;
- setup and validation APIs;
- export and evidence APIs;
- optional adapters for NetKingdom IAM Profile claims.

This keeps Audit Core reusable for non-NetKingdom platforms while still letting
NetKingdom provide a polished setup and operating experience.

## Product Shape

Audit Core is not just a log store. It is an audit control plane and data plane.

The control plane owns:

- tenants, scopes, sources, streams, and audit policies;
- retention profiles and cost tiers;
- ingestion credentials and source registration;
- search/export entitlements;
- archive and tamper-evidence configuration;
- setup validation and health reporting;
- integration status for upstream platforms.

The data plane owns:

- event ingestion;
- normalization to the Audit Core event envelope;
- routing to hot search, immutable archive, and optional SIEM sinks;
- buffering and retry behavior;
- batch manifests and integrity proofs;
- source-specific adapters and collectors.

## Core Principles

1. **Audit is a product boundary.** Audit Core owns audit semantics and
   retention behavior. Other systems emit events; they do not define the whole
   audit fabric.

2. **Standalone first, integrated second.** NetKingdom should be an excellent
   integration target, not a hidden prerequisite.

3. **Tenant-aware by design.** Every event must be attributable to a tenant,
   scope, source, or platform-control-plane context. Shared platform events are
   never silently downgraded to tenant-owned optional audit.

4. **Policy before plumbing.** A source is not "onboarded" merely because logs
   arrive. It is onboarded when ownership, retention, access, export, and
   evidence policy are declared and validated.

5. **Immutable archive and hot search are separate concerns.** Hot search can
   be short-lived and cost-tuned. Immutable archive is the evidence record.

6. **Tamper evidence is explicit, and bounded.** Audit Core should store
   signed or hash-chained manifests for retained batches so operators can later
   prove whether a record set was changed or truncated. The delivered bound is
   narrower than that aspiration and `docs/integrity.md` is authoritative on it:
   an in-database chain does not withstand a database owner without the external
   chain-head attestation, and the chain proves nothing about an event that was
   never emitted. Completeness at the boundary is the emitting source's
   property, not the archive's.

7. **Least-privilege access.** Tenants may access their own audit records
   according to policy. Platform operators may access cross-tenant records only
   through explicit privileged workflows.

8. **Opt-in where legitimate, mandatory where necessary.** Tenants may choose
   optional audit tiers for their own workloads. Platform-control-plane audit
   for shared infrastructure is mandatory.

9. **No secret dumping.** Audit events may contain sensitive metadata and
   secret identifiers, but must avoid plaintext secrets, OTP seeds, private
   keys, root tokens, unseal shares, and password material.

10. **Failure must be visible.** Dropped, delayed, blocked, or degraded audit
    streams are themselves audit and operations events.

## Initial Scope

Audit Core should initially cover:

- a canonical audit event envelope;
- source registration and tenant/scope mapping;
- HTTP ingestion API;
- batch file/archive writer;
- hash-chain or signed manifest generation;
- retention profile metadata;
- source health and validation API;
- local development deployment;
- NetKingdom setup adapter;
- OpenBao audit ingestion path;
- Kubernetes audit or workload log ingestion path;
- basic query/export API over archived batches or configured hot search.

## Out Of Scope Initially

Audit Core should not initially attempt to own:

- every observability use case;
- metrics and traces;
- generic application logging;
- incident response automation;
- policy decision making;
- tenant identity provisioning;
- SIEM correlation rules beyond simple routing metadata;
- replacing NetKingdom, Railiance, OpenBao, or application-specific audit
  semantics.

Those capabilities may integrate later, but the first product must stay focused
on audit custody, integrity, retention, and integration contracts.

## Architecture Fit

Audit Core should sit beside identity, secret management, and platform services:

```text
Audit sources
  OpenBao, Kubernetes, identity providers, policy engines, apps
        |
Collectors / adapters
  Fluent Bit, Vector, OTel Collector, source-specific shippers
        |
Audit Core ingestion API
  validation, normalization, tenant/scope mapping
        |
        +--> immutable archive
        |    object storage, WORM/object lock, encrypted batches
        |
        +--> tamper evidence
        |    signed manifests, hash chains, optional transparency log
        |
        +--> hot search
        |    Loki, OpenSearch, or another configured backend
        |
        +--> optional SIEM
             Wazuh, OpenSearch Security Analytics, or external SOC tools
```

Audit Core should prefer pluggable sinks. The default implementation can start
with object storage for archive and one hot-search backend, but the contracts
must allow future alternatives.

## NetKingdom Integration

NetKingdom should integrate with Audit Core through APIs and adapters.

NetKingdom can provide:

- tenant and scope metadata;
- IAM Profile claim mappings;
- operator and tenant-admin identity;
- setup wizard integration;
- entitlement selection;
- audit policy approval;
- status display in the NetKingdom control surface;
- links to evidence, export, and validation views.

Audit Core should provide NetKingdom:

- a setup API that declares required configuration steps;
- a validation API that reports readiness by source, tenant, and sink;
- an ingestion credential bootstrap flow;
- tenant/scope registration endpoints;
- policy templates for common NetKingdom tiers;
- OpenAPI specifications and machine-readable capability descriptors;
- health and evidence endpoints that NetKingdom can surface without knowing
  Audit Core internals.

NetKingdom must not be required for Audit Core's internal authorization model.
Audit Core may accept NetKingdom OIDC claims when configured, but should also
support a generic OIDC provider and local development auth mode.

## Evidence Bound

Security Layer Model v0.7 §9.6 fixes what Audit Core may claim, and the bound is
narrower than principle 6 aspires to. `docs/integrity.md` is authoritative on the
delivered guarantee; this section states the doctrine it must never exceed.

**Sound:** *the archive proves the records it holds were not altered or truncated
after arrival.*

**Unsound, and Audit Core must never say or imply either:**

- *"the audit record proves it happened"* — the archive proves nothing about an
  event that was never sent;
- *"there is no record, so it did not happen"* — absence of a record is not
  evidence of non-occurrence, and no control may read it as such.

Which control covers which threat:

| Threat | Covered by | When |
| --- | --- | --- |
| Accidental omission — process dies between mutation and emit | atomic emission via a **local** outbox at the source (§9.4) | prevented |
| Adversarial omission — a compromised source declines to insert, deletes before drain, or drains to nowhere | cadence and reconciliation | detected, after the fact |
| Adversarial omission at a compromised source | — | **nothing in the model prevents it** |

That third row is a known, accepted residual. Audit Core raised it against a
remedy it had itself proposed, and states it here so no consumer plans around a
guarantee that does not exist.

**Load-bearing versus attributive.** Where a control's soundness depends on an
event being present or absent — a revocation, a denial, a containment action —
the evidence is **load-bearing**: emission MUST be atomic with the state change
at the source, and the source **MUST** declare an expected emission cadence.
Otherwise it is **attributive**: atomicity SHOULD be sought, and where it is
deliberately traded away the trade MUST be declared and completeness MUST NOT be
claimed.

**Rate monitoring is the wrong form for rare events**, which is exactly where the
stakes are highest — the most valuable event to suppress is the negative one, and
revocations and denials are infrequent by nature. For **low-volume load-bearing
classes** the required form is **positive reconciliation or a heartbeat**:
compare the source's own state transitions against Audit Core's event count per
class, or assert *nothing to report* as a signed positive claim that can itself
go missing. Rate monitoring never produces a claim that can be missing.

Supporting these obligations is Audit Core's work, not only its senders' — a
source cannot declare a cadence to a system that has nowhere to put it. See
`workplans/AUDIT-WP-0009-evidence-role-conformance.md`.

## Approval Evidence

Audit Core carries the **evidence half** of approvals as a distinct source, per
security layer model §9.4 and `AUDIT-IN-0001` (assented 2026-08-28).

`approval-engine` owns the operative approval state — the durable object, atomic
supersession, single consumption, and revocation. Audit Core owns the record of
what happened to it: the four event classes **issuance, use, supersession, and
revocation**.

Terms Audit Core accepts this under:

- `approval-engine` is registered as a distinct source, with its own sender
  registration, tenancy mapping, retention profile, and `secret_policy`,
  onboarded under principle 4 like any other source;
- `approval-engine` guarantees **emission atomicity** — an approval cannot be
  issued, consumed, superseded, or revoked without the corresponding event being
  durably queued in the same transaction. Audit Core cannot detect a suppressed
  emission and will not imply that what it received is everything that happened;
- Audit Core exposes **no approval-validity query**. Records, yes; a verdict
  answering whether an approval is still valid, never. That would be deciding
  early under §6.1 and would couple authorization to the audit fabric, which is
  what §9.4 exists to prevent. Callers needing current state ask
  `approval-engine`.

Full reasoning: `history/2026-08-28-approval-evidence-assent.md`.

## Tenant And Scope Model

Audit Core should distinguish:

- **platform scope**: shared infrastructure and control-plane audit that is
  mandatory for the operator;
- **tenant scope**: tenant-owned systems and workload audit;
- **application scope**: a specific app, product, or service surface;
- **security scope**: high-trust operations such as break-glass, restore,
  key rotation, and privileged access;
- **source scope**: a concrete emitter such as OpenBao, Kubernetes API server,
  KeyCape, privacyIDEA, or a workload.

Tenants should be able to select audit tiers for tenant-owned scopes. They
should not be able to disable platform-scope records required to operate shared
critical infrastructure safely.

## Audit Capability Tiers

Audit Core should support tiered operation:

- **Platform Mandatory**: shared control-plane audit, always on.
- **Archive Only**: immutable retained batches, limited query, lowest cost.
- **Search**: archive plus hot-search backend for operational investigation.
- **Security**: search plus alerting, detection rules, and SOC export.
- **Dedicated**: stronger tenant isolation through dedicated buckets, indexes,
  keys, or runtime instances.

The tier model is both technical and commercial: it controls cost, retention,
query capability, and operational responsibilities.

## API Surface

The first API surface should include:

- `POST /v1/events` for normalized event ingestion;
- `POST /v1/sources` for source registration;
- `GET /v1/sources/{id}/status` for source health;
- `POST /v1/tenants` and `POST /v1/scopes` for tenant/scope registration;
- `PUT /v1/policies/{scope}` for retention and routing policy;
- `GET /v1/readiness` for setup validation;
- `GET /v1/evidence/batches` for retained batch inventory;
- `GET /v1/evidence/batches/{id}/manifest` for integrity metadata;
- `POST /v1/exports` for controlled export jobs;
- `GET /v1/capabilities` for integration discovery.

The API should be specified with OpenAPI and backed by conformance tests.

## Event Envelope

The canonical event envelope should carry at least:

- event id;
- source id and source type;
- tenant id, scope id, and platform/tenant ownership class;
- timestamp observed and timestamp emitted;
- actor subject, issuer, groups, and authentication context where known;
- action, resource, result, and reason;
- correlation id and request id;
- sensitivity classification;
- retention class;
- payload reference or normalized payload;
- original event hash;
- ingestion batch id;
- schema version.

The envelope should permit source-specific extension fields without making
every consumer understand every source.

## Trust And Compliance Posture

Audit Core should be suitable for environments that care about:

- critical infrastructure operations;
- privileged access review;
- tenant isolation;
- incident response;
- restore and break-glass evidence;
- tamper-evident retention;
- export under legal, regulatory, or customer request;
- operational cost control.

It should be honest about guarantees. A searchable log backend is not the same
as immutable evidence. A hash in a task note is not audit custody. A local PVC
is not durable retention.

## Early Success Criteria

Audit Core is useful when:

- OpenBao audit events can be shipped out of the OpenBao audit PVC;
- events are normalized with tenant/scope/source metadata;
- an immutable archive batch is written and has a verifiable manifest;
- a readiness API can tell NetKingdom whether audit is configured enough for a
  given tenant or platform gate;
- a tenant or operator can see whether audit is enabled, degraded, or disabled
  by policy;
- local development works without NetKingdom;
- NetKingdom integration works without special-case code inside Audit Core.

## Relationship To Existing Projects

- **NetKingdom** owns identity, tenant/scope semantics, setup UX, and policy
  decisions for NetKingdom deployments.
- **Audit Core** owns audit ingestion, normalization, retention routing,
  evidence manifests, and audit APIs.
- **Railiance Platform** may operate storage, hot-search, and infrastructure
  backends used by Audit Core.
- **OpenBao** emits secret-manager audit events; Audit Core does not replace
  OpenBao audit devices.
- **Application repositories** emit application audit events using the Audit
  Core envelope or adapters.

## Initial Direction

Start small but choose the right spine:

1. define the event envelope and API contract;
2. implement local file/object archive batches with manifests;
3. add OpenBao file-audit ingestion;
4. expose readiness and validation APIs;
5. integrate NetKingdom setup through the API;
6. add hot-search sink support;
7. add tenant tiers, retention policy, and export flows;
8. add stronger tamper-evidence and optional SIEM integrations.

The first version should be boring, inspectable, and trustworthy. Enterprise
features should grow from clear contracts, not from hidden coupling to the first
deployment environment.