Skip to content

Contract: Security audit events

Status

Canonical.

Purpose

This contract defines the minimum structure and behavior for security-relevant audit events.

Contract

Security-relevant actions must produce durable audit events.

Audit events must be append-only from normal application flows.

Required fields

A security audit event must include:

  • event identifier;
  • event timestamp;
  • actor identifier;
  • company identifier when the action is company-scoped;
  • action name;
  • target type;
  • target identifier when applicable;
  • result;
  • reason/comment when applicable;
  • machine or installation identifier when available;
  • correlation identifier when part of a larger workflow.

Rules

  • Audit events must not be edited through ordinary application behavior.
  • Audit events must preserve historical actor identity.
  • Failed authorization or failed step-up confirmation may be logged when relevant.
  • Sensitive exports, backup restores, user changes, and permission changes must be logged.
  • Correction staging actions and reversal or adjustment posting attempts must be logged with their stable protected action name and result.
  • Close evaluation, waiver, approval, abandonment, finalization, and reopen attempts must be logged with the stable actions and targets defined by the Close Run Contract.
  • Formal report viewing and ReportRun capture attempts must be logged with report.view or report_run.capture and the stable definition or ReportRun target defined by the Reporting Contract.
  • Sales-tax return and remittance staging, readiness, filing approval, external-filing evidence, abandonment, remittance approval, external-payment evidence, remittance posting, remittance abandonment, and bank-match attempts must use the stable action and target defined by the Sales Tax Accounting and Remittance Contract. Audit payloads must exclude tax-provider, bank, and payment credentials.
  • Company conversion staging, mapping, reconciliation, approval, application, failure, abandonment, and supersession attempts must use the stable action and CompanyConversionRun target defined by the Company Conversion Run Contract.
  • Successful reversal or adjustment audit evidence targets the corrected entry; the correction workflow record links the audit event and resulting correction entry.
  • Audit events must be readable by authorized reviewers.
  • Protected action audit events must use the same action names as the protected action registry.
  • Company-scoped audit events must use company identity as defined by the Company Identity and Context contract.
  • Development and test actors must produce ordinary audit events when they perform protected actions.

Acceptance criteria

  • Creating a user emits an audit event.
  • Changing permissions emits an audit event.
  • Closing or reopening a period emits an audit event.
  • Exporting company data emits an audit event.
  • Restoring a backup emits an audit event.
  • A developer test actor performing a protected action emits an audit event with actor, company, action, result, and correlation context when available.
  • Successful, denied, and failed correction posting attempts preserve company, actor, action, target, result, reason, and correlation context.
  • Successful, denied, and failed consequential Close attempts preserve company, actor, action, CloseRun or financial-period target, result, reason, machine context when available, and correlation context.
  • Successful, denied, and failed Reporting attempts preserve company, actor, action, report definition or ReportRun target, result, machine context when available, and correlation context. A succeeded capture audit id remains linked from the immutable ReportRun.
  • Successful, denied, and failed sales-tax control attempts preserve company, actor, stable action, return-control or remittance target, result, reason when required, machine context when available, correlation context, and linked workflow result without credential values.
  • Successful, denied, and failed company-conversion attempts, including interrupted or replayed attempts, preserve company, actor, stable action, CompanyConversionRun target, result, reason when applicable, machine context when available, correlation context, and links required by the conversion status history.

Related truth:

  • ../accounting-correction.contract.md
  • ../close-run.contract.md
  • ../reporting.contract.md
  • ../sales-tax-accounting-and-remittance.contract.md
  • ../company-conversion-run.contract.md