Enriching scans with EC2

View as Markdown

Community Platform

During a discovery scan, runZero automatically enriches scanned assets with data from the AWS EC2 API when it’s available. Assets pick up internal IP addresses, external IP addresses, hostnames, MAC addresses, and tags, along with other EC2-specific attributes such as the account ID and instance type.

runZero needs no extra configuration for this enrichment, but you may need to modify the permissions on the instance’s IAM role.

Find Explorers with EC2 enrichment capabilities

EC2 enrichment works when the runZero Explorer runs on an instance with permission to describe your EC2 instance list. You can grant that through an IAM role attached to the instance or by configuring AWS credentials for the root user account.

To see which Explorers have this capability, view your registered Explorers. An Explorer with the cloud icon can enumerate EC2 instances.

Scans from these Explorers automatically merge EC2 instance fields into the asset for any in-scope target that matches the instance list.

Add permissions to describe instances

To enable EC2 instance data enrichment, add the EC2 ec2:DescribeInstances permission to the instance role configured for your instance. The Amazon docs explain how to create and update policies.

Your policy will look like this:

{
   "Version": "2012-10-17",
   "Statement": [{
     "Sid": "VisualEditor0", 
      "Effect": "Allow",
      "Action": [
         "ec2:DescribeInstances", 
      ],
      "Resource": "*"
   }
   ]
}

In the IAM UI, go to Roles > Permissions > Attach policies and search for the EC2 service. Under the actions, select DescribeInstances, which is listed under List.

Instead of the IAM instance role, you can also configure credentials on the instance by running aws configure as root.

After you save your policy, restart your Explorer. The easiest way is to force an update from the Explorer menu.

If your configuration uses one region but the instance is in another, the Explorer uses the instance’s region for all API requests.

Attributes runZero gets from the EC2 API

When runZero determines that an IP address is also an EC2 instance, it enriches the existing asset data with EC2 metadata, including more hostnames (based on AWS asset tags), MAC addresses, and internal and external IPs.

Attributes runZero can get from the EC2 API metadata include:

  • aws.accountID
  • aws.architecture
  • aws.availabilityZone
  • aws.hypervisor
  • aws.imageID
  • aws.instanceID
  • aws.instanceType
  • aws.ipv4
  • aws.ipv6
  • aws.keyName
  • aws.launchTimeTS
  • aws.macs
  • aws.privateDNS
  • aws.privateIP
  • aws.publicDNS
  • aws.publicIP
  • aws.region
  • aws.rootDeviceName
  • aws.rootDeviceType
  • aws.scanner.instanceID
  • aws.scanner.instanceType
  • aws.state
  • aws.subnetID
  • aws.tags
  • aws.tenancy
  • aws.virtualizationType
  • aws.vpcID

runZero also reports other things that respond to the scan but don’t match an EC2 entry. You may see Amazon RDS, temporary ELBs, and Lambdas in your inventory, but only EC2 assets carry EC2 metadata. For broader visibility across your AWS environment, set up the Amazon Web Services integration.

Updated