--- title: AWS analyze slug: docs/aws-analyze icon: {"faIcon":"fa-brands fa-aws"} docTags: createdAt: 2025-06-18T17:02:20.737Z --- :::BlockQuote **Edition:** Enterprise only ::: AWS Analyze shows the IAM identity behind a discovered AWS key, the identity-based permissions attached to it, and related revocation metadata, so you can triage the finding. ## Overview Leverage AWS Analyze when you want to enrich AWS secret detections with IAM context. TruffleHog uses a privileged AWS identity you provide to run read-only permission checks against the detected secret. After the integration is healthy, AWS secrets detected from that point are analyzed with those credentials. You must create that privileged identity in AWS before you can add the integration. The calls are read-only. ## How it works - **A privileged AWS identity does the analysis.** You give TruffleHog credentials for an IAM user, or for an IAM role assumed through IAM Roles Anywhere. TruffleHog uses that identity to make read-only IAM and STS calls for the principal behind a discovered key. - **Setup is validated on save.** Adding the integration runs a credential self-check. **Healthy** means the required permissions are in place. **Unhealthy** means the self-check failed. Opening the status shows what went wrong. - **Analysis runs on newly detected AWS secrets.** A scanner that finds a live AWS credential after the integration is healthy uses those credentials to analyze it. - **Two authentication methods.** Access keys on an IAM user, or a client certificate via IAM Roles Anywhere. With access keys, you can optionally assume a role for the analysis. ## Prerequisites | Requirement | Detail | | ------------------- | ------------------------------------------------------------------------------------------------------------------- | | AWS account | Permission to create an IAM user, or to create a Private CA, IAM role, trust anchor, and profile for Roles Anywhere | | TruffleHog Analyze | AWS Analyze is a Cloud Analyze integration in TruffleHog Enterprise | | Privileged identity | An IAM user or Roles Anywhere role with the permissions below | Attach a customer-managed policy with these permissions. If you set a role ARN on the access-key integration, the identity also needs sts\:AssumeRole on arn\:aws\:iam\::\*:role/\*. | Permission | Resource | | ------------------------------ | ------------------------------------------------------------ | | sts\:GetCallerIdentity | \* | | iam\:GetUser | arn\:aws\:iam\::\*:user/\* | | iam\:ListGroupsForUser | arn\:aws\:iam\::\*:user/\* | | iam\:ListAttachedUserPolicies | arn\:aws\:iam\::\*:user/\* | | iam\:ListUserPolicies | arn\:aws\:iam\::\*:user/\* | | iam\:GetUserPolicy | arn\:aws\:iam\::\*:user/\* | | iam\:ListAttachedGroupPolicies | arn\:aws\:iam\::\*:group/\* | | iam\:ListGroupPolicies | arn\:aws\:iam\::\*:group/\* | | iam\:GetGroupPolicy | arn\:aws\:iam\::\*:group/\* | | iam\:ListRoles | \* | | iam\:ListAttachedRolePolicies | arn\:aws\:iam\::\*:role/\* | | iam\:ListRolePolicies | arn\:aws\:iam\::\*:role/\* | | iam\:GetRolePolicy | arn\:aws\:iam\::\*:role/\* | | iam\:GetPolicy | arn\:aws\:iam\::\*:policy/\*, arn\:aws\:iam\::aws\:policy/\* | | iam\:GetPolicyVersion | arn\:aws\:iam\::\*:policy/\*, arn\:aws\:iam\::aws\:policy/\* | | iam\:ListAccountAliases | \* | | iam\:GetAccessKeyLastUsed | arn\:aws\:iam\::\*:user/\* | :::BlockQuote \{ "Version": "2012-10-17", "Statement": \[ \{ "Sid": "TruffleHogAnalyzeAccount", "Effect": "Allow", "Action": \[ "sts\:GetCallerIdentity", "iam\:ListRoles", "iam\:ListAccountAliases" ], "Resource": "\*" }, \{ "Sid": "TruffleHogAnalyzeUsers", "Effect": "Allow", "Action": \[ "iam\:GetUser", "iam\:ListGroupsForUser", "iam\:ListAttachedUserPolicies", "iam\:ListUserPolicies", "iam\:GetUserPolicy", "iam\:GetAccessKeyLastUsed" ], "Resource": "arn\:aws\:iam\::\*:user/\*" }, \{ "Sid": "TruffleHogAnalyzeGroups", "Effect": "Allow", "Action": \[ "iam\:ListAttachedGroupPolicies", "iam\:ListGroupPolicies", "iam\:GetGroupPolicy" ], "Resource": "arn\:aws\:iam\::\*:group/\*" }, \{ "Sid": "TruffleHogAnalyzeRoles", "Effect": "Allow", "Action": \[ "iam\:ListAttachedRolePolicies", "iam\:ListRolePolicies", "iam\:GetRolePolicy" ], "Resource": "arn\:aws\:iam\::\*:role/\*" }, \{ "Sid": "TruffleHogAnalyzePolicies", "Effect": "Allow", "Action": \[ "iam\:GetPolicy", "iam\:GetPolicyVersion" ], "Resource": \[ "arn\:aws\:iam\::\*:policy/\*", "arn\:aws\:iam\::aws\:policy/\*" ] } ] } ::: ## Create an IAM user and access keys Use this method unless your organization requires short-lived credentials. 1. In the AWS console, go to **IAM**, then **Users**. 2. Click **Create user** and enter a name, such as trufflehog-aws-analyze. 3. Attach a customer-managed policy with the permissions in Prerequisites. Save the user. 4. On the user's detail view, click **Create access key**. 5. Select **Third-party service**, then click **Next**. 6. Enter a description and click **Create access key**. 7. Copy the access key ID and the secret access key. AWS does not show the secret access key again. Store it before you leave the wizard. You now have an access key ID and secret access key to paste into TruffleHog Enterprise. ## Set up IAM Roles Anywhere Use this method when you cannot issue long-lived access keys. TruffleHog presents a client certificate to [IAM Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html) and receives temporary credentials. An AWS administrator creates the infrastructure once per account. Repeat the certificate steps when you rotate or add a credential. ### Create the AWS infrastructure **Private CA.** TruffleHog authenticates through [AWS Private CA](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome.html). If you already have an ACM PCA-registered CA, skip to the IAM role. Creating a root CA bills as a Private CA. A subordinate CA under an existing organization CA avoids a second monthly charge. :::BlockQuote aws acm-pca create-certificate-authority \\ \--certificate-authority-type ROOT \\ \--certificate-authority-configuration \\ "KeyAlgorithm=RSA\_2048,SigningAlgorithm=SHA256WITHRSA,Subject=\{CommonName=TruffleHogAnalyzeCA}" \\ \--region us-east-1 ::: Activate a new root CA by self-signing it: :::BlockQuote aws acm-pca get-certificate-authority-csr \\ \--certificate-authority-arn $CA\_ARN \\ \--output text --region us-east-1 > ca-csr.pem aws acm-pca issue-certificate \\ \--certificate-authority-arn $CA\_ARN \\ \--csr fileb://ca-csr.pem \\ \--signing-algorithm SHA256WITHRSA \\ \--template-arn arn\:aws\:acm-pca\:::template/RootCACertificate/V1 \\ \--validity Value=3650,Type=DAYS \\ \--region us-east-1 aws acm-pca get-certificate \\ \--certificate-authority-arn $CA\_ARN \\ \--certificate-arn $ROOT\_CERT\_ARN \\ \--query 'Certificate' --output text --region us-east-1 > ca-cert.pem aws acm-pca import-certificate-authority-certificate \\ \--certificate-authority-arn $CA\_ARN \\ \--certificate fileb://ca-cert.pem \\ \--region us-east-1 ::: **IAM role.** Create a role that Roles Anywhere can assume, and attach the policy from Prerequisites. Trust policy (trust-policy.json): :::BlockQuote \{ "Version": "2012-10-17", "Statement": \[ \{ "Effect": "Allow", "Principal": \{ "Service": "rolesanywhere.amazonaws.com" }, "Action": \["sts\:AssumeRole", "sts\:SetSourceIdentity", "sts\:TagSession"] } ] } ::: :::BlockQuote aws iam create-role \\ \--role-name TruffleHogAnalyze \\ \--assume-role-policy-document file://trust-policy.json aws iam create-policy \\ \--policy-name TruffleHogAnalyzePolicy \\ \--policy-document file://analyze-policy.json aws iam attach-role-policy \\ \--role-name TruffleHogAnalyze \\ \--policy-arn arn\:aws\:iam\::\\:policy/TruffleHogAnalyzePolicy ::: **Trust anchor.** This tells Roles Anywhere which CA to trust. :::BlockQuote aws rolesanywhere create-trust-anchor \\ \--name TruffleHogAnalyzeAnchor \\ \--source "sourceType=AWS\_ACM\_PCA,sourceData=\{acmPcaArn=$CA\_ARN}" \\ \--enabled \\ \--region us-east-1 ::: Save the trustAnchorArn from the output. **Profile.** This links the trust anchor to the IAM role. The trust anchor and profile must be in the same region. :::BlockQuote aws rolesanywhere create-profile \\ \--name TruffleHogAnalyzeProfile \\ \--role-arns arn\:aws\:iam\::\\:role/TruffleHogAnalyze \\ \--enabled \\ \--region us-east-1 ::: Save the profileArn from the output. You should now have three ARNs: the trust anchor, the profile, and arn\:aws\:iam\::\\:role/TruffleHogAnalyze. ### Issue a client certificate Repeat these steps to rotate a credential or create another one. 1. Generate a key and a certificate signing request: :::BlockQuote openssl genrsa -out client-key.pem 2048 openssl req -new -key client-key.pem -out client-csr.pem \\ -subj "/CN=trufflehog-analyze" ::: The Common Name is for identification. Use any descriptive value. 1. Issue an end-entity certificate from your Private CA. Set --validity to a duration your organization accepts. :::BlockQuote aws acm-pca issue-certificate \\ \--certificate-authority-arn $CA\_ARN \\ \--csr fileb://client-csr.pem \\ \--signing-algorithm SHA256WITHRSA \\ \--template-arn arn\:aws\:acm-pca\:::template/EndEntityCertificate/V1 \\ \--validity Value=365,Type=DAYS \\ \--region us-east-1 ::: 1. Save the CertificateArn from the output, then retrieve the certificate: :::BlockQuote aws acm-pca get-certificate \\ \--certificate-authority-arn $CA\_ARN \\ \--certificate-arn $CLIENT\_CERT\_ARN \\ \--query 'Certificate' --output text \\ \--region us-east-1 > client-cert.pem ::: You now have client-cert.pem, client-key.pem, and the three ARNs to paste into TruffleHog Enterprise. ## Add an AWS Analyze integration 1. Go to **Integrations** 2. Open the **Cloud Analyze** tab. 3. Click **Add integration**, then **Cloud Analyze**, then **Amazon Web Services (AWS)**. 4. Select a **Hosted or Self-hosted scanner**. ## Hosted scanner configuration ### Access keys 1. Name the integration. 2. Enter the access key ID and secret access key from the IAM user. 3. Optionally enter a role ARN to assume for analysis, and an AWS region. 4. Click **Add integration**. ![](https://api.archbee.com/api/optimize/S23bFlGfp3a-8_a9YY_cE/mlb3GQjlgK0UrA9FiLuoY_image.png) The integration runs a credential self-check. It is **Healthy** when the required permissions are in place. AWS secrets detected from this point are analyzed with these credentials. If you set a role ARN, the IAM user also needs sts\:AssumeRole on arn\:aws\:iam\::\*:role/\*. ### Certificate Every field is required. 1. Name the integration. 2. Paste the trust anchor ARN, profile ARN, role ARN, client certificate, and private key from Set up IAM Roles Anywhere. 3. Click **Add integration**. ![](https://api.archbee.com/api/optimize/S23bFlGfp3a-8_a9YY_cE/1nTEQ3ahB8bTORGeGHR36_image.png) The integration runs a credential self-check. It is **Healthy** when the required permissions are in place. AWS secrets detected from this point are analyzed with these credentials. ## Self-hosted scanner configuration - In the scanner config yaml, set `analyze_aws_using_default_credentials: true` - set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` in the scanner process environment - *or*, set `AWS_AUTH_CERT` to point to a complete cert file - optional: `AWS_ASSUME_ROLE_ARN` for the assumed role ## Notes - Analysis applies to AWS secrets detected after the integration is healthy. ## Interpret AWS Analyze results AWS Analyze organizes results around the identity behind the key and the roles that identity may reach. - **Identity** shows the AWS account, principal ARN, identity type, groups, tags, creation date, and permissions boundary when available. - **All permissions** combines the permission rows found during analysis. Select it or an individual role to populate the permissions table. “No permissions found” before making a selection does not mean the key has no permissions. - **Direct roles** can be assumed directly by the discovered identity. - **Assumable roles** are reachable through one additional role assumption. These paths can expand the key’s access beyond its original identity policies. Each permission row shows: - **Effect:** Whether the source statement declares Allow or Deny. - **Action:** The AWS API operation covered by the statement. - **Resource:** The ARN or resource pattern to which it applies. \* indicates broad scope. - **Policy:** The policy that produced the row. - **Limits:** Conditions that may restrict when the statement applies. Policy labels describe the source of a policy: - **managed:** An AWS-managed or customer-managed policy attached to the identity or role. - **inline:** A policy embedded directly in an IAM user or role. - **group\_managed / group\_inline:** A policy inherited through an IAM group. - **trust:** A role trust policy. Trust policies determine who may assume a role. They do not grant the permissions available after assumption. ## Troubleshooting | Condition | Cause | Solution | | ------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Integration marked **Unhealthy** | The credential self-check failed | Open the status for the failure. Edit the credential if a value you entered is wrong. Click **Refresh** if the failure was on AWS's side, then try again. | | Self-check fails after you set a role ARN | The IAM user cannot assume that role | Grant sts\:AssumeRole on the role, then edit the integration or click **Refresh**. | | Secret access key is no longer in the AWS console | AWS shows the secret access key only at creation | Create a new access key on the IAM user and edit the integration. |