@openauditmodel/cli 0.1.0

package/semantic-conventions/data-access.md

@@ -0,0 +1,115 @@
+# Data Access Events
+
+**Specification version: 0.1 · Status: Experimental**
+
+Categories: `data-access`, `data-modification`
+
+## 1. Recommended event names
+
+### Reading
+
+| Name                     | Operation                      |
+| ------------------------ | ------------------------------ |
+| `data.record.read`       | A record was read individually |
+| `data.record.search`     | A search returned records      |
+| `data.report.generate`   | A report was produced          |
+| `data.export.create`     | An export was produced         |
+| `data.export.download`   | An export was retrieved        |
+| `document.file.view`     | A document was viewed          |
+| `document.file.download` | A document was downloaded      |
+
+### Writing
+
+| Name                  | Operation                     |
+| --------------------- | ----------------------------- |
+| `data.record.create`  | A record was created          |
+| `data.record.update`  | A record was modified         |
+| `data.record.delete`  | A record was deleted          |
+| `data.record.restore` | A deleted record was restored |
+| `data.import.create`  | Data was imported             |
+
+### Sharing
+
+| Name                         | Operation                                            |
+| ---------------------------- | ---------------------------------------------------- |
+| `document.share.create`      | Access was granted to a recipient                    |
+| `document.share.revoke`      | A share was withdrawn                                |
+| `document.permission.grant`  | A permission was granted on a resource               |
+| `document.permission.revoke` | A permission was removed                             |
+| `data.transfer.external`     | Data was transmitted outside the operator's boundary |
+
+## 2. Not everything is worth auditing
+
+Read events are the highest-volume category in most systems and the least useful by default. An audit
+trail that records every list view is expensive, hard to search, and hides the events that matter.
+
+Producers SHOULD audit reads where at least one of these holds:
+
+- The resource is classified above `internal`.
+- The read crosses a tenant, organization or customer boundary.
+- The actor is privileged, or is acting for someone else.
+- The volume is unusual: an export, a bulk search, a full extract.
+- The data is personal data and the operator has committed to access transparency.
+
+Producers SHOULD NOT audit ordinary reads of unclassified data by their owner. That is what
+application logs are for.
+
+## 3. Context to populate
+
+| Field                     | Guidance                                                          |
+| ------------------------- | ----------------------------------------------------------------- |
+| `resource.classification` | Frequently the reason the event is being recorded at all          |
+| `resource.ownerId`        | Who the data belongs to, where it differs from the actor          |
+| `privacy`                 | `containsPersonalData`, `dataCategories`, `processing`, `purpose` |
+| `authorization`           | The decision that permitted the access                            |
+| `reason`                  | For support access and any access to another party's data         |
+| `request.route`           | The route template, never a resolved URL with a query string      |
+| `metadata`                | `recordCount`, `exportFormat`, `scope`, `filterName`              |
+| `controlCategories`       | `data-access-logging`, `external-data-sharing`                    |
+
+## 4. Search and bulk reads
+
+A search returns an unknown number of records. Recording each one is usually infeasible and often
+undesirable. Recommended handling:
+
+- Record one `data.record.search` event with `resource` set to the collection searched.
+- Record `metadata.recordCount`, and the **name** of the filter applied, not its values.
+- MUST NOT record the query string or the search terms. Search terms routinely contain personal data
+  and are among the most sensitive values a system holds. See
+  [privacy.md](../specification/privacy.md).
+
+## 5. External sharing
+
+Sharing outside the operator's boundary is a distinct control, and SHOULD be recorded as such:
+
+- Include `external-data-sharing` in `controlCategories`.
+- Record the recipient **type** and **domain**, not the recipient's address, unless the audit purpose
+  specifically requires identifying the individual.
+- Record share constraints — expiry, password protection, watermarking, download permission — in
+  `metadata`, because they are what a reviewer assesses.
+- Emit a matching `document.share.revoke` when the share ends, so that the trail shows exposure
+  windows rather than only their beginning.
+
+See [examples/valid/document-external-share.json](../examples/valid/document-external-share.json).
+
+## 6. Exports
+
+Exports concentrate risk: one operation moves a large volume of data out of the controlled system.
+
+- `data.export.create` records production of the export; `data.export.download` records retrieval.
+  Both are worth recording, because they can be separated by days and performed by different
+  principals.
+- Record `metadata.recordCount` and `metadata.exportFormat`.
+- Record `privacy` fully. An export is the event most likely to be reviewed under a data protection
+  question.
+- Where the export is produced by a service for a user, record the `subject` and `delegation`. See
+  [examples/valid/service-account-data-export.json](../examples/valid/service-account-data-export.json).
+
+## 7. Modification
+
+For data modification, `change` carries the substance. Prefer `changedFields` over values; see
+[change-model.md](../specification/change-model.md).
+
+`data-modification` is the category for business data. Changes to application or platform settings
+belong in `configuration`; see
+[configuration-and-change.md](configuration-and-change.md).

