1 Prerequisites
2 Setting up an AWS environment for onboarding
- 2.1 Creating the AWS policy
- 2.2 Creating the AWS role
3 Onboarding an AWS environment via API
- 3.1 Using the command line
- 3.2 Using our Python library

Prerequisites

To onboard a new AWS environment into Data Theorem using the API, you will need the following information:

An API key that can access Data Theorem’s API Security Results API (beta).
- An API key can be generated from the Data Theorem portal at https://www.securetheorem.com/sdlc/results_api_access. It should have the "API Security Results API“ access enabled:
The ARN of the AWS role that Data Theorem will use to access the environment.
The external ID of the AWS role that Data Theorem will use to access the environment.

Instructions on how to create the AWS ARN and external ID follow.

Setting up an AWS environment for onboarding

Creating the AWS policy

Sign in to the AWS Management Console by clicking here
- The link will take you to create policy page
Select the JSON tab in the policy editor and paste the following policy (overwriting the existing items):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Resource": "*",
      "Action": [
        "apigateway:GET"
      ]
    }
  ]
}

Select Review policy, and enter the name below:
- DataTheorem-APIGateway-SecurityAudit
Select Create policy

Creating the AWS role

Navigate to Create Role page on AWS by clicking here
- The link will pre-fill Data Theorem's account ID
- You need to fill the External ID field by generating a random password. We suggest one of the following:
  - Generate a UUID
  - Generate from terminal: openssl rand -base64 32
  - Keep the External ID somewhere temporarily as you will need it later.
Ensure the field Account ID and External ID are filled
Select Next: Permissions
Enter SecurityAudit in the search box and then select its checkbox
Erase the search box, and enter DataTheorem-APIGateway-SecurityAudit. Select its checkbox
Select Next: Review and enter the following for the name:
- DataTheorem-Service
- Ensure it has the two SecurityAudit and DataTheorem-APIGateway-SecurityAudit policies enabled
Select Create role
Select on the newly created role DataTheorem-Service
Copy the Role ARN value on the top of the page and keep it somewhere temporarily as you will need it later

Onboarding an AWS environment via API

Using the command line

The API endpoint to onboard a new cloud environment is available at https://api.securetheorem.com/apis/api_security/results/v1beta1/cloud_authenticators.

The following sample curl request shows how to call this API to onboard an AWS environment:

$ curl -X POST -H "Content-Type: application/json" -H "Authorization: APIKey YOUR_API_KEY" \
https://api.securetheorem.com/apis/api_security/results/v1beta1/cloud_authenticators \
-d '{"cloud_authenticator_type": 3, \
"aws_credential": {"role_arn": "REPLACE WITH YOUR ROLE ARN", \
"external_id": "REPLACE WITH YOUR EXTERNAL ID"}}'

Look at https://bitbucket.org/datatheorem/dt-api-security-results/src/fb50aaca1fcb7e13b64f7368b890d4b56285d975/dt_api_security_results/models/cloud_authenticators.py#lines-11 to find the cloud_authenticator_type's value and the credential’s data structure that needed to call this API.

Using our Python library

In dt-api-security-results, a sample script to onboard an AWS environment is available here:

""" Example script showing how to onboard a cloud authenticator.
"""
import logging

from dt_api_security_results.client import ApiSecurityResultsClient, \
CloudAuthenticatorCreateRequest
from dt_api_security_results.models.cloud_authenticators import AwsCredential, \
CloudAuthenticatorTypesEnum

API_KEY = "REPLACE WITH YOUR API KEY"
ROLE_ARN = "REPLACE WITH YOUR ROLE ARN"
EXTERNAL_ID = "REPLACE WITH YOUR EXTERNAL ID"

logging.basicConfig(
    level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s"
)

if __name__ == "__main__":
    client = ApiSecurityResultsClient(api_key=API_KEY)
    
    request = CloudAuthenticatorCreateRequest(
        cloud_authenticator_type=CloudAuthenticatorTypesEnum.AMAZON_WEB_SERVICES,
        aws_credential=AwsCredential(role_arn=ROLE_ARN, external_id=EXTERNAL_ID,),
    )
    try:
        response = client.cloud_authenticator_create(authenticator_request=request)
    except Exception:
        logging.exception("An error occurred.")
    else:
        logging.info(
            f"Successfully onboarded cloud authenticator: {response.json()}"
        )
    logging.info("All done.")

Public Knowledge Base

On-boarding AWS environments via Data Theorem's API