# Audit Event Taxonomy {#audit-event-taxonomy}


This document defines the complete taxonomy of audit events across all MQUAD services. It covers what to audit, what to skip, the event schema, and which events each service produces.


## Scope: What NOT to Audit {#scope-what-not-to-audit}


The following paths and actions are excluded from audit logging:

- Health checks (`/health`, `/health/`)
- Metrics (`/metrics`)
- Application configuration reads
- Debug endpoints
- Static assets


## What TO Audit {#what-to-audit}



### 1. Authentication & Access {#1-authentication--access}


| Action | Description | Resource |
|--------|--------------|----------|
| `login.success` | User successfully logged in | Session |
| `login.failure` | Login attempt failed | Session |
| `logout` | User logged out | Session |
| `password_changed` | Password updated | User |
| `password_reset` | Password reset requested | User |
| `mfa_enabled` | MFA enabled | User |
| `mfa_disabled` | MFA disabled | User |
| `token_revoked` | JWT/token revoked | Token |
| `role_changed` | User role modified | User |
| `permission_changed` | Permission modified | Role |
| `user_invited` | User invited to workspace | Workspace |
| `user_removed` | User removed from workspace | Workspace |


### 2. Tenant/Workspace Management {#2-tenantworkspace-management}


| Action | Description | Resource |
|--------|--------------|----------|
| `workspace.created` | Workspace created | Workspace |
| `workspace.deleted` | Workspace deleted | Workspace |
| `workspace.settings_changed` | Workspace settings modified | Workspace |
| `domain_added` | Custom domain added | Workspace |
| `domain_removed` | Custom domain removed | Workspace |


### 3. Survey Lifecycle {#3-survey-lifecycle}


| Action | Description | Resource |
|--------|--------------|----------|
| `survey.created` | Survey created | Survey |
| `survey.updated` | Survey modified | Survey |
| `survey.deleted` | Survey deleted | Survey |
| `survey.published` | Survey published | Survey |
| `survey.unpublished` | Survey unpublished | Survey |
| `xlsform_imported` | XLSForm imported | Survey |
| `survey_schema_changed` | Survey schema version changed | Survey |


### 4. Form Responses {#4-form-responses}


| Action | Description | Resource |
|--------|--------------|----------|
| `response.submitted` | Response submitted | Response |
| `response.edited` | Response modified | Response |
| `response.deleted` | Response deleted | Response |
| `responses.bulk_import` | Bulk import of responses | Response |
| `responses.exported` | Responses exported | Response |


### 5. Media & File Access {#5-media--file-access}


| Action | Description | Resource |
|--------|--------------|----------|
| `file.uploaded` | File uploaded | File |
| `file.deleted` | File deleted | File |
| `signed_url.generated` | Signed URL generated | File |
| `file.downloaded` | File downloaded | File |


### 6. Admin / Dangerous Actions {#6-admin--dangerous-actions}


| Action | Description | Resource |
|--------|--------------|----------|
| `feature_flag_changed` | Feature flag modified | Feature |
| `system_settings.updated` | System settings changed | Settings |
| `api_key.created` | API key created | APIKey |
| `api_key.revoked` | API key revoked | APIKey |
| `webhook.created` | Webhook created | Webhook |
| `webhook.modified` | Webhook modified | Webhook |
| `webhook.deleted` | Webhook deleted | Webhook |


## Audit Event Schema {#audit-event-schema}


```json
{
  "event_id": "uuid",
  "timestamp": "ISO8601 UTC",
  "service_name": "string",
  "environment": "development|production",

  "tenant_id": "uuid",
  "workspace_id": "uuid",

  "actor_type": "user|api_key|system",
  "actor_id": "uuid",
  "actor_email": "email",

  "action": "login.success",
  "resource_type": "survey|response|workspace|user|file|role|api_key",
  "resource_id": "uuid",

  "status": "success|failure",
  "ip_address": "string",
  "user_agent": "string",

  "metadata": {}
}
```


## Services and Their Audit Events {#services-and-their-audit-events}



### backend (Port 8000) {#backend-port-8000}
- Authentication events (login/logout/password)
- User management
- Workspace/tenant events
- API key management


### survey-service (Port 8001) {#survey-service-port-8001}
- Survey CRUD
- Survey publish/unpublish
- XLSForm import
- Schema changes


### data-service (Port 8002) {#data-service-port-8002}
- Response submission/editing/deletion
- Bulk import/export
- File downloads


### form-service (Port 8010) {#form-service-port-8010}
- Form building events


### webhook-service (Port 8007) {#webhook-service-port-8007}
- Webhook CRUD


### media-service (Port 8011) {#media-service-port-8011}
- File upload/delete
- Signed URL generation


## Implementation Notes {#implementation-notes}


1. **Whitelist Approach**: Only audit events in the whitelist are captured
2. **Skip Paths**: Do NOT audit health, metrics, docs, static assets
3. **Action Types**: Map HTTP methods to audit actions appropriately
   - POST -> create (only for audit events)
   - PUT/PATCH -> update (only for audit events)
   - DELETE -> delete (only for audit events)
4. **No GET**: Reading data is NOT an audit event (except file downloads)