# Export Audit Logs to Amazon S3 {% hint style="info" %} **Public preview**: This feature is available to all accounts. {% endhint %} **Requirements**: * Immuta permission `AUDIT` * If you will use the Immuta CLI instead of GraphQL API, [install and configure the Immuta CLI](https://documentation.immuta.com/saas/developer-guides/the-immuta-cli/installation). Must be CLI v1.4.0 or newer. * An S3 bucket you want to use to store the exported audit logs. Use the following how-to to configure a periodical export of your Immuta audit logs to an S3 bucket. This export configuration requires access to your S3 bucket to add objects using one of the following authentication methods: * [Access and secret key](#how-to-export-using-an-access-key) * [AWS IAM role](#how-to-export-using-an-aws-iam-role) ## How to export using an IAM user with access key Configure your Immuta audit logs to export to your S3 bucket and allow Immuta to authenticate using your AWS access key ID and secret access key. Here's a visual representation of the authentication flow:
### 1 - Configure an IAM user and policy Access keys are tied to [IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html), which must be allowed to deposit objects in the target bucket via an attached [IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html). Immuta requires that the user it authenticates as has the following permissions: * [s3:PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html): Allows Immuta to upload objects to the bucket. If your S3 bucket is encrypted, the following permissions must also be granted to the role: * [kms:Decrypt](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-keys): Allows Immuta to verify the integrity of the new data key before using it. * [kms:GenerateDataKey](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-keys): Allows Immuta to generate a key that is used to encrypt the audit objects that are exported to S3 using your KMS key. To begin, create an IAM user and attach a policy with the above permissions. 1. Follow [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) to create a new user for Immuta to authenticate as and add objects to your S3 bucket. 2. Follow [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) for creating IAM policies in the Amazon S3 console for the new policy. Here is an example IAM policy that contains the required permissions for a KMS encrypted bucket. If you use this example, replace the **content in angle brackets** with the [**Amazon Resource Names (ARNs)**](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) for your **S3 bucket** and **KMS key**: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutObject" ], "Resource": "/*" }, { "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:GenerateDataKey" ], "Resource": "" } ] } ``` 3. Follow [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) to attach the policy to your newly created user. 4. Follow [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) to generate the credentials that will be used to configure the export. ### 2 - Create an S3 bucket policy for the export Before Immuta can export audit events to your S3 bucket using your configured IAM user, you need to create a bucket policy that allows that IAM user to add objects to your specified S3 bucket. The following Amazon S3 actions must be granted in the bucket policy: * [s3:PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html): Allows Immuta to upload objects to the 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. 2. Edit the JSON in the **Policy** section to include a bucket policy like the example below. In this example, the policy allows an IAM user (the [principal](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-bucket-user-policy-specifying-principal-intro.html)) to add objects to the bucket. If you use this example, replace the **content in angle brackets** with the [**Amazon Resource Names (ARNs)**](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) for your **IAM user** and **S3 bucket**. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "" }, "Action": "s3:PutObject", "Resource": "/*" } ] } ``` 3. **Save** your changes. {% hint style="warning" %} **Example policy** The example policy may block bucket access for other services, which then need to be configured via separate statements. Configure bucket policies with caution. {% endhint %} ### 3 - Configure the audit export to S3 Configure the audit export to S3 using the Immuta CLI or GraphQL API with the following fields: * **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 that you added the policy to above. * **bucket path**: The name of the folder within the bucket to put the audit logs in. This field is optional. * **region**: AWS region (such as "us-east-1"). * **accessKeyId**: AWS access key ID for authentication. See the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) for information about using an access key ID and secret access key. * **secretAccessKey**: AWS secret access key for authentication. {% tabs %} {% tab title="Immuta CLI" %} Run the following command with the above fields in a JSON file: ```bash immuta audit exportConfig create:s3:accessKey ./exportConfig.json ``` **Example `./exportConfig.json` file** ```json { "interval": "EVERY_12_HOURS", "bucket": "your-s3-bucket", "path": "your-optional-s3-bucket-path", "region": "your-aws-region", "accessKeyId": "YOURACCESSKEYID", "secretAccessKey": "YOUR/SECRET/ACCESSKEY" } ``` For additional CLI commands, see the [audit CLI reference guide](https://documentation.immuta.com/saas/developer-guides/the-immuta-cli/cli-reference-guide). {% endtab %} {% tab title="GraphQL API" %} Run the following mutation to this URL, `https://your-immuta.com/api/audit/graphql`, with the above fields passed directly: ```graphql mutation { createS3AccessKeyExportConfiguration( data: { interval: EVERY_12_HOURS bucket: "your-s3-bucket" path: "your-optional-s3-bucket-path" region: "your-aws-region" accessKeyId: "YOURACCESSKEYID" secretAccessKey: "YOUR/SECRET/ACCESSKEY" } ) { id interval enabled connectionStatus endpointConfiguration { ... on S3AccessKeyEndpointConfiguration { bucket path region } } } } ``` **Example response** ```graphql { "data": { "createS3AccessKeyExportConfiguration": { "id": "259fc41c-b502-418a-a8ff-d875335dbe9b", "interval": "EVERY_12_HOURS", "enabled": true, "connectionStatus": "SUCCESS", "endpointConfiguration": { "bucket": "your-s3-bucket", "path": "your-optional-s3-bucket-path", "region": "your-region", } } } } ``` For additional GraphQL API commands, see the [GraphQL API reference guide](https://documentation.immuta.com/saas/govern/detect-your-data/audit/reference-guides/immuta-audit-export-to-s3-and-adls-gen2-graphql-reference-guide). {% endtab %} {% endtabs %} ### 4 - Verify the export configuration connection If the configuration is successful, you will see an `.immuta.export.log` file in your bucket. ## How to export using an AWS IAM role Configure your Immuta audit logs to export to your S3 bucket and allow Immuta to authenticate using an [AWS role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html). With this option, you provide Immuta with an IAM role from your AWS account that is granted a trust relationship with Immuta’s IAM role for adding objects to your S3 bucket. Immuta will assume this IAM role from Immuta’s AWS account in order to perform operations in your AWS account. Here's a visual representation of the authentication flow:
AWS STS vends a token to the Immuta IAM role so that it can export Immuta audit logs to your S3 bucket.
Immuta requires a role with the following allowed action to the S3 bucket you want the audit logs exported to: * [s3:PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) which allows the role to add an object to a bucket. If your S3 bucket is encrypted, the following permissions must also be granted to the role: * [kms:Decrypt](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-keys): Allows Immuta to verify the integrity of the new data key before using it. * [kms:GenerateDataKey](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#aws-managed-customer-managed-keys): Allows Immuta to generate a key that is used to encrypt the audit objects that are exported to S3 using your KMS key. ### 1 - Configure an IAM role and policy 1. Follow [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html) to create a new role for Immuta to assume and add objects to your S3 bucket. 2. Follow [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) for creating IAM policies in the Amazon S3 console for the new role. Here is an example IAM Policy that contains the required permissions for a KMS encrypted bucket. **If you are not using KMS encryption, you may omit the second statement**. If you use this example, replace the **content in angle brackets** with the [**Amazon Resource Names (ARNs)**](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) for your **S3 bucket** and **KMS key**: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutObject" ], "Resource": "/*" }, { "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:GenerateDataKey" ], "Resource": "" } ] } ``` 3. Follow [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-permissions.html#id_roles_update-role-permissions-policy) to attach the policy to your newly created role. ### 2 - Create an S3 bucket policy for the export Before Immuta can export audit events to your S3 bucket using your configured IAM role, you need to create a bucket policy that allows that IAM role to add objects to your specified S3 bucket. The following Amazon S3 actions must be granted in the bucket policy: * [s3:PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html): Allows Immuta to upload objects to the 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. 2. Edit the JSON in the **Policy** section to include a bucket policy like the example below. In this example, the policy allows an IAM user (the [principal](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-bucket-user-policy-specifying-principal-intro.html)) to add objects to the bucket. If you use this example, replace the **content in angle brackets** with the [**Amazon Resource Names (ARNs)**](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) for your **IAM role** and **S3 bucket**. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "" }, "Action": "s3:PutObject", "Resource": "/*" } ] } ``` 3. **Save** your changes. {% hint style="warning" %} **Example policy** The example policy may block bucket access for other services, which then need to be configured via separate statements. Configure bucket policies with caution. {% endhint %} ### 3 - Configure the audit export to S3 {% hint style="warning" %} **Response error** When creating the export configuration, this step will return an error. Take the returned export configuration ID and continue with step 4 and 5 to create a trust relationship and verify the connection between Immuta and S3. {% endhint %} Configure the audit export to S3 using the Immuta CLI or GraphQL API with the following fields: * **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**: The name of the folder within the bucket to put the audit logs in. This field is optional. * **region**: AWS region (such as "us-east-1"). * **roleArn**: AWS role ARN for authentication that you added the policies to above. Immuta will assume this role when exporting audit logs to S3. {% tabs %} {% tab title="Immuta CLI" %} Run the following command with the above fields in a JSON file: ```bash immuta audit exportConfig create:s3:assumedRole ./exportConfig.json ``` **Example `./exportConfig.json` file** ```json { "interval": "EVERY_12_HOURS", "bucket": "your-s3-bucket", "path": "your-optional-s3-bucket-path", "region": "your-region", "roleArn": "arn:aws:iam:::role/" } ``` **Example response**: ```bash { "data": { "createS3AssumedRoleExportConfiguration": { "id": "259fc41c-b502-418a-a8ff-d875335dbe9b", "interval": "EVERY_12_HOURS", "enabled": true, "connectionStatus": "Error testing access to S3 using AssumedRole - User: is not authorized to perform: sts:AssumeRole on resource: ", "endpointConfiguration": { "__typename": "S3AssumedRoleEndpointConfiguration", "bucket": "your-s3-bucket", "path": "your-optional-s3-bucket-path", "region": "your-region", } } } } ``` For additional CLI commands, see the [audit CLI reference guide.](https://documentation.immuta.com/saas/developer-guides/the-immuta-cli/cli-reference-guide) {% endtab %} {% tab title="GraphQL API" %} Run the following mutation to this URL, `https://your-immuta.com/api/audit/graphql`, with the above fields passed directly: ```graphql mutation { createS3AssumedRoleExportConfiguration( data: { interval: EVERY_12_HOURS bucket: "your-s3-bucket" path: "your-optional-s3-bucket-path" region: "your-region" roleArn: "arn:aws:iam:::role/" } ) { id interval enabled connectionStatus endpointConfiguration { ... on S3AssumedRoleEndpointConfiguration { bucket path region } } } } ``` **Example response** ```graphql { "data": { "createS3AssumedRoleExportConfiguration": { "id": "259fc41c-b502-418a-a8ff-d875335dbe9b", "interval": "EVERY_12_HOURS", "enabled": true, "connectionStatus": "Error testing access to S3 using AssumedRole - User: is not authorized to perform: sts:AssumeRole on resource: ", "endpointConfiguration": { "bucket": "your-s3-bucket", "path": "your-optional-s3-bucket-path", "region": "your-region", } } } } ``` For additional GraphQL API commands, see the [GraphQL API reference guide](https://documentation.immuta.com/saas/govern/detect-your-data/audit/reference-guides/immuta-audit-export-to-s3-and-adls-gen2-graphql-reference-guide). {% endtab %} {% endtabs %} ### 4 - Create a trust relationship and assume role policy Follow [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) for creating IAM trust relationships and assume role polices in the Amazon IAM console. Use the example JSON below to create a trust policy between Immuta and your AWS bucket. Fill in the content in angle brackets with the following: * **Immuta AWS Account ID**: Contact your Immuta representative for this ID. * **Export Configuration ID**: Insert the ID from step 3's response. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam:::root" }, "Action": "sts:AssumeRole", "Condition": {"StringEquals": {"sts:ExternalId": ""}} } ] } ``` ### 5 - Verify the export configuration connection Now that the configuration and the trust relationship have been created, test the connection from Immuta to S3 to ensure your audit logs are exported to your S3 bucket. Additionally, if the configuration is successful, you will see an `.immuta.export.log` file in your bucket. If `connectionStatus` returns `SUCCESS`, your export configuration has been successfully set up. {% tabs %} {% tab title="Immuta CLI" %} Run the following command ```bash immuta audit exportConfig list ``` {% endtab %} {% tab title="GraphQL API" %} Run the following mutation to this URL, `https://your-immuta.com/api/audit/graphql`: ```graphql query { getAllExportConfigurations{ id connectionStatus } } ``` {% endtab %} {% endtabs %} ### Troubleshooting
Error: Unknown error occurred making request to http://your-immuta.com/api/audit/graphql You are not running the required CLI version, which must be CLI v1.4.0 or newer. Update your CLI and reconfigure the CLI with your Immuta tenant.
list returns 0 You do not have any exports configured. Start again from a "Configure the audit export to S3" step and ensure the authentication is correct.