83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
# Audit Trace Context
|
|
|
|
Operational audit entries should let an administrator answer four questions:
|
|
|
|
- who initiated the operation
|
|
- what object was changed
|
|
- which lifecycle request or run carried the change
|
|
- how the entry connects to surrounding request, installer, or worker logs
|
|
|
|
The actor, tenant, scope, action, object type, and object ID remain first-class
|
|
`audit_log` columns. Additional operational context belongs in `details`.
|
|
|
|
## Standard Fields
|
|
|
|
Use these fields for admin, module lifecycle, installer, and worker operations:
|
|
|
|
- `module_id`: module affected by the operation, when a single module is the
|
|
target.
|
|
- `request_id`: queued installer/admin request identifier.
|
|
- `run_id`: installer/worker run identifier.
|
|
- `outcome`: compact state such as `planned`, `queued`, `applied`,
|
|
`cancelled`, `failed`, or `completed`.
|
|
- `_trace.correlation_id`: request or workflow correlation ID.
|
|
- `_trace.causation_id`: event, run, or operation that caused this audit entry.
|
|
|
|
Bulk operations may also include concise arrays such as `activated`,
|
|
`deactivated`, `mounted`, `planned_modules`, or sanitized `items`.
|
|
|
|
## Access Provenance
|
|
|
|
Access-sensitive events should include a compact provenance array when the
|
|
decision depends on semantic access state. Use `details.access_provenance` with
|
|
items shaped like `AccessDecisionProvenance.to_dict()` from
|
|
`govoplan_core.core.access`.
|
|
|
|
Expected provenance kinds:
|
|
|
|
- `identity`
|
|
- `account`
|
|
- `tenant_membership`
|
|
- `organization_unit`
|
|
- `function`
|
|
- `group`
|
|
- `role`
|
|
- `right`
|
|
- `delegation`
|
|
- `policy`
|
|
- `system_actor`
|
|
|
|
Delegation and acting-in-place events must show both the real actor account and
|
|
the represented/delegated account or function assignment. Feature modules
|
|
should obtain this shape through `access.explanation` instead of inspecting
|
|
access tables directly.
|
|
|
|
## Redaction
|
|
|
|
Audit detail payloads must not contain credentials, tokens, raw cookies,
|
|
authorization headers, private keys, message bodies, uploaded file content, or
|
|
other secret material. Use stable IDs, vault references, or package identifiers
|
|
instead.
|
|
|
|
The compatibility helper in core, `audit_operation_context`, keeps the standard
|
|
fields compact and applies the shared audit redaction pass to additional detail
|
|
values. Feature modules should follow the same shape even when they later write
|
|
through a dedicated audit sink capability.
|
|
|
|
## Module Lifecycle Events
|
|
|
|
Module install, uninstall, enable, disable, rollback, and package-catalog
|
|
acceptance events should include:
|
|
|
|
- `object_type`: `module_install_plan`, `module_install_request`,
|
|
`module_state`, or another stable lifecycle object type.
|
|
- `object_id`: module ID for single-module actions, otherwise `global` or the
|
|
request/run ID.
|
|
- `details.module_id`, `details.request_id`, or `details.run_id` when present.
|
|
- `details.outcome` with the lifecycle result.
|
|
- `details._trace` when the operation originated from a request or queued
|
|
daemon action.
|
|
|
|
This keeps admin UI timelines, audit exports, and rollback diagnostics aligned
|
|
without coupling modules to the audit table implementation.
|