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

# AWS Integration

> Connect Pwnbook to AWS to discover cloud resources, identify security misconfigurations, and import infrastructure into your engagement's architecture model.

## Overview

The AWS integration lets you scan one or more AWS accounts from within Pwnbook. It discovers running resources, checks for security misconfigurations, and imports the findings into your engagement. This is especially useful for cloud security assessments and infrastructure reviews.

## Prerequisites

To connect an AWS account, you'll need:

* An AWS account with permissions to create IAM roles and policies
* Admin or Owner access in Pwnbook to configure the integration
* The target AWS account ID and the region(s) you want to scan

## Connecting an AWS account

Pwnbook uses an IAM role with read-only permissions to access your AWS account. This follows the AWS recommended cross-account access pattern, giving you full control over what Pwnbook can see.

<Steps>
  <Step title="Open the AWS integration">
    Go to **Organization Settings** → **Marketplace** → **AWS**.

    Click **Connect AWS Account**.
  </Step>

  <Step title="Create the IAM role in AWS">
    Pwnbook will provide a CloudFormation template or manual instructions for creating an IAM role in your target AWS account.

    **Using CloudFormation (recommended):**

    1. Click **Deploy CloudFormation Stack**.
    2. You'll be redirected to the AWS CloudFormation console with the template pre-loaded.
    3. Review the template — it creates a read-only IAM role with an external ID for secure cross-account access.
    4. Click **Create Stack**.
    5. Wait for the stack to complete (usually 1-2 minutes).

    **Manual setup:**

    1. In the AWS IAM console, create a new IAM role.
    2. Choose **Another AWS account** as the trusted entity.
    3. Enter the Pwnbook AWS account ID shown in the integration setup.
    4. Enter the External ID shown in the integration setup.
    5. Attach the `SecurityAudit` and `ReadOnlyAccess` managed policies.
    6. Create the role and copy its ARN.
  </Step>

  <Step title="Enter the role ARN in Pwnbook">
    Back in Pwnbook, paste the IAM role ARN into the **Role ARN** field.

    Select the AWS regions you want to include in scans.

    Click **Test Connection** to verify Pwnbook can assume the role successfully.

    Click **Save** to complete the connection.
  </Step>
</Steps>

## Running resource discovery

Once an AWS account is connected, you can discover what's running in it:

1. Go to **Organization Settings** → **Integrations** → **AWS**.
2. Select the connected account.
3. Click **Run Discovery**.
4. Choose the resource types to discover and the regions to scan.
5. Click **Start**.

Discovery runs as a background job. You'll receive a notification when it completes.

### Discoverable resource types

Pwnbook can discover and inventory the following AWS resource types:

<AccordionGroup>
  <Accordion title="Compute">
    EC2 instances, Auto Scaling groups, ECS clusters and tasks, Lambda functions, Elastic Beanstalk environments
  </Accordion>

  <Accordion title="Networking">
    VPCs, subnets, security groups, load balancers (ALB, NLB, CLB), CloudFront distributions, Route 53 zones and records
  </Accordion>

  <Accordion title="Storage">
    S3 buckets (with public access status), EBS volumes, EFS file systems, RDS instances and clusters
  </Accordion>

  <Accordion title="Identity and access">
    IAM users, roles, policies, and access keys; Cognito user pools
  </Accordion>

  <Accordion title="Security services">
    GuardDuty findings, Security Hub findings, Inspector findings, CloudTrail trails, Config rules and compliance status
  </Accordion>
</AccordionGroup>

## Security findings

Pwnbook automatically checks for common security misconfigurations during discovery scans:

| Check                             | Description                                                           |
| --------------------------------- | --------------------------------------------------------------------- |
| Public S3 buckets                 | Identifies buckets with public read or write access                   |
| Overly permissive security groups | Flags security groups allowing `0.0.0.0/0` inbound on sensitive ports |
| Unencrypted storage               | RDS instances, EBS volumes, and S3 buckets without encryption         |
| Exposed IAM access keys           | IAM users with active access keys that haven't been rotated recently  |
| MFA not enforced                  | IAM users without MFA enabled                                         |
| CloudTrail not enabled            | Regions without active CloudTrail logging                             |
| GuardDuty/Security Hub findings   | Imports active findings from AWS security services                    |

Findings are imported into the engagement as security findings and appear in the recon results and can be referenced in reports.

## Importing into architecture models

After running discovery, import the discovered resources into an engagement's architecture model:

1. Open the engagement.
2. Navigate to the **Architecture** tab.
3. Click **Import Infrastructure**.
4. Select **AWS** and the connected account.
5. Choose which resources to import.
6. Click **Import**.

Pwnbook creates components for each resource and maps data flows based on security group rules and VPC topology. You can then edit, annotate, and extend the model from the architecture canvas.

## Scan jobs

Each discovery or security scan is tracked as a scan job. To view scan history:

1. Go to **Organization Settings** → **Integrations** → **AWS**.
2. Select the connected account.
3. Click **Scan History**.

Each job shows:

* Start and completion time
* Regions scanned
* Resource counts by type
* Any errors encountered

## Removing an AWS account

To disconnect an AWS account:

1. Go to **Organization Settings** → **Integrations** → **AWS**.
2. Click **Disconnect** next to the account.
3. Confirm the disconnection.

After disconnecting, delete the IAM role from your AWS account to remove Pwnbook's access entirely. Previously discovered data remains in Pwnbook until you delete it manually.