Amazon Web Services

View as Markdown

Community Platform

runZero integrates with Amazon Web Services (AWS) to give you better visibility across your cloud environment. The integration imports data from each applicable API to add detail to your asset inventory:

With AWS synced, you can see at a glance how many EC2 instances, elastic load balancers, relational database services, FSx file systems, and VPCs you have running, along with their region, account, and more.

The integration imports all running EC2 instances, RDS instances, Lambda functions, FSx file systems, VPCs, and active application, network, gateway, or classic load balancers. You can connect it to a single AWS account or to all accounts in your organization, and it imports data across multiple regions.

Getting started

runZero supports these AWS resource types:

  • EC2 instances
  • Elastic load balancers
  • RDS instances
  • Lambda instances
  • FSx file systems
  • VPCs

To set up the AWS integration:

  1. Configure AWS to allow API access for runZero.
  2. Add the AWS credential to runZero, including the access key and secret key.
  3. Choose whether to run the integration as a scan probe or connector task.
  4. Activate the AWS integration to sync your data with runZero.

Requirements

Before you set up the AWS integration:

  • Make sure you have access to the AWS console.
  • Use AWS Organizations if you want to connect to multiple accounts.

Step 1: Create an AWS credential

runZero can authenticate to AWS with any of these credential types:

  • IAM Role Credential (recommended): runZero authenticates to AWS with an IAM role that you create in your AWS account. No long-term access keys are needed.
    • IAM Role credentials are not supported for self-hosted instances, GovCloud-based accounts, or Explorer tasks. Use IAM Key credentials in those cases.
  • IAM Role Credential - Manual Account Selection (alternative): runZero authenticates to AWS the same way as the IAM Role Credential, but with account IDs you specify by hand rather than AWS Organization subaccounts. Recommended only for advanced use cases.
  • IAM Key Credential (deprecated): runZero authenticates to AWS with an IAM user and long-term access keys.

Option A: IAM role credential

To give runZero authenticated access to AWS through an IAM role, you need an External ID. An external ID is a unique ID that runZero provides for your IAM role. You use it when configuring the IAM role so that only your runZero account can access the role.

For more on external IDs in cross-account access, see AWS’ documentation on the confused deputy problem.

Step 1a.1: Create a runZero credential and external ID

To generate an external ID, create an AWS IAM Role credential in the runZero console:

  1. Go to the Credentials page and click Add Credential.

  2. Choose AWS IAM Role from the list of credential types.

  3. Name the credential, for example AWS IAM Role.

  4. In the AWS IAM role ARN field, enter the full ARN of the IAM role you will create in the next step. An IAM role ARN has the format arn:aws:iam::123456789012:role/runzero-sync, where 123456789012 is your AWS account ID and runzero-sync is the name of the role you will create.

    If you don’t know your AWS account ID yet, use arn:aws:iam::XXXXXXXXXXXX:role/runzero-sync as a placeholder and update it later.

  5. Click Save to save the credential and generate an external ID.

    Verify & Save won’t work yet, because the IAM role doesn’t exist in AWS. You’ll test the credential in Step 1a.3.

  6. Copy the external ID. You’ll need it in the next step.

Step 1a.2: Create AWS IAM role(s)

Follow the directions below to create an IAM role in every AWS account you want to sync with runZero. If you use AWS Organizations, reuse the same role name and external ID from your credential in each account.

The preferred way to create the IAM role is with CloudFormation StackSets:

  1. Create a runzero-cloudformation-stackset.json file with the following content. Replace <externalID> with the external ID generated in the runZero console.
"Resources": {
  "IamrunZeroAccessRole": {
    "Type": "AWS::IAM::Role",
    "Properties": {
      "RoleName": "runzero-sync",
      "AssumeRolePolicyDocument": {
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::336004405641:root"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "<externalID>"
            }
          }
        }]
      },
      "ManagedPolicyArns": [
        "arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess",
        "arn:aws:iam::aws:policy/AmazonRDSReadOnlyAccess",
        "arn:aws:iam::aws:policy/AWSLambda_ReadOnlyAccess",
        "arn:aws:iam::aws:policy/AmazonFSxReadOnlyAccess",
        "arn:aws:iam::aws:policy/AWSOrganizationsReadOnlyAccess",
        "arn:aws:iam::aws:policy/AmazonInspector2ReadOnlyAccess"
      ]
    }
  }
}
  1. Go to CloudFormation > StackSets and click Create StackSet.
  2. Select Template is ready and Upload a template file. Upload the template you just created.
  3. Enter a name for the StackSet, for example runZero-IAM-Role. Click next.
  4. (Optional) Set tags. Click next.
  5. Set deployment options. Click next.
  6. Review and create the StackSet.
  7. The StackSet creates an IAM role with the format arn:aws:iam::<accountID>:role/runzero-sync. Copy the full ARN of the role. You’ll need it in Step 1a.3.

