Amazon EC2

Amazon EC2 (Elastic Cloud Compute) by Amazon Web Services (AWS) provides management for your cloud instances. You can bring instance data from Amazon EC2 into Brinqa to gain a comprehensive view of your cloud security landscape, thus strengthening your cybersecurity posture.

This document details the information you must provide for the connector to authenticate with Amazon EC2 and how to obtain that information from Amazon. See create a data integration for step-by-step instructions on setting up the integration.

Required connection settings

When setting up a data integration, select Amazon EC2 from the Connector drop-down. If you cannot find the connector in the drop-down, make sure that you have installed it first. You must provide the following information to authenticate Amazon EC2 with Brinqa:

Access key ID and Secret access key: The access keys associated with the Amazon EC2 account, which must have the AmazonEC2ReadOnlyAccess permission in order to access EC2 instances from the Amazon SDK. For additional information, see Create an IAM user for Amazon EC2 access.
Default region: The AWS region for the Amazon EC2 connector. If not specified, the connector uses the AWS Default Region Provider Chain to automatically determine the most appropriate region. This ensures that the connector adheres to the recommended AWS practices for region selection. For additional information on the AWS Default Region Provider Chain, refer to the AWS documentation.
Assume role: The Amazon Resource Name (ARN) for the role that the connector assumes when accessing AWS services, which must have permissions to log in to the API server and return data. You can use multiple ARNs separated by commas, e.g., target1RoleARN,target2RoleARN.

Create an IAM user for Amazon EC2 access

For the Amazon EC2 connector to interact with the AWS SDK and retrieve instances, you must provide specific AWS credentials and permissions. If you want to configure cross-account access, you can skip this section and go to the Set up permissions for cross-account access section instead.

To create an IAM user for EC2 access, follow these steps:

Log in to your organization's AWS Management Console as an administrator.
Navigate to the Identity and Access Management (IAM) dashboard.
From the navigation pane under Access management, click Users, and then click Create user.
Provide a User name, leave the Provide user access to AWS Management Console option unchecked, and then click Next.
Click the Attach policies directly option, search for and select the AmazonEC2ReadOnlyAccess permission.
Click Next and then click Create user.

The Users page displays and the new IAM user is available in the Users table.

note

If you do not have permissions to create a new IAM user, contact your AWS administrator. For additional information, see AWS documentation.

Obtain Amazon EC2 access keys

After you have created an IAM user, you can then generate the access keys that are required for the Amazon EC2 connector to access the AWS SDK. To do so, follow these steps:

Navigate to the IAM dashboard.
From the navigation pane under Access management, click Users.
Choose the IAM user you created in the earlier steps.
Click the Security credentials tab and then click Create access key.
Select the Application running outside AWS use case and then click Next.
Provide a description and then click Create access key.

The access key ID and secret access key display. The secret access key is shown only once and cannot be retrieved again, so copy the key and save it to a secure location.

note

If you do not have the permissions to create access keys, contact your Amazon EC2 administrator. For additional information, see AWS documentation.

Create a role and assign permissions

After creating an IAM user and obtaining the Amazon EC2 access keys, the next step is to create a role and obtain the ARN that is required for the integration. To do so, follow these steps:

From the IAM dashboard, click Roles, and then click Create role.
For the Trusted entity type, choose AWS account, and then click Next.
Search for and select the AmazonEC2ReadOnlyAccess permission from the list of permissions and click Next.
Assign a name and description and then click Create role.
Back on the Roles page, click the new role and copy the value in the ARN field as shown below:

The ARN, along with the access key ID and secret access key, are required for authentication in the integration configuration.

note

If you do not have the permissions to create roles, contact your Amazon EC2 administrator. For additional information, see AWS documentation.

(Optional) Set up permissions for cross-account access

You can configure cross-account access to allow the Amazon EC2 connector to interact with multiple AWS accounts. If this is what you want to do, you can skip the Create an IAM user for Amazon EC2 access section.

Before we begin, let's introduce some terms for clarity:

Source account: The AWS account with EC2 instances that the connector will access.
Target account: The AWS account that is connected to the EC2 instances in the source account.

In every AWS target account with EC2 Instances, follow these steps:

From the IAM dashboard, click Roles, and then click Create role.
For the Trusted entity type, select AWS account, and then select Another AWS account.
Enter the AWS account ID of the AWS source account and then click Next
Attach a policy to the role that grants permissions for the actions you want to allow in the target account (e.g., AmazonEC2ReadOnlyAccess).
After creating the role, select it from the list of roles and then click the Trust relationships tab.
Click Edit trust policy and edit the trust relationship policy document to include the AWS source account ID you entered in step 3.
Click Update policy and note down the Role ARN, as you will need this ARN in the source account for the next steps.

In the AWS source account connecting to the EC2 Instances, follow these steps:

From the IAM dashboard, click Users, and then click Create user.
Enter a username (e.g., CrossAccountUser) and click Next.
Select Attach policies directly and then click Create policy.
Click the JSON tab and attach a policy to the user that allows it to assume roles in the target account. For example, the policy should allow sts:AssumeRole for the target account's role:
```
{
    "Version": "2024-05-30",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "<target-role-arn>"
        }
    ]
}
```
Replace <target-role-arn> with the ARN of the role created in the target account.
Click Next.
Repeat steps 3-5 for each target ARN.
Search for and select the AmazonEC2ReadOnlyAccess permission from the list of permissions and click Next.
Click Create user.

After creating the user, follow the steps for obtaining access keys. Use these credentials in the integration configuration along with the role ARN for the target you created earlier. You can enter the ARNs in a comma-separated format: target1RoleARN, target2RoleARN, target3RoleARN.

