AWS

The AWS connector reads one AWS account and files three snapshot evidence items. It signs in with an IAM user’s access key. We recommend that the key only assumes a read-only role (see section 1); the key can also read the account itself, as before. For several accounts, add one integration per account.

Proofroom keeps only what the summaries need: no finding descriptions, remediation text or resource details, and no credentials beyond the integration’s own key (sealed at rest, redacted from every log and error). A role’s temporary credentials live only in memory for the run, and are redacted too.

1. Recommended: a read-only role and a user that can only assume it

The role holds the read permissions; the IAM user’s access key can do nothing else than assume it. A leaked key is then useless without the role’s external ID, and you can revoke access by editing the role’s trust policy.

1. IAM console → Users → Create user, for example proofroom-audit. Do not give it console access. Note its ARN (arn:aws:iam::<account>:user/proofroom-audit).

2. IAM console → Roles → Create role → Custom trust policy. Pick a long random external ID (for example from a password generator; letters, digits and _+=,.@:/-) and paste, with your values:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": { "AWS": "arn:aws:iam::<account>:user/proofroom-audit" },
         "Action": "sts:AssumeRole",
         "Condition": { "StringEquals": { "sts:ExternalId": "<your external ID>" } }
       }
     ]
   }
   

3. Attach the AWS managed policy SecurityAudit to the role, name it (for example ProofroomAudit) and create it. Keep the default maximum session duration (1 hour) or longer: Proofroom asks for 1-hour sessions.

4. Give the user one inline policy that allows only assuming the role and reading its own access keys (the second statement lets Proofroom track the key’s age; it is optional):

   {
     "Version": "2012-10-17",
     "Statement": [
       { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::<account>:role/ProofroomAudit" },
       { "Effect": "Allow", "Action": "iam:ListAccessKeys", "Resource": "arn:aws:iam::*:user/${aws:username}" }
     ]
   }
   

5. Open the user → Security credentials → Create access key → “Application running outside AWS”. Copy the access key ID and secret access key at once.

The role may sit in another account than the user (a cross-account role): put the user’s ARN in that role’s trust policy and the role’s ARN in the user’s policy. Then the role cannot read the user’s access keys, so keep the iam:ListAccessKeys statement on the user if you want the key’s age tracked.

Without a role. Attach SecurityAudit to the user itself instead (steps 1 and 5) and leave the role fields blank. Existing integrations keep working this way.

Tighter alternative to SecurityAudit. If you prefer a policy that allows only the calls Proofroom makes, attach this to the role (or to the user, without a role) instead of SecurityAudit. STS GetCallerIdentity needs no permission.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ProofroomEvidence",
      "Effect": "Allow",
      "Action": [
        "iam:GenerateCredentialReport",
        "iam:GetCredentialReport",
        "iam:GetAccountSummary",
        "iam:ListAccessKeys",
        "ec2:DescribeRegions",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus",
        "cloudtrail:GetEventSelectors",
        "securityhub:GetFindings",
        "securityhub:DescribeSecurityHubV2"
      ],
      "Resource": "*"
    }
  ]
}

securityhub:GetFindings covers both GetFindings (Security Hub CSPM) and GetFindingsV2 (Security Hub).

2. Create the integration

Integrations → Catalogue → AWS → Connect:

• Access key ID and secret access key of the user above.
• Role ARN (recommended) and external ID: the role from section 1. Leave both blank to read with the key itself.
• Regions, one per line (for example eu-west-2), or blank. Blank: Proofroom reads every region enabled in the account (EC2 DescribeRegions; opt-in regions you have not enabled are skipped). Listed: only those regions are read. They are checked against the account’s regions: a listed region the account has not enabled is skipped and named in the evidence; a name that is not an AWS region fails the run.
• Lowest severity of Security Hub findings to list (default HIGH).
• Findings API (default auto): auto asks each region whether the new Security Hub is enabled and reads it there, and reads Security Hub CSPM elsewhere; v2 reads only the new Security Hub; cspm reads only Security Hub CSPM.

Test connection names the account and who it ran as (“as role ProofroomAudit” or “as user proofroom-audit”), checks that IAM is readable and lists the regions it will read. If it says STS refused AssumeRole, check the role’s trust policy, the external ID and the user’s policy. If it says IAM refused GetAccountSummary, SecurityAudit is not attached to the role (or user).