To create the IAM role(s) manually instead:

  1. Sign in to the AWS console.
  2. Go to Identity and Access Management (IAM) > Roles to create a role that gives runZero access.
  3. Click the Create role button.
  4. On the “Select trusted entity” step:
    1. Select AWS account in the Trusted entity type panel.
    2. Select Another AWS account in the An AWS account panel.
    3. Enter 336004405641 for the account ID. This is the account runZero uses to access your AWS account.
    4. Check the Require external ID… checkbox and enter the external ID generated in Step 1a.1.
    5. Click the Next button.
  5. On the “Add permissions” step, select the following AWS managed policies and click the Next button. These grant runZero read-only access to the inventory in your AWS account.
    • AmazonEC2ReadOnlyAccess to sync EC2, ELB, and VPC resources
    • AmazonRDSReadOnlyAccess to sync RDS instances
    • AWSLambda_ReadOnlyAccess to sync Lambda functions
    • AmazonFSxReadOnlyAccess to sync FSx file systems
    • AWSOrganizationsReadOnlyAccess to sync AWS Organization account information
    • AmazonInspector2ReadOnlyAccess to import AWS Inspector vulnerability findings for EC2 instances and Lambda functions
  6. On the “Name, review, and create” step, enter a role name, such as runzero-sync, and a description. Click the Create role button.
  7. Copy the full ARN of the new role. It has the format arn:aws:iam::<accountID>:role/<roleName>. You’ll need it in Step 1a.3.

Additional notes:

  • A StackSet often can’t configure the payer account by default. In that case, the StackSet can configure all member accounts, and you may need to configure the payer account manually.
  • If you intend to sync AWS regions that are not enabled by default, change the region compatibility of the global STS endpoint. In the AWS console, go to IAM > Account Settings > Security Token Service (STS) and change the Global Endpoint to be compatible with “All AWS Regions.”

Step 1a.3: Update the runZero credential

  1. Return to the runZero console, go to the Credentials page, and edit the credential you created in Step 1a.1.
  2. Update the AWS IAM role ARN field with the full ARN of the role you created in Step 1a.2.
  3. Click Verify & Save to save and test the credential.

The credential is ready. Continue to Step 2 to set up and activate the connection that brings in data from AWS.

Option B: IAM role credential with manual account selection

Choose this option only when the default IAM Role Credential can’t target the subset of AWS accounts you need. It adds operational overhead, so weigh it carefully.

Step 1b.1: Create a runZero credential and external ID

This step is almost the same as step 1a.1.

To generate an external ID, create an AWS IAM Role credential in the runZero console:

  1. Go to the Credentials page and click Add Credential.

  2. Choose AWS IAM Role - Manual Account Selection from the list of credential types.

  3. Name the credential, for example AWS IAM Role - Manual.

  4. In the AWS IAM Role field, enter the name of the role you are using for all accounts.

  5. Enter a newline-separated list of the account IDs to import asset information from. An AWS account ID is a 12-digit number, so an entry looks like 123456789012.

  6. Click Save to save the credential and generate an external ID.

    Verify & Save won’t work yet, because the IAM role doesn’t exist in AWS. You’ll test the credential in Step 1b.3.

  7. Copy the external ID. You’ll need it in the next step.

Step 1b.2: Create AWS IAM role(s)

Follow the directions in step 1a.2: the setup is the same. Repeat them in each account you intend to import asset data from, because this credential type doesn’t use AWS Organizations the way the IAM Role Credential does.

Step 1b.3: Update the runZero credential

  1. Return to the runZero console, go to the Credentials page, and edit the credential you created in Step 1b.1.
  2. Click Verify & Save to save and test the credential.

