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

1. Sign in to the AWS Management Console by clicking here

   • The link will take you to create policy page

2. 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"
      ]
    }
  ]
}

1. Select Review policy, and enter the name below:

   • DataTheorem-APIGateway-SecurityAudit

2. Select Create policy

Creating the AWS role

1. 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.

2. Ensure the field Account ID and External ID are filled

3. Select Next: Permissions

4. Enter SecurityAudit in the search box and then select its checkbox

5. Erase the search box, and enter DataTheorem-APIGateway-SecurityAudit. Select its checkbox

6. Select Next: Review and enter the following for the name:

   • DataTheorem-Service

   • Ensure it has the two SecurityAudit and DataTheorem-APIGateway-SecurityAudit policies enabled

7. Select Create role

8. Select on the newly created role DataTheorem-Service

9. Copy the Role ARN value on the top of the page.

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.")