package/semantic-conventions/event-naming.md

@@ -0,0 +1,114 @@
+# Event Naming
+
+**Specification version: 0.1 · Status: Experimental**
+
+The normative naming rules are in [event-model.md](../specification/event-model.md) §7. This document
+gives the recommended vocabularies and the reasoning behind them.
+
+## 1. The shape
+
+```text
+domain.resource.action
+```
+
+| Segment    | Answers                   | Examples                                 |
+| ---------- | ------------------------- | ---------------------------------------- |
+| `domain`   | Which area of the system? | `authentication`, `identity`, `document` |
+| `resource` | Which kind of thing?      | `role`, `share`, `case`, `setting`       |
+| `action`   | What was done to it?      | `assign`, `create`, `close`, `update`    |
+
+Two segments are permitted where a resource segment would be artificial:
+
+```text
+authentication.login
+authentication.logout
+```
+
+Action segments may be hyphenated where the action is genuinely two words:
+
+```text
+queue.consumer.offset-reset
+identity.credential.self-service-reset
+```
+
+## 2. Recommended categories
+
+`event.category` groups names for filtering and routing. It is an open vocabulary; these values cover
+the domains this model targets:
+
+| Category               | Covers                                                   |
+| ---------------------- | -------------------------------------------------------- |
+| `authentication`       | Proving identity, sessions, factors, credentials         |
+| `identity`             | Accounts, roles, permissions, service accounts           |
+| `data-access`          | Reading, exporting, sharing, downloading                 |
+| `data-modification`    | Creating, updating, deleting business data               |
+| `configuration`        | Application and platform settings, secrets               |
+| `deployment`           | Releases, rollouts, rollbacks                            |
+| `workflow`             | Requests, approvals, case and incident lifecycle         |
+| `privileged-operation` | Administrative and break-glass operations                |
+| `data-infrastructure`  | Brokers, topics, queues, caches, database administration |
+| `security`             | Security-relevant events that fit no other category      |
+| `resource-lifecycle`   | Provisioning and decommissioning of resources            |
+
+A category is a coarse label. When an event fits two, choose the one a reviewer would filter on.
+
+## 3. Recommended activity types
+
+`event.type` is an OPTIONAL, domain-independent classifier. It exists so that a consumer can ask
+"show me every deletion" without knowing every domain's vocabulary.
+
+```text
+create   read     update   delete    execute
+approve  reject   share    grant     revoke
+login    logout   export   import    rotate
+```
+
+`event.type` never replaces `event.name`. `identity.role.revoke` and `document.permission.revoke` are
+different operations that share `type: revoke`.
+
+## 4. Rules, restated
+
+1. **Stable.** A published name keeps its meaning. If the meaning changes, the name changes.
+2. **No product names.** `document.share.create`, not `sharepointish.share.create`.
+3. **No company names.** The audit trail outlives the vendor relationship.
+4. **No jurisdiction names.** `data.export.create`, not `data.export.create-eu`.
+5. **Describe the operation, not the mechanism.** `identity.role.assign` is right whether the role was
+   assigned through a console, an API, a sync job or a script. Names that encode the mechanism
+   fragment the trail and break when the mechanism changes.
+6. **Same name for success and failure.** Use `outcome`, not a different name.
+
+## 5. The failure-name anti-pattern
+
+This is the most common naming mistake, and it is worth stating twice:
+
+```text
+authentication.login          outcome: success     ← RECOMMENDED
+authentication.login          outcome: failure     ← RECOMMENDED
+
+authentication.login-success                        ← NOT RECOMMENDED
+authentication.login-failed                         ← NOT RECOMMENDED
+```
+
+Encoding the outcome in the name doubles the vocabulary, makes "how often does this operation fail?"
+a string-matching problem, and guarantees that some operations get a failure name and others do not.
+
+## 6. Granularity
+
+Prefer the granularity a reviewer would ask about.
+
+| Too coarse            | Too fine                                        | Recommended                    |
+| --------------------- | ----------------------------------------------- | ------------------------------ |
+| `document.update`     | `document.metadata.title.update`                | `document.version.create`      |
+| `identity.change`     | `identity.role.assign.via-bulk-import`          | `identity.role.assign`         |
+| `configuration.write` | `configuration.setting.session-lifetime.update` | `configuration.setting.update` |
+
+Detail that varies per operation belongs in `resource`, `change.changedFields` and `metadata`, not in
+the name. A name is a category; a category with one member is not a category.
+
+## 7. Naming new events
+
+1. Find the closest existing convention document and follow its pattern.
+2. Use the resource type you already use in `resource.type` as the resource segment where possible.
+3. Use a verb in the imperative for the action: `assign`, not `assigned` or `assignment`.
+4. Check the name does not encode outcome, mechanism, product, company or jurisdiction.
+5. Check that a reviewer who has never seen your system can guess what it means.

