CloudTrail

CloudTrail provides event history of your AWS account activity, including actions taken through the AWS Management Console, AWS SDKs, command line tools, and other AWS services. Use this integration to track Shadow Changes from your AWS account in BigPanda.

Supported Versions:
SaaS

Type:
API

Key Features

  • Notifies BigPanda of CloudTrail events, capturing Shadow Changes in your AWS account.
  • Intelligently correlates changes in AWS with high-level incidents in BigPanda to expedite the Root Cause Analysis (RCA) process and reduce Mean Time To Repair (MTTR).
  • Automatically identifies which CloudTrail events correspond to actual changes in your environment

How It Works

The process starts by configuring an S3 bucket holding CloudTrail events with an SQS event notification to a BigPanda owned queue for all new objects. Once BigPanda's SQS queue receives a message it will retrieve the new CloudTrail file from S3 using an IAM Role provided by the customer. Once it retrieves the file it will parse it for CloudTrail events, filter the events which represent actual changes, and finally normalize and make the changes available in BigPanda for correlation with alerts.

Data Models

BigPanda converts and organizes the change data from CloudTrail into tags.

Standard CloudTrail Event Properties

The Event fields below populate the Changes tags.

Property

Change Tag

Attributes

eventID

identifier

Generates the ticket_url tag.

eventTime

start / end

eventName

summary

awsRegion & eventID

ticket_url

Hyperlink for the identifier tag

userIdentity

user_name, user_type, and user_arn

The userIdentity object is normalized to generate the user information tags

requestParameters

rp_{{object_key}}

This event property is an object. The keys are translated into Change tags with a prefix of rp_.

resources

resources{{array position}}_{object_key}}

This event property can be an array of Objects. The Change tag will always be resources + position number in the array + key

Installing the Integration

Prerequisites

  • Permission to create IAM roles and modify S3 event notifications in your AWS account
  • One or more CloudTrail trails configured and saving events to S3
  • Create and save a BigPanda API Key.
  • Create a Changes CloudTrail integration and save the app key.

Create an AWS Role for BigPanda

  1. In your AWS account, begin the creation of a new IAM role
  2. For Type of Trusted Entity select Another AWS Account
  3. For the Account ID field provide the BigPanda Account ID from the in-app integration page
  4. Click the checkbox for Require external ID and provide a random string for the External ID, noting the value for use later in these instructions
  5. Ensure the Require MFA box is NOT checked
  6. Click the Next button to move on to permissions
  7. Click the Create Policy button to create a new IAM policy for this role, a new browser tab should open
  8. In the JSON tab copy and paste the policy below, replacing BUCKET_NAME_HERE with the name of your S3 bucket which holds your CloudTrail events.
  9. Click Review Policy and name your policy, then click Create Policy.
  10. Once the policy is created, return to the role creation process and click the refresh button then search for and select your new role
  11. Proceed to the Review step of role creation and name your role, then click Create Role
  12. Locate your new role and note down its ARN
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowBigPandaGetObject",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::BUCKET_NAME_HERE/*"
    }
  ]
}

📘

IAM Role Policy

This policy only allows BigPanda to read CloudTrail events from your S3 bucket

Subscribe S3 Bucket to the CloudTrail Integration

With a role created and the S3 bucket configured you need to subscribe bucket to the CloudTrail integration.

Using cURL, Postman, or another tool, send a POST command to the CloudTrail subscription API endpoint, replacing the placeholders in the request body with their correct values.

POST https://inbound.bigpanda.io/cloudtrail/changes/subscribe
 
 {
  "apiKey": "BIGPANDA_API_KEY",
  "appKey": "BIGPANDA_APP_KEY",
  "bucket_name": "S3_BUCKET_NAME",
  "bucket_region": "S3_BUCKET_REGION",
  "iam_role_arn": "IAM_ROLE_ARN",
  "iam_role_external_id": "IAM_ROLE_EXTERNAL_ID"
}
curl -X POST \
  https://inbound.bigpanda.io/cloudtrail/changes/subscribe \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "BIGPANDA_API_KEY",
    "appKey": "BIGPANDA_APP_KEY",
    "bucket_name": "S3_BUCKET_NAME",
    "bucket_region": "S3_BUCKET_REGION",
    "iam_role_arn": "IAM_ROLE_ARN",
    "iam_role_external_id": "IAM_ROLE_EXTERNAL_ID"
}'

Configure S3 Bucket

In order for BigPanda to know when a new CloudTrail event is available, we need to configure an SQS event notification on your S3 Bucket which holds your trail data, sending a message to a BigPanda owned SQS Queue for every new trail file.

  1. In the AWS S3 Console locate and select the S3 bucket with your CloudTrail data
  2. From the Properties tab, under Advanced settings, click on the Events block
  3. Click Add notification
  4. Provide a name to the notification
  5. For Events select the All object create events option
  6. For Prefix provide the object path for CloudTrail logs objects, not for digest objects
  • Ex path: AWSLogs/<YOUR_AWS_ACCOUNT_ID>/CloudTrail/
  1. Leave Suffix blank
  2. For Send to select SQS Queue
  3. For SQS dropdown, scroll to the bottom to select Add SQS Queue ARN
  4. For SQS queue ARN provide BigPanda SQS Queue ARN which can be found on the in-app integration page

Uninstalling the Integration

Remove Event Notification from S3 Bucket

Please remove the previously configured event notification from your S3 bucket.

Remove BigPanda IAM Role

Please remove the previously created BigPanda IAM role. NOTE: Skip this step if you have more buckets configured using the same IAM role.

Unsubscribe from the Integration

Please also make sure to do the following to remove all aspects of the integration

  • Delete the S3 event notification
  • Delete the IAM Role created for this integration

Perform a DELETE request call to the CloudTrail subscription API endpoint. This will remove your bucket and AWS role from our records, though you can still re-add them again at a later date.

DELETE https://inbound.bigpanda.io/cloudtrail/changes/subscribe

{
    "apiKey": "BIGPANDA_API_KEY",
    "bucket_name": "S3_BUCKET_NAME"
}
curl -X DELETE \
  https://inbound.bigpanda.io/cloudtrail/changes/subscribe \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "BIGPANDA_API_KEY",
    "bucket_name": "S3_BUCKET_NAME"
}'

Updated 2 months ago

CloudTrail


CloudTrail provides event history of your AWS account activity, including actions taken through the AWS Management Console, AWS SDKs, command line tools, and other AWS services. Use this integration to track Shadow Changes from your AWS account in BigPanda.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.