Skip to main content

Implementing Change Detection with IAMbic on AWS

Introduction​

IAMbic, in a standard production deployment, periodically imports your cloud resources into Git, establishing an "eventually consistent" state between your Git repository and your Cloud IAM. This process can be resource-intensive as it involves fetching all resources from the cloud, comparing them to your existing IAMbic templates, and updating them if needed.

By default, this import operation runs every four hours in a standard production deployment via GitHub using AWS EventBridge Rules

However, if you're like us, you'd want a more real-time reflection of your IAM in Git, desiring changes to be visible soon after their occurrence. For AWS, this is achievable via AWS Change Detection. This feature utilizes AWS EventBridge and SQS to promptly identify modifications to your IAM resources. IAMbic can be invoked frequently to perform the inexpensive operation of reading an SQS queue, and refreshing the cloud resources that have changed. By default, this action runs every 15 minutes. If you're using self-hosted runners, and have a normal IAM setup, you should be able to run the detection flow every minute. Git would typically be updated with the actual state of your cloud IAM within a few minutes of the change occurring.

Understanding AWS Change Detection in IAMbic​

AWS Change Detection operates by setting up a Cloudformation Stack on your Organizational Management account. This stack is responsible for:

  1. Establishing an EventBridge Event Bus for IAMbic, facilitating the receipt of messages from any other event bus within your organization.
  2. Creating an EventBridge change detection rule that monitors create, update, and delete (CRUD) events on IAM or Identity Center resources.
  3. Producing an SQS queue that acts as a target for receiving corresponding events.

In addition, IAMbic employs a Cloudformation Stackset to set up an EventBridge rule and an IAM role across all other accounts in your Organization. These keep track of CRUD events on IAM or Identity Center resources on the respective account, and forward them to the Event Bus that was created on your Organizational Management account.

Configuring AWS Change Detection​

Setting up change detection with IAMbic is a straightforward process. Run the command iambic setup and choose Setup AWS change detection. This option will only appear if you have previously configured an AWS Organization.

Executing this command will initiate the Cloudformation Stack and Stackset on your behalf, effectively activating AWS Change Detection for your IAM resources.

Configure CloudTrail Log Integration with AWS Change Detection​

  1. Make sure you have already configure AWS Change Detection from the above section
  2. Make sure you have allowed your gist repo to be accessed by your IAMbic GitHub App
  3. (Optional) If you have branch protection in your gist repo, you allow your IAMbic GItHub App to bypass pull request requirement
  4. Update your IAMbic config in your iambic-templates repo just like this example change:
  5. Make an out-of-band change in your AWS console to update the description of a IAM role
  6. Trigger a detect run in your IAMbic template repo (Note: This is a manual run. Automatic run is triggered from EventBridge Rule Schedule)
  7. In a few minutes, you should see the out-of-band change reflected in your iambic-templates repo

Filtering Event Messages using AWS EventBridge Rules​

You may customize the EventBridge rule that is used to trigger IAMbic resource imports on changes, if you want to trigger refreshes on a subset of events.

To modify the AWS EventBridge rule, visit the Amazon EventBridge page in the rule's respective region, select the rule that you want to modify and edit the event pattern attribute. By default, IAMbic uses the rule configuration below, what is listening to mutation events from IAM, Identity Center (SSO) and Organizations.

EventPattern:
    detail-type:
        - AWS API Call via CloudTrail
    detail:
        eventSource:
            - iam.amazonaws.com
            - sso.amazonaws.com
            - organizations.amazonaws.com
        eventName:
            - prefix: Create
            - prefix: Update
            - prefix: Attach
            - prefix: Detach
            - prefix: Add
            - prefix: Delete
            - prefix: Put
            - prefix: Remove
            - prefix: Tag
            - prefix: Untag

Please be cautious when modifying the Event Pattern. An incorrect configuration could cause IAMbic to miss events that are important to you, or flood IAMbic with irrelevant CloudTrail logs. Reference the guides below to understand how event patterns can be modified.

Additional Resources: