AWS CloudTrail Integration

Note: This feature is currently in a limited access beta . Please contact us if you'd like to participate.

AWS CloudTrail is a very comprehensive audit log of every action taken in your AWS account. FireHydrant's CloudTrail integration imports these changes to your AWS infrastructure and links them with your environments, letting you see changes to your system alongside GitHub Pull Requests, deploys, PagerDuty alerts and more. 

You can install by clicking Setup next to AWS CloudTrail on your organization's integration page and following the prompts. You'll be guided to create a role in your AWS account allowing FireHydrant access to your resources without exchanging any credentials.

We have a Terraform module, CloudFormation template and documentation with raw policies to create the role and necessary policies. Specific examples customized to your account are available on the Edit Connection page.

Terraform Module

Our Terraform Module is available on GitHub and can be used as-is or imported into your own infrastructure module repository. 

The only part of this example that needs to be modified is the firehydrant_external_id  parameter and this can be found on the Edit Connection page. More details about the external ID parameter can be found under Authentication Workflow.

module "firehydrant-cloudtrail" {
  source = ""
  firehydrant_external_id = "c0ffeec0ffeec0ffee"

output "firehydrant-readonly-role-arn" {
  value = "${module.firehydrant-cloudtrail.firehydrant-readonly-role-arn}"

Once you create this resource, the ARN for the new role will be returned as an output. Update your AWS CloudTrail connection with that ARN and we'll begin importing events.

CloudFormation Template

Our CloudFormation Template is available on Github and can be used through the AWS Console or as part of your existing CloudFormation infrastructure.

The simplest way to get started with this is by clicking the Quick Create CloudFormation Stack button on the Connection Edit page. This will redirect you to the AWS Console where you'll be prompted to accept the new role.

To create this from the command line you'll need to include the ExternalId  parameter when creating the stack, as above in the Terraform example. When you call create-stack , AWS will start creating the resources in the background.

$ aws cloudformation create-stack --stack-name firehydrant-read-only \
--template-url= \
--capabilities CAPABILITY_IAM --parameters ParameterKey=ExternalId,ParameterValue=c0ffeec0ffeec0ffee

$ watch aws cloudformation describe-stacks --stack-name firehydrant-read-only --query 'Stacks[0].StackStatus' --output=text

$ aws cloudformation describe-stacks --stack-name firehydrant-read-only --query "Stacks[0].Outputs[0].OutputValue" --output=text

Wait until the status of the newly created stack is CREATE_COMPLETE then run the last describe-stacks  command to get the ARN of your new role. Update your AWS CloudTrail connection with that ARN and we'll begin importing events.


Thanks to AWS' powerful IAM capabilities we're able to consume CloudTrail events from your account without exchanging credentials. There are three pieces involved in this connection:

  • IAM Role - the actor we'll be assuming in your account
  • Trust Relationship - the document restricting who can assume that role
  • IAM Policy - the specific permissions granted to the new role

Amazon has a great document explaining the process of granting another AWS account access to your resources. The following documents are examples of the trust relationship and IAM policy we require in order to read your CloudTrail events. The real documents can be found on the Edit Connection page on your CloudTrail connection.

  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam:123456789012:role/FireHydrant"
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "c0ffeec0ffeec0ffee"

This trust policy says that only the FireHydrant role in account 123456789012 is allowed to assume the new role. The ExternalId parameter is extra security to guard against the "confused deputy" problem; AWS has a great summary of it in their documentation. We generate this parameter for each connection and it is not configurable.

    "Version": "2012-10-17",
    "Statement": [
            "Effect": "Allow",
            "Action": [
            "Resource": "*"

This IAM policy restricts the actions we're allowed to perform in your account; most of them are self-explanatory as far as reading CloudTrail resources. The last one in the list, sts:GetCallerIdentity  simply allows our API to confirm the role name that we're acting as. 

Once these resources are created in your account, we'll begin importing your events on a regular schedule. AWS CloudTrail events are batched up and made available through their API approximately ten minutes after the action is taken. We aim to display these events as quickly as possible but please remember that they will be delayed at least ten minutes.

Was this article helpful?
0 out of 0 found this helpful

Articles in this section

See more