@openauditmodel/cli 0.3.0 → 0.4.0

package/semantic-conventions/message-brokers.md

@@ -0,0 +1,128 @@
+# Message Broker Events
+
+**Specification version: 0.1 · Status: Experimental**
+
+Category: `data-infrastructure`
+
+## 1. Recommended event names
+
+These names cover the **control plane** of a message broker: the operations that change what the
+broker is, who may use it and what consumers will see. The data plane is out of scope — see §2.
+
+### Cluster and configuration
+
+| Name                          | Operation                               |
+| ----------------------------- | --------------------------------------- |
+| `broker.cluster.create`       | A cluster was provisioned               |
+| `broker.cluster.delete`       | A cluster was decommissioned            |
+| `broker.cluster.scale`        | Cluster capacity was changed            |
+| `broker.cluster.upgrade`      | A cluster was upgraded                  |
+| `broker.cluster.failover`     | Traffic was moved to another cluster    |
+| `broker.configuration.update` | Broker or cluster configuration changed |
+
+### Destinations
+
+| Name                           | Operation                            |
+| ------------------------------ | ------------------------------------ |
+| `broker.topic.create`          | A topic was created                  |
+| `broker.topic.update`          | A topic's configuration changed      |
+| `broker.topic.delete`          | A topic was deleted                  |
+| `broker.queue.create`          | A queue was created                  |
+| `broker.queue.update`          | A queue's configuration changed      |
+| `broker.queue.delete`          | A queue was deleted                  |
+| `broker.queue.purge`           | A queue's messages were discarded    |
+| `broker.exchange.create`       | An exchange was created              |
+| `broker.exchange.update`       | An exchange's configuration changed  |
+| `broker.exchange.delete`       | An exchange was deleted              |
+| `broker.stream.create`         | A stream was created                 |
+| `broker.stream.update`         | A stream's configuration changed     |
+| `broker.stream.trim`           | A stream's retained records were cut |
+| `broker.stream.delete`         | A stream was deleted                 |
+| `broker.consumer-group.create` | A consumer group was created         |
+| `broker.consumer-group.update` | A consumer group's settings changed  |
+| `broker.consumer-group.delete` | A consumer group was removed         |
+
+### Access and quotas
+
+| Name                       | Operation                               |
+| -------------------------- | --------------------------------------- |
+| `broker.acl.grant`         | An access control entry was added       |
+| `broker.acl.revoke`        | An access control entry was removed     |
+| `broker.permission.grant`  | A permission was granted to a principal |
+| `broker.permission.revoke` | A permission was removed                |
+| `broker.quota.create`      | A quota was defined                     |
+| `broker.quota.update`      | A quota was changed                     |
+| `broker.quota.delete`      | A quota was removed                     |
+
+### Position and replay
+
+| Name                    | Operation                                         |
+| ----------------------- | ------------------------------------------------- |
+| `broker.offset.reset`   | A consumer group's position was moved             |
+| `broker.message.replay` | Messages were re-delivered from a stored position |
+
+## 2. The data plane is not an audit trail
+
+A published message is not an audit event, and a broker that emitted one per message would produce
+volume nobody reviews. Recording every publish and every consume also duplicates the broker's own
+telemetry while adding the one thing telemetry must not carry: message content.
+
+What belongs here is the operation that changed the broker, not the traffic that flowed through it.
+Where a business operation happens to be carried by a message, the **application** records the
+business event; the broker records that a destination or a permission changed.
+
+`broker.queue.purge`, `broker.stream.trim`, `broker.offset.reset` and `broker.message.replay` are the
+exceptions that prove the rule: each is a control-plane operation whose effect is on data, which is
+exactly why they are governed.
+
+## 3. Position changes deserve their own attention
+
+`broker.offset.reset` and `broker.message.replay` change what consumers see without changing what was
+written. A reset can hide a poison message, replay a day of financial instructions, or make a
+downstream system process an order twice — and none of it leaves a trace in the destination itself.
+
+An auditor reading a broker trail looks for these first. The event SHOULD carry the position moved
+from and the position moved to in `metadata`, and the reason the position was moved in `reason`. Where
+the operation was performed to recover from an incident, `request.correlationId` SHOULD tie it to the
+incident's own events.
+
+## 4. Which principal goes where
+
+| Operation                                    | `actor`            | `resource`             | `subject` |
+| -------------------------------------------- | ------------------ | ---------------------- | --------- |
+| An operator creates a topic                  | the operator       | the **topic**          | absent    |
+| An operator grants a service an ACL entry    | the operator       | the **topic or queue** | absent    |
+| A platform job upgrades a cluster            | the job's identity | the **cluster**        | absent    |
+| An operator resets a consumer group's offset | the operator       | the **consumer group** | absent    |
+
+The principal receiving an ACL or a permission is a **related resource**, never a `subject`. `subject`
+is the principal on whose behalf the actor acted, and a service being granted access delegated
+nothing to the operator granting it. See [actor-model.md](../specification/actor-model.md) §5.
+
+## 5. What must never be recorded
+
+**Message payloads, keys and headers.** A broker carries other systems' data, and an audit event that
+quoted a message would copy that data into a store with a different retention period, a different
+access model and a different threat model. This includes a "sample" message, a truncated payload and a
+payload hash that could confirm a guess.
+
+Connection strings, SASL credentials and TLS private material are equally out of bounds — see
+[privacy.md](../specification/privacy.md) §6.
+
+## 6. Context to populate
+
+| Field                   | Guidance                                                                 |
+| ----------------------- | ------------------------------------------------------------------------ |
+| `authorization`         | The decision that permitted the control-plane operation                  |
+| `change`                | `changedFields`, and before and after for configuration and quotas       |
+| `relatedResources`      | The cluster the destination belongs to, and the principal granted access |
+| `reason`                | Why a purge, trim, offset reset or replay was performed                  |
+| `metadata.broker`       | The broker's own identifiers: cluster, destination, group, position      |
+| `request.correlationId` | Shared with the incident or change request that prompted the operation   |
+
+## 7. Example
+
+See
+[examples/profiles/message-broker-management/valid/offset-reset.json](../examples/profiles/message-broker-management/valid/offset-reset.json)
+for a consumer-group offset reset with the authorization decision, the positions moved between and
+the reason it was moved.

package/semantic-conventions/secrets-and-keys.md

@@ -0,0 +1,132 @@
+# Secret and Key Events
+
+**Specification version: 0.1 · Status: Experimental**
+
+## 1. Recommended event names
+
+This domain spans four categories, because the operations differ in kind rather than in subject: a
+key generation is a security operation, reading a secret is data access, and changing a rotation
+policy is configuration.
+
+| Family                              | `event.category`       |
+| ----------------------------------- | ---------------------- |
+| Secret and key lifecycle            | `security`             |
+| Reading a secret or exporting a key | `data-access`          |
+| Emergency and break-glass access    | `privileged-operation` |
+| Rotation and expiry policy          | `configuration`        |
+
+### Secrets
+
+| Name            | Operation                                    |
+| --------------- | -------------------------------------------- |
+| `secret.create` | A secret was stored                          |
+| `secret.update` | A secret's value was replaced in place       |
+| `secret.rotate` | A secret was replaced on a rotation schedule |
+| `secret.reveal` | A principal read a secret's value            |
+| `secret.export` | A secret left the store                      |
+| `secret.revoke` | A secret was invalidated before its expiry   |
+| `secret.delete` | A secret was removed from the store          |
+
+### Keys
+
+| Name           | Operation                                       |
+| -------------- | ----------------------------------------------- |
+| `key.generate` | A key was created inside the store              |
+| `key.import`   | A key created elsewhere was brought in          |
+| `key.rotate`   | A new key version replaced the active one       |
+| `key.enable`   | A key was made usable                           |
+| `key.disable`  | A key was made unusable without being destroyed |
+| `key.export`   | Key material left the store                     |
+| `key.destroy`  | A key was destroyed and cannot be recovered     |
+
+### Certificates
+
+| Name                 | Operation                                |
+| -------------------- | ---------------------------------------- |
+| `certificate.issue`  | A certificate was issued                 |
+| `certificate.renew`  | A certificate was reissued before expiry |
+| `certificate.revoke` | A certificate was revoked                |
+| `certificate.delete` | A certificate was removed                |
+
+### Policy
+
+`secret.policy.update` records a change to the rules governing rotation, expiry or access for a
+secret or a class of secrets.
+
+**Open item.** The profile also selects the prefix `key.policy.`, and no name is published under it
+and no fixture carries one. Either a key policy operation exists and should be named here, or the
+prefix should be withdrawn. It is recorded as an open question rather than filled with an invented
+name.
+
+## 2. The overlap with `configuration.secret.access`
+
+[configuration-and-change.md](configuration-and-change.md) §6 publishes `configuration.secret.access`
+for a principal reading a secret held as application configuration. This document publishes
+`secret.reveal` for a principal reading a secret from a secret store, which is what the
+secrets-and-key-management profile enforces.
+
+These are two names for what is arguably one operation, and this document does not resolve that. A
+convention may not quietly withdraw a name another convention publishes: `event-model.md` §7.2 makes
+name stability a MUST, and a producer already emitting either name is conforming. Reconciling the two
+is a specification change and needs an issue against
+[CONTRIBUTING.md](../CONTRIBUTING.md)'s specification-change process.
+
+Until then: a producer whose secrets are configuration values SHOULD use
+`configuration.secret.access`; a producer with a secret store as a distinct system SHOULD use
+`secret.reveal`. A producer SHOULD NOT emit both for one read.
+
+## 3. What must never be recorded
+
+**The material itself.** Not the secret, not the key, not a private key, not a certificate's private
+half, not a fragment, not a prefix, and not a hash that would let a reader confirm a guess. This is
+the domain where the rule matters most, because the events are about material whose whole value is
+that nobody else has it.
+
+An event records that a secret was read, by whom, under what authorization, and which secret — by
+identifier. It does not record what the secret was. See
+[privacy.md](../specification/privacy.md) §6, and note that the privacy linter is a backstop for
+this rule, not the control that enforces it.
+
+`keyId` names a key and MUST NOT carry key material — [integrity.md](../specification/integrity.md)
+§6.1 already says so for the integrity object, and the same holds here.
+
+## 4. Which principal goes where
+
+| Operation                                            | `actor`      | `resource`     | `subject`    |
+| ---------------------------------------------------- | ------------ | -------------- | ------------ |
+| An engineer reads a secret                           | the engineer | the **secret** | absent       |
+| A service reads a secret at start-up                 | the service  | the **secret** | absent       |
+| An operator generates a key for an application       | the operator | the **key**    | absent       |
+| An operator reveals a secret for an on-call engineer | the operator | the **secret** | the engineer |
+
+The last row is the only one where `subject` appears, and only because the operator acted on someone
+else's behalf. The application a secret belongs to is a **related resource**, not a subject — see
+[actor-model.md](../specification/actor-model.md) §5.
+
+## 5. Emergency access
+
+Break-glass reads are the events this domain exists for. Where a producer distinguishes emergency
+access from routine access, the event SHOULD carry that distinction in `metadata` and SHOULD record
+the justification in `reason`. An emergency read with no recorded reason is the finding an auditor is
+looking for.
+
+Where the producer's own policy requires approval for a class of access, the decision belongs in
+`approval` — including when approval was evaluated and found not to be required.
+
+## 6. Context to populate
+
+| Field                     | Guidance                                                             |
+| ------------------------- | -------------------------------------------------------------------- |
+| `authorization`           | The decision that permitted the operation                            |
+| `resource.classification` | How sensitive the secret or key is, in the producer's own vocabulary |
+| `approval`                | Where the operation required a second principal's decision           |
+| `reason`                  | Why a reveal, export, revoke or destroy was performed                |
+| `metadata.secret`         | The store's own identifiers, the secret type, and the rotation state |
+| `relatedResources`        | The application or service the secret or key serves                  |
+
+## 7. Example
+
+See
+[examples/profiles/secrets-and-key-management/valid/secret-reveal-emergency.json](../examples/profiles/secrets-and-key-management/valid/secret-reveal-emergency.json)
+for an emergency secret read with the authorization decision, the justification and the approval that
+permitted it — and no trace of the secret itself.