AWS Single Account Setup

Overview

Heeler supports 3 different approaches for setting a single AWS account

  • Cloud Formation

  • Terraform

  • AWS CLI

CloudFormation

To set up Heeler in a single AWS account, Heeler deploys a CloudFormation template that provisions the necessary resources. This includes a dedicated IAM role and policy with tightly scoped permissions. These permissions allow Heeler to access only metadata and configuration information about your cloud environment—never your application data. The CloudFormation template is automatically launched during the onboarding wizard, or you can download it here.

The template performs the following actions:

Account

  • Create an IAM policy, Heeler, that denies visibility to the customer data plane. This includes actions such as s3:GetObject, dynamodb:GetItem and more.

  • Create an IAM policy, HeelerEKS, that allows EKS cluster API access configuration so Heeler can automatically harvest Kubernetes resources.

  • Create a single role, heeler-member, with the newly created policies as well as the AWS-managed policy ReadOnlyAccessto allow visibility into the account. It also is configured with a trust policy that allows heeler-management-ro to assume it.

Heeler Connection Setup

  1. Select the icon from the top navigation

  2. Navigate to the Connections tab

  3. Select Cloud Accounts

  4. Click Add Cloud Account and select AWS

  5. Select Setup with CloudFormation

  1. Select Launch CloudFormation Template

  1. Choose your active session or sign into a new session. The session should be in the payer account.

a

  1. On Heeler click the next button so you can retrieve the generated External ID

  1. Confirm that the stack launches into the desired AWS account, that it is deploying the Heeler CFT, and that it has the HeelerAccountSetup Stack name.

  1. Provide or accept the default parameters:

  2. Heeler Role Name (Required): Default value is heeler-member. Can be updated

  3. External ID (Recommended): Retrieve the generated External ID from Heeler. Can be updated or deleted if desired

  4. Role ARN provided by Heeler Security: Default value should not be changed unless instructed otherwise

  1. As this CloudFormation StackSet deploys IAM roles and policies, you must acknowledge their creation and then select Create stack

  1. No action required. You can monitor the creation of resources by viewing the Events tab. The deployment is complete when it says CREATE_COMPETE.

  1. Coply the newly created ARN for heeler-member to use when configuring the connection in Heeler, by clicking the link.

  1. Back in the Heeler modal, populate the values:

    1. Name: a human-friendly name that identies the organization in Heeler

    2. Role ARN: the ARN for heeler-member

    3. External ID: the ExternalID

    4. Region Restrictions: Optional list of regions in which to limit harvesting. This configuration is helpful if resources are limited by Service Control Policies to specific regions.

    5. Select Done

  1. When added successfully, you will see a Healthy notification status

Terraform

Heeler provides the template within the on-boarding wizard but you can also view here.

Manual with AWS CLI

For utilizing the AWS CLI, a bash script is provided to execute the AWS CLI commands.

AWS CLI Script

5KB
heeler_aws_cli.sh

What the script does:

  1. Creates the main "Heeler" managed policy with deny rules for sensitive data access and allow rules for Lambda and SSM

  2. Creates the "heeler-member" IAM role with proper assume role policy and external ID condition

  3. Attaches the AWS managed ReadOnlyAccess policy to the role

  4. Attaches the custom Heeler policy to the role

  5. Creates and attaches the "HeelerEKS" policy for EKS cluster access

Before running the script:

  1. Set the EXTERNAL_ID variable - Replace "your-external-id-here" with the actual external ID provided by Heeler Security

  2. Optionally modify MEMBER_ROLE_NAME if you want a different role name

  3. Verify the HEELER_SECURITY_ROLE_ARN is correct (currently set to the default from the template)

To use the script:

  1. Make it executable: chmod +x heeler_aws_cli.sh

  2. Run it: ./heeler_aws_cli.sh

The script includes verification commands at the end to help you confirm everything was created correctly. It also cleans up the temporary JSON policy files after use.

Heeler Connection Setup

  1. Select the icon from the top navigation

  2. Navigate to the Connections tab

  3. Select Cloud Accounts

  4. Click Add Cloud Account and select AWS

  5. Select Setup account manually

  1. Click Next to retrieve the generated External ID needed for the script

  1. After updating the script with the External ID, run the script:

aws configure
./heeler_aws_cli.sh

  1. Retrive the Member Role Arn from the script output

  1. Back in the Heeler modal, populate the values:

    1. Name: a human-friendly name that identies the organization in Heeler

    2. Role ARN: the ARN for heeler-member

    3. External ID: the ExternalID

    4. Region Restrictions: Optional list of regions in which to limit harvesting. This configuration is helpful if resources are limited by Service Control Policies to specific regions.

    5. Select Done

  1. When added successfully, you will see a Healthy notification status

PreviousAWS Event CollectionNextGoogle Cloud Platform

Last updated

Was this helpful?