Export Audit Logs to S3

Requirements:

Immuta permission AUDIT
If you will use the Immuta CLI instead of GraphQL API, install and configure the Immuta CLI. Must be CLI v1.4.0 or newer.

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
AWS IAM role

How to export using an 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.

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: Adds an object to a bucket.

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

Follow AWS documentation for adding a bucket policy in the Amazon S3 console. To create the policy for the bucket, you must be the bucket owner.

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) 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) and bucket name.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<Your AWS account ID>:user/<Your IAM User>"
            },
            "Action": [
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::<your-s3-bucket>",
                "arn:aws:s3:::<your-s3-bucket>/*"
            ]
        }
    ]
}

Save your changes.

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 the policy was added 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 for information about using an access key ID and secret access key.
secretAccessKey: AWS secret access key for authentication.

Immuta CLIGraphQL API

Run the following command with the above fields in a JSON file:

immuta audit exportConfig create:s3:accessKey ./exportConfig.json

Example ./exportConfig.json file

{
"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.

Run the following mutation to this URL, https://your-immuta.com/api/audit/graphql, with the above fields passed directly:

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

{
    "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.

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. 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.

Immuta requires a role with the following allowed action to the S3 bucket you want the audit logs exported to:

s3:PutObject which allows to the role to add an object to a bucket.

1 - Create an AWS policy for the role

Follow AWS documentation to create a new role for Immuta to assume and add objects to your S3 bucket.

Follow AWS documentation for creating IAM policies in the Amazon S3 console for the new role. Use the example JSON below to allow the provided role to add objects to the specified buckets. Ensure the buckets provided here are the ones used when configuring the export.

Note: If you use this example, replace the content in angle brackets with your bucket name.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::<your-s3-bucket>",
                "arn:aws:s3:::<your-s3-bucket>/*"
            ]
        }
    ]
}

2 - Configure the audit export to S3

Response error

When creating the export configuration, this step will return an error. Take the returned export configuration ID and continue with step 3 and 4 to create a trust relationship and verify the connection between Immuta and 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.
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.

Immuta CLIGraphQL API

Run the following command with the above fields in a JSON file:

immuta audit exportConfig create:s3:assumedRole ./exportConfig.json

Example ./exportConfig.json file

{
"interval": "EVERY_12_HOURS",
"bucket": "your-s3-bucket",
"path": "your-optional-s3-bucket-path",
"region": "your-region",
"roleArn": "arn:aws:iam::<Your AWS Account ID>:role/<the prepared role>"
}

Example response:

{
    "data": {
        "createS3AssumedRoleExportConfiguration": {
            "id": "259fc41c-b502-418a-a8ff-d875335dbe9b",
            "interval": "EVERY_12_HOURS",
            "enabled": true,
            "connectionStatus": "Error testing access to S3 using AssumedRole <Your Role> - User: <Immuta Account> is not authorized to perform: sts:AssumeRole on resource: <Your Role>",
            "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.

Run the following mutation to this URL, https://your-immuta.com/api/audit/graphql, with the above fields passed directly:

mutation {
  createS3AssumedRoleExportConfiguration(
    data: {
      interval: EVERY_12_HOURS
      bucket: "your-s3-bucket"
      path: "your-optional-s3-bucket-path"
      region: "your-region"
      roleArn: "arn:aws:iam::<Your AWS Account ID>:role/<the prepared role>"
    }
  )
    {
        id
        interval
        enabled
        connectionStatus
        endpointConfiguration {
            ... on S3AssumedRoleExportConfiguration {
                bucket
                path
                region
            }
        }
    }
}

Example response

{
    "data": {
        "createS3AssumedRoleExportConfiguration": {
            "id": "259fc41c-b502-418a-a8ff-d875335dbe9b",
            "interval": "EVERY_12_HOURS",
            "enabled": true,
            "connectionStatus": "Error testing access to S3 using AssumedRole <Your Role> - User: <Immuta Account> is not authorized to perform: sts:AssumeRole on resource: <Your Role>",
            "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.

3 - Create a trust relationship

Follow AWS documentation for creating IAM policies in the Amazon S3 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 you Immuta representative for this ID.
Export Configuration ID: Insert the ID from step 2's response.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<Immuta AWS Account ID>:root"
            },
            "Action": "sts:AssumeRole",
            "Condition": {"StringEquals": {"sts:ExternalId": "<Export Configuration ID>"}}
        }
    ]
}

4 - 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.

If connectionStatus returns SUCCESS, your export configuration has been successfully set up.

Immuta CLIGraphQL API

Run the following command

immuta cli audit exportConfig list

Run the following mutation to this URL, https://your-immuta.com/api/audit/graphql:

query {
    getAllExportConfigurations{
        id
        connectionStatus
    }
}

Troubleshooting

If you see the following error: 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.