@openauditmodel/cli 0.1.0

package/specification/overview.md

@@ -0,0 +1,172 @@
+# OpenAuditModel Core Specification — Overview
+
+**Specification version: 0.1 · Status: Experimental · This document: Normative**
+
+> OpenAuditModel defines a common, verifiable and backend-independent audit event model for business
+> applications.
+
+## 1. Purpose
+
+Business applications record auditable operations. Almost every application invents its own shape for
+those records, so audit data cannot be validated, correlated, reviewed or exported without bespoke
+work in every system. OpenAuditModel defines one shape for that data.
+
+The specification describes **what an audit event is**, not where it is stored, how it is
+transported, or which regulation it satisfies.
+
+## 2. Scope
+
+This specification defines:
+
+1. The structure of an audit event.
+2. The meaning of each field in that structure.
+3. The rules a conforming event MUST satisfy.
+4. The rules a conforming producer and consumer MUST satisfy.
+5. The extension mechanism by which vendors and domains add their own data.
+
+This specification does not define:
+
+- A storage format, database, index or retention system.
+- A transport protocol, wire encoding or delivery guarantee.
+- A query language or reporting model.
+- An authorization or policy evaluation engine.
+- A mapping to any regulation, standard or control framework.
+
+See [design-principles.md](design-principles.md) for why these exclusions exist, and the repository
+[README](../README.md) for the full list of non-goals.
+
+## 3. Conformance
+
+### 3.1 Conforming event
+
+A JSON document is a **conforming OpenAuditModel v0.1 event** if and only if it validates against the
+[OpenAuditModel Audit Event Schema](../schemas/v0.1/audit-event.schema.json), identified by:
+
+```text
+https://openauditmodel.org/schemas/audit-event/0.1/schema.json
+```
+
+Schema validation is necessary but **not sufficient** for a good audit event. Rules that a schema
+cannot express — a `subject` used as a target resource, a secret placed in `metadata`, an event name
+that changed meaning between releases — are stated normatively in this specification and MUST be
+satisfied by conforming producers even though a validator cannot detect their violation.
+
+### 3.2 Conforming producer
+
+A conforming producer:
+
+- MUST emit events that validate against the canonical schema.
+- MUST set `specVersion` to the version of the specification the event conforms to.
+- MUST NOT record the values listed as prohibited in [privacy.md](privacy.md).
+- MUST keep the meaning of an event name stable across releases, as required by
+  [event-model.md](event-model.md).
+- SHOULD populate only the optional fields its audit purpose requires.
+
+### 3.3 Conforming consumer
+
+A conforming consumer:
+
+- MUST accept any event that validates against the canonical schema, including events that use only
+  the required fields.
+- MUST NOT reject an event because it carries `metadata` or `extensions` the consumer does not
+  recognise.
+- MUST treat `event.summary` as human-readable text and MUST NOT parse it for machine decisions.
+- SHOULD deduplicate events by `id`, as described in [delivery.md](delivery.md).
+
+### 3.4 Conformance is not compliance
+
+Conformance to this specification is a statement about the **shape and semantics of data**. It is not
+a statement about regulatory, legal or contractual compliance, and it MUST NOT be presented as one.
+
+## 4. Document status labels
+
+Every document in this repository is labelled with one of:
+
+| Label            | Meaning                                                                                                     |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Normative**    | Defines requirements. Conforming implementations MUST satisfy them.                                         |
+| **Informative**  | Explains, illustrates or maps. Carries no requirements, even where it uses examples that look prescriptive. |
+| **Experimental** | Expected to change, possibly incompatibly, before version 1.0. All of version 0.1 is experimental.          |
+
+Where a document is normative, only the capitalized keywords defined in
+[terminology.md](terminology.md) express requirements.
+
+Everything under [examples/](../examples/), [mappings/](../mappings/) and [profiles/](../profiles/)
+is informative in v0.1. [semantic-conventions/](../semantic-conventions/) is normative only where it
+says so explicitly; its recommended vocabularies are otherwise SHOULD-level guidance.
+
+## 5. Specification documents
+
+| Document                                                 | Covers                                                          |
+| -------------------------------------------------------- | --------------------------------------------------------------- |
+| [terminology.md](terminology.md)                         | Normative keywords and the vocabulary used throughout           |
+| [design-principles.md](design-principles.md)             | The constraints that shape every decision in the model          |
+| [event-model.md](event-model.md)                         | Top-level structure, identity, time, event descriptor, outcomes |
+| [actor-model.md](actor-model.md)                         | Who acted, and on whose behalf                                  |
+| [resource-model.md](resource-model.md)                   | What was acted upon                                             |
+| [authentication.md](authentication.md)                   | How the actor was authenticated                                 |
+| [authorization.md](authorization.md)                     | Which decision permitted or denied the operation                |
+| [approval-and-delegation.md](approval-and-delegation.md) | Human approval and transferred authority                        |
+| [change-model.md](change-model.md)                       | What changed, without leaking the data that changed             |
+| [evidence-model.md](evidence-model.md)                   | Referencing supporting material                                 |
+| [privacy.md](privacy.md)                                 | What MUST NOT be recorded, and how personal data is described   |
+| [integrity.md](integrity.md)                             | Tamper-evidence, and what it does and does not guarantee        |
+| [delivery.md](delivery.md)                               | Producing, transporting and receiving events                    |
+| [extension-model.md](extension-model.md)                 | `metadata`, `extensions` and profile boundaries                 |
+
+## 6. Versioning and compatibility
+
+### 6.1 Version 0.1
+
+`specVersion` is a constant in v0.1:
+
+```json
+{ "specVersion": "0.1" }
+```
+
+The canonical schema enforces this with `const`. An event that declares any other value is not a
+conforming v0.1 event.
+
+Fixing the value keeps the experimental phase unambiguous: there is exactly one version of the model
+in existence, and no producer can claim conformance to a version that has not been published.
+
+### 6.2 Future versions
+
+The compatibility strategy **is expected to change** after v0.1. Later versions may:
+
+- Replace the `const` constraint with a range or a set of accepted versions.
+- Define which changes are compatible and which require a version increment.
+- Define how a consumer should behave when it receives a newer minor version.
+
+None of that is decided in v0.1, and implementations MUST NOT assume any particular future strategy.
+The decision will be recorded as an architecture decision record in [decisions/](../decisions/).
+
+### 6.3 What is already committed to
+
+Even in the experimental phase, two rules hold:
+
+1. **Event names do not silently change meaning.** If the meaning of an event name changes, the name
+   changes. See [event-model.md](event-model.md).
+2. **Extensions never weaken the core.** An extension MUST NOT remove a required field, relax a
+   constraint, or redefine the meaning of a core field. See
+   [extension-model.md](extension-model.md).
+
+## 7. Relationship to other standards
+
+OpenAuditModel is an **event model**, not a transport, a telemetry pipeline or a security taxonomy.
+It is designed to be carried by, and mapped to, the standards that already exist:
+
+- **CloudEvents** MAY carry an OpenAuditModel event as its `data` payload.
+- **OpenTelemetry** MAY transport, collect and correlate audit events, and `request.traceId` /
+  `request.spanId` are defined to be compatible with W3C Trace Context.
+- **ECS** and **OCSF** MAY be produced from OpenAuditModel events by export mappings.
+- **CADF** is a conceptual reference for audit semantics.
+- **OSCAL** may later be used for control and assessment mappings.
+
+None of these are required. An OpenAuditModel event is valid on its own, with no envelope and no
+pipeline. See [mappings/](../mappings/), which is informative.
+
+## 8. Stability warning
+
+Version 0.1 is **experimental and not production-ready**. Field names, constraints, vocabularies and
+the compatibility strategy may all change. It carries **no compliance guarantee** of any kind.

