> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/feature-guides/security-and-governance/audit-trail.md).

# Audit Trail

Track changes to resources within Bindplane.

{% hint style="info" %}
Audit Trail is not available in Bindplane Free Edition
{% endhint %}

### What is Audit Trail?

Audit Trail 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, collectors, users, access, and API keys in your project.

### Configuration

The audit trail feature is automatically enabled

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="https://content.gitbook.com/content/DBruzp1JKFyzeaBOInfR/blobs/JfsrOJiqElTGlevBHawY/feature-guides-audit-trail-image-1.png" alt="Bindplane docs - Audit Trail - image 1"><figcaption></figcaption></figure>

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

<figure><img src="https://content.gitbook.com/content/DBruzp1JKFyzeaBOInfR/blobs/BfR4a1e42zS1q7IKd1Qc/feature-guides-audit-trail-image-2.png" 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

Audit events are grouped into the categories below. The **Action** and **Resource** columns correspond to the columns on the Audit Events table in Bindplane, indicating the action of the audit event and on which kind of resource the action was taken.

**Configuration Events**

When a configuration is created or modified, an event is logged for each component within the configuration that changed, along with the user that changed it. The following events may be emitted:

<table><thead><tr><th width="121.9296875">Action</th><th width="200">Resource</th><th>Description</th></tr></thead><tbody><tr><td>Created</td><td>Configuration</td><td>A new configuration has been created.</td></tr><tr><td>Added</td><td>Source, Processor, Destination, Extension</td><td>A component of the type specified by the resource name has been added to the configuration.</td></tr><tr><td>Modified</td><td>Source, Processor, Destination, Extension</td><td>An inline component of the configuration has been modified.</td></tr><tr><td>Updated</td><td>Source, Processor, Destination, Extension</td><td>A reusable component has had its version changed within the configuration.</td></tr><tr><td>Removed</td><td>Source, Processor, Destination, Extension</td><td>A component has been removed from the configuration.</td></tr></tbody></table>

**Resource Events**

When a resource is created, modified, or deleted, whether that be through the UI, the API, or `bindplane apply` / `bindplane delete`, an event is logged for that resource:

<table><thead><tr><th width="121.9296875">Action</th><th>Description</th></tr></thead><tbody><tr><td>Created</td><td>The resource specified by the resource name has been created.</td></tr><tr><td>Modified</td><td>The resource specified by the resource name has been modified.</td></tr><tr><td>Deleted</td><td>The resource specified by the resource name has been deleted.</td></tr></tbody></table>

These events are emitted for the following resource kinds:

* `Configuration`
* `Source`
* `Processor`
* `Destination`
* `Extension`
* `Connector`
* `Fleet`
* `Integration`

**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</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>

**Collector Events**

When collectors are modified, an event is logged listing the affected collector ID(s) in the resource name. The following events may be emitted:

<table><thead><tr><th width="220">Action</th><th width="119.21875">Resource</th><th>Description</th></tr></thead><tbody><tr><td>Labels Updated</td><td>Collector</td><td>The labels of one or more collectors have been changed. The description records the labels before and after the change.</td></tr><tr><td>Assigned to Fleet</td><td>Collector</td><td>One or more collectors have been assigned to a fleet.</td></tr><tr><td>Removed from Fleet</td><td>Collector</td><td>One or more collectors have been removed from a fleet.</td></tr><tr><td>Assigned to Configuration</td><td>Collector</td><td>One or more collectors have been assigned to a configuration.</td></tr><tr><td>Removed from Configuration</td><td>Collector</td><td>One or more collectors have been removed from a configuration.</td></tr><tr><td>Upgrade Started</td><td>Collector</td><td>An upgrade has been requested for the collector specified by the resource name.</td></tr></tbody></table>

**User Events**

When users are modified or perform certain actions, an audit event is logged for that user. The following events may be emitted:

<table><thead><tr><th width="240">Action</th><th width="119.21875">Resource</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><tr><td>Logged In</td><td>User</td><td>The user specified by the resource name logged in.</td></tr><tr><td>Set Active Project</td><td>User</td><td>The user switched to the project this event is recorded under.</td></tr><tr><td>User Bypassed SSO</td><td>User</td><td>The user logged in with local credentials instead of the configured single sign-on provider.</td></tr><tr><td>Permissions Synced with IdP</td><td>User</td><td>The user's single sign-on group bindings were synced from the identity provider during login.</td></tr><tr><td>Access Enabled by IdP</td><td>User</td><td>The identity provider granted the user access to the project during a sync. The description includes the role granted.</td></tr><tr><td>Access Removed by IdP</td><td>User</td><td>The identity provider revoked the user's access to the project during a sync.</td></tr></tbody></table>

**API Key Events**

When an API key is created or deleted, an event is logged with the key's identifier as the resource name. The following events may be emitted:

<table><thead><tr><th width="121.9296875">Action</th><th width="119.21875">Resource</th><th>Description</th></tr></thead><tbody><tr><td>Created</td><td>APIKey</td><td>A new API key has been created.</td></tr><tr><td>Deleted</td><td>APIKey</td><td>An API key has been deleted.</td></tr></tbody></table>

**Invitation Events**

When a user is invited to a project, an event is logged with the invitee's email address as the resource name. The following events may be emitted:

<table><thead><tr><th width="121.9296875">Action</th><th width="119.21875">Resource</th><th>Description</th></tr></thead><tbody><tr><td>Created</td><td>Invitation</td><td>An invitation has been created for the email address specified by the resource name. The description includes the role the invitee will be granted.</td></tr></tbody></table>


---

# 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 dynamically by asking a question.

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

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.