# Audit Trail

{% hint style="warning" %}
**IMPORTANT**

📘 Audit Trail is a [Bindplane Enterprise Edition](https://bindplane.com/solutions/) feature.
{% endhint %}

### What is Audit Trail?

Audit Trail is a feature for Bindplane Enterprise Edition that creates a log of events that can be used for auditing resources that are created and modified within Bindplane. With the audit trail, you can keep track of changes to configurations, rollouts, and users in your project.

### Configuration

The audit trail feature is automatically enabled in Bindplane Enterprise Edition.

Retention may be configured in your server config, by setting the `auditTrail.retentionDays` configuration option. In this example, events are configured to be retained for 60 days:

```yaml
auditTrail:
  retentionDays: 60
```

By default, the audit trail will retain audit events for 30 days.

### Viewing Audit Events

Audit events can be viewed through either the UI or the CLI.

#### UI

The audit logs can be accessed by admins of the project by clicking the gear icon in the top right of the Bindplane UI, then on the Audit Logs option.

<figure><img src="/files/FcXaL1s7pSlRCRVO2BdE" alt="Bindplane docs - Audit Trail - image 1"><figcaption></figcaption></figure>

On the Audit Logs page, you will see the following:

<figure><img src="/files/IrHACwuW6A4zmuOsQC0Z" alt="Bindplane docs - Audit Trail - image 2"><figcaption></figcaption></figure>

1. You can filter by the affected configuration. This input accepts both the configuration name, as well as the configuration name + version (e.g. myconfig:3 would filter out all logs except for ones affecting version 3 of myconfig).
2. You can filter by the user whose action created the log.
3. You can set the minimum date of logs to view.
4. You can set the maximum date of logs to view.
5. You can export and download the current view with all active filters to a CSV file.

Below, you will see a table of all audit events that match the current filters.

#### CLI

To retrieve audit events, the `bindplane get audit-events` command can be used.\
In addition to the standard options for `bindplane get`, there are some extra parameters that may optionally be specified in order to filter the retrieved audit events:

<table><thead><tr><th width="149.734375">Flag</th><th>Description</th></tr></thead><tbody><tr><td>--configuration</td><td>The name of the configuration to filter by</td></tr><tr><td>--max-date</td><td>The maximum date for the events filter, in the format of YYYYMMDDHHMMSS</td></tr><tr><td>--min-date</td><td>The minimum date for the events filter, in the format of YYYYMMDDHHMMSS</td></tr><tr><td>--user</td><td>The display name of the user who made the change to filter by</td></tr></tbody></table>

For a full list of configuration flags, run the `bindplane get audit-events --help` command.

#### CLI Examples

**Output Audit Events as CSV**

```sh
bindplane get audit-events -o csv
```

**Get All Audit Events Generated by a Specific User**

```sh
bindplane get audit-events --user "admin-user"
```

**Get All Audit Events for a Specific Configuration**

```sh
bindplane get audit-events --configuration "my-configuration"
```

**Get All Audit Events for a Specific Configuration (with version)**

```sh
bindplane get audit-events --configuration "my-configuration:13"
```

**Get All Audit Events for the Past Day**

```sh
bindplane get audit-events --min-date "$(date -u --date='1 days ago' '+%Y%m%d%H%M%S')"
```

### Types of Events

Currently, there are three categories of events that are logged to the audit trail.

**Configuration Events**

When a configuration is created or modified, an event is logged specifying which resource of the config was modified, along with the user that modified it. The following events may be emitted:

<table><thead><tr><th width="121.9296875">Action</th><th width="138.9609375">Resource Kind</th><th>Description</th></tr></thead><tbody><tr><td>Created</td><td>Source</td><td>A new source of the type specified by the resource name has been added to the configuration.</td></tr><tr><td>Created</td><td>Processor</td><td>A new processor of the type specified by the resource name has been added to the configuration.</td></tr><tr><td>Created</td><td>Destination</td><td>A new destination of the type specified by the resource name has been added to the configuration.</td></tr><tr><td>Modified</td><td>Source</td><td>A source of the type specified by the resource name has been modified for the configuration.</td></tr><tr><td>Modified</td><td>Processor</td><td>A processor of the type specified by the resource name has been modified for the configuration.</td></tr><tr><td>Modified</td><td>Destination</td><td>A destination of the type specified by the resource name has been modified for the configuration.</td></tr><tr><td>Deleted</td><td>Source</td><td>A source of the type specified by the resource name has been removed from the configuration</td></tr><tr><td>Deleted</td><td>Processor</td><td>A processor of the type specified by the resource name has been removed from the configuration.</td></tr><tr><td>Deleted</td><td>Destination</td><td>A destination of the type specified by the resource name has been removed from the configuration.</td></tr></tbody></table>

#### Rollout Events

When a new rollout is created, started, paused, or resumed, an event is logged for the configuration. The following events may be emitted:

<table><thead><tr><th width="117.91796875">Action</th><th width="119.21875">Resource Kind</th><th>Description</th></tr></thead><tbody><tr><td>Pending</td><td>Rollout</td><td>A new rollout has been created in a Pending state for the configuration.</td></tr><tr><td>Started</td><td>Rollout</td><td>A rollout has been started for the configuration.</td></tr><tr><td>Paused</td><td>Rollout</td><td>An in-progress rollout has been paused for the configuration.</td></tr><tr><td>Resumed</td><td>Rollout</td><td>A previously paused rollout has been resumed for the configuration.</td></tr></tbody></table>

#### User Events

When users are added, removed, or modified to a project, an audit event is logged for that user. The following events may be emitted:

<table><thead><tr><th width="108.4375">Action</th><th width="117.20703125">Resource Kind</th><th>Description</th></tr></thead><tbody><tr><td>Created</td><td>User</td><td>The user specified by the resource name has been added to the project.</td></tr><tr><td>Modified</td><td>User</td><td>The user specified by the resource name has had their role changed to the role specified in the resource name.</td></tr><tr><td>Deleted</td><td>User</td><td>The user specified by the resource name has been removed from the project.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bindplane.com/feature-guides/security-and-governance/audit-trail.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.