Set Up Censys ASM Cloud Connector for AWS
Psst! There's a faster way to do this now: use AWS Cloud Formation – Follow these 3 QUICK steps!
Introduction
Follow this how-to guide to set up a Cloud Connector that will seed the Censys Attack Surface Management platform with Internet-addressable assets from your AWS accounts for monitoring and enhanced discovery.
What the Cloud Connector Collects
For each AWS account connected, the Cloud Connector collects public IP addresses and DNS names for the following services to send to the Censys ASM platform:
-
All Public Virtual Machine instances
-
Serverless assets like ECS and Fargate
-
DNS and Domain Services
-
S3 Buckets
-
All public databases
-
AWS API Gateway endpoints
Prerequisites
Ready to get started? Here’s what you need:
-
A
secrets/.env
file configured with your Censys ASM API key -
A list of AWS account numbers and regions where your services are running
Other prerequisites depend on your setup and deployment choices:
-
Programmatic access to each AWS account (if you’re not using Censys Rapid Setup)
-
A server with Docker and Docker Compose installed (if you’re not deploying to AWS Fargate)
Quick Start
Execute the command below in the cloud connector project with the options that fit your setup and deployment decisions.
Before running these commands, you must fill out the .env
file as outlined in step one below.
Censys Rapid Setup + AWS Fargate Deploy
Set up IAM infrastructure using the AWS CLI config/credentials files on your machine’s ~/.aws
directory and automatically deploy to AWS Fargate:
./run.sh -raof
Censys Rapid Setup + Local Deploy
Set up IAM infrastructure using this project’s rapid_setup_config
file and deploy locally:
./run.sh -roc
Before running this command, you must fill out the rapid_setup_config
as outlined in step two below.
The -c
option assumes that you have a server with Docker and Docker Compose installed.
Tip | See more setup and deployment Options in this list. |
Step 1: Configure the Cloud Connector
Provide Your API Key
Copy the (hidden) file .env.example
to .env
.
Open the file and change the CENSYS_PLATFORM_KEY
placeholder value to your API key from the Censys ASM Integrations page.
Set LOOP_CONNECTOR
to true
to repeatedly run cloud asset scans on a schedule (default is true
). Set LOOP_CONNECTOR
to false
to run the connector scan once and then exit.
Step 2: Set Up AWS IAM Access
Option 1 (Fastest): Censys Rapid Setup
Provided with a config file, the Censys Rapid Setup module automatically creates and provisions all IAM accounts, roles, and permissions needed to run the connector. Consult the AWS docs here for more information on the config
and credentials
files formats.
Configure Censys Rapid Setup
If you have AWS CLI already installed and want to use those config files to provide your account list, continue to Run Censys Rapid Setup and be sure to add the -a
flag.
Alternatively, this project contains a rapid_setup_config.example
file: add your AWS accounts and rename the file rapid_setup_config
. This file should have the same format as the AWS config
and credentials
files referenced in the above link.
Run Censys Rapid Setup
Run Censys Rapid Setup by executing the following command from the project’s root directory, adding the -a
flag if you are using the AWS CLI config files.
./run.sh -ro
IAM infrastructure will be provisioned for all specified accounts and the /secrets/aws_cc_config.yml
file will be populated.
Option 2: Manual AWS IAM Setup
See this guide to manually set up AWS account access for the cloud connector.
Step 3: Run the Cloud Connector
The AWS Cloud Connector can be run in a Docker container on a server of your choice, or in an AWS Fargate instance.
Option 1: Local Container Deployment
This step assumes you have a server where Docker and Docker Compose are installed.
Use the following command to deploy the Docker container locally:
./run.sh -c
Option 2: Fargate Container Deployment
Use the following command to deploy the container in an AWS Fargate instance.
./run.sh -f
The connector’s run frequency is automatically set to every 12 hours. It can be customized by editing the schedule expression under the Scheduled Tasks tab in the censys-rapid-setup
ECS cluster.
Confirm You’re Seeing Results
Visit the Seeds Review Page in the app to confirm you’re seeing seeds with labels that begin with AWS: [service-name] - XXXXX
.
Please contact support@censys.io for questions, feature requests, or support.
Reference
Cloud Connector Command
./run.sh
- Run AWS Cloud Connector with or without Censys Rapid Setup.
Synopsis
./run.sh [OPTIONS] [PARAMETERS]
Options
-
-a [ABS_AWS_CLI_DIR_PATH]
– Use the default AWS CLI config files for the Censys Rapid Setup module.The optional parameter specifies the absolute location of the
.aws
directory on your local system.If no parameter is provided, the path defaults to
~/.aws
. -
-c
– Deploy the AWS Cloud Connector in a local Docker container. -
-f
– Deploy the AWS Cloud Connector in a Fargate instance in AWS ECS. -
-o
– Overwrite theaws_cc_config.yml
file with the settings generated by the Censys Rapid Setup module. -
-r
– Run the Censys Rapid Setup module and provision primary and secondary IAM infrastructure for each account specified in therapid_setup_config
file or the AWS CLI config files.
Comments
0 comments
Article is closed for comments.