note

For additional information on configuring cross-account access, see AWS documentation

Additional settings

The Amazon EC2 connector contains an additional option for specific configuration:

Session duration: The duration, in seconds, for the assumed role session. This determines the time period during which the credentials issued by the assumed role remain valid. The default setting is 900 seconds, or 15 minutes.
Page size: The maximum number of records to get per API request. The default setting is 100. It is not recommended to go over 100.

Types of data to retrieve

The Amazon EC2 connector can retrieve the following types of data from the Amazon EC2 API:

Table 1: Data retrieved from Amazon EC2

Connector Object	Required	Maps to Data Model
Instance	Yes	Host

info

For detailed steps on how to view the data retrieved from Amazon EC2 in the Brinqa Platform, see How to view your data.

Attribute mappings

Expand the section below to view the mappings between the source and the Brinqa data model attributes.

Instance

Table 2: Instance attribute mappings

Source Field Name	Maps to Attribute
architectureAsString	Local variable
availabilityZone	Local variable
categories	categories
cloudProvider	cloudProvider
description	description
hypervisorAsString	Local variable
imageId	Local variable
instanceId	uid
instanceTypeAsString	Local variable
keyName	Local variable
lastSeen	lastSeen
launchTime	firstSeen
monitoring	Local variable
name	name
networkInterfaces.macAddress	macAddresses
networkInterfaces.privateIpAddress	ipAddresses, privateIpAddresses, publicIpAddresses
ownerId	Local variable
platformAsString, platformDetails	os
privateDNSName	hostnames, privateDnsName
publicDNSName	publicDnsName
ramdiskId	Local variable
region	region
rootDeviceName	Local variable
rootDeviceTypeAsString	Local variable
securityGroups	Local variable
state	status, sourceStatus
stateTransitionReason	Local variable
subnetId	Local variable
tags	tags
virtualizationTypeAsString	Local variable
vpcId	Local variable

info

Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.

Operation options

The Amazon EC2 connector supports the following operation options. See connector operation options for information about how to apply them.

Table 2: Amazon EC2 connector operation options

Connector Object	Option	All Possible Values	Description	Example
Instance	maxResults	Any numeric value	Limit the number of instances returned per API call. The default value is 1000.	Key: `maxResults` Value: `10`. This key and value combination only retrieves 10 instances per API call.
	regions	Any region where your Amazon EC2 instances reside	Retrieve instances by the specified AWS regions.	Key: `regions` Value: `us-east-1`,`us-west-1`. This key and value combination only retrieves instances from the `us-east-1` and `us-west-1` AWS regions.

note

The option keys and values are case-sensitive as they are shown in this documentation.

AWS SDK

The Amazon EC2 connector uses the AWS SDK v2.25.6. Specifically, it uses the following classes and methods:

Table 3: Amazon EC2 AWS SDK classes

AWS SDK Class	Description
`com.amazonaws.auth.AWSCredentialsProvider`	Returns AWS credentials.
`com.amazonaws.services.ec2.AmazonEC2`	Interacts with the Amazon EC2 service.
`com.amazonaws.services.ec2.model.AmazonEC2Exception`	Handles exceptions specific to Amazon EC2 operations.
`com.amazonaws.services.ec2.model.DescribeInstancesRequest`	Retrieves instance details.
`com.amazonaws.services.ec2.model.DescribeInstancesResult`	Processes the results of instance details requests.
`com.amazonaws.services.ec2.model.DescribeTagsRequest`	Manages EC2 tags retrieval.
`com.amazonaws.services.ec2.model.DescribeTagsResult`	Processes the results of EC2 tags requests.
`com.amazonaws.services.ec2.model.Filter`	Applies filtering for data retrieval.
`com.amazonaws.services.ec2.model.GroupIdentifier`	Provides details related to instance security groups.
`com.amazonaws.services.ec2.model.Reservation`	Provides information about reserved EC2 instances.
`com.amazonaws.services.ec2.model.TagDescription`	Provides detailed information about EC2 tags.

Changelog

The Amazon EC2 connector has undergone the following changes:

3.0.11

Fixed an issue where the EC2 connector sync was failing due to deprecated attributes on the Instance object. As a result, the following attributes were updated:
- HOST_NAME -> HOST_NAMES
- PRIVATE_DNS_NAME -> PRIVATE_DNS_NAMES
- PUBLIC_DNS_NAME -> PUBLIC_DNS_NAMES
- PUBLIC_IP_ADDRESS -> PUBLIC_IP_ADDRESSES
Changed the SECURITY_GROUP attribute type on the Instance object from single to multi-valued.

3.0.10

No change.

3.0.9

No change.

3.0.8

No change.

3.0.7

No change.

3.0.6

No change.

3.0.5

Fixed an issue where the connector wasn't timing out properly.

3.0.2

Added API call timeouts and API call attempt timeouts.

3.0.1

Added the AWS icon and some missing attributes.

3.0.0

Initial Integration+ release.

Required connection settings​

Create an IAM user for Amazon EC2 access​

Obtain Amazon EC2 access keys​

Create a role and assign permissions​

(Optional) Set up permissions for cross-account access​

Additional settings​

Types of data to retrieve​

Attribute mappings​

Operation options​

AWS SDK​

Changelog​

Required connection settings

Create an IAM user for Amazon EC2 access

Obtain Amazon EC2 access keys

Create a role and assign permissions

(Optional) Set up permissions for cross-account access

Additional settings

Types of data to retrieve

Attribute mappings

Operation options

AWS SDK

Changelog