3. Outbound access

The server needs HTTPS (443) to iam.amazonaws.com, and for each region read sts.<region>.amazonaws.com (the first listed region, or us-east-1), ec2.<region>.amazonaws.com (the same region), cloudtrail.<region>.amazonaws.com and securityhub.<region>.amazonaws.com.

Access key expiry

AWS access keys never expire. Proofroom reads when the key was created (ListAccessKeys for the key’s own user) and shows it on the integration page as due for rotation a year later, labelled Access key …<last 4 characters of the key ID>. With a role, the user’s access key is still the credential tracked: Proofroom reads it with the key itself (the optional iam:ListAccessKeys statement above) or, when that is refused, with the role (same account only). When neither may read it, or the key belongs to the root user, the page shows a note instead.

Rotate the key under your usual policy: create a second key, update the integration, then deactivate and delete the old one. The IAM credentials evidence also flags keys over 90 days old, including Proofroom’s own.

Notes

• The credential report is generated by AWS at most every four hours; the summary shows when it was generated.
• The report covers each user’s first two access keys, which is all IAM allows.
• Security Hub and Security Hub CSPM. The new Security Hub (generally available since December 2025) keeps its findings in OCSF and is read with GetFindingsV2; the older service, now called Security Hub CSPM, is read with GetFindings. Open means: Security Hub CSPM record state ACTIVE with workflow status NEW or NOTIFIED; Security Hub status New, In Progress, Unknown or Other (Suppressed, Resolved and Archived are left out). Security Hub’s Fatal severity is listed as CRITICAL.
• In auto mode, if the key may not call securityhub:DescribeSecurityHubV2, Proofroom cannot tell whether the new Security Hub is enabled; it reads Security Hub CSPM in that region and says so in the evidence.
• Security Hub CSPM answers HTTP 401 (InvalidAccessException) both when it is not enabled in a region and when the key lacks securityhub:GetFindings; the two cannot be told apart. The summary lists such a region as “Security Hub: not enabled in this region, or the key lacks securityhub:GetFindings” and the run still succeeds, as long as at least one region read answers; if none does, the run fails.
• A region AWS refuses. When CloudTrail or Security Hub answers access denied in one region (HTTP 403, or 400 AccessDeniedException — for example a service control policy that denies a region), that region is listed as “denied” in the evidence and the description, and the other regions are still read. The run fails only when every region read is refused.
• Organisation trails. A member account may be refused GetEventSelectors on an organisation trail owned by the management account. The trail is still listed (and counts as logging when it is logging), with the note “event selectors not readable from this account” and its management events shown as unknown. Read the logging evidence from the management account to see them.
• If EC2 refuses DescribeRegions and regions are listed, Proofroom reads them unchecked and says so; with no regions listed, the run fails naming ec2:DescribeRegions. SecurityAudit includes it.
• AWS throttling (HTTP 400 with Throttling, ThrottlingException or RequestLimitExceeded, or 429 TooManyRequestsException) is a rate limit: Proofroom backs off and retries up to three times. If it persists, the run fails and is retried automatically an hour later, then 6 and 24 hours later.

Not yet confirmed on a live account (UNVERIFIED)

• DescribeSecurityHubV2 answering 404 (ResourceNotFoundException) in a region where the new Security Hub is not enabled. The API reference lists the 404 but does not tie it to “not enabled”.
• The OCSF field names Proofroom reads from GetFindingsV2 results (finding_info.uid, finding_info.title, finding_info.first_seen_time_dt, severity_id, status_id, cloud.region, resources[].type/uid, metadata.product.name) and the names of the severity_id and status_id values, which come from the OCSF schema.
• Reading a shadow trail’s event selectors: Proofroom calls GetEventSelectors in the trail’s home region.
• How a member account is refused GetEventSelectors on an organisation trail (Proofroom treats HTTP 403, or 400 with an access-denied message, as refused), and how an SCP region denial is answered by CloudTrail and Security Hub.
• GetFindingsV2 accepting a severity_id filter of Eq 0 / Eq 99 alongside Gte in one OR composite filter.