# Export Audit Logs to S3

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

## Create an S3 bucket policy for the export

Before Immuta can export audit events to your S3 bucket, you need to create a bucket policy that allows the Immuta audit service to add objects to your specified S3 bucket. The following Amazon S3 action will be granted to the audit service in the bucket policy:

* [s3:PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html): Adds an object to a bucket.

To create the policy for the bucket, you must be the bucket owner.

1. Follow [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/add-bucket-policy.html) for adding a bucket policy in the Amazon S3 console. To create the policy for the bucket, you must be the bucket owner.
2. Edit the JSON in the **Policy** section to include a bucket policy like the example below. In this example, the policy allows immuta-audit-service (the [Principal](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-bucket-user-policy-specifying-principal-intro.html)) to add objects to customer-bucket-name (and the contents within that bucket).

   Note: If you use this example, replace the **content in angle brackets** with your [**Amazon Resource Name (ARN)**](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) and **bucket name**.

   ```json
   {
   "Version": "2012-10-17",
   "Statement": [{
       "Effect": "Allow",
       "Principal": {
       "AWS": "arn:aws:iam::<INSERT CUSTOMER ACCOUNT NUMBER WITHOUT HYPHENS>:role/<INSERT A ROLE CREATED FOR IMMUTA>"
       },
       "Action": [
       "s3:PutObject"
       ],
       "Resource": [
       "arn:aws:s3:::<INSERT CUSTOMER BUCKET NAME TO RECEIVE EXPORT>/*",
       "arn:aws:s3:::<INSERT CUSTOMER BUCKET NAME TO RECEIVE EXPORT>"
       ]
   } ]
   }
   ```
3. **Save** your changes.

## Configure the audit export to S3

You can configure your audit export destination using one of two methods:

