Ajutant feature 043: audit logging

Ajutant feature 043: audit logging

Feature id: 043

Status: shipped

What it does: Ajutant records an immutable audit trail in an external audit store (Azure Log Analytics) and provides an admin viewer and export for clients.

What you get

• Immutable audit trail stored externally in Azure Log Analytics
• Queryable audit events for compliance and investigations
• Dedicated admin UI to view and export audit logs
• Audit coverage for:
  • Significant lifecycle actions (for example, create, publish, discard)
  • Kill switch operations
  • Access and authentication events (including failures)
  • Role changes
  • Audit log viewing and exporting (viewer/export actions)

Dependencies and prerequisites

This feature depends on earlier phases so there are meaningful events to log.

• Phases 1 to 3 (core versioning, kill switch, draft/publish workflow) should be complete so audit events correspond to real operations.

What gets audited

The feature specification states that every significant action is automatically captured as an audit event with contextual metadata and sent to the immutable external audit store.

Audit events covered by the acceptance scenarios

The following event types are explicitly listed in the spec overview acceptance scenarios:

Event type	When it is recorded	Key details mentioned in the spec
assistant.created	An admin creates and saves a new assistant	tenant_id, user_id, user_email, user_role, entity details, timestamp
version.published	An admin publishes an assistant draft	version number, superseded version, entity name
version.draft_discarded	An admin discards a draft	(event recorded on discard completion)
kill_switch.activated	An admin activates a kill switch	scope, target details, reason
kill_switch.lifted	An admin lifts a kill switch	duration, original reason
user.login	A user authenticates via Azure AD	authentication method, success: true/false
user.role_changed	An admin changes a user role	old role, new role
audit_log.viewed	A client views audit logs in the admin UI	(viewer action is audited)
audit_log.exported	A client exports audit logs	(export action is audited)

Authentication success and failure

The spec clarifies that audit logging includes both successful and failed login attempts.

• Successful Azure AD authentication: user.login with success: true
• Failed Azure AD authentication: user.login with success: false

Audit log access (viewer and export)

The spec clarifies that viewing and exporting the audit log itself generates audit events:

• audit_log.viewed
• audit_log.exported

It also notes that direct Azure Log Analytics access is covered natively by Azure Activity Logs.

How alerts are handled for audit delivery failures

The spec does not require a custom in-app notification system.

• Platform Admin alerting for persistent audit delivery failures is done via:
  • Structured application log entries
  • Azure Monitor alert rules to route notifications (for example, email or Teams)

How to test (mandatory scenarios)

The spec includes an independent test approach and acceptance scenarios. You can validate the feature by performing the listed actions and confirming the corresponding audit events appear in the audit store with required fields.

Independent test approach

• Perform actions such as:
  • Create assistant
  • Publish draft
  • Activate kill switch
• Verify corresponding audit events appear in the immutable audit store with required fields populated.

Acceptance scenarios to verify

1. Assistant creation

   • Given an admin creates a new assistant
   • When the assistant is saved
   • Then an assistant.created audit event is recorded with tenant_id, user_id, user_email, user_role, entity details, and timestamp

2. Version publish

   • Given an admin publishes an assistant draft
   • When the publish operation completes
   • Then a version.published event is recorded including the version number, superseded version, and entity name

3. Draft discard

   • Given an admin discards a draft
   • When the discard completes
   • Then a version.draft_discarded event is recorded

4. Kill switch activation

   • Given an admin activates a kill switch
   • When the kill switch is applied
   • Then a kill_switch.activated event is recorded with scope, target details, and reason

5. Kill switch lifted

   • Given an admin lifts a kill switch
   • When the kill is lifted
   • Then a kill_switch.lifted event is recorded with duration and original reason

6. Login success

   • Given a user logs in via Azure AD
   • When authentication succeeds
   • Then a user.login event is recorded with the authentication method and success: true

7. Login failure

   • Given a user attempts to log in via Azure AD
   • When authentication fails
   • Then a user.login event is recorded with the authentication method and success: false

8. Role change

   • Given an admin changes a user’s role
   • When the role change is saved
   • Then a user.role_changed event is recorded with old and new roles

Viewing and exporting audit logs

The spec states that clients can view and export their audit logs through a dedicated admin UI.

• Viewing generates audit_log.viewed
• Exporting generates audit_log.exported

Compliance context (as stated in the spec)

The feature is intended to support compliance with:

• SOC 2
• GDPR Article 30
• ISO 27001

It does this by providing a comprehensive audit logging capability with an immutable external audit store (Azure Log Analytics) and an admin viewer/export.

---

Note for reviewers: The provided source text cuts off mid-way through the user story list (it ends at “Given an admi”). This document only includes event types and details that are explicitly present in the provided spec overview and clarifications.