> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threataware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS EC2 & SSM

> Connect ThreatAware to AWS for EC2 instance and Systems Manager monitoring

## Overview

The AWS EC2 & SSM integration enables ThreatAware to collect read-only data from your AWS account, providing visibility into EC2 instances, Systems Manager configurations, and cloud infrastructure.

<Info>
  **Connection Method**: IAM Role with Cross-Account Access
  **Setup Time**: 20 minutes
  **Access Required**: AWS Account Administrator or IAM permissions
  **ThreatAware Account ID**: available in-product under **Settings → Integrations → AWS Account / IP Whitelist Info**
</Info>

## Data collected

The AWS integration provides:

* EC2 instance details and status
* Systems Manager (SSM) agent information
* Instance metadata and configuration
* Multi-account inventory (optional)

## Use cases

<CardGroup cols={2}>
  <Card title="EC2 Instance Monitoring" icon="server">
    Track EC2 instances and compute resources across accounts
  </Card>

  <Card title="Systems Manager Tracking" icon="wrench">
    Monitor SSM agent status and Systems Manager configurations
  </Card>

  <Card title="Multi-Account Inventory" icon="sitemap">
    Discover resources across multiple AWS accounts with Organisations
  </Card>

  <Card title="Compliance Verification" icon="shield-halved">
    Validate EC2 and SSM configurations meet organisational standards
  </Card>
</CardGroup>

## Setup instructions

<Steps>
  <Step title="Log in to AWS Console">
    Visit the [AWS Management Console](https://aws.amazon.com/console/) and sign in with your AWS credentials.
  </Step>

  <Step title="Navigate to IAM">
    Access the **Identity and Access Management (IAM)** service from the AWS console dashboard.
  </Step>

  <Step title="Create a New Role">
    In the IAM console:

    * Select **Roles** from the left navigation
    * Click **Create role**
  </Step>

  <Step title="Select Trusted Entity">
    In the role creation wizard:

    * Choose **Another AWS Account** as the trusted entity type
    * Enter the ThreatAware Account ID (from **Settings → Integrations → AWS Account / IP Whitelist Info**)
    * Leave **Require external ID** unchecked for now
  </Step>

  <Step title="Configure External ID">
    For enhanced security, enable external ID:

    * Check **Require external ID**
    * Enter a complex string (like a password with no special characters)
    * Example: `ThreatAware123ExternalID456`

    <Warning>
      Use a complex string with letters and numbers, but no special characters. You will need to provide this to ThreatAware.
    </Warning>
  </Step>

  <Step title="Attach IAM Permissions">
    Add the required permissions to the role:

    * Select or create a policy with these permissions:
      * `ec2:DescribeInstances`
      * `ssm:DescribeInstanceInformation`

    <Tip>
      For AWS Organisations setup, also add: `organization:ListAccounts`
    </Tip>
  </Step>

  <Step title="Review and Create Role">
    Review the role configuration:

    * Verify the trusted entity is the ThreatAware Account
    * Confirm the permissions are correct
    * Copy the **Role ARN** for later use
    * Click **Create role**
  </Step>

  <Step title="Record Credentials">
    Document the following for ThreatAware configuration:

    * **AWS Account ID**: Your 12-digit AWS account ID
    * **Role ARN**: The full ARN of the role you created
    * **External ID**: The external ID string you configured (if used)
    * **Region**: Your primary AWS region
  </Step>

  <Step title="Configure Multiple Accounts (Optional)">
    If connecting multiple AWS accounts:

    * Repeat steps 3-7 for each AWS account
    * Each account needs its own role with the same permissions
    * Each role must trust the ThreatAware Account (see **Settings → Integrations → AWS Account / IP Whitelist Info**)
  </Step>

  <Step title="AWS Organisations Setup (Optional)">
    For organisation-wide monitoring:

    * Create a role in the parent/management account
    * Add permission: `organization:ListAccounts`
    * Add the same EC2 and SSM permissions as individual accounts
    * Provide only the parent account ID to ThreatAware
    * ThreatAware will discover all member accounts automatically
  </Step>

  <Step title="Configure in ThreatAware">
    In ThreatAware, go to **Integrations** and select **AWS EC2 & SSM**:

    * Enter the **AWS Account ID**
    * Enter the **Role ARN**
    * Enter the **External ID** (if configured)
    * Enter your primary **Region**
    * Click **Connect**
  </Step>

  <Step title="Verify Connection">
    After connecting, verify the integration:

    * Check that the **Integration Status** shows as **Active**
    * Wait for initial data synchronization (typically 1 hour)
    * Verify EC2 and SSM data appears in ThreatAware
  </Step>
</Steps>

## Required configuration

<AccordionGroup>
  <Accordion title="AWS Account ID" icon="key">
    **Field Name**: AWS Account ID
    **Type**: String (12 digits)
    **Description**: Your AWS account ID where the role is created

    Example: `123456789012`

    <Tip>
      Find your account ID in the AWS Console top right corner or in the Account menu.
    </Tip>
  </Accordion>

  <Accordion title="Role ARN" icon="shield">
    **Field Name**: IAM Role ARN
    **Type**: String
    **Description**: The full ARN of the cross-account role

    **Format**: `arn:aws:iam::123456789012:role/RoleName`

    **Example**: `arn:aws:iam::123456789012:role/ThreatAwareRole`
  </Accordion>

  <Accordion title="External ID" icon="lock">
    **Field Name**: External ID
    **Type**: String (optional)
    **Description**: The external ID configured for enhanced security

    Example: `ThreatAware123ExternalID456`

    <Warning>
      Only required if you enabled "Require external ID" when creating the role.
    </Warning>
  </Accordion>

  <Accordion title="AWS Region" icon="globe">
    **Field Name**: AWS Region
    **Type**: String
    **Description**: Your primary AWS region

    **Examples**:

    * `us-east-1`
    * `eu-west-1`
    * `ap-southeast-1`
  </Accordion>
</AccordionGroup>

## IAM policy templates

<AccordionGroup>
  <Accordion title="Single Account Policy" icon="file-contract">
    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "ec2:DescribeInstances",
            "ssm:DescribeInstanceInformation"
          ],
          "Resource": "*"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Assume Role Policy" icon="handshake">
    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::<THREATAWARE_ACCOUNT_ID>:root"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "YourExternalIDHere"
            }
          }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Parent Account Policy (Organisations)" icon="sitemap">
    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": [
            "ec2:DescribeInstances",
            "ssm:DescribeInstanceInformation",
            "organizations:ListAccounts"
          ],
          "Resource": "*"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## Verification and testing

