## **Table of Contents**

1. [Overview](#overview)

2. [Prerequisites](#prerequisites)

3. [Quick Start (CloudFormation)](#quick-start-cloudformation)

4. [Manual Setup](#manual-setup)

5. [Verifying the Connection](#verifying-the-connection)

6. [Enabling Evidence Sources](#enabling-evidence-sources)

7. [Troubleshooting](#troubleshooting)

8. [Security & Permissions](#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`](https://humadroid-static-assets.s3.eu-central-1.amazonaws.com/cloudformation/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](guide_aws-integration.md#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](guide_aws-integration.md#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:

* Documentation: [AuditBadger AWS integration documentation](https://docs.auditbadger.com/integrations/aws)

* Related guide: [AWS Integration User Guide](guide_aws-integration.md)