package/semantic-conventions/identity-and-access.md

@@ -0,0 +1,112 @@
+# Identity and Access Events
+
+**Specification version: 0.1 · Status: Experimental**
+
+Category: `identity`
+
+## 1. Recommended event names
+
+### Accounts
+
+| Name                    | Operation                         |
+| ----------------------- | --------------------------------- |
+| `identity.user.create`  | An account was created            |
+| `identity.user.update`  | Account attributes changed        |
+| `identity.user.disable` | An account was disabled           |
+| `identity.user.enable`  | A disabled account was re-enabled |
+| `identity.user.delete`  | An account was deleted            |
+
+### Roles and permissions
+
+| Name                           | Operation                           |
+| ------------------------------ | ----------------------------------- |
+| `identity.role.create`         | A role was defined                  |
+| `identity.role.update`         | A role definition changed           |
+| `identity.role.delete`         | A role was removed                  |
+| `identity.role.assign`         | A role was granted to a principal   |
+| `identity.role.revoke`         | A role was removed from a principal |
+| `identity.permission.grant`    | A permission was granted directly   |
+| `identity.permission.revoke`   | A permission was removed            |
+| `identity.group.member-add`    | A principal joined a group          |
+| `identity.group.member-remove` | A principal left a group            |
+
+### Machine identities and sessions
+
+| Name                               | Operation                              |
+| ---------------------------------- | -------------------------------------- |
+| `identity.service-account.create`  | A machine identity was created         |
+| `identity.service-account.disable` | A machine identity was disabled        |
+| `identity.credential.rotate`       | A machine credential was replaced      |
+| `identity.session.impersonate`     | A principal began acting as another    |
+| `identity.delegation.grant`        | Authority was delegated to a principal |
+| `identity.delegation.revoke`       | A delegation was withdrawn             |
+
+## 2. Which principal goes where
+
+This is the most error-prone area in the whole model.
+
+| Operation                                  | `actor`           | `resource`             | `subject` |
+| ------------------------------------------ | ----------------- | ---------------------- | --------- |
+| Administrator assigns a role to a user     | the administrator | the **user**           | absent    |
+| User accepts an invitation                 | the user          | the user's own account | absent    |
+| Service provisions an account from HR data | the service       | the new account        | absent    |
+| Administrator impersonates a user          | the administrator | the session            | the user  |
+| Delegated administrator acts for an owner  | the delegate      | the affected resource  | the owner |
+
+The target of an identity operation is a `resource`, not a `subject`. `subject` appears only when
+someone's authority was borrowed. See [actor-model.md](../specification/actor-model.md).
+
+The role or permission being granted is a **related resource** or `metadata`, not the primary
+resource — the primary resource is what changed, and what changed is the principal's access.
+
+## 3. Context to populate
+
+| Field               | Guidance                                                                |
+| ------------------- | ----------------------------------------------------------------------- |
+| `relatedResources`  | The role, permission, group or scope involved                           |
+| `change`            | `changedFields`, and before/after where the values are safe to record   |
+| `authorization`     | The decision that permitted the change                                  |
+| `approval`          | Where access requires approval, including `not-required` when evaluated |
+| `reason`            | The access request or ticket that justifies the grant                   |
+| `metadata`          | `assignedRole`, `assignmentScope`, `effectiveFrom`, `expiresAt`         |
+| `controlCategories` | `privileged-access`, `separation-of-duties`, `change-approval`          |
+
+## 4. Privileged grants
+
+An event that grants administrative access SHOULD:
+
+- Set `event.severity` to `high` or `critical`.
+- Include `privileged-access` in `controlCategories`.
+- Populate `approval` where the operator requires approval for privileged grants.
+- Record `metadata.expiresAt` for time-bound grants, so that a reviewer can distinguish standing
+  privilege from just-in-time access.
+
+## 5. Effective time
+
+Access changes are often scheduled. `time` is when the **change was recorded**, not when it takes
+effect. Where they differ, record the effective window in `metadata`:
+
+```json
+{
+  "metadata": {
+    "assignedRole": "support-agent",
+    "effectiveFrom": "2026-03-16T00:00:00Z",
+    "expiresAt": "2026-06-16T00:00:00Z"
+  }
+}
+```
+
+A separate event SHOULD be emitted when a time-bound grant actually expires, so that the trail shows
+the access ending rather than only the intention that it would.
+
+## 6. Bulk changes
+
+Access changes are frequently bulk operations. Producers SHOULD emit one event per affected principal
+where the principals are individually significant — which, for access, they usually are. Where a bulk
+operation is recorded as one event, the count and scope MUST be recorded in `metadata`, and the
+producer MUST document the choice. See [resource-model.md](../specification/resource-model.md) §6.
+
+## 7. Example
+
+See [examples/valid/user-role-assignment.json](../examples/valid/user-role-assignment.json) for a
+complete role assignment with authorization, approval, reason and change context.