package/specification/privacy.md

@@ -0,0 +1,386 @@
+# Privacy
+
+**Specification version: 0.1 · Status: Experimental · This document: Normative**
+
+Audit data concentrates the most sensitive relationship in a system: who did what to whom, and when.
+It is frequently retained longer than production data, replicated to more systems, and read by more
+people. This document defines what MUST NOT be recorded, and how the personal-data character of an
+event is described.
+
+None of this constitutes legal advice or a compliance guarantee. See §9.
+
+## 1. Values that MUST NEVER be recorded
+
+The following MUST NOT appear in any field of an OpenAuditModel event — not in `metadata`, not in
+`extensions`, not in `attributes`, not in `before` or `after`, not in an error message, not in a
+summary, and not inside a reference:
+
+1. Passwords, in any form, including password hashes and password history.
+2. Access tokens.
+3. Refresh tokens.
+4. API keys.
+5. Connection strings.
+6. Private keys and other secret key material.
+7. Authorization headers.
+8. Session cookies and any other value that grants a session by possession.
+
+This list is absolute. There is no audit purpose that requires the value of a credential; the audit
+purpose is served by recording the **fact** of its creation, use, rotation or revocation.
+
+Where a system's session identifier is itself a bearer credential, producers MUST record a derived,
+non-reversible correlation value or omit the field. See
+[authentication.md](authentication.md).
+
+## 2. Data that MUST NOT be captured automatically
+
+The following MUST NOT be captured automatically — that is, without an explicit, per-field decision
+by the producer:
+
+1. Full request bodies.
+2. Full response bodies.
+3. Message broker payloads.
+4. Database query parameters.
+5. Query strings. The canonical schema enforces this for `request.route`.
+6. Complete database records in `change.before` or `change.after`.
+7. Raw forwarding and client headers copied verbatim.
+
+A producer MAY record a **selected, named subset** of any of these where the audit purpose requires
+it and the values have been reviewed. The prohibition is on capturing them wholesale because they
+happened to be available.
+
+## 3. The allowlist model
+
+Audit event fields MUST follow an **allowlist** model.
+
+A producer decides, per field, what it records. It MUST NOT populate audit fields by serializing
+whatever object was at hand and removing known-bad keys afterwards. Denylists fail silently: the
+first time a new field appears in an upstream model, it is captured, and nobody finds out until it is
+in seven years of retained records.
+
+Practically:
+
+- Map application data to audit fields explicitly, field by field.
+- Prefer `changedFields` over `before`/`after` when the field names alone answer the question.
+- Prefer identifiers over values, and stable identifiers over personal identifiers.
+- Prefer references over content.
+- Prefer route templates over resolved paths.
+- Treat every new audit field as a change that needs review, in the same way a new database column
+  containing personal data would.
+
+## 4. Data minimization
+
+Audit data MUST be minimized to what the audit purpose requires.
+
+- A field that no reviewer, control or investigation would use SHOULD NOT be recorded.
+- An optional object SHOULD be omitted when the producer has no specific need for it. Completeness is
+  not a goal; see [design-principles.md](design-principles.md).
+- `actor.displayName`, `resource.name` and `request.ipAddress` are the fields most often recorded out
+  of habit. Each is personal data in common circumstances, and each SHOULD be justified rather than
+  defaulted.
+- Minimization applies to retention as well as capture. The model provides `privacy.retentionClass`
+  so that events can be governed differently; enforcing it is the operator's responsibility.
+
+## 5. The privacy object
+
+`privacy` is OPTIONAL and describes how this event relates to personal data.
+
+| Field                  | Meaning                                                       |
+| ---------------------- | ------------------------------------------------------------- |
+| `containsPersonalData` | Whether the event as serialized contains personal data.       |
+| `dataCategories`       | Categories of personal data present. Open vocabulary.         |
+| `processing`           | How personal data was handled when the event was produced.    |
+| `minimized`            | Whether the producer applied data minimization to this event. |
+| `retentionClass`       | Producer-defined retention class governing this event.        |
+| `purpose`              | Purpose for which the event is recorded.                      |
+
+### 5.1 Data categories
+
+RECOMMENDED values:
+
+```text
+identifier   contact    network      financial   health
+biometric    location   employment   behavioral  special-category
+other
+```
+
+`special-category` marks data that the operator's own policy treats as requiring heightened
+protection. The specification deliberately does not define which categories are special, because that
+determination is jurisdictional.
+
+Producers SHOULD populate `dataCategories` whenever `containsPersonalData` is `true`. The schema does
+not enforce this, because a producer may know that personal data is present before it has classified
+it.
+
+### 5.2 Processing
+
+`processing` MUST be one of:
+
+| Value       | Meaning                                                        |
+| ----------- | -------------------------------------------------------------- |
+| `include`   | Personal data is present in the event as recorded.             |
+| `mask`      | Personal data was partially obscured before recording.         |
+| `hash`      | Personal data was replaced with a digest.                      |
+| `drop`      | Personal data was removed entirely.                            |
+| `encrypt`   | Personal data was encrypted before recording.                  |
+| `reference` | Personal data was replaced with a reference to another system. |
+
+A single value describes the treatment applied to the event as a whole. Per-field processing
+descriptions are an open question for v0.2.
+
+Note that `hash` is not anonymization. Hashing a low-entropy identifier such as an email address or a
+national identification number is reversible by enumeration and MUST NOT be presented as removing the
+personal-data character of the field.
+
+### 5.3 Regulation neutrality
+
+The privacy object MUST NOT be extended with regulation-specific fields: no lawful basis
+enumerations, no article references, no jurisdiction-specific consent flags, no framework identifiers.
+
+Those are interpretations of audit data, produced by mapping artifacts maintained outside this
+specification. Encoding one framework's vocabulary into the core model would make the model wrong
+everywhere else, and stale as soon as the framework is revised.
+
+## 6. Validation cannot detect secrets
+
+Schema validation alone **cannot** detect a leaked secret.
+
+A password placed in `metadata.oldValue` is a valid string in a valid free-form object. The event will
+pass every conformance test in this repository. This is a limitation of machine validation, not a gap
+that a future schema version will close.
+
+Implementations SHOULD therefore:
+
+- Run secret scanning over audit events before they leave the producer, and again in the pipeline.
+- Review audit instrumentation in code review with the same seriousness as data model changes.
+- Fail closed: when a producer cannot determine whether a value is safe, it SHOULD omit the value.
+- Treat the audit store as a system holding personal data, with corresponding access control,
+  retention and disclosure controls.
+
+`auditmodel lint-privacy` makes **part** of this checkable. The rest of this section describes what
+that part is, and — more importantly — what it is not.
+
+### 6.1 Four kinds of rule
+
+The requirements in this document fall into four groups. Conflating them is how a linter comes to be
+trusted for things it cannot do.
+
+| Kind                        | Enforced by                  | Examples                                                  |
+| --------------------------- | ---------------------------- | --------------------------------------------------------- |
+| **Normative requirement**   | This specification. Binding. | §1 "passwords MUST NEVER be recorded"                     |
+| **Deterministic lint rule** | Exact matching. No guessing. | A property named `password`; a PEM private key marker     |
+| **Heuristic lint rule**     | Measurement. Guesses.        | High character entropy; an oversized object               |
+| **Not automatable**         | Review. Nothing else.        | Whether a value is personal data; whether §3 was followed |
+
+A deterministic rule can still be wrong about **meaning**: a property named `password` might hold a
+policy description. It is deterministic because the same input always produces the same finding, not
+because the finding is always correct.
+
+### 6.2 What the linter checks
+
+`auditmodel lint-privacy` is deterministic local static analysis. It reads events, reports
+suspicions, and does nothing else. It MUST NOT send event content anywhere, resolve or fetch any
+reference, open any file an event names, modify or redact an event, or consult any remote service or
+model.
+
+Deterministic rules:
+
+| Rule                             | Detects                                                                               |
+| -------------------------------- | ------------------------------------------------------------------------------------- |
+| `OAM-PRIV-001`                   | A populated property whose name is a credential name after normalization              |
+| `OAM-PRIV-002`                   | A value shaped as `Bearer`, `Basic`, `Digest`, `ApiKey` or `Token` plus a credential  |
+| `OAM-PRIV-003`                   | A PEM marker introducing private key material                                         |
+| `OAM-PRIV-010`                   | A structurally valid JSON Web Token                                                   |
+| `OAM-PRIV-011`                   | A published access key identifier shape                                               |
+| `OAM-PRIV-012` to `OAM-PRIV-016` | Published credential prefixes for source forge, messaging, payment and cloud API keys |
+| `OAM-PRIV-030`                   | A URL with embedded user information                                                  |
+| `OAM-PRIV-031`                   | An evidence reference carrying a query string or fragment                             |
+| `OAM-PRIV-040`                   | A connection string carrying a password                                               |
+| `OAM-PRIV-041`                   | A connection string without a credential, which still discloses infrastructure        |
+| `OAM-PRIV-061`                   | A populated property whose name denotes a raw request, response or message body       |
+
+Heuristic rules:
+
+| Rule           | Measures                                |
+| -------------- | --------------------------------------- |
+| `OAM-PRIV-050` | Character entropy, as a token candidate |
+| `OAM-PRIV-060` | Value size, as a minimization signal    |
+
+Recognising a published credential prefix is a property of the **tooling**, not of the model. The
+specification, the canonical schema and the semantic conventions name no vendor, and no lint rule
+introduces a field, vocabulary or concept into the model.
+
+### 6.3 What the linter does not check
+
+It does not, and largely cannot, determine:
+
+- Whether a value **is** personal data. `privacy.dataCategories` is a producer declaration; nothing
+  verifies it.
+- Whether `privacy.minimized` is truthful.
+- Whether the audit purpose required a field to be recorded at all.
+- Whether a hash of a low-entropy identifier is reversible by enumeration.
+- Whether `actor.displayName`, `resource.name` or `request.ipAddress` were justified.
+- Whether §3's allowlist model was followed. That is a property of the producer's **code**; an event
+  built by copying a request object and one built field by field can be byte-identical.
+- Whether the audit store has access control or retention (§7).
+- Anything about regulatory classification (§9).
+- Whether a detected credential is real, current, revoked or usable. No rule validates a signature,
+  decodes a token for its claims, or contacts an issuer.
+
+### 6.4 A finding is a suspicion; a clean result is not a clearance
+
+A finding means a value **matched a rule**. It does not establish a data breach, a regulatory
+violation, a confirmed credential or confirmed personal data. Tooling and documentation MUST NOT
+present findings in those terms.
+
+**A clean result does not mean an event is safe or compliant.** A password that happens to be a
+dictionary word, stored under a field named `note`, matches nothing here. Neither does a national
+identification number, a home address or a medical detail: the linter looks for values shaped like
+secrets, and most personal data is not shaped like anything.
+
+### 6.5 Findings never contain the offending value
+
+No finding — in any output format — contains the value that produced it, any part of it, a preview, a
+prefix, a suffix, or a decoded claim. A finding carries a rule identifier, a severity, a confidence,
+a JSON Pointer, a message and a recommendation.
+
+The reason is direct: linter output goes into CI logs, pull request comments and issue trackers,
+which are usually less protected than the audit store. A tool that echoed what it found would move
+secrets from a controlled system into an uncontrolled one, and would do it precisely when a secret
+was present.
+
+### 6.6 Inspected locations
+
+Values are inspected under:
+
+```text
+/metadata                        /change/before
+/extensions                      /change/after
+/actor/attributes                /event/error/message
+/subject/attributes              /event/summary
+/resource/attributes             /reason/text
+/relatedResources/*/attributes   /reason/reference
+/evidence/*/reference            /request/route
+/authorization/reason            /delegation/reason
+```
+
+Property **names** are inspected recursively within `metadata`, `extensions`, every `attributes`
+object, `change.before` and `change.after`. Extension keys are also tested on their final
+dot-separated segment, because a reverse-domain key names its field there.
+
+Everything else is excluded, including `integrity` digests and signatures, `request.traceId` and
+`request.spanId`, and the event `id`. Those fields hold high-entropy values by design; scanning them
+would produce a finding on every well-formed event.
+
+### 6.7 Known-safe exclusions from the entropy heuristic
+
+The entropy rule — and **only** the entropy rule — ignores values recognised as: UUIDs, ULIDs, W3C
+Trace Context trace and span identifiers, lower-case hexadecimal digests of SHA-256, SHA-384 and
+SHA-512 length, RFC 3339 timestamps, purely numeric identifiers, lower-case separated identifiers and
+reference paths, anything containing `://`, and redaction placeholders.
+
+A value under a property named `password` is reported whatever it looks like. A value matching a
+published credential format is reported even if it also looks like an identifier.
+
+### 6.8 Fixed thresholds
+
+Version 0.1 hard-codes these. They are not configurable; see
+[ADR 0007](../decisions/0007-deterministic-privacy-linting.md).
+
+| Threshold                       | Value                                |
+| ------------------------------- | ------------------------------------ |
+| Minimum length for entropy      | 24 characters                        |
+| Maximum length for entropy      | 4096 characters                      |
+| Entropy threshold               | 4.0 bits per character               |
+| Minimum character classes       | 3 of 4 (lower, upper, digit, symbol) |
+| Oversized: serialized size      | 4096 bytes                           |
+| Oversized: property count       | 50                                   |
+| Oversized: nesting depth        | 6                                    |
+| Oversized: array length         | 100                                  |
+| Oversized: single string length | 2048 characters                      |
+| Maximum traversal depth         | 64                                   |
+
+### 6.9 False positives and false negatives
+
+Both are expected, and the design prefers false negatives in the heuristic rules and false positives
+in nothing.
+
+**False positives** are most likely from `OAM-PRIV-050` on legitimate opaque identifiers, from
+`OAM-PRIV-060` on genuinely detailed metadata, and from `OAM-PRIV-001` where a credential-named field
+holds something else. `OAM-PRIV-050` reports at low confidence for exactly this reason.
+
+**False negatives** are certain. A secret in an unpublished format, under a harmless name, below the
+entropy threshold, or in all lower case with a separator, is invisible. So is any personal data that
+is not shaped like a secret. A recognised redaction placeholder under a credential name is
+deliberately not reported, because a tool that flags `"password": "[REDACTED]"` teaches people to
+ignore it.
+
+`OAM-PRIV-001` reports a credential-named property when it holds a **scalar**. A **container** under
+such a name is treated as a descriptor and is not itself reported; its members are inspected
+individually. `credential: { "type": "api-key" }` describes a credential without carrying one, and is
+the shape the identity-and-access-management profile requires for credential rotation events —
+flagging it would fire on every conforming rotation event, which is how a linter earns the reputation
+that gets it switched off. The accepted cost is a secret stored under a harmless member name inside
+such a container.
+
+### 6.10 Schema validation is not secret scanning
+
+These are different questions and neither substitutes for the other.
+
+Schema validation asks whether an event is **well formed**. It passes an event containing a password
+in `metadata`, because a password is a valid string. Privacy linting asks whether an event **looks
+like it contains something it should not**. It passes an event that is structurally broken, which is
+why the linter validates first and refuses to deep-lint an invalid event: traversing an arbitrary
+structure yields findings whose paths mean nothing.
+
+### 6.11 Exit codes
+
+```text
+0  no findings
+1  one or more privacy findings, or a schema-invalid event
+2  usage error, or a file could not be read or parsed
+```
+
+A schema-invalid event is reported and **not** deep linted, and exits non-zero: a clean privacy
+result for an event that was never linted would be misleading.
+
+### 6.12 Using it
+
+```bash
+auditmodel lint-privacy examples/privacy/clean/minimal-clean-event.json
+auditmodel lint-privacy examples/privacy/findings/access-token-field.json
+auditmodel lint-privacy examples/privacy --format json
+```
+
+Producers SHOULD run it in CI over fixture events and over samples of real output, and SHOULD treat
+it as one control among several. It is not a substitute for reviewing audit instrumentation, and
+running it does not make an event safe.
+
+## 7. Access to audit data
+
+Audit data MUST be access-controlled. It describes individuals' behaviour, and in many systems it is
+readable by more people than the data it describes.
+
+The specification defines no access control model. It notes only that an audit trail readable by
+everyone in an organization is a privacy exposure that no amount of field-level minimization
+compensates for.
+
+## 8. Example
+
+```json
+{
+  "privacy": {
+    "containsPersonalData": true,
+    "dataCategories": ["identifier", "contact", "behavioral"],
+    "processing": "reference",
+    "minimized": true,
+    "retentionClass": "standard",
+    "purpose": "operational-audit"
+  }
+}
+```
+
+## 9. No legal or compliance guarantee
+
+This document describes engineering practice for reducing the risk that audit data creates. It is not
+legal advice, it does not establish a lawful basis for processing, and conformance to it does not
+constitute compliance with any law, regulation, standard or contract.