The credential is ready. Continue to Step 2 to set up and activate the connection that brings in data from AWS.

Option C: IAM key credential

If you created an IAM role in Option A above, skip this section and proceed to Step 2. This option authenticates runZero to AWS with an IAM user and long-term access keys, which we don’t recommend. Use an IAM role instead.

Step 1c.1: Create an AWS IAM user

  1. Sign in to the AWS console. If you use AWS Organizations and intend to sync multiple accounts, sign in to the AWS Organizations management account, sometimes called the “payer” or “root” account.
  2. Go to Identity and Access Management (IAM) > Users and select or create a user that gives runZero API access.
  3. Click Add permissions > Attach existing policies directly. Search for and attach the policies for the services you want to sync:
    • AmazonEC2ReadOnlyAccess to sync EC2, ELB, and VPC resources
    • AmazonRDSReadOnlyAccess to sync RDS instances
    • AWSLambda_ReadOnlyAccess to sync Lambda functions
    • AmazonFSxReadOnlyAccess to sync FSx file systems
    • AWSOrganizationsReadOnlyAccess to sync AWS Organization account information
    • AmazonInspector2ReadOnlyAccess to import AWS Inspector vulnerability findings for EC2 instances and Lambda functions
  4. Add an inline policy that allows assuming runZero roles in sub-accounts (only required with AWS Organizations): 
    {
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": "sts:AssumeRole",
        "Resource": "arn:aws:iam::*:role/<rolename>"
    }]
}
  5. From the user summary screen, open the Security credentials tab and click Create access key.
  6. Save the Access key ID and Secret access key. You’ll need them in Step 1c.3.
  7. If you intend to sync AWS regions that are not enabled by default, change the region compatibility of the global STS endpoint. In the AWS console, go to IAM > Account Settings > Security Token Service (STS) and change the Global Endpoint to be compatible with “All AWS Regions.”

Step 1c.2: Add an IAM role to sub-accounts

If you use AWS Organizations and want runZero to sync all accounts in your organization, create an IAM role in each sub-account that lets the IAM user from Step 1c.1 assume it. If you aren’t using AWS Organizations, skip this step and proceed to Step 1c.3.

In every AWS sub-account:

  1. Go to Identity and Access Management (IAM) > Roles and click Create role.
  2. Choose Another AWS Account for the type of trusted entity.
  3. For Account ID, enter the ID of your organization’s management account.
  4. Click Next: Permissions.
  5. Attach the AmazonEC2ReadOnlyAccess policy if you want to sync EC2, ELB, and VPC resources.
  6. Attach the AmazonRDSReadOnlyAccess policy if you want to sync RDS instances.
  7. Attach the AWSLambda_ReadOnlyAccess policy if you want to sync Lambda functions.
  8. Attach the AmazonFSxReadOnlyAccess policy if you want to sync FSx file systems.
  9. Attach the AmazonInspector2ReadOnlyAccess policy if you want to import AWS Inspector vulnerability findings for EC2 instances and Lambda functions.
  10. Click Next: Tags and optionally add tags.
  11. Click Next: Review and name the role. (The role must have the same name in every account.)
  12. Click Create role.

Step 1c.3: Add the AWS credential to runZero

  1. Go to the Credentials page in runZero and click Add Credential.
  2. Name the credential, for example AWS IAM User.
  3. Choose AWS Access & Secret from the list of credential types.
  4. Fill in the credential:
    • In AWS access key, enter the access key ID from Step 1c.1.
    • In AWS secret access key, enter the secret access key from Step 1c.1.
    • In AWS role, enter the assumed role used to connect to other accounts in your organization. This is the role name you used in Step 1c.2.
    • Select the region(s) that you want to sync.
  5. Save the credential.

Step 2: Choose how to configure the AWS integration

You can run the AWS integration as either a scan probe or a connector task. A scan probe gathers integration data during a scan task. A connector task runs on its own, from the cloud or from one of your Explorers, and performs only the integration sync.

Step 3: Set up and activate the AWS integration to sync data

After you add your AWS credential, set up a connector task or scan probe to sync your data.

Step 3a: Configure the AWS integration as a connector task

