Summary
Use this connector to seed the Censys ASM platform with accurate, up-to-date information about Internet-addressable assets from your AWS accounts for monitoring and enhanced discovery.
In this guide:
Introduction
For each AWS account you enable, the cloud connector will extract IP addresses and DNS names to send to the Censys ASM platform for the following AWS services:
- All Public Virtual Machine Instances
- All Serverless Instances
- DNS and Domain Services
- S3 Buckets
- Elastic Container Services
What You'll Need:
Ready to get started? Here's what you need:
- The AWS account numbers and regions where your services are running
- Programmatic access to each AWS account
- Your Censys ASM API key
- A server with Docker and Docker Compose installed
- The
aws-cloud-connector.tar.gzcode file (please email Censys support for access)
Installation Considerations
Where should I run it?
The location of the server where you'll run the cloud connector is not prescribed by the application, although we recommend running it in the cloud environment if you're comfortable with that.
If you wish to run Censys' other cloud connectors for GCP and Microsoft Azure, you can run all of them on a single host as long as you provide the correct credentials.
How can I reduce administration of the connector?
Once the cloud connector is up and running successfully, you will not need to administer it except to update credentials.
If you have a large AWS footprint with multiple accounts and you are concerned about frequent credential rotation, we recommend you create a user with role assumption capabilities into your other accounts so that you only have to update one key when you rotate credentials.
Install the Censys Cloud Connector
Extract the contents of the
aws-cloud-connector.tar.gz file to your preferred directory. For access, please contact support@censys.io.Create Config File
Copy the file named
aws_config.yml.example and rename as aws_config.yml.Open
aws_config.yml with an editor and replace the example values with values corresponding to your AWS accounts.Example YAML for Accounts Accessed via a User
For each account number that Censys will access directly via a user, the access key and secret will need to be provided, along with a list of the regions where your services are running.
The AWS credentials must have the
SecurityAudit policy attached. Learn how to create a user with the correct permissions.accounts:
- account_number: 444XXXXXXXXX
aws_access_key: AKIAU3JWEKXXXXXXXXXX
aws_secret_access_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXX
regions:
- us-west-1
Example YAML for Accounts Accessed via a Role
If Censys will access your accounts via an assumed role, the access key and secret for the primary account (with the user) will need to be provided, along with the name of the role to assume in other accounts. For the other accounts, only the account number and regions where your services are running are needed.
Learn how to set up cross-account access.
primary_aws_access_id: AKIAU3JWEKXXXXXXXXXX
primary_aws_access_secret_id: XXXXXXXXXXXXXXXXXXXXXXXXX
role_to_assume: role_name
accounts:
- account_number: 444XXXXXXXXX
regions:
- us-west-1
Other Optional Fields You Can Specify for Each Account
session_duration: The number of seconds the cloud connector is given in each account to connect to your services and collect public-facing identifiers. The default is 3600.role_session_name: The session name that will show up in Cloudtrail logs. The default iscensys_cloud_connector.external_id: An additional ID that the user in the primary account can supply when accessing roles in secondary accounts. This field is necessary if you chose to require it during role set-up and must match the string you specified.
NOTE: The cloud connector is much more efficient if you define the regions where your services are running; however, the script will still work if you leave the
regions list empty or remove it.After listing each account and the required information, save changes and close the file.
Create Environment File
Copy the file named
.env.example and rename as .env.Open
.env with an editor and replace the example value for the CENSYS_PLATFORM_KEY with your Censys ASM API key, located on the Censys ASM Admin page.
Save changes and close the file.
Build and Run the Container
This guide assumes you already have a server running with Docker and Docker Compose installed.
Run the following command on your server from the directory where the code is located:
docker-compose up -d --build
Confirm You're Seeing Results
Visit the Censys ASM Seeds page to confirm you're seeing seeds with labels that reflect your AWS accounts. The format of the label is
AWS: {serviceType} - {accountNumber}/{region}.
Additional Help
This section provides step-by-step guides to setting up least privilege access to your accounts for the Censys ASM cloud connector.
Set Up AWS Account Access
The cloud connector requires the AWS
SecurityAudit policy to be applied to each user or role that is reading from an account.In the configuration of the Censys ASM Cloud Connector, you can provide user credentials for each account, or user credentials for a primary account that has role assumption capabilities in secondary accounts, or a mix of both.
A guide for each authentication method is provided below.
Option 1: Create a User for an Account
If you have only one or a small number of accounts, you can create a user in each account with the
SecurityAudit policy attached and input those credentials to the cloud connector configuration file. Here's how:1. Log in and Create User
Log into the AWS account whose assets you would like to feed into the Censys ASM platform.
Navigate to IAM Provisioning.
Click the Users item from the left menu.
On the Users page, click the Add User button.
2. Set User Details
On page one of the Add User flow, give the user a name (e.g.,
censys_asm_cloud_connector) and check the box next to Programmatic Access.Then, click Next.
3. Set User Permissions
On page two, set the permissions of the user. Click the tile that says, "Attach existing policies directly."
In the search bar, type "SecurityAudit," and check the box next to the policy that appears in the results.
Then, click Next.
4. Tag User
On page three, add tags to the user according to your organization's best practices.
Then, click Next.
5. Create User and Save Credentials
On page four, review your selections.
Then, click Create user.
On the confirmation page, download or copy the credentials.
Repeat steps 1-5 for each account you'd like to connect to the Censys ASM platform.
Now that you have a user with the appropriate permissions, you are ready to add the AWS account number and user credentials to the Censys ASM Cloud Connector configuration file.
Option 2: Create a Role for Cross-Account-Based Authentication
If your organization uses many AWS accounts and you want to centralize the cloud connector's auditing access to those accounts, you can use cross-account authentication.
To enable cross-account authentication, you'll need to create an IAM role for a user to assume in each secondary account and then create a user in your primary account with permission to assume that role. Here's how:
1. Log In and Create Role
Log into the (secondary) AWS account you would like to access via an assumed role.
Navigate to IAM Provisioning.
Click the Roles item from the left menu.
On the Roles page, click the Create role button.
2. Select Entity to Assume Role
On page one of the Add Role flow, select the trusted entity that will assume the role you're creating. Click the tile that says, "Another AWS User."
In the text input next to "Account ID", type the 12-digit number of the primary account which will access this one via the role.
You can optionally require an external ID. The Censys ASM Cloud Connector supports the requirement of an external ID.
WARNING: Do not select the checkbox next to Require MFA.
Afterward, click Next.
3. Set Role Permissions
On page two, set the permissions of the role.
In the search bar, type "SecurityAudit," and check the box next to the policy that appears in the results.
Then, click Next.
3. Tag Role
On page three, add tags to the role according to your organization's best practices.
Then, click Next.
4. Name Role
On page four, give your role a name and an optional description and review your selections.
If you will be creating this role in more than one account, the name must match exactly.
Then, click Create role.
On the list page, a success banner will confirm that the role has been created.
Repeat steps 1-4 for each secondary account you'd like to monitor.
IMPORTANT: The name of the role must be exactly the same in every (secondary) account because it is the identifier that the user in the primary account will be configured to look for.
Give a User the Ability to Assume the New Role(s)
Now that a role with the correct permissions is available to assume in your accounts, you'll create a user in your primary AWS account which will assume that role. Here's how:
1. Log In and Add (Cross-Account) User
Log into the (primary) AWS account whose user will access your other accounts.
Navigate to IAM Provisioning.
Click the Users item from the left menu.
On the Users page, click the Add User button.
2. Set Cross-Account User Details
On page one of the Add User flow, give the user a name (e.g.,
censys_asm_cloud_connector) and check the box next to Programmatic Access.Then, click Next.
3. Set Cross-Account User Permissions
On page two, set the permissions of the user. Click the tile that says, "Attach existing policies directly."
Then, click the grey button directly below the tiles called Create policy.
4. Create Policy for Cross-Account Role Assumption
On the Create policy page that opens in a new tab, expand the "Service" options, then search for and select "STS."
In the "Actions" section, expand "Write" and select the check box next to Assume Role.
In the "Resources" section, leave the "Specific" radio button selected and click the Add ARN linked text in the "role" subsection.
In the modal that pops up, change the "Account" selection to any by typing an asterisk (
*) in the text input or by selecting the check box next to Any.Copy the name of the role you created in your other AWS accounts (step 4 of the role creation process) into the text input for Role name with path.
Then, click Add.
Once the modal collapses, click Review Policy.
On the Review page, give your policy a name (e.g.,
assume_censys_asm_role) and optional description.
After reviewing, click Create policy.
On the policies list page, a success banner will confirm that the policy has been created.
Close this tab and return to the Add User page.
Attach New Policy to User
Back on page two of the add user flow, ensure the "Attach existing policies directly" tile is selected and type the name of your newly created policy.
Check the box next to it in the results list.
If there are services in this account that you'd like to collect data from, you'll also need to search for and select the
SecurityAudit policy.Then, click Next.
Tag User
On page three, add tags to the user according to your organization's best practices.
Then, click Next.
Create User and Save Credentials
On page four, review your selections.
Then, click Create user.
On the confirmation page, download or copy the credentials.
Now that you have a cross-account user with the appropriate permissions, you are ready to add the AWS account numbers and user credentials to the Censys ASM Cloud Connector configuration file.
Please contact support@censys.io for questions, feature requests, or support.