package/specification/resource-model.md

@@ -0,0 +1,116 @@
+# Resource Model
+
+**Specification version: 0.1 · Status: Experimental · This document: Normative**
+
+## 1. Purpose
+
+`resource` answers "what was acted upon". It is REQUIRED, because an audit event that records an
+action without a target cannot be reviewed, correlated or scoped to a data subject.
+
+## 2. Structure
+
+### 2.1 Required
+
+| Field  | Meaning                                                        |
+| ------ | -------------------------------------------------------------- |
+| `type` | Kind of resource. Open vocabulary.                             |
+| `id`   | Stable identifier of the resource within the producing system. |
+
+### 2.2 Optional
+
+| Field            | Meaning                                                            |
+| ---------------- | ------------------------------------------------------------------ |
+| `name`           | Human-readable resource name.                                      |
+| `parentId`       | Containing resource: folder, workspace, project, cluster, account. |
+| `classification` | Data classification of the resource. Open vocabulary.              |
+| `ownerId`        | Owning principal or team.                                          |
+| `tenantId`       | Tenant the resource belongs to.                                    |
+| `attributes`     | Producer-defined additional attributes.                            |
+
+## 3. Resource types are open-ended
+
+`resource.type` is an **open vocabulary**. The core schema MUST NOT enumerate resource types, and a
+consumer MUST NOT reject a resource type it does not recognise.
+
+Types observed across the domains this model targets include:
+
+```text
+user            role            document        incident
+configuration   deployment      database-record api-key
+consumer-group  topic           queue           workflow
+tenant          report          session         share-link
+policy          secret          cluster         service
+```
+
+This list is illustrative, not exhaustive and not normative. A hard-coded list of resource types is
+the fastest way to make a general model unusable in a domain nobody thought of.
+
+Resource types MUST be lower-case, hyphen-separated tokens, so that independently produced events
+remain comparable in form even when the vocabularies differ.
+
+## 4. Identifiers and names
+
+- `id` MUST be stable for the lifetime of the resource. A path or display name that changes when the
+  resource is moved or renamed is not an identifier.
+- `id` MUST be recorded even when the operation failed, when the producer knows what was attempted.
+- `name` is OPTIONAL, and MAY itself be sensitive. Document titles, incident summaries and file names
+  routinely contain personal data, customer names and unreleased business information. Producers
+  SHOULD consider whether recording `name` is necessary for the audit purpose. See
+  [privacy.md](privacy.md).
+- `resource.attributes` MUST NOT contain the **contents** of the resource. An audit event records
+  that a document was downloaded; it does not carry the document.
+
+## 5. Classification
+
+`classification` describes the sensitivity of the resource. It is an **open vocabulary**, because
+classification schemes are defined by organizations and differ legitimately in the number of levels
+and their names.
+
+RECOMMENDED values:
+
+```text
+public  internal  confidential  restricted  secret  unknown
+```
+
+Organizations that use a different scheme MAY use their own tokens. Where a mapping to the
+recommended values is possible, producers SHOULD publish it so that cross-system reporting remains
+meaningful.
+
+`classification` describes the **resource**, not the event. The sensitivity of the audit event itself
+is described by [privacy.md](privacy.md).
+
+## 6. Related resources
+
+`relatedResources` is an OPTIONAL array of additional resources affected by, or required to
+interpret, the same operation. Each entry has the same shape as `resource`.
+
+Rules:
+
+1. `resource` MUST hold the **primary** target. `relatedResources` MUST NOT be used as an alternative
+   to choosing one.
+2. `relatedResources`, when present, MUST contain at least one entry.
+3. `relatedResources` SHOULD be used for genuinely affected resources, not for arbitrary context. A
+   consumer group reset affects the consumer group primarily and the topic secondarily; both belong.
+   The cluster's monitoring dashboard does not.
+4. A bulk operation over many resources SHOULD be recorded as one event per resource where the
+   resources are individually significant, and as a single event with a representative primary
+   resource and a count in `metadata` where they are not. Producers SHOULD document which approach
+   they use, because the two are not interchangeable for review purposes.
+
+Example:
+
+```json
+{
+  "resource": { "type": "consumer-group", "id": "payments-settlement-consumer" },
+  "relatedResources": [
+    { "type": "topic", "id": "payments.settlement.completed" },
+    { "type": "cluster", "id": "cluster-streaming-production" }
+  ]
+}
+```
+
+## 7. Resource is not subject
+
+`resource` is what the operation acted **on**. `subject` is the principal the operation was performed
+**for**. When an administrator disables a user account, the user is a `resource` — nobody delegated
+authority to the administrator. See [actor-model.md](actor-model.md).