AuditBadger Help Center

AuditBadger AWS Integration Setup Guide

Open in
View as Markdown Open in ChatGPT Open in Claude
M

Maciej Litwiniuk

Last updated on Jul 29, 2026

Table of Contents

  1. Overview

  2. Prerequisites

  3. Quick Start (CloudFormation)

  4. Manual Setup

  5. Verifying the Connection

  6. Enabling Evidence Sources

  7. Troubleshooting

  8. Security & Permissions

Overview

AuditBadger's AWS integration enables automated evidence collection for SOC 2 and ISO 27001 compliance. Once connected, AuditBadger can:

  • Collect IAM password policies and MFA status

  • Monitor CloudTrail audit logging configuration

  • Check S3 encryption and public access settings

  • Verify GuardDuty threat detection status

  • Review security group configurations

  • Track RDS encryption and backups

  • Monitor KMS key rotation

  • And more...

How It Works

  1. You create a read-only IAM role in your AWS account

  2. AuditBadger assumes this role to collect compliance evidence

  3. Evidence is collected on a compliance-focused schedule (weekly or monthly)

  4. Sources with auto-verification enabled are checked against their configured compliance rules

  5. Results are linked to your SOC 2/ISO 27001 controls

Security Model

  • Read-only access: AuditBadger cannot modify your AWS resources

  • Cross-account role assumption: We use AWS STS to securely access your account

  • External ID protection: Prevents confused deputy attacks

  • Time-limited credentials: Sessions expire after 1 hour

  • Auditable sessions: AWS API activity is attributable to the assumed AuditBadger role session where AWS records the relevant CloudTrail management events

Prerequisites

Before starting, ensure you have:

  • An AWS account with admin access (to create IAM roles)

  • Your AuditBadger account with an active subscription

  • Access to the AWS Console or AWS CLI

Quick Start (CloudFormation)

The fastest way to set up the integration is using CloudFormation.

Step 1: Navigate to AWS Integration

  1. Log in to AuditBadger

  2. Go to Settings → Integrations → AWS

  3. Click Connect AWS Account

Step 2: Launch CloudFormation Stack

  1. Click Launch CloudFormation Stack

  2. This opens AWS CloudFormation with a pre-configured template

  3. The required parameters (AuditBadger Account ID and External ID) are pre-filled

  4. New stacks use the AuditBadgerAccountId parameter and default to the AuditBadgerComplianceRole role name

Legacy compatibility: Older saved links or existing stacks may still show the HumadroidAccountId parameter or HumadroidComplianceRole role name. The template also retains HumadroidComplianceRole as its internal CloudFormation resource identifier. These names remain only to prevent existing installations from breaking. HumadroidAccountId is an alias for the same AuditBadger AWS account ID; it does not identify a separate service or account.

Step 3: Create the Stack

  1. Review the stack parameters

  2. Scroll down to Capabilities

  3. Check the box: "I acknowledge that AWS CloudFormation might create IAM resources"

  4. Click Create stack

Step 4: Copy Role ARN

  1. Wait for the stack to reach CREATE_COMPLETE status (~1-2 minutes)

  2. Go to the Outputs tab

  3. Copy the RoleArn value

Step 5: Complete Connection

  1. Return to AuditBadger

  2. Paste the Role ARN and choose the default AWS region

  3. Click Connect AWS account

  4. AuditBadger validates the connection in the background; use Test connection on the connected-account panel to run the health checks again

Manual Setup

If you prefer to create the IAM role manually:

Step 1: Create IAM Role

  1. Open the AWS Console

  2. Navigate to IAM → Roles

  3. Click Create role

Step 2: Configure Trust Relationship

  1. Select Another AWS account as the trusted entity type

  2. Enter the AuditBadger AWS Account ID: [shown in AuditBadger setup page]

  3. Check Require external ID

  4. Enter the External ID: [shown in AuditBadger setup page]

  5. Click Next

Step 3: Attach Permissions

Attach the following policies:

  1. SecurityAudit (AWS managed policy)

  2. A custom inline policy for additional permissions (see below)

Step 4: Name the Role

  1. Role name: Use the name shown in the AuditBadger setup page (default: AuditBadgerComplianceRole)

  2. Add a description: "Read-only role for AuditBadger compliance evidence collection"

  3. Click Create role

Note: The role name is configurable per AuditBadger environment. If you're connecting the same AWS account to multiple AuditBadger environments (e.g., production and development), each environment will specify a different role name to avoid conflicts.

Compatibility: Existing roles named HumadroidComplianceRole do not need to be renamed. AuditBadger validates the role ARN, trust policy, external ID, and permissions; the role name itself is not part of the application contract.

Step 5: Copy Role ARN

  1. Open the newly created role

  2. Copy the Role ARN from the Summary section

  3. Format: arn:aws:iam::YOUR_ACCOUNT_ID:role/ROLE_NAME

Custom Inline Policy