package/semantic-conventions/privileged-operations.md

@@ -0,0 +1,110 @@
+# Privileged Operations
+
+**Specification version: 0.1 · Status: Experimental**
+
+Category: `privileged-operation`
+
+## 1. What counts as privileged
+
+An operation is privileged when it can affect data or controls beyond the actor's ordinary scope.
+Concretely, when at least one of these holds:
+
+- It uses administrative authority rather than the actor's own entitlements.
+- It bypasses or disables a control.
+- It reaches across a tenant, customer or organization boundary.
+- It acts on another principal's data or identity.
+- It changes security-relevant configuration.
+- It operates directly on infrastructure rather than through the application.
+
+Privilege is a property of **the operation**, not of the account. The same account performs ordinary
+and privileged operations, and the audit trail should distinguish them.
+
+## 2. Recommended event names
+
+| Name                                | Operation                                           |
+| ----------------------------------- | --------------------------------------------------- |
+| `identity.session.impersonate`      | A principal began acting as another                 |
+| `privileged.access.request`         | Elevated access was requested                       |
+| `privileged.access.grant`           | Elevated access was granted                         |
+| `privileged.access.revoke`          | Elevated access was withdrawn                       |
+| `privileged.break-glass.activate`   | An emergency access path was used                   |
+| `privileged.break-glass.close`      | An emergency access episode was closed              |
+| `privileged.control.disable`        | A control was switched off                          |
+| `privileged.control.enable`         | A control was switched back on                      |
+| `privileged.database.query-execute` | A direct data store query was run                   |
+| `privileged.maintenance.execute`    | A maintenance operation was performed on production |
+
+Domain-specific privileged operations keep their domain name and are marked privileged through
+`controlCategories` and `severity`, rather than being renamed. `configuration.setting.update` on
+production security configuration is a privileged operation with the name it already has.
+
+## 3. Required signals
+
+For an operation the producer considers privileged, it SHOULD:
+
+1. Set `event.severity` to `high` or `critical`.
+2. Include `privileged-access` in `controlCategories`.
+3. Populate `authorization` with the decision that permitted it.
+4. Populate `reason` with a business justification.
+5. Populate `approval` where the operator requires approval, including `not-required` when that was
+   evaluated.
+6. Populate `authentication`, including `mfa`, where the operator requires re-authentication for
+   privileged actions.
+7. Populate `subject` and `delegation` where the operation was performed for someone else.
+
+The value of a privileged-operation trail is that a reviewer can answer "was this justified?" without
+asking the person who did it. An event with none of the fields above cannot answer that.
+
+## 4. Break-glass access
+
+Emergency access exists because controls sometimes have to be bypassed. The audit trail is what makes
+that acceptable.
+
+Producers SHOULD:
+
+- Emit `privileged.break-glass.activate` at the start and `privileged.break-glass.close` at the end,
+  so the episode has a duration rather than a single moment.
+- Share one `request.correlationId` across every operation performed during the episode, so the
+  entire episode can be reviewed as a unit.
+- Record `reason` with a real justification, and `reason.reference` pointing at the incident.
+- Set `event.severity` to `critical`.
+- Record `approval` even when it was retrospective, using `approvedAt` to make the sequence visible.
+
+## 5. Direct data store access
+
+Running queries directly against a production data store bypasses every application-level control,
+including the application's own audit trail.
+
+Producers that support it SHOULD record:
+
+- The store as `resource`, and the affected tables or collections in `relatedResources` where known.
+- `metadata.statementType` — `select`, `update`, `delete` — and `metadata.affectedRowCount`.
+- `metadata.queryHash` where a query needs to be identifiable across events.
+
+Producers MUST NOT record query text or parameters automatically. Both routinely contain personal
+data, and parameters in particular are the values of the very records being accessed. See
+[privacy.md](../specification/privacy.md) §2.
+
+## 6. Message broker and infrastructure operations
+
+Operations on brokers, queues and caches are administrative operations on data-carrying
+infrastructure, and are privileged when performed against production.
+
+- Use the broker family as the domain segment: `kafka.consumer.offset-reset`,
+  `rabbitmq.queue.purge`, `redis.key.delete`.
+- Record the affected topic, queue or key space in `relatedResources`.
+- Record offsets, partitions and counts in `metadata`.
+- MUST NOT record message payloads. See
+  [profiles/message-broker-management/](../profiles/message-broker-management/).
+
+See
+[examples/valid/kafka-consumer-offset-reset.json](../examples/valid/kafka-consumer-offset-reset.json).
+
+## 7. Control changes
+
+Disabling a control is the operation most worth auditing and the one most likely to go unaudited,
+because it is often performed on the system that does the auditing.
+
+Producers SHOULD emit `privileged.control.disable` and `privileged.control.enable` as a pair, record
+the control in `resource`, and record the window in `metadata`. A control that was disabled and never
+re-enabled should be visible as an open pair, not inferred from silence.

package/semantic-conventions/workflow-and-approval.md

@@ -0,0 +1,109 @@
+# Workflow and Approval Events
+
+**Specification version: 0.1 · Status: Experimental**
+
+Category: `workflow`
+
+## 1. Recommended event names
+
+### Requests and approvals
+
+| Name                         | Operation                                          |
+| ---------------------------- | -------------------------------------------------- |
+| `workflow.request.create`    | A request entered a workflow                       |
+| `workflow.request.submit`    | A request was submitted for decision               |
+| `workflow.approval.request`  | Approval was requested from one or more principals |
+| `workflow.approval.grant`    | An approver approved                               |
+| `workflow.approval.reject`   | An approver refused                                |
+| `workflow.approval.expire`   | An approval request lapsed undecided               |
+| `workflow.approval.delegate` | Approval authority was passed to another principal |
+| `workflow.stage.advance`     | A workflow moved to the next stage                 |
+| `workflow.request.cancel`    | A request was withdrawn                            |
+| `workflow.request.close`     | A request reached a terminal state                 |
+
+### Case and incident lifecycle
+
+| Name                         | Operation                             |
+| ---------------------------- | ------------------------------------- |
+| `incident.case.create`       | An incident was raised                |
+| `incident.priority.change`   | Priority was reassessed               |
+| `incident.assignment.change` | Ownership changed                     |
+| `incident.major.declare`     | An incident was escalated to major    |
+| `incident.case.resolve`      | An incident was resolved              |
+| `incident.case.close`        | An incident was closed                |
+| `incident.case.reopen`       | A closed incident was reopened        |
+| `incident.rca.create`        | A root cause analysis was recorded    |
+| `incident.rca.approve`       | A root cause analysis was approved    |
+| `incident.sla.breach`        | A service level commitment was missed |
+
+## 2. The approval object versus approval events
+
+Both exist, and they answer different questions.
+
+| Question                                        | Where it is answered                  |
+| ----------------------------------------------- | ------------------------------------- |
+| Was this operation approved?                    | `approval` on the **operated** event  |
+| Who approved what, when, and did anyone refuse? | Separate `workflow.approval.*` events |
+
+A configuration change carries `approval` describing the state of its approval. The approval decisions
+themselves — each approver, each timestamp, each rejection — are their own events, because they are
+separate auditable operations performed by different principals at different times.
+
+Producers SHOULD emit both. Recording only the summary loses who decided; recording only the decisions
+makes it impossible to tell what they authorized.
+
+## 3. Approval status transitions
+
+Recommended transitions, and the event that records each:
+
+```text
+not-required                          (no approval event; recorded on the operated event)
+pending    → approved                 workflow.approval.grant
+pending    → rejected                 workflow.approval.reject
+pending    → expired                  workflow.approval.expire
+```
+
+An operated event whose `approval.status` is `pending`, `rejected` or `expired` and whose outcome is
+`success` describes a control bypass. Producers MUST record it accurately.
+
+## 4. Context to populate
+
+| Field                        | Guidance                                                           |
+| ---------------------------- | ------------------------------------------------------------------ |
+| `resource`                   | The request, case or workflow instance                             |
+| `relatedResources`           | The resource the workflow governs, and any affected services       |
+| `approval.approvers`         | Only the principals whose decisions counted                        |
+| `approval.requiredApprovals` | The policy threshold, so a reviewer can see whether it was met     |
+| `change`                     | Status transitions, as `changedFields` with before and after       |
+| `evidence`                   | The approval record, the analysis document, the ticket             |
+| `reason`                     | Why the decision was made, where a justification is required       |
+| `request.correlationId`      | Shared across the whole workflow, so its events can be assembled   |
+| `controlCategories`          | `change-approval`, `separation-of-duties`, `incident-traceability` |
+
+## 5. Correlation across a workflow
+
+A workflow produces many events over hours or weeks, from different applications and principals. They
+are assembled by correlation, not by timestamp.
+
+Producers SHOULD:
+
+- Use one `request.correlationId` for the life of the workflow instance.
+- Use the workflow instance identifier consistently in `approval.workflowId`.
+- Reference the same case identifier in `change.incidentId` or `reason.reference`.
+
+## 6. Separation of duties
+
+Where policy requires that the approver differ from the requester, the audit trail must make the
+comparison possible. Producers SHOULD:
+
+- Record `actor` on the operated event and `approval.approvers` such that both are identifiable.
+- Include `separation-of-duties` in `controlCategories`.
+- Emit the event even when the check **passes**. A control that only produces evidence when it fails
+  cannot be shown to have been operating.
+
+The model records the facts. It does not evaluate the rule: OpenAuditModel is not a policy engine.
+
+## 7. Example
+
+See [examples/valid/incident-case-close.json](../examples/valid/incident-case-close.json) for an
+incident closure with approvals, evidence references, status transition and trace correlation.