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

# AWS

> Discover public-exposure AWS resources across accounts and regions, and add them to your attack surface

The AWS integration discovers internet-facing resources in your AWS account and adds them to your workspace as targets and assets. It connects read-only and runs on a schedule you control.

## Prerequisites

* An AWS account with permission to create IAM policies and, for role-based methods, an assumable IAM role.
* For **multi-account discovery**, AWS Organizations enabled and the ability to list its accounts.
* Read access to the services you want discovered: Route 53, EC2, Elastic Load Balancing, CloudFront, API Gateway, RDS, and S3. Add `organizations:ListAccounts` for multi-account discovery, and `sts:AssumeRole` for role-based methods.

<Info>
  The integration is read-only. It calls only list, describe, and get operations, plus STS and Organizations calls to resolve credentials. It never changes your AWS resources.
</Info>

## Choose a connection method

AWS supports five credential methods. Pick the one that matches how your organization issues AWS access.

| Method | Use it when | Required fields |
| - | - | - |
| **Access key** | You have a static IAM user or role access key for one account. | Access key ID, secret access key |
| **Assume role (multi-account)** | You want to scan every account in AWS Organizations from one set of base credentials. | Access key ID, secret access key, role ARN, external ID |
| **Cross-account role** | You want to scan one other account by assuming a role in it. | Access key ID, secret access key, role ARN, external ID |
| **Workload identity** | You authenticate with a short-lived OIDC/OAuth token instead of long-lived keys. | Role ARN, web identity token |
| **IAM Identity Center (SSO)** | You sign in through an AWS access portal and the integration uses a refresh token. | Region, start URL — the connect wizard fills the rest |

## Connect AWS

<Steps>
  <Step title="Open the Applications tab">
    In the console sidebar, open **Integrations** and select the **Applications** tab.
  </Step>

  <Step title="Open AWS">
    Select the **AWS** card. The connection form opens on the right.
  </Step>

  <Step title="Enter a name and choose a connection method">
    Enter an **Integration name**, then select a **Connection method**. The form shows only the fields that method needs.
  </Step>

  <Step title="Fill in the credentials">
    Enter the value for each visible field. Expanded descriptions for every method are below.
  </Step>

  <Step title="Choose a region">
    Enter the **AWS region** to query — for example, `us-east-1`. Optionally add a **Regions** allow-list to scan more than one region.
  </Step>

  <Step title="Set a sync schedule (optional)">
    Turn on **Sync schedule** and build a cron schedule, or leave it off to sync manually. See [Schedule asset syncs](/integrations/overview#schedule-asset-syncs).
  </Step>

  <Step title="Connect">
    Select **Connect**. OASM validates the credentials against AWS before saving the integration.
  </Step>
</Steps>

### Access key

Enter the **Access Key ID** and **Secret Access Key**. If your credentials are temporary, also enter the **Session Token**. The integration uses these credentials directly and scans the account they belong to.

### Assume role (multi-account)

Enter base **Access Key ID** and **Secret Access Key** credentials, then the **Role ARN** and **External ID** of a role that exists in each account. The integration lists the active accounts in AWS Organizations and assumes that role in each one, in sequence.

The base account is checked before any scanning starts. If the base credentials fail, the whole sync fails; if a single member account cannot be assumed, that account is skipped and the rest continue.

### Cross-account role

Identical to assume role, but without Organizations. Enter base credentials plus the **Role ARN** and **External ID** of the role in the single target account.

### Workload identity

Enter the **Role ARN** and the **Web Identity Token**. Use this method when another system issues a short-lived OIDC token.

<Warning>
  Workload identity integrations cannot use a sync schedule — the token is short-lived and would be expired on the next run. Leave the schedule off and select **Sync now** when you want to scan.
</Warning>

### IAM Identity Center (SSO)

The SSO method uses the AWS device-authorization flow, so OASM connects without ever handling your password.

<Steps>
  <Step title="Enter the region and start URL">
    Select the **IAM Identity Center (SSO)** connection method. Enter the **AWS region** and the **SSO Start URL** — the address of your access portal, for example `https://your-org.awsapps.com/start`.
  </Step>

  <Step title="Start authorization">
    Select **Start authorization**. OASM generates a one-time code and opens the AWS verification page.
  </Step>

  <Step title="Approve the request in AWS">
    Enter the displayed code in the AWS access portal and approve the request. The console polls until AWS confirms it.
  </Step>

  <Step title="Select an account and role">
    Choose the **Account ID** and **Role name** the integration should use.
  </Step>

  <Step title="Connect">
    Select **Connect**. OASM stores the refresh token, encrypted with the workspace key, and completes the integration.
  </Step>
</Steps>

<Info>
  While the console waits for approval, the device code remains valid for a limited time. If it expires, restart the flow from the beginning.
</Info>

## What AWS discovery finds

Discovery runs in two passes: global services once per account, and regional services once per enabled region.

| Source | What is collected |
| - | - |
| Route 53 | Public hosted zones and their A, AAAA, and CNAME records |
| EC2 | Instances with a public IP or public DNS name, and Elastic IP addresses |
| VPCs and subnets | VPC and subnet CIDR ranges |
| Elastic Load Balancing | DNS names of internet-facing load balancers |
| CloudFront | Distribution domain names and CNAME aliases |
| API Gateway | Custom domain names |
| RDS | Endpoints of publicly accessible databases |
| S3 | Publicly exposed buckets, as `<bucket>.s3.amazonaws.com` |

Collections map to target types:

* Domains and hostnames become **domain** targets.
* Public IP addresses become **IP** targets.
* VPC and subnet ranges become **CIDR** targets.

Each sync is bounded: at most 50 regions, 20,000 API calls, and 5,000 new targets. A very large account may reach one of these limits, in which case the run is marked truncated and the remainder is picked up on the next sync. Multi-account discovery processes accounts one after another, so a large organization can take several minutes.

## Test and sync

* **Test Integration** runs a read-only credential check and counts what it would discover. It writes nothing to your inventory.
* **Sync now** queues a real sync and returns immediately. The detail sheet shows the last run time.
* A scheduled sync uses the same code path as **Sync now**.

## Troubleshooting

<Accordion title="Connect fails with a credential error">
  Confirm the region and credentials are correct, and that the identity has the read-only permissions listed above. For role-based methods, verify the role ARN, the external ID, and that the base credentials are allowed to assume the role.
</Accordion>

<Accordion title="The scheduler rejects my workload identity integration">
  Workload identity integrations cannot be scheduled. Turn the schedule off and use **Sync now**.
</Accordion>

<Accordion title="Some accounts or regions are missing">
  Multi-account discovery lists active AWS Organizations accounts, and regional discovery queries the regions you configure. If a sync reports truncation, run it again to continue, or narrow the region allow-list.
</Accordion>

<Accordion title="The SSO code expired before I approved it">
  Restart the connect flow to generate a new code.
</Accordion>

## Related

<Card icon="crosshair" title="Targets" horizontal href="/target">
  Review the domains and IP ranges AWS discovery adds
</Card>

<Card icon="box" title="Assets" horizontal href="/asset">
  See the assets and services discovered under each target
</Card>

<Card icon="plug" title="Integrations overview" horizontal href="/integrations/overview">
  Learn how connections, secrets, and schedules work
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.