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 are available in the following article at Cloud Integration: On-board AWS.
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.")