Documentation
Start typing to search…

AWS Hosted Cloud Connector

Access Levels: | Advanced | Enterprise

The Censys Cloud Connector for Amazon Web Services (AWS) enumerates your cloud environment, ensuring that Censys Attack Surface Management (ASM) is always up to date and your security teams are working with the most current data. This integration scans each resource to determine whether it is public.

You can configure this integration via the API or in the Censys ASM UI.

The Censys AWS Cloud Connector authenticates to an IAM Role with the following permissions:

  • AWSOrganizationsReadOnlyAccess
  • SecurityAudit

These are the least privileged permissions required to access your cloud resources and import them into Censys.

Data refresh frequency

Cloud Connectors refresh more often than other connections. After you set up Cloud Connectors, your data will refresh as often as every four hours.

To see the latest refresh time in Censys ASM:

  1. Go to the ASM web console and click Integrations.
  2. Scroll down to see the date within the Cloud Service Provider cards.

Configure the Censys Cloud Connector for AWS

There are two options for configuring Censys Cloud Connectors for AWS: using the Censys ASM UI or via the Censys API.

Prerequisites

You will need the following before you get started:

  • Your AWS Organization Management Account ID
  • Optionally, you may need:
    • A list of accounts or services you wish to exclude from being sent to Censys ASM

The following users and permissions are required:

  • Censys ASM user with the workspace role Manager
  • AWS Admin with the following privileges:
    • Access to the AWS Organization management account.
    • Ability to deploy a CloudFormation Template, creating a StackSet in the AWS Organization management account.

Option 1: Configure the Cloud Connector in the ASM UI

Step 1: Configure the integration in Censys

  1. Go to the ASM web console and click Integrations at the top of the page.
  2. Locate AWS and click Set Up.
  3. In the setup wizard, configure the following:
    1. Role Name: Enter a role name or leave this field blank to use the default name.
    2. Account ID: Enter your AWS account ID. If you are configuring this for an AWS organization, enter your organization management account ID.
    3. Excluded Fields: Optionally, enter any resource types or regions you wish you exclude from being sent to Censys ASM.
  4. Click Next Step.
  5. On the IAM Resource page, click Create Stack next to the template where you are deploying.
    1. You must create an IAM role in all of the accounts associated with the Cloud Connector. If you configure this for an AWS organization, it will automatically deploy to all AWS accounts within the organization and auto-deploy the IAM role to any new accounts added to the organization via StackSet.
    2. The page will redirect to your AWS console.

Step 2: Configure the stack in AWS

  1. In the AWS web console, verify that your parameters are configured properly:

    1. ExternalId: This field should contain the external ID provided in Censys ASM.

    2. Do not make changes to the RoleName parameter.

  2. Check the box next to I acknowledge that AWS CloudFormation might create IAM resources with custom names.

  3. For a standalone AWS account, click Create stack. For an organization, follow these additional steps:

    1. Navigate to CloudFormation > StackSets.

    2. Click Actions > Add stacks to StackSet.

    3. For the deployment target, select Deploy to organization.

    4. Under Specify regions, select your AWS region.

    5. Click Next, then click Next again.

    6. Verify your configuration, then click Submit.

      1. This will add all member accounts within the organization to this StackSet.

  4. Click Create stack.

    1. The page will redirect to an Events page within the AWS console, showing that the stack creation is in progress.

Step 3: Finish configuration in Censys

  1. Go to the ASM web console and click Next Step, then click Done.

Option 2: Configure the Cloud Connector via Censys API

Step 1: Creating the connector using Censys API

  1. Craft a JSON body with the appropriate scopes describing how you want the Cloud Connector to scan your AWS environments. Any combination of Organizations and standalone accounts is acceptable.
    1. To include an AWS Organization, provide the Organization’s Management Account ID and any optional account, region, or service type exclusions.
    2. Provide the Account ID and any optional account, region, or service type exclusions to include a standalone AWS account.
    3. For examples, see the JSON section below.
  2. When the JSON body is ready, create a new hosted connector using the Censys Hosted Connectors API endpoint.
    1. Go to the Integrations Marketplace.
    2. Copy your API Key to your clipboard.
    3. Follow the link to API documentation.
    4. Click Authorize and paste in your API key.
    5. Click Authorize > Close.
    6. Expand the hosted connectors header to expose the Hosted Connector endpoints.
    7. Expand the POST /v1/hosted-connectors endpoint.
      1. Click Try it out, then replace the example value with your own JSON body.
      2. Click Execute.
  3. Censys will return a response body including two URLs to deploy a CloudFormation template as a stack.
    1. For a standalone account, use the accountTemplate URL.
      1. Use the organizationTemplate URL to deploy to an entire AWS organization or specific OUs. You must be logged in to your AWS Management account to deploy to the organization.

📘

Note

If your Organization does not use Cloudformation templates, build similar logic using Terraform or another preferred method. Ensure that a role is created with permissions and that a trust relationship contains our Account ID and the provided External ID.

Step 2: Deploy in AWS

  1. After signing in to AWS, copy the proper URL from the response body, paste the URL into your browser, review the Stack options, and deploy.
    1. If using an accountTemplate, no additional steps are required.
    2. If using organizationTemplate, navigate to the CensysHostedCloudConnector StackSet created in your Management Account to add stacks to the StackSet:
      1. Click Actions, then click Add stacks to StackSet.
      2. Choose your deployment targets. The recommended target is Deploy to organization.
      3. Choose your preferred region and deployment options.
      4. Click Next, click Next, then click Submit.
  2. Wait for the StackSet to create the IAM Role in all of the specified Member Accounts.
  3. Initiate a permissions check to verify that all permissions are properly granted.
    1. Go back to the API documentation.
    2. Expand the POST /v1/hosted-connectors/{id}/checkendpoint
    3. Click Try it out.
    4. Paste in the ID of the connector you want to check.
    5. Click Execute. In the response body, use the Date field to note the time that the check was started.
  4. Using the GET /v1/hosted-connectors/{id} endpointcheck the status.
    1. Expand GET /v1/hosted-connectors/{id} and click Try it out.
    2. Paste the ID of the connector you wish to check, then click Execute.
      1. Verify that statusTimestamp is the same time as what you noted from the /check endpoint.
      2. Verify that status is either checking-configuration or connected.
        1. If status is connected, your connector is correctly configured.
        2. If status is checking-configuration” wait a few moments and Execute the GET call again.
        3. If status is not-connected, check the response for errors that need to be corrected

JSON examples

Example one

This example has one scope, which includes all asset types in all regions for all accounts within the AWS Organization.

{
    "aws": {
        "partition": "AWS",
        "roleName": "censys-hosted-connector-role",
        "scopes": [
            {
                "organization": {
                    "managementAccountId": "123123123123",
                    "excludedAccountIds": []
                },
                "excludedAssetTypes": [],
                "excludedRegions": []
            }
        ]
    }
}

Example two

This example has two scopes. The first scope includes all asset types in all regions for all accounts except 789789789 contained within the AWS Organization. The second scope is to scan account 789789789789, excluding the API Gateway and API Gateway v2 asset types and the entire us-east-2 region.


{
    "aws": {
        "partition": "AWS",
        "roleName": "censys-hosted-connector-role",
        "scopes": [
            {
                "organization": {
                    "managementAccountId": "123123123123",
                    "excludedAccountIds": [
                        "789789789789"
                    ]
                },
                "excludedAssetTypes": [],
                "excludedRegions": []
            },
            {
                "account": {
                    "accountId": "789789789789"
                },
                "excludedAssetTypes": [
                    "API_GATEWAY",
                    "API_GATEWAY_V2"
                ],
                "excludedRegions": [
                    "us-east-2"
                ]
            }
        ]
    }
}

Updated 18 days ago