🚧

NOTE

There are multiple versions of the AWS console and the order/terminology of following steps may be slightly different

Create a new role for ChaosSearch in AWS

1. Please log into your AWS console or create an AWS account if you have not yet done so
2. Navigate to the Roles page of the IAM service (Services > Security, Identity & Compliance > IAM > Roles)
3. Select Create role

📘

AWS IAM Role Requirements

ChaosSearch uses Amazon AWS IAM roles to allow you to delegate access to your S3 buckets to the ChaosSearch service. Follow these steps to configure your Amazon AWS account.

Create role for another AWS account

1. Select Another AWS account
2. Enter the ChaosSearch AWS account ID (515570774723) in the Account ID field

3. Check Require External ID, Navigate to your ChaosSearch account and click Settings under the gear icon in your account
4. Select AWS Credentials, then Copy and Paste the External ID value into the Required External ID field
5. Select Next: Permissions

IAM Role Policy Permissions

🚧

CHAOSSEARCH S3 Bucket Access

In order for ChaosSearch to read the bucket(s) you want to start indexing, we will need to list all of the S3 buckets. If you have any questions, please feel welcome to reach out to our Team!

Read-only permissions - All Buckets

1. Enter a name for the policy - for this example, we use “ChaosSearchReadOnly”
2. Enter a brief description for the policy (optional)
3. Select Create policy and close the tab

Read-only permissions - Specified Bucket (recommended)

1. Select Create policy (opens in new tab) and then select the JSON tab to enter a custom policy
2. In the editor, copy the following policy (be sure to replace EXTERNAL-ID)

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Action": [
               "s3:ListAllMyBuckets",
               "s3:GetBucketLocation"
           ],
           "Resource": "*"
       },
       {
           "Effect": "Allow",
           "Action": [
               "s3:List*"
           ],
           "Resource": "arn:aws:s3:::airtest-testdata"
       },
       {
           "Effect": "Allow",
           "Action": [
               "s3:Get*",
               "s3:PutObjectTagging"
           ],
           "Resource": "arn:aws:s3:::airtest-testdata/*"
       },
       {
           "Effect": "Allow",
           "Action": "*",
           "Resource": [
               "arn:aws:s3:::cs-EXTERNAL-ID",
               "arn:aws:s3:::cs-EXTERNAL-ID/*"
           ]
       }
   ]
}

3. Click Review policy.

Read-only permissions - Prefix specific

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListAllMyBuckets",
                "s3:GetBucketLocation"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:List*"
            ],
            "Resource": "arn:aws:s3:::SOURCE_BUCKET"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:Get*",
                "s3:PutObjectTagging"
            ],
            "Resource": "arn:aws:s3:::SOURCE_BUCKET/some/path/prefix/*"
        },
        {
            "Effect": "Allow",
            "Action": "*",
            "Resource": [
                "arn:aws:s3:::cs-EXTERNAL-ID",
                "arn:aws:s3:::cs-EXTERNAL-ID/*"
            ]
        }
    ]
}

📘

KMS Encryption

If the Objects stored in S3 are encrypted, there is no need to unencrypt these objects. ChaosSearch can naturally work with these objects when the appropriate resources are defined in the IAM Policy. Below is an example of what this policy should look like.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "kms:GenerateDataKey",
                "kms:Decrypt"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:kms:us-east-1:123456789012:key/enter-key-here",
                "arn:aws:kms:us-east-1:123456789012:key/enter-key-here",
                "arn:aws:kms:us-east-1:123456789012:key/enter-key-here",
                "arn:aws:kms:us-east-1:123456789012:key/enter-key-here"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:Get*",
                "s3:List*",
                "s3:PutObjectTagging"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": "*",
            "Resource": [
                "arn:aws:s3:::cs-s3bucketname",
                "arn:aws:s3:::cs-s3bucketname"
            ]
        },
        {
            "Effect": "Allow",
            "Action": "*",
            "Resource": [
                "arn:aws:s3:::cs-s3bucketname/*",
                "arn:aws:s3:::cs-s3bucketname/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": "*",
            "Resource": [
                "arn:aws:s3:::cs-*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": "*",
            "Resource": [
                "arn:aws:s3:::cs-*/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": "sqs:*",
            "Resource": [
                "arn:aws:sqs:*:123456789012:s3-sqs"
            ]
        }
    ]
}

📘

What access does this JSON object provide?

The first statement is to provide ChaosSearch access to the Get, List, and PutObjectTagging operations (Read-only access).

Note: "s3:PutObjectTagging" is optional - this is only required to enable object tagging in the CHAOSSEARCH UI.

The second statement is to provide a bucket for ChaosSearch to write its metadata and statistics. The name of the bucket must be prefixed with a "cs-" plus your "External ID"

Attach the policy to the ChaosSearch IAM role

• On the Create Role page, select Refresh to update the grid with the newly created custom policy
• Enter the custom policy name into policy type filter - for this example we use "ChaosSearchReadOnly"
• Check the custom policy and select Next: Review

Full access permissions

📘

If you choose to grant full access to ChaosSearch, you can select one of the AWS predefined policies instead of creating a custom policy.

• Type “AmazonS3FullAccess” into policy type filter
• Check “AmazonS3Full Access” policy checkbox and select Next: Review

Name and review role

• Choose a name for the new role - for this example we use “ChaosSearchS3Role”
• Review the ChaosSearch AWS account ID in Trusted entities for accuracy
• Review the S3 privileges in Policies for accuracy
• Select Create role

Communicate Role ARN to CHAOSSEARCH

• From the IAM console Roles page, click on the newly created role name
• Copy the value in the Role ARN field

• Navigate back to the ChaosSearch settings page
• Paste the Role ARN into the Role ARN field and click Update

You are all setup to begin indexing and analyzing your long-term log and event data!

📘

Troubleshooting S3 Access

If you're getting 'Request Failed' when click into a bucket or object, please review this AWS doc