The CloudFormation template is the source of truth for the AuditBadgerCompliancePolicy inline policy. The older abbreviated S3, Backup, and AWS Config example previously shown here was not a complete replacement for the current template.

For a manual installation:

  1. Open the current auditbadger_compliance_role.yaml template

  2. Copy the complete AuditBadgerCompliancePolicy policy document to the manually created role

  3. Keep the AWS-managed SecurityAudit policy attached

  4. Return to AuditBadger and run Test connection

The template's S3 hostname retains legacy infrastructure naming, but the published filename, policy, default role name, and customer-facing setup all use AuditBadger.

For the exact operations used by current evidence checks and the permissions inherited from SecurityAudit, see AWS Permissions Required.

Verifying the Connection

In AuditBadger

After entering your Role ARN:

  1. Click Test Connection

  2. You should see:

    • ✅ Connection successful

    • AWS Account ID: Your 12-digit account ID

    • Account Alias: Your AWS account alias (if set)

    • Available Services: List of accessible AWS services

Common Verification Results

  • All services accessible: The integration is ready; enable the desired evidence sources.

  • Some services inaccessible: The role has partial permissions; compare its policies with the current CloudFormation template.

  • Authentication failed: AuditBadger could not assume the role; verify the AuditBadger Account ID, External ID, and trust policy.

  • Role not found: Check that the Role ARN was copied exactly from the CloudFormation stack output or IAM role summary.

Enabling Evidence Sources

Once connected, enable evidence sources for your compliance controls:

Step 1: Navigate to a Control

  1. Go to Compliance → Projects → Select your SOC 2 or ISO 27001 project

  2. Open a control (e.g., CC6.1 - Logical Access Security)

Step 2: View Available Evidence Sources

  1. Click the Evidence Sources tab

  2. You'll see suggested AWS evidence sources for this control

  3. Each source shows:

    • Name and description

    • Collection frequency

    • Auto-verify status

Step 3: Enable Sources

  1. Click Enable next to each desired source

  2. Optionally customize:

    • Collection frequency (weekly or monthly)

    • Verification rules thresholds

  3. Click Save

Evidence Collection Schedule

  • Weekly: Used by active findings and backup-job evidence sources.

  • Monthly: Used by configuration, encryption, access, and audit-snapshot evidence sources.

Collection scheduling is managed by AuditBadger. The evidence source shows its configured frequency in the application.

Troubleshooting

Error: "Cannot assume role"

Cause: Trust relationship is incorrectly configured.

Solution:

  1. Open your IAM role in AWS Console

  2. Go to Trust relationships tab

  3. Verify the trust policy contains:

    {
  "Principal": {"AWS": "arn:aws:iam::AUDITBADGER_ACCOUNT_ID:root"},
  "Condition": {
    "StringEquals": {"sts:ExternalId": "YOUR_EXTERNAL_ID"}
  }
}

  4. Ensure both Account ID and External ID match AuditBadger's values exactly

Error: "Access Denied for iam:GetAccountPasswordPolicy"

Cause: Missing IAM permissions.

Solution:

  1. Ensure the SecurityAudit policy is attached

  2. Or add the specific permission to your inline policy

Error: "Rate limit exceeded"

Cause: Too many API requests in a short period.

Solution:

  1. AuditBadger automatically retries with exponential backoff

  2. If persistent, reduce collection frequency

  3. Contact support if issues continue

Error: "Service unavailable"

Cause: Temporary AWS service issue.

Solution:

  1. AuditBadger automatically retries these errors

  2. Check AWS Service Health Dashboard

  3. Collection will succeed on next attempt

Connection works but evidence collection fails

Possible causes:

  1. Role permissions changed after initial connection

  2. Evidence source needs permissions not in SecurityAudit

  3. AWS service not enabled in your account (e.g., GuardDuty)

Solution:

  1. Re-test connection to verify permissions

  2. Check the evidence source error message for specific permissions

  3. Enable the AWS service if required

Security & Permissions

Permissions by Evidence Type

The role uses read-only operations across IAM, CloudTrail, CloudWatch, AWS Config, GuardDuty, Security Hub, EC2, S3, RDS, KMS, AWS Backup, and STS.

The complete, current operation list is maintained in AWS Permissions Required. That guide also explains why the role can show permissions inherited from AWS's managed SecurityAudit policy even when AuditBadger does not call those operations.

Data Handling

  • Evidence data is encrypted at rest and in transit

  • Raw API responses are stored for audit purposes

  • Data retention follows your AuditBadger plan settings

  • You can delete evidence at any time

Revoking Access

To disconnect AuditBadger from your AWS account:

  1. In AuditBadger: Settings → Integrations → AWS → Disconnect

  2. In AWS: Delete the role shown in your integration settings, usually AuditBadgerComplianceRole. Older installations may still use HumadroidComplianceRole.

Support

If you need help with your AWS integration: