Continuously Scan AWS - Mondoo-Hosted Integration

With WIF, Mondoo acts as an OIDC identity provider. When it's time to scan, Mondoo issues a short-lived OIDC token and presents it to AWS STS through the AssumeRoleWithWebIdentity action. AWS validates the token against Mondoo's public signing keys (fetched from Mondoo's OIDC discovery endpoint), then issues temporary credentials for an IAM role that Mondoo assumes to read resources from your account. No static keys are stored or transmitted.

Setting up WIF is a three-phase process. You create an IAM role that trusts Mondoo as an OIDC provider, create the integration in Mondoo to get a unique subject identifier, and then return to AWS to lock the IAM role down to that exact subject.

Step 1: Add Mondoo as an IAM OIDC identity provider

Register Mondoo as a trusted OpenID Connect identity provider in your AWS account. AWS fetches Mondoo's public signing keys from this provider to validate tokens.

1. In the AWS Management Console, go to Identity and Access Management (IAM).

2. In the left menu, select Identity providers.

3. Select Add provider.

4. For Provider type, select OpenID Connect.

5. Set the Provider URL to the Mondoo STS endpoint for your environment:

   Environment	Provider URL
   Mondoo (US)	https://sts.us.mondoo.com
   Mondoo (EU)	https://sts.eu.mondoo.com
   Mondoo Edge	https://sts.edge.mondoo.com
   Dedicated deployment	https://sts.mondoo.CUSTOMER.com

   To learn more about Mondoo's OIDC endpoints, read Mondoo as an OIDC identity provider.

6. Set the Audience to mondoo.

7. Select Get thumbprint and then select Add provider.

Step 2: Create an IAM role for Mondoo to assume

Create an IAM role that trusts the Mondoo OIDC provider and has read-only access to your AWS account. At this point you cannot yet pin the trust policy to a specific integration subject, so you configure it with a placeholder and tighten it in Step 5.

1. In the IAM console, select Roles and then select Create role.

2. For Trusted entity type, select Web identity.

3. For Identity provider, choose the Mondoo provider you created in Step 1 (for example, sts.example.mondoo.com).

4. For Audience, choose mondoo.

5. Select Next.

6. Search for ReadOnlyAccess and check the box next to the policy named simply ReadOnlyAccess. Its ARN is arn:aws:iam::aws:policy/ReadOnlyAccess.

7. Select Next. Give the role a name (for example, MondooScan) and select Create role.

8. Open the role you just created and note its ARN. It looks like arn:aws:iam::111122223333:role/MondooScan. You enter this value in Mondoo in the next step.

Step 3: Create the AWS integration in Mondoo

1. In the Mondoo App, navigate to the space where you want to add the integration. In the side navigation bar, select Integrations. In the top right, select + INSTALL. On the integrations page, find AWS by browsing or searching by name, then select it.

   

2. Select SELECT MONDOO-HOSTED INTEGRATION.

   

3. In the Choose an integration name box, type a recognizable name for this AWS account.

4. Under Choose authentication, select Workload Identity Federation.

5. In the IAM Role ARN box, enter the ARN of the IAM role you created in Step 2 (for example, arn:aws:iam::111122223333:role/MondooScan).

6. In the OIDC Audience box, enter mondoo. This must match the audience you configured on the IAM OIDC provider in Step 1.

7. (Optional) Under Asset annotations, add key-value annotations that Mondoo applies to every asset this integration scans. Annotations make it easier to filter assets later or build workspaces that include only the assets from this integration.

8. Select START SCANNING.

Step 4: Copy the WIF subject value

After you create the integration, Mondoo computes a WIF subject value that uniquely identifies this integration. You need this value to authorize Mondoo in AWS.

1. On the integration details page in the Mondoo App, find the WifSubject field.

2. Copy the subject value. It has the format INTEGRATION_ID@integrations.SPACE_ID, for example:

   ExampleIntegrationID@integrations.example-space-000000.spaces.iam.example.mondoo.app

Step 5: Pin the IAM role trust policy to the WIF subject

Return to AWS and edit the IAM role's trust policy so that only the specific Mondoo integration you just created can assume the role.

1. In the IAM console, open the role you created in Step 2 (for example, MondooScan).

2. Select the Trust relationships tab and then select Edit trust policy.

3. Replace the trust policy with this document, substituting your own AWS account ID, Mondoo OIDC provider host, and the WIF subject value you copied in Step 4:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Federated": "arn:aws:iam::111122223333:oidc-provider/sts.example.mondoo.com"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
             "sts.example.mondoo.com:sub": "ExampleIntegrationID@integrations.example-space-000000.spaces.iam.example.mondoo.app",
             "sts.example.mondoo.com:aud": "mondoo"
           }
         }
       }
     ]
   }

   Placeholder	Replace with
   111122223333	Your AWS account ID
   sts.example.mondoo.com	The Mondoo STS host for your environment (without https://), in all three places it appears
   ExampleIntegrationID...mondoo.app	The WIF subject value you copied in Step 4

4. Select Update policy.

Step 6: Enable policies and verify the integration

1. On the Recommended Policies page, enable the policies on which you want to base assessments of your AWS environment. To learn more, read Manage Policies.

2. Return to the integration details page and wait for the first scan to complete. If the status changes to active, the setup is working correctly.

If the scan fails, double-check:

• The IAM Role ARN entered in Mondoo matches the IAM role exactly.
• The audience value in Mondoo, on the IAM OIDC provider, and in the trust policy's :aud condition are all mondoo.
• The :sub condition in the trust policy matches the WIF subject value from the integration details page exactly.
• The IAM role has the ReadOnlyAccess policy attached.

Step 1: Create an AWS user and access key for Mondoo

To give Mondoo the access it needs to continuously scan your AWS account, create an AWS user and access key. You give the key and its secret to Mondoo, which securely stores them. To learn about AWS access keys, read Managing access keys for IAM users in the AWS documentation.

1. In the AWS access portal for the account you want to integrate with Mondoo, go to Identity and Access Management (IAM).

2. In the left menu, select Users.

   

3. Select the Create user button.

   

4. Enter the user name Mondoo and select the Next button.

5. Select Attach policies directly.

6. Search for ReadOnlyAccess and check the box next to the permission named simply ReadOnlyAccess. The ARN for this permission is arn:aws:iam::aws:policy/ReadOnlyAccess.

   

7. Select the Next button and then select the Create User button.

   

8. In the success confirmation message, select the View user button.

9. Select the Security Credentials tab.

   

10. Under Access Keys, select the Create access key button.

11. Select Third-party service, check the I understand the above recommendation and want to proceed to create an access key box, and select the Next button.

    

12. Enter a description for the key and select the Create access key button.

13. Keep the page with the key open in your browser as you continue to the next steps.

Step 2: Set up a new AWS integration

1. In the Mondoo App, navigate to the space where you want to add the integration. In the side navigation bar, select Integrations. In the top right, select + INSTALL. On the integrations page, find AWS by browsing or searching by name, then select it.

   

2. Select SELECT MONDOO-HOSTED INTEGRATION.

   

3. In the Choose an integration name box, type a recognizable name for this AWS asset.

4. Under Choose authentication, select Access Key.

5. Access the AWS IAM tab in your browser that shows the access keys you created in the steps above. Copy the Access key value.

   

6. In the Mondoo App tab in your browser, under Enter authentication details, paste the value in the Access Key ID box.

   

7. In the AWS IAM tab in your browser, copy the Secret access key value.

8. In the Mondoo App tab in your browser, under Enter authentication details, paste the value in the AWS Secret Access Key box.

9. (Optional) Under Asset annotations, add key-value annotations that Mondoo applies to every asset this integration scans. Annotations make it easier to filter assets later or build workspaces that include only the assets from this integration.

10. Select the START SCANNING button.