# Monitor audit logs

Effective security monitoring depends on comprehensive, timely audit logs. This guide explains how to ingest and analyze Foundry audit logs to maintain oversight of user activity, detect security incidents, and ensure compliance with organizational policies.

## Overview

Audit logs capture critical information about every action taken in Foundry, enabling you to understand:

* **Who** performed an action (user identity, session, or token).
* **What** the action was (categorized by type and intent).
* **When** the action happened (with precise timestamps).
* **Where** the action occurred (which resources were involved).

These logs may contain contextual information including Personally Identifiable Information (PII) such as names and email addresses. Access should be restricted to personnel with appropriate security qualifications.

## Audit log delivery

Foundry provides flexible delivery mechanisms to support diverse security infrastructure and Security Information and Event Management (SIEM) requirements.

### Choose your delivery method

**For external SIEM integration (`audit.3` only, preferred):**
External SIEMs can continuously poll `audit.3` logs directly using Palantir's audit API endpoints. The [`list-log-files` endpoint](../../api/v2/audit-v2-resources/log-files/list-log-files/index.md) lists available log files filtered by date range, and the [`get-log-file-content` endpoint](../../api/v2/audit-v2-resources/log-files/get-log-file-content/index.md) retrieves the content of specific log files. This approach is preferred for organizations with dedicated security operation centers and established SIEM platforms, offering low latency for timely detection and response.

**For Foundry-based analysis:**
For organizations without dedicated SIEM tooling or organizations with lighter analytical needs, both `audit.2` and `audit.3` logs can be exported to per-organization Foundry datasets. Organization admins configure the target file system location during setup. Once exported, logs can be analyzed directly in Foundry or forwarded to an external SIEM through Foundry's Data Connection application.

