> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultra.security/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Log

> Security audit events for compliance

Ultra's audit interceptor records security-relevant events for every MCP operation. The audit log provides a compliance-ready trail of who did what, when, and whether it was allowed.

## Audit Event Structure

| Field        | Type     | Description                                                                              |
| ------------ | -------- | ---------------------------------------------------------------------------------------- |
| `id`         | string   | Unique event identifier                                                                  |
| `trace_id`   | string   | Linked trace ID (if applicable)                                                          |
| `event_type` | string   | Event classification (see below)                                                         |
| `severity`   | string   | `info`, `warning`, `error`, `critical`                                                   |
| `upstream`   | string   | Upstream server involved                                                                 |
| `action`     | string   | The tool/resource/prompt name or action                                                  |
| `principal`  | string   | MCP Client/Agent identity                                                                |
| `outcome`    | string   | `allow`, `deny`, `alert`, `monitor`, `redact`, `error`, `success`, `failure`, `canceled` |
| `reason`     | string   | Why (for deny/error outcomes)                                                            |
| `details`    | map      | Flexible key-value context                                                               |
| `timestamp`  | datetime | When the event occurred                                                                  |

### Multi-Tenant Fields

| Field             | Description                                                                                                                                                                                                |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace_id`    | Workspace context                                                                                                                                                                                          |
| `gateway_id`      | Gateway that recorded the event                                                                                                                                                                            |
| `organization_id` | Organization context                                                                                                                                                                                       |
| `user_id`         | User who performed the action                                                                                                                                                                              |
| `user_email`      | User's email address                                                                                                                                                                                       |
| `user_name`       | User's display name                                                                                                                                                                                        |
| `user_role`       | Organization role of the user (e.g. `owner`, `admin`, `member`)                                                                                                                                            |
| `user_member`     | Whether the user is a current member of the organization. `true` for active members, `false` for observed non-members, omitted when membership has not been resolved (for example, in standalone gateways) |
| `user_assurance`  | Strength of the identity attribution for this event — see [Identity attribution](#identity-attribution)                                                                                                    |

### Identity attribution

Each audit event carries an attribution tier indicating how confidently Ultra associated the activity with a specific user. The Hub dashboard renders this as a small coloured dot next to the user's name in the audit drawer and trace drawer. See the [Identities](/hub/identities) page for the full attribution model and how each identity rolls up across the dashboard.

| `user_assurance` | Meaning                                                                                                                                             | Dashboard indicator |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `authenticated`  | The event was performed by a logged-in user with an active session                                                                                  | Green dot           |
| `gateway`        | The event was attributed via the gateway's registered owner rather than a session — typical for unauthenticated stdio traffic on a personal gateway | Amber dot           |
| `none`           | No identity could be attributed                                                                                                                     | Grey dot            |

When `user_member` is `false`, the dashboard also displays a **Non-member** badge next to the user's name. This indicates the user was observed in activity but is no longer a member of the organization — useful for spotting access by offboarded employees or external identities that were never granted membership.

## Event Types

| Event Type            | When It's Recorded                                                                                    |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| `tool_call`           | An MCP tool was called                                                                                |
| `resource_read`       | An MCP resource was read                                                                              |
| `prompt_get`          | An MCP prompt was retrieved                                                                           |
| `policy_deny`         | A policy denied a request                                                                             |
| `policy_allow`        | A policy explicitly allowed a request                                                                 |
| `auth_failure`        | Authentication failed                                                                                 |
| `auth_success`        | Authentication succeeded                                                                              |
| `config_change`       | Configuration was modified                                                                            |
| `server_start`        | Ultra server started                                                                                  |
| `server_stop`         | Ultra server stopped                                                                                  |
| `upstream_connect`    | Connected to an upstream server                                                                       |
| `upstream_disconnect` | Disconnected from an upstream server                                                                  |
| `guardrail`           | A guardrail evaluated a request                                                                       |
| `governance`          | A governance rule or default posture allowed or denied a request, or a governance posture was changed |
| `token_refresh`       | An authentication token was refreshed                                                                 |
| `error`               | An error occurred                                                                                     |

## Severity Levels

| Level      | Description       | Examples                                  |
| ---------- | ----------------- | ----------------------------------------- |
| `info`     | Normal operations | Tool calls, resource reads                |
| `warning`  | Potential issues  | Auth token expiring, slow responses       |
| `error`    | Failures          | Upstream connection errors, tool failures |
| `critical` | Security events   | Auth failures, policy denials             |

## Outcomes

| Outcome    | Description                                                        |
| ---------- | ------------------------------------------------------------------ |
| `allow`    | Operation was permitted                                            |
| `deny`     | Operation was blocked                                              |
| `alert`    | Guardrail matched and generated a warning, but allowed the request |
| `monitor`  | Guardrail matched silently for visibility only                     |
| `redact`   | Guardrail matched and masked sensitive content before forwarding   |
| `error`    | Operation failed with an error                                     |
| `success`  | Operation completed successfully                                   |
| `failure`  | Operation did not complete                                         |
| `canceled` | Operation was canceled                                             |

## Audit Completeness

The audit layer is designed to block a successful operation if it can't be recorded. There is no way for an operation to succeed without being captured in the audit log.

This is a deliberate security design choice. For compliance-sensitive deployments, it guarantees that every successful operation has a corresponding audit record.

## Querying Audit Events

### Dashboard

The web dashboard provides an audit log viewer with filtering:

```bash theme={null}
ultra dashboard
```

### Query Options

Audit events can be filtered by:

* Event type, severity, outcome
* Upstream server
* MCP Client/Agent (principal)
* User ID, organization ID
* Time range
* Workspace and gateway (for Hub deployments)

Each event has a **Copy link** button to share a deep link to it, and the filtered list can be downloaded with the **Export** control as CSV or JSON. See [Exporting table data](/observability/dashboard#exporting-table-data) and [Sharing links](/observability/dashboard#sharing-links).