1. [Immuta CLI](#using-the-immuta-cli)
2. [Immuta Audit Service GraphQL API](#using-the-audit-service-graphql-api)

### Using the Immuta CLI

#### Install the Immuta CLI

Download the binary in a tab below that corresponds to your operating system:

{% tabs %}
{% tab title="Linux" %}

* Linux x86\_64 (amd64)

  ```
  curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_linux_amd64 && chmod +x immuta
  ```
* Linux ARMv8 (arm64)

  ```
  curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_linux_arm64 && chmod +x immuta
  ```

{% endtab %}

{% tab title="MacOS" %}

* Darwin x86\_64 (amd64)

  ```
  curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_darwin_amd64 && chmod +x immuta
  ```
* Darwin ARMv8 (arm64)

  ```
  curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_darwin_arm64 && chmod +x immuta
  ```

{% endtab %}

{% tab title="Windows" %}
The latest stable binary can be found here: <https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_windows_amd64>.

Download and add the binary to a directory in your system's $PATH as immuta.exe.
{% endtab %}
{% endtabs %}

#### Configure the Immuta CLI

*For descriptions of the commands used below, see the* [*Immuta audit export configuration CLI reference guide*](https://documentation.immuta.com/2024.2/detect-your-activity/audit/reference-guides/cli-reference-guide)*.*

1. The SHA 256 checksum is available to verify the file at <https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_SHA256SUMS>.
2. Run `immuta configure` in your terminal.
3. Enter the **URL** of your Immuta tenant in the interactive prompt.
4. Enter your **Immuta API Key**.

#### Configure Immuta to export audit logs to S3

1. Set the following parameters in a JSON or YAML file:

   * **interval**: The interval at which audit logs will be exported to your S3 bucket. They can be sent at 2-, 4-, 6-, 12-, or 24-hour intervals.
   * **bucket name**: Name of the bucket your audit logs will be sent to.
   * **bucket path**: Path to your bucket in Amazon S3.
   * **region**: AWS region (such as "us-east-1").
   * **accessKeyId**: AWS access key ID.
   * **secretAccessKey**: AWS secret access key.

   ```json
   {
   "interval": "EVERY_12_HOURS",
   "bucket": "your-s3-bucket",
   "path": "hr-data",
   "region": "us-east-1",
   "accessKeyId": "your-access-key-id",
   "secretAccessKey": "your-secret-access-key"
   }
   ```
2. Configure these settings in Immuta by running the following command:

   ```shell
   immuta audit exportConfig create:s3 ./exportConfig.json
   ```

#### List all configurations

To view all of the export configurations created for your instance of Immuta, run the following command:

```shell
immuta audit exportConfig list
```

#### View a configuration

To review a specific export configuration, run the get command with the export configuration ID as the argument:

```shell
immuta audit exportConfig get f7f9e289-f37b-4942-a18d-66d6de6e7cb2
```

#### Disable a configuration

To disable a configuration, run the following command with the export configuration ID as the argument:

```shell
immuta audit exportConfig disable f7f9e289-f37b-4942-a18d-66d6de6e7cb2
```

#### Enable a configuration

To enable a disabled configuration, run the following command with the export configuration ID as the argument:

```shell
immuta audit exportConfig enable f7f9e289-f37b-4942-a18d-66d6de6e7cb2
```

#### Delete a configuration

To delete an export configuration, run the following command with the export configuration ID as the argument:

```shell
immuta audit exportConfig delete f7f9e289-f37b-4942-a18d-66d6de6e7cb2
```

### Using the audit service GraphQL API

#### Configure Immuta to export audit logs to S3

1. Pass the following fields into the **$data variable** used in the mutation in the next step:

   * **interval**: The interval at which audit logs will be exported to your S3 bucket. They can be sent at 2-, 4-, 6-, 12-, or 24-hour intervals.
   * **bucket name**: Name of the bucket your audit logs will be sent to.
   * **bucket path**: Path to your bucket in Amazon S3.
   * **region**: AWS region (such as "us-east-1").
   * **accessKeyId**: AWS access key ID.
   * **secretAccessKey**: AWS secret access key.

   ```json
   {
     "data":{
       "interval": "EVERY_12_HOURS",
       "bucket": "your-s3-bucket",
       "path": "hr-data",
       "region": "us-east-1",
       "accessKeyId": "your-access-key-id",
       "secretAccessKey": "your-secret-access-key"
     }
   }
   ```
2. Configure these settings in Immuta using the `createS3ExportConfiguration` mutation:

{% tabs %}
{% tab title="Mutation" %}

```shell
mutation createS3ExportConfiguration($data: CreateS3ExportConfigurationInput!) {
  createS3ExportConfiguration(data: $data) {
    id
    interval
    endpointConfiguration {
      ... on S3EndpointConfiguration {
        ...S3EndpointConfigurationFragment
      }
    }
  }
}
```

{% endtab %}

{% tab title="Variable" %}
The S3 export configuration to create.

```json
{"data": CreateS3ExportConfigurationInput}
```

{% endtab %}

{% tab title="CreateS3ExportConfigurationInput Example" %}

```json
{
  "interval": "EVERY_2_HOURS",
  "bucket": "abc123",
  "path": "xyz789",
  "region": "xyz789",
  "accessKeyId": "xyz789",
  "secretAccessKey": "abc123"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "data": {
    "createS3ExportConfiguration": {
      "id": "4",
      "interval": "EVERY_2_HOURS",
      "enabled": false,
      "endpointConfiguration": S3EndpointConfiguration,
      "createdBy": User,
      "createdAt": "2007-12-03T10:15:30Z",
      "updatedBy": User,
      "updatedAt": "2007-12-03T10:15:30Z"
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Disable a configuration

To disable a configuration, use the `disableExportConfiguration` mutation:

{% tabs %}
{% tab title="Mutation" %}

```shell
mutation disableExportConfiguration($id: String!) {
  disableExportConfiguration(id: $id) {
    id
    interval
    enabled
    endpointConfiguration {
      ... on S3EndpointConfiguration {
        ...S3EndpointConfigurationFragment
      }
    }
    createdBy {
      ...UserFragment
    }
    createdAt
    updatedBy {
      ...UserFragment
    }
    updatedAt
  }
}
```

{% endtab %}

{% tab title="Variable" %}
The ID of the export configuration to disable.

```json
{"id": "abc123"}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "data": {
    "disableExportConfiguration": {
      "id": "4",
      "interval": "EVERY_2_HOURS",
      "enabled": true,
      "endpointConfiguration": S3EndpointConfiguration,
      "createdBy": User,
      "createdAt": "2007-12-03T10:15:30Z",
      "updatedBy": User,
      "updatedAt": "2007-12-03T10:15:30Z"
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Enable a configuration

To enable a disabled configuration, use the `enableExportConfiguration` mutation:

{% tabs %}
{% tab title="Mutation" %}

```shell
mutation enableExportConfiguration($id: String!) {
  enableExportConfiguration(id: $id) {
    id
    interval
    enabled
    endpointConfiguration {
      ... on S3EndpointConfiguration {
        ...S3EndpointConfigurationFragment
      }
    }
    createdBy {
      ...UserFragment
    }
    createdAt
    updatedBy {
      ...UserFragment
    }
    updatedAt
  }
}
```

{% endtab %}

{% tab title="Variable" %}
The ID of the export configuration to enable.

```json
{"id": "abc123"}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "data": {
    "enableExportConfiguration": {
      "id": 4,
      "interval": "EVERY_2_HOURS",
      "enabled": true,
      "endpointConfiguration": S3EndpointConfiguration,
      "createdBy": User,
      "createdAt": "2007-12-03T10:15:30Z",
      "updatedBy": User,
      "updatedAt": "2007-12-03T10:15:30Z"
    }
  }
}
```

{% endtab %}
{% endtabs %}