After setup, verify the integration is working correctly:

1. **Check Integration Status**
   * Navigate to **Integrations** in ThreatAware
   * Confirm the AWS EC2 & SSM integration shows **Active** status

2. **Verify Data Collection**
   * Wait for initial data sync (1 hour)
   * Log in to AWS Console and note your EC2 instances
   * Verify the same instances appear in ThreatAware

3. **Test Multi-Account Setup**
   * Verify instances from all accounts appear
   * Check that instance metadata is complete and accurate

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid Account ID or Role ARN" icon="triangle-exclamation">
    **Symptoms**: Connection fails immediately or shows invalid credentials

    **Solutions**:

    * Verify the AWS Account ID is exactly 12 digits
    * Check the Role ARN format is correct: `arn:aws:iam::ACCOUNT:role/ROLENAME`
    * Ensure the role exists and is visible in the AWS IAM console
    * Copy values directly from AWS console to avoid typos
  </Accordion>

  <Accordion title="External ID Mismatch" icon="ban">
    **Symptoms**: Connection fails with authentication error

    **Solutions**:

    * Verify the External ID matches exactly (case-sensitive)
    * Ensure you only use letters and numbers (no special characters)
    * Double-check the External ID in both the role and ThreatAware
    * If unsure, create a new role without External ID for testing
  </Accordion>

  <Accordion title="Permission Denied" icon="shield-exclamation">
    **Symptoms**: Integration connects but shows no EC2/SSM data

    **Solutions**:

    * Verify the role has these permissions: `ec2:DescribeInstances`, `ssm:DescribeInstanceInformation`
    * Check that the policy is attached to the role
    * Wait 5-10 minutes for IAM changes to propagate
    * Confirm the Assume Role policy trusts the ThreatAware account (see **Settings → Integrations → AWS Account / IP Whitelist Info**)
  </Accordion>

  <Accordion title="No Data After 1 Hour" icon="database">
    **Symptoms**: Integration shows active but EC2/SSM data doesn't appear

    **Solutions**:

    * Verify you have EC2 instances in the specified region
    * Confirm the role permissions include all required actions
    * Check that Systems Manager is properly configured for SSM data
    * Review AWS CloudTrail logs for API calls from ThreatAware
    * Contact AWS support if permission issues persist
  </Accordion>

  <Accordion title="AWS Organisations Not Working" icon="sitemap">
    **Symptoms**: Organisations setup returns no member accounts

    **Solutions**:

    * Verify the role is created in the parent/management account
    * Ensure the role includes `organization:ListAccounts` permission
    * Confirm AWS Organisations is enabled in your account
    * Check that all member accounts are properly linked
    * Provide only the parent account ID to ThreatAware, not member accounts
  </Accordion>
</AccordionGroup>

## Additional resources

<CardGroup cols={2}>
  <Card title="AWS IAM Documentation" icon="book" href="https://docs.aws.amazon.com/iam/">
    Official AWS IAM documentation for role configuration
  </Card>

  <Card title="AWS EC2 Documentation" icon="server" href="https://docs.aws.amazon.com/ec2/">
    AWS EC2 service documentation
  </Card>

  <Card title="AWS Systems Manager Documentation" icon="wrench" href="https://docs.aws.amazon.com/systems-manager/">
    AWS Systems Manager documentation
  </Card>

  <Card title="ThreatAware Support" icon="life-ring" href="mailto:help@threataware.com">
    Contact ThreatAware support for integration assistance
  </Card>
</CardGroup>

## Best practices

<Tip>
  **Security Configuration**

  * Always enable External ID for enhanced security
  * Use complex External ID strings (letters and numbers only)
  * Document all credentials and External IDs securely
  * Review IAM permissions regularly
  * Monitor CloudTrail for ThreatAware API activity
</Tip>

<Tip>
  **Multi-Account Management**

  * Use AWS Organisations for centralized monitoring
  * Create dedicated roles for ThreatAware in each account
  * Maintain consistent External IDs across all accounts
  * Test connectivity in one account before adding others
  * Document the structure of your AWS accounts
</Tip>