A connection needs a schedule and a site. The schedule sets when the sync runs, and the site is where runZero creates new AWS-only assets.

  1. Activate a connection to AWS. All available third-party connections are reachable from the integrations page, your inventory, or the tasks page.
  2. Choose the credential you added earlier. If it isn’t listed, make sure the credential has access to your current organization.
  3. Name the task, for example AWS sync.
  4. Schedule the sync to run once or on a recurring schedule. It starts on the date and time you set.
  5. Under Task configuration:
    • Choose the site to add your assets to. All newly discovered assets are stored in this site. You can also choose Automatically create a new site per VPC or Automatically create a new site per account, and runZero creates the sites for newly discovered assets or accounts.
    • Choose whether to automatically delete stale AWS assets. With this option checked, runZero deletes AWS assets it saw in an earlier sync but did not find in the most recent one.
    • Choose whether to include AWS assets that are not currently running. With this option checked, runZero imports asset data for AWS assets that are not in a running state.
  6. Under Service options, select the services to sync data from. You must choose at least one.
  7. To import AWS Inspector vulnerability findings for your EC2 instances and Lambda functions, switch the Import AWS vulnerabilities toggle to Yes. The credential’s IAM role or user needs the AmazonInspector2ReadOnlyAccess managed policy (or the equivalent inspector2:ListFindings permission) attached in each account you sync. See Step 1: Create an AWS credential above. runZero imports findings only for resources that AWS Inspector has already scanned and matched to an existing EC2 instance or Lambda function.
  8. To exclude from the import any assets that runZero has not scanned, switch the Exclude unknown assets toggle to Yes. By default, the integration includes assets that runZero has not scanned.
  9. Activate the connection when you are done. The sync runs on the schedule you set, and the Scheduled tasks page shows when the next sync will occur.

Step 3b: Configure the AWS integration as a scan probe

  1. Create a new scan task or select a future or recurring scan task from your Tasks page.
  2. Add or update the scan parameters as needed.
  3. On the Probes and SNMP tab, choose which additional probes to include, set the AWS toggle to Yes, and change any default options if needed.
  4. On the Credentials tab, set the AWS toggle for the credential you want to use to Yes.
  5. Click Initialize scan to save the scan task and run it immediately or at the scheduled time.

Step 4: View AWS assets

After a successful sync, go to your inventory to view your AWS assets. They show an AWS icon in the Source column.

To filter for AWS assets, try these queries:

Click into an asset to see its attributes as returned by the AWS APIs.

Troubleshooting

If the integration isn’t working, the questions and answers below may help.

Why is the Amazon Web Services integration unable to connect?

  1. Check whether the AWS integration is returning any data.
    • Query the inventory rather than the task details to review all the data available from this integration.
    • In some cases, an integration’s configuration limits how much data reaches the runZero console.
  2. Some integrations require specific actions that are easy to overlook. If you miss a step during setup, the integration may not work correctly. Review this page and follow the steps exactly.
  3. If the AWS integration can’t connect, check the task log for errors. Common errors include:
    • 500: server error, unable to connect to the endpoint
    • 404: hitting an unknown endpoint on the server
    • 403: not authorized, likely a credential issue

Why aren’t AWS Inspector vulnerabilities showing up on my EC2 or Lambda assets?

  1. Confirm the Import AWS vulnerabilities option is enabled on the connector task or scan probe. This is separate from selecting the EC2 or Lambda service options.
  2. Confirm the IAM role or user behind the credential has the AmazonInspector2ReadOnlyAccess managed policy (or a custom policy granting inspector2:ListFindings) attached in the specific AWS account and region being synced. Every member account needs this permission, not just the payer/root account. If it is missing, the task log shows an AccessDeniedException similar to: 
    AccessDeniedException: User: arn:aws:sts::<account-id>:assumed-role/<role-name>/runZeroAWSIntegrationSession is not
authorized to perform: inspector2:ListFindings on resource: arn:aws:inspector2:<region>:<account-id>:/findings/list
because no identity-based policy allows the inspector2:ListFindings action
  3. Confirm that AWS Inspector scanning (EC2 deep inspection and/or Lambda standard scanning) is activated for the account and region, and that AWS Inspector has scanned the resource. runZero imports only findings that AWS Inspector has already generated; it does not trigger new scans.
  4. For Lambda functions, confirm the function was invoked or updated within the last 90 days, uses the $LATEST version, and is not excluded from scanning by tag or a customer-managed KMS key.
Updated