> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/saas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/saas/govern/detect-introduction/index.md).

# Audit

Learn about the components of the universal audit model and what platforms support query audit

Immuta’s universal audit model (UAM) provides audit logs with a consistent structure for query, authentication, policy, project, and tag events from your Immuta users and data sources. You can view the information in these UAM audit logs on the [audit dashboards](https://documentation.immuta.com/saas/govern/detect-introduction/detection/detect-concept.md) or [export the full audit logs to S3 and ADLS](#audit-export-workflow) for long-term backup and processing with log data processors and tools.

The events captured are events relevant to user and system actions that affect Immuta or the integrated data platforms, such as creating policies or data sources and running queries.

See a list of the events captured and example schemas on the [UAM schema reference guide](https://documentation.immuta.com/saas/govern/detect-introduction/index/reference-guides/uam-schema.md).

{% hint style="info" %}
**Retain audit logs long-term**

Audit logs in Immuta expire after 90 days. To keep audit logs for compliance or long-term analysis, [export them to S3 or ADLS Gen2](#audit-export-workflow).
{% endhint %}

## Event types

UAM audit logs fall into two categories.

### Application events

Application events record how Immuta is used, details about who took what action, and when:

* Policy creation, updates, and deletions
* Changes to data source metadata, including applied tags
* User and group attribute changes that affect entitlements
* Access requests and approvals
* Permission changes

Application events help you trace how access decisions were made over time. For example, if a user gains access to a data source tagged as sensitive, application events show whether that access came from a new policy, a group change, a new user attribute, or a tag applied to the data source.

### Query events

Query events record governed data access in [supported platforms](#audit-support-for-platform-queries), including which user queried which data source, when, and, where supported, which columns were accessed. See the [query audit logs reference guides](https://documentation.immuta.com/saas/govern/detect-introduction/index/reference-guides/query-audit-logs.md) for the details captured for each platform.

## Event structure

All UAM events share a consistent structure, so you can filter and join events of different types. The following fields are common to most events:

| Field                       | Description                                                                                         |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| `action`                    | The base action performed on the target, such as `CREATE`, `UPDATE`, `DELETE`, or `QUERY`.          |
| `actionStatus`              | The outcome of the action, such as `SUCCESS`, `FAILURE`, or `UNAUTHORIZED`.                         |
| `targetType`                | The type of Immuta object affected by the action, such as `USER`, `POLICY`, `DATASOURCE`, or `TAG`. |
| `targets`                   | The specific objects affected by the action.                                                        |
| `actor`                     | The user or system that performed the action, including their Immuta user ID and identity provider. |
| `eventTimestamp`            | When the action occurred.                                                                           |
| `receivedTimestamp`         | When Immuta received the event.                                                                     |
| `sessionId` and `requestId` | Identifiers for correlating related events from the same session or request.                        |
| `relatedResources`          | Other objects involved in the event, such as the tag or attribute applied.                          |
| `auditPayload`              | Event-specific details, such as the attribute value applied or the objects accessed by a query.     |

For the full schema of each event, see the [UAM schema reference guide](https://documentation.immuta.com/saas/govern/detect-introduction/index/reference-guides/uam-schema.md).

## Events for common audit questions

Use the following table to find the events that answer common governance and compliance questions. For examples of querying these events in exported logs, see [Monitor key events in exported audit logs](https://documentation.immuta.com/saas/govern/detect-introduction/index/how-to-guides/monitor-key-events-in-exported-audit-logs.md).

| Question                                                             | Events                                                                                                 |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| How have user entitlements changed over time?                        | `SubscriptionUpdated`, `SubscriptionDeleted`                                                           |
| Who approved access to a data source?                                | `SubscriptionRequestApproved`, `SubscriptionCreated`                                                   |
| Which tags were applied to or removed from data sources and columns? | `TagApplied`, `TagRemoved`                                                                             |
| Which tags were created, updated, or deleted in Immuta?              | `TagCreated`, `TagUpdated`, `TagDeleted`                                                               |
| Which user attributes were applied or removed?                       | `AttributeApplied`, `AttributeRemoved`                                                                 |
| Are users being created or updated in Immuta instead of in your IAM? | `UserCreated`, `UserCloned`, `UserDeleted`, `UserUpdated`                                              |
| Which Immuta permissions were changed?                               | `PermissionApplied`, `PermissionRemoved`, `DomainPermissionsUpdated`                                   |
| Who created, updated, or deleted a global policy?                    | `GlobalPolicyCreated`, `GlobalPolicyUpdated`, `GlobalPolicyDeleted`                                    |
| Which data sources did a policy change affect?                       | `GlobalPolicyUpdated`, followed by `DatasourceGlobalPolicyApplied` and `DatasourceGlobalPolicyRemoved` |
| Has sensitive data been tagged?                                      | `TagApplied`                                                                                           |
| Who accessed what data and when?                                     | Query events, using `actionStatus`, `eventTimestamp`, and `auditPayload.objectsAccessed`               |
| Who queried sensitive data?                                          | Query events, using `auditPayload.securityProfile.sensitivity`                                         |
| Did anyone try to access data they aren't authorized to see?         | Query events where `actionStatus` is `UNAUTHORIZED`                                                    |
| When were new data sources registered?                               | `DatasourceCreated`                                                                                    |
| Were Immuta app settings changed?                                    | `ConfigurationUpdated`                                                                                 |

## Audit export workflow

{% hint style="info" %}
**Public preview:** This feature is available to all accounts.
{% endhint %}

1. When you configure the audit export using the CLI for [S3](https://documentation.immuta.com/saas/govern/detect-introduction/index/how-to-guides/enable-uam.md#using-the-immuta-cli) and [ADLS](https://documentation.immuta.com/saas/govern/detect-introduction/index/how-to-guides/export-adls.md#using-the-immuta-cli), Immuta stores the export endpoint you provided.
2. After the integration endpoint has been configured, the export scheduler will run on the schedule you defined in your configuration.
3. When users query data and the event is audited, Immuta receives events from your Snowflake, Databricks Spark, Databricks Unity Catalog, or Starburst (Trino) integration.
4. Immuta exports the audit logs to your configured S3 bucket or ADLS container.

You can specify an S3 bucket destination where Immuta will periodically export audit logs when using S3. When using ADLS, you can specify the container destination where Immuta will export audit logs. If desired, users can configure both export options to export their audit logs to S3 and ADLS simultaneously.

## Audit support for platform queries

The table below outlines what information is included in the query audit logs for each integration where query audit is supported.

<table data-full-width="false"><thead><tr><th></th><th>Snowflake</th><th>Databricks Spark</th><th>Databricks Unity Catalog</th><th>Starburst (Trino)</th></tr></thead><tbody><tr><td>Table and user coverage</td><td>Registered data sources and users</td><td>Registered data sources and users</td><td>All tables and users</td><td>Registered data sources and users</td></tr><tr><td>Object queried</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>Columns returned</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>Rows returned</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>Query text</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>Unauthorized information</td><td><a data-footnote-ref href="#user-content-fn-1">Limited support</a></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td></tr></tbody></table>

**Legend**:

* :white\_check\_mark: This is available and the information is included in audit logs.
* :x: This is not available and the information is not included in audit logs.

## Limitations

Immuta audit logs cover actions in Immuta and queries in the platforms Immuta governs. Immuta audit does not capture the following:

* System-level logging and debugging information, such as 404 errors.
* Activity outside governed platforms, such as access to data sources not connected to Immuta.
* Failed SSO login attempts. Use your SSO provider's audit logs for these events.

### Snowflake query audit limitation

Snowflake query audit events from a query using cached results will show `0` for the `rowsProduced` field.

### Unity Catalog query audit limitations

* Immuta determines unauthorized events based on error messages within Unity Catalog records. When the error messages contain expected language, unauthorized events will be available for Databricks Unity Catalog audit logs. In other cases, it is not possible to determine the cause of an error.
* Immuta audit records include unregistered data sources and users; however, activity from them will not appear in any [governance reports](https://documentation.immuta.com/saas/govern/detect-introduction/index/reference-guides/reports.md).
* Databricks queries where the response is being served from cache will not be represented in the `system.access.column_lineage` table which means the query audit records will be unmapped in Immuta.
* The Databricks tables used to populate Immuta audit logs may be populated with a delay, so Immuta has a 5 hour buffer for updates with each audit ingest. When an audit event is first ingested, Immuta will create an audit log, even if it is missing details. If on a later audit ingest the Databricks tables have new details about the audit event, Immuta will update the audit log with the new information.
  * If using Immuta's audit export, there may be multiple records for a single Databricks query event due to updates. If this scenario occurs and you have multiple audit logs for the same event, they can be matched with the `id` field, and the audit log with the most recent `receivedTimestamp` should be used. Then, the additional logs with the missing `objectsAccessed` can be deleted. This is more likely to happen on setups with a shorter audit export window.

### Starburst (Trino) limitation

* Audit for unauthorized access is not currently supported.
* `objectsAccessed` is not available with Hive or Iceberg views.
* `columnsAccessed` will include columns related to the query that were not actually accessed in some cases:
  * For row access policies that rely on a column in the queried table, even if that column was not a part of the query, it will be included in the `columnsAccessed`.
  * For conditional masking, if the policy protects a column accessed, then the conditional column will be included in the `columnsAccessed`.

[^1]: Unauthorized audit records will show a table name, but will not be connected to an Immuta data source.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.immuta.com/saas/govern/detect-introduction/index.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