Refer to our [audit delivery](../audit-logs-overview/index.md#audit-delivery) documentation for detailed API endpoint information and export setup instructions.

### Data integrity

The infrastructure through which audit logs flow from generation to storage is engineered to be append-only, ensuring audit trail integrity. Access to log archival storage is aggressively restricted. If information captured in audit logs must be removed for legal purposes, you can work with Palantir Support directly to identify a remediation plan to eradicate the suspected disallowed data in place within audit log storage.

## Common monitoring use cases

Upon ingesting audit logs, security and compliance teams typically focus on themes described in the following sections.

### Security monitoring and incident response

Detect and respond to potential security incidents, including the following:

* **Compromised accounts:** Unusual login patterns, geographic anomalies, or impossible travel scenarios.
* **Data exfiltration attempts:** Large-scale data loads followed by exports, especially outside normal working hours.
* **Privilege escalation:** Unexpected permission changes or access to resources beyond normal scope.
* **Malicious code execution:** Code executed with suspicious patterns or from unexpected sources.

**Example investigation workflow:**

A security analyst receives an alert about unusual data access by a user account. Using `audit.3` logs with category filtering:

1. Query for all logs within a certain `time` filter where `categories` contains `dataLoad` for the user in question.
2. Examine the `resultFields` to identify exactly which datasets were accessed.
3. Query for logs where `categories` contains `dataExport` to verify whether any data was actually exported.
4. Review the `users` and `entities` fields to understand the complete activity timeline.
5. Contact the user to understand business context and determine if activity was legitimate.

The structured audit log categories eliminate the need to know which specific Foundry services or event names to search for; the analyst can focus on understanding behavior rather than navigating system architecture.

### Accountability and compliance

For organizations handling sensitive or regulated data:

* **Access auditing:** Verify data was accessed only within approved scope and for legitimate purposes.
* **Privilege abuse detection:** Identify when authorized users exceed their intended access patterns.
* **Regulatory compliance:** Demonstrate adherence to data protection regulations through comprehensive audit trails.
* **Legal hold support:** Quickly retrieve complete activity records for specific users or data assets.

**Example compliance workflow:**

A compliance team needs to verify that patient data exports only occurred for users with appropriate training certifications:

1. Query for all logs within a certain `time` filter where `categories` contains `dataExport` and resources match patient datasets.
2. Cross-reference the `uid` field against internal certification records.
3. Set up continuous monitoring to alert on any exports by users.
4. Generate periodic compliance reports showing all data access and export activity.

## Work with audit categories

Audit logs are organized into [audit categories](../audit-log-categories/index.md) that group related events by intent and action type. Categories provide a product-agnostic way to identify relevant events; for example, the `dataExport` category captures all data export events regardless of which Foundry application performed the export.

This abstraction enables security analysts to reason about user behavior without deep knowledge of Foundry's internal architecture. When investigating potential data exfiltration for example, simply filter for `dataExport` rather than enumerating dozens of product-specific event names. Categories frequently used in security monitoring and compliance workflows might include the following:

| Category | Description | Example use case |
|----------|-------------|------------------|
| `authenticationCheck` | Checks authentication status via a programmatic or manual authentication event, such as token validation. | Detect token validation patterns that suggest credential stuffing. |
| `dataCreate` | Indicates the addition of some new entry of data into the platform where it did not exist prior. This event may be reflected as a `dataPromote` in a separate service if it is logged in the landing service. | Track data creation patterns and enforce governance policies. |
| `dataDelete` | Related to the deletion of data, independent of the granularity of that deletion. | Alert on deletion of critical or protected resources. |
| `dataExport` | Export of data from the platform. Use for things like downloading data from the platform, such as a system external to Palantir, CSV file and more. If data was exported to another Palantir system, use the `dataPromote category.` | Alert on large exports, exports of sensitive data, or exports outside business hours. |
| `dataImport` | Imports to the platform. Unlike `dataPromote`, `dataImport` refers only to data being ingested from outside the platform. This means that a `dataImport` in one service could show up as a `dataPromote` in a separate service. | Monitor for malicious file uploads or policy violations. |
| `dataLoad` | Refers to the loading of data to be returned to a user. For purely backend loads, use `internal`. | Establish baseline normal access patterns and detect anomalous bulk data access. |
| `tokenGeneration` | Action that leads to generation of a new token. | Detect unusual token creation that could indicate preparation for bulk data access. |
| `userLogin` | Login events of users. | Monitor for failed login attempts, unusual login times, or geographic anomalies. |
| `userLogout` | Logout events of users. | Track session durations and identify abnormally long sessions. |

For the complete list of available categories with detailed field specifications, refer to our full [audit log categories documentation](../audit-log-categories/index.md).

**Performance note:** Audit log datasets can contain very high volumes of data. Always filter using the `time` column before performing aggregations or visualizations to ensure performant queries.

### Build category-based queries

Audit log categories enable powerful, maintainable queries that work across all Foundry products. In pseudo-code this would look like the following:

**Monitoring all export activity:**

```
categories contains "dataExport"
```

**Investigating potential credential compromise:**

```
categories contains "authenticationCheck" AND result = "FAILURE" 
GROUP BY uid
HAVING COUNT(*) > 5
```

**Tracking permission changes on sensitive resources:**

```
categories contains "managementPermissions" AND resource_id IN (sensitive_resource_list)
```

The category-based approach ensures queries remain valid even as new features are added. New export capabilities we develop will use the `dataExport` category without requiring query updates in your analyses.

## Best practices for audit monitoring

### Establish baseline behavior

Before implementing automated alerting, establish baselines for normal activity:

* Typical login times and locations for each user or user group.
* Normal data access patterns (which datasets, access frequency, volume).
* Expected export behavior (purpose, timing, data volumes).
* Standard permission change workflows.

Anomalies are only meaningful in context. Understanding normal behavior patterns and platform usage enables high-fidelity alerting with minimal false positives.

### Implement defense in depth

Layer multiple detection mechanisms:

* **Real-time alerting** for critical security events (failed logins, sensitive data exports).
* **Periodic analysis** for trending and pattern detection (unusual access growth, permission drift).
* **Incident response procedures** for investigating alerts and coordinating response.
* **Regular audits** to verify monitoring coverage and alert effectiveness.

### Optimize for performance

When working with large audit datasets:

* Always filter by `time` range first to reduce data volume.
* Use `categories` filters early in query pipeline before examining detailed fields.
* Pre-configure/index commonly filtered fields in your SIEM or analysis platform.

### Coordinate with Palantir CIRT

As part of Foundry's [shared security model](../shared-security-responsibility-model/index.md), Palantir's Computer Incident Response Team (CIRT) monitors hosted customer platforms for security threats. CIRT maintains [alerting and detection strategies ↗](https://blog.palantir.com/alerting-and-detection-strategy-framework-52dc33722df2) targeted towards activity on our hosted customer platforms. If CIRT identifies suspicious activity on your platform, you will be contacted to reconcile the activity.

We encourage customers to implement their own audit log monitoring in accordance with their understanding of normal user behavior and organizational security requirements; you have the domain knowledge to identify anomalies that platform-level monitoring cannot detect. Only you can ensure that usage of your platform is appropriate and meets your own policies and obligations.

## Getting started

For new implementations, follow the steps below that are discussed in detail throughout this documentation:

1. [**Choose a delivery method:**](#choose-your-delivery-method) Decide between direct API ingestion (for existing SIEM infrastructure) or Foundry export (for in-platform analysis).
2. [**Configure API access or Foundry export:**](../audit-logs-overview/index.md#audit-delivery) Follow the setup instructions for your preferred method.
3. [**Identify priority categories:**](#work-with-audit-categories) Determine which categories align with your security and compliance requirements.
4. [**Build initial queries:**](#build-category-based-queries) Start with broad category-based filters before adding specific field conditions.
5. [**Establish baselines:**](#establish-baseline-behavior) Run queries over historical data to understand normal patterns.
6. [**Implement alerting:**](#implement-defense-in-depth) Configure alerts for high-priority security events.
7. [**Iterate and refine:**](#optimize-for-performance) Adjust alert thresholds and add new detections based on operational experience.

For additional assistance with audit log monitoring or questions about specific use cases, contact Palantir Support.