Amazon Web Services

Community Platform

runZero integrates with Amazon Web Services (AWS) to provide better visibility across your cloud environment. This integration imports data from each applicable API to add detailed information to your asset inventory:

Syncing with AWS allows you to quickly identify the number of EC2 instances, elastic load balancers, and relational database services you have running, as well as their region, account, and more.

This integration supports the import of all running EC2 instances, RDS instances, and active application, network, gateway, or classic load balancers. It can be configured to connect to a single AWS account or to all accounts in your organization and imports data across multiple regions.

Getting started

The following AWS resource types are supported:

  • EC2 instances
  • Elastic load balancers
  • RDS instances
  • Lambda instances

To set up the AWS integration, you’ll need to:

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

Requirements

Before you can set up the AWS integration:

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

Step 1: Create an AWS credential

There are two options for creating an AWS credential:

  • IAM Role Credential (recommended) - runZero authenticates to AWS using an IAM role that you create in your AWS account. No long-term access keys are needed.
  • IAM Key Credential (deprecated) - runZero authenticates to AWS using an IAM user and long-term access keys.

Option A: IAM Role Credential

When using an IAM role to provide runZero with authenticated access to AWS, you’ll need to establish an External ID. An external ID is a unique ID provided by runZero for your IAM role. You’ll use this external ID when configuring your IAM role to ensure that only your runZero account can access the role.

To learn more about the use of external IDs in cross-account access, refer to AWS’ documentation on the confused deputy problem.

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

To generate an external ID, you’ll need to create an AWS IAM Role credential in the runZero console:

  1. In the runZero console, navigate to the Credentials page and click Add Credential.

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

  3. Provide a name for the credential, like AWS IAM Role.

  4. Enter the full ARN of the AWS IAM role you plan to create in the next step into the AWS IAM role ARN field. 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, that’s ok. You can 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.

    Note: Clicking Verify & Save will not work because you haven’t created the IAM Role in AWS yet. You’ll come back and test the credential in Step 1a.3.

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

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

You must create an IAM role using the directions below in every AWS account you want to sync with runZero. If you utilize AWS Organizations, you must reuse the same role name and external ID in each account.

The preferred way to create an IAM Role is using CloudFormation StackSets:

  1. Create a runzero-cloudformation-stackset.json file with the following content. Replace <externalID> with the external ID generated using 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"
      ]
    }
  }
}
  2. Go to CloudFormation > StackSets and click Create StackSet.
  3. Select Template is ready and Upload a template file. Upload the template you downloaded earlier.
  4. Enter a name for the StackSet, for example runZero-IAM-Role. Click next.
  5. (Optional) Set tags. Click next.
  6. Set deployment options. Click next.
  7. Review and create the StackSet.
  8. The StackSet will create an IAM Role of the format: arn:aws:iam::<accountID>:role/runzero-sync. Copy the full ARN of the role you created. You’ll need this in Step 1a.3.

Alternatively, you may create the IAM Role(s) manually:

  1. Sign in to the AWS console.
  2. Go to Identity and Access Managment (IAM) > Roles and create a role that will provide access to runZero.
  3. On the “Select trusted entity” page: i. Select AWS account > Another AWS account ii. Enter 336004405641 for the account ID. This the account runZero uses to access your AWS account. iii. Select Require external ID… and enter the external ID that was generated in Step 1a.1. iv. Click Next to proceed to the next page.
  4. On the “Add permissions” page, select the following AWS managed policies and click Next to proceed to the next page. These grant runZero read-only access to read inventory from your AWS account.
    • AmazonEC2ReadOnlyAccess to sync EC2 and ELB resources
    • AmazonRDSReadOnlyAccess to sync RDS instances
    • AWSLambda_ReadOnlyAccess to sync Lambda functions
    • AWSOrganizationsReadOnlyAccess to sync AWS Organization account information
  5. Provide a relevant role name, such as runzero-sync, and description for the role. Once confirmed select Create role.
  6. Copy the full ARN of the role you just created. It will have the format arn:aws:iam::<accountID>:role/<roleName>. You’ll need this in Step 1a.3.

Note: If you intend to sync with AWS regions that are not enabled by default, change the region compatibility of the global STS endpoint. To do this, in the AWS console navigate to IAM -> Account Settings -> Security Token Service (STS). Then change the Global Endpoint to be compatible with “All AWS Regions.”

Step 1a.3: Update the runZero credential

  1. Return to the runZero console, navigate to the Credentials page and edit to 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. Use the Verify & Save button to save and test the credential.

You’re now ready to set up and activate the connection to bring in data from AWS. Continue to Step 2.

Option B: IAM Key Credential

If you created an IAM Role using Option 1 above, you may skip this step and proceed to Step 2 below. This section describes how to authenticate runZero to AWS using an IAM user and long-term access keys. Using long-term access keys is not recommended. We recommend using an IAM Role instead.

Step 1b.1: Create an AWS IAM user

  1. Sign in to the AWS console. If you are using AWS Organizations and intend to sync with multiple accounts, sign into 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 will provide API access to runZero.
  3. Click Add permissions > Attach existing policies directly. Search for and attach the following policies based on the services you would like to sync:
    • AmazonEC2ReadOnlyAccess to sync EC2 and ELB resources
    • AmazonRDSReadOnlyAccess to sync RDS instances
    • AWSLambda_ReadOnlyAccess to sync Lambda functions
    • AWSOrganizationsReadOnlyAccess to sync AWS Organization account information
  4. Add an inline policy to allow assuming runZero roles in sub-accounts (only required if using 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 on Create access key.
  6. Save the Access key ID and Secret access key. You’ll need them in Step 1b.3.
  7. If you intend to sync with AWS regions that are not enabled by default, change the region compatibility of the global STS endpoint to be compatible with All AWS Regions. To do this, in the AWS console navigate to IAM -> Account Settings -> Security Token Service (STS). Then change the Global Endpoint to be compatible with “All AWS Regions.”

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

If you are using AWS Organizations and want runZero to sync with all accounts in your organization, you must create an IAM role in each sub-account that allows the IAM user you created in Step 1b.1 to assume the role. If you aren’t using AWS Organizations, you may skip this step and proceed to Step 1b.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 for your organization’s management account.
  4. Click Next: Permissions.
  5. Attach the AmazonEC2ReadOnlyAccess policy if you want to sync EC2 and ELB 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. Click Next: Tags and add tags optionally.
  9. Click Next: Review and provide a name for the role. (The role must be named the same for all accounts)
  10. Click Create role.

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

  1. Go to the Credentials page in runZero and click Add Credential.
  2. Provide a name for the credential, like AWS IAM User.
  3. Choose AWS Access & Secret from the list of credential types.
  4. Provide the following information:
    • AWS access key - Access key ID obtained from Step 1b.1.
    • AWS secret access key - Secret access key obtained Step 1b.1
    • AWS role - Assumed role used to connect to other accounts in your organization. This is the role name you used in Step 1b.2.
    • Select the region(s) that you want to sync.
  5. Save the credential.

Step 2: Choose how to configure the AWS integration

The AWS integration can be configured as either a scan probe or a connector task. Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync.

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

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

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

A connection requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new AWS-only assets are created.

  1. Activate a connection to AWS. You can access all available third-party connections from the integrations page, your inventory, or the tasks page.
  2. Choose the credential you added earlier. If you don’t see the credential listed, make sure the credential has access to the organization you are currently in.
  3. Enter a name for the task, like AWS sync.
  4. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set.
  5. Under Task configuration:
    • Choose the site you want to add your assets to. All newly discovered assets will be stored in this site. You can also choose to Automatically create a new site per VPC or Automatically create a new site per account, and runZero will take care of creating the sites for newly discovered assets or accounts.
    • Choose whether to automatically delete stale AWS assets. If you check this option, runZero will automatically delete AWS assets previously seen in AWS that were not found in the most recent sync.
    • Choose whether to include AWS assets that are not currently running. If you check this option, runZero will import AWS asset data for assets that are not in a running state.
  6. Under Service options, select the services you would like to sync data from. You must choose at least one.
  7. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the Exclude unknown assets toggle to Yes. By default, the integration will include assets that have not been scanned by runZero.
  8. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the Scheduled tasks to see 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 based on any additional requirements.
  3. On the Probes and SNMP tab, choose which additional probes to include, set the AWS toggle to Yes, and change any of the default options if needed.
  4. On the Credentials tab, set the AWS toggle for the credential you wish to use to Yes.
  5. Click Initialize scan to save the scan task and have it run immediately or at the scheduled time.

Step 4: View AWS assets

After a successful sync, you can go to your inventory to view your AWS assets. These assets will have an AWS icon listed in the Source column.

To filter by AWS assets, consider running the following queries:

Click into each asset to see its individual attributes. runZero will show you the attributes returned by the AWS APIs.

Troubleshooting

If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting.

Why is the Amazon Web Services integration unable to connect?

  1. Are you getting any data from the AWS integration?
    • Make sure to query the inventory rather than look at the task details to review all the data available from this integration.
    • In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console.
  2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the integration, it may not work correctly. Please review this documentation and follow the steps exactly.
  3. If the AWS integration is unable to connect be sure to check the task log for errors. Some 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
Updated
Previous: Inbound integrations Next: Enriching scans with EC2