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

# AWS

> Discover AWS resources and import them as Cymph assets.

## What Cymph uses it for

The AWS integration discovers cloud resources (EC2, Lambda, RDS, S3, IAM, etc.) and imports them as Cymph assets. See [Asset actions](/howto/asset_actions).

All operations are **read-only** — Cymph only calls `Describe*` / `List*` / `Get*` actions.

It supports two credential modes: **Access Key** and **IAM Role**. Cross-account IAM Role is the recommended mode, because no long-lived credentials are stored by either party.

## Access Key mode

You will need to supply an IAM user's access key ID and secret access key. Optionally a session token can be provided for temporary (STS) credentials.

| Field               | Required | Secret | Notes                             |
| ------------------- | -------- | ------ | --------------------------------- |
| `access_key_id`     | yes      | no     | Access key ID of the IAM user     |
| `secret_access_key` | yes      | yes    | Secret access key of the IAM user |
| `session_token`     | no       | yes    | For temporary (STS) credentials   |
| `region`            | yes      | no     | Default region for API calls      |

## Cross-account IAM Role mode

Instead of long-lived keys, the customer creates a read-only IAM role that trusts Cymph's AWS account. Cymph assumes the role via STS `AssumeRole`, so **no long-lived credentials are stored by either party** and access is easy to rotate or revoke.

| Field         | Required | Secret | Notes                                               |
| ------------- | -------- | ------ | --------------------------------------------------- |
| `role_arn`    | yes      | no     | ARN of the role to assume                           |
| `external_id` | no\*     | no     | Shared value in the role's trust policy (see below) |
| `region`      | yes      | no     | Default region for API calls                        |

\* Optional as far as AWS is concerned, but **strongly recommended** — see [the confused-deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html).

### Setup

1. **Create the role** in the customer's AWS account with a trust policy that allows Cymph's account to assume it, gated by an external ID:

   ```json theme={"system"}
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": { "AWS": "arn:aws:iam::<CYMPH_ACCOUNT_ID>:root" },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": { "sts:ExternalId": "<AGREED_EXTERNAL_ID>" }
         }
       }
     ]
   }
   ```

2. **Attach a read-only policy.** The AWS managed policy `ReadOnlyAccess` (or `SecurityAudit`) covers the discovery calls; a tighter custom policy limited to the `Describe*` / `List*` / `Get*` actions used by the executor is preferable.

3. **Provide Cymph** the role ARN and the external ID. Enter them in the integration form (Authentication method → *IAM role*) and click **Test Connection** to verify the role can be assumed.

### Deployment-side IAM

In `Assume Role` mode Cymph calls STS using the **API host's own identity** (the ECS task role / EC2 instance role, or ambient credentials from the environment). That identity must be allowed to call `sts:AssumeRole` on the customer roles, e.g.:

```json theme={"system"}
{
  "Effect": "Allow",
  "Action": "sts:AssumeRole",
  "Resource": "arn:aws:iam::*:role/*"
}
```

There is no Cymph-side config for this — it is part of the deployment's IAM setup, not the integration record. This applies to [self-hosted deployments](/deployment/self-hosted/architecture); on a managed cloud tenant it is already in place.

## What Cymph reads

## Testing the connection