1. Censys
  2. Censys Attack Surface Management
  3. Cloud Connectors

Other Articles In This Section

In this article:

Set Up Censys ASM Cloud Connector for AWS

  • Updated

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.

copy-asm-api-key.png

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.

edit-cc-schedule.gif

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.

seed-data-labels.png

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 the aws_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 the rapid_setup_config file or the AWS CLI config files.

Related articles

Comments

0 comments

Article is closed for comments.