Add an Amazon Web Services Connector

You can use the SDK to add an Amazon Web Services (AWS) connector and synchronize EC2 Instances and WorkSpaces from AWS to Deep Security. For an overview of adding connectors in the Deep Security console, see this article in the Deep Security Help Center.

You can use either of the following ways to add an AWS connector:

Use a cross-account role
Use the manager instance role

You must have an AWS account to use for connecting to Deep Security.

Add a connector using a cross-account role

To add a connector using a cross-account role, you must first retrieve your external ID from Deep Security Manager and configure your AWS account's role.

Retrieve the external ID

The externalId parameter can be retrieved from the AwsConnectorSettingsApi:

Python

# Initialization
api_instance = deepsecurity.AwsConnectorSettingsApi(deepsecurity.ApiClient(configuration))
api_version = 'YOUR VERSION'
try:
    api_response = api_instance.list_aws_connector_settings(api_version)
    pprint(api_response)
except ApiException as e:
    print("An exception occurred when calling AwsConnectorSettingsApi.list_aws_connector_settings: %s\n" % e)

JavaScript

// Initialization
let apiInstance = new Deepsecurity.AwsConnectorSettingsApi();
let apiVersion = 'YOUR VERSION';

apiInstance.listAwsConnectorSettings(apiVersion).then(data => {
  console.log(`API called successfully. Returned data: ${JSON.stringify(data, null, 4)}`);
}, error => {
  console.error(error);
});

Java

// Initialization
AwsConnectorSettingsApi instance = new AwsConnectorSettingsApi();
String apiVersion = "YOUR VERSION";
try {
    Awsconnectorsettings result = instance.listAwsConnectorSettings(apiVersion);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("An exception occurred when calling AwsConnectorSettingsApi.listAwsConnectorSettings");
    e.printStackTrace();
}

Configure the AWS account

On AWS, create a cross-account role for your AWS account that references the Deep Security Manager's instance role. For more details, refer to this guide in the Deep Security Help Center. When you enter the external ID, use the externalId value that you retrieved in the previous step.

Create the AWS connector

Python

View source

def create_aws_connector_using_cross_account_role(api, configuration, api_version, api_exception, display_name,
                                                  cross_account_role_arn, workspaces_enabled):
    """Creates an AWS Connector using the provided credentials.

    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Deep Security API exception module.
    :param display_name: The name to display for this connector in Deep Security.
    :param cross_account_role_arn: The role from this AWS Account that DSM will assume to authenticate this connector.
    :param workspaces_enabled: Whether WorkSpace computers should be synchronized with this account
    :return: An AWSConnectorsApi object that contains the ID of the created AWS Connector and its details.
    """

    aws_connectors_api = api.AWSConnectorsApi(api.ApiClient(configuration))
    aws_connector = api.AWSConnector()

    # Set the AWS Connector Properties
    aws_connector.display_name = display_name
    aws_connector.cross_account_role_arn = cross_account_role_arn
    aws_connector.workspaces_enabled = workspaces_enabled

    api_response = aws_connectors_api.create_aws_connector(aws_connector, api_version)
    return api_response

JavaScript

View source

/**
 * Create an AWS connector using a cross-account role.
 * @param {ApiClient} api           The Deep Security API exports.
 * @param {String} displayName      The display name of the AWS connector.
 * @param {String} crossAccountRoleArn        The AWS cross account role ARN used to connect to the AWS connector.
 * @param {String} apiVersion       The API version to use.
 * @returns {Promise}               The promise contains the AWS connector object.
 */
exports.createAWSConnectorUsingCrossAccountRole = function(api, displayName, crossAccountRoleArn, apiVersion){
    let apiInstance = new api.AWSConnectorsApi();
    let AWSConnector = new api.AWSConnector();

    // Set the AWS connector properties.
    AWSConnector.displayName = displayName;
    AWSConnector.crossAccountRoleArn = crossAccountRoleArn;

    return apiInstance.createAWSConnector(AWSConnector, apiVersion);
}

Java

View source

/**
 * Create an AWS connector using a cross-account-role.
 * 
 * @param displayName       The name of the AWS connector to show in Deep Security
 * @param crossAccountRoleArn       AWS Cross Account Role ARN used to access this account.
 * @param apiVersion        The version of the API to use.
 * @return                  Return the created AWS connector object.
 * @throws ApiException     Throw an exception if a problem occurs when creating a AWS connector on
 *                          Deep Security Manager.
 */
public static AWSConnector createAWSConnectorUsingCrossAccountRole(String displayName, String crossAccountRoleArn, String apiVersion)
        throws Exception {

    AwsConnectorsApi apiInstance = new AwsConnectorsApi();

    // Create an AWS connector object.
    AWSConnector AWSConnector = new AWSConnector();
    AWSConnector.setDisplayName(displayName);
    AWSConnector.setCrossAccountRoleArn(crossAccountRoleArn);

    // Add the AWS connector to Deep Security Manager.
    AWSConnector result = null;
    result = apiInstance.createAWSConnector(AWSConnector, apiVersion);

    return result;
}

Add a connector using the manager instance role

When your Deep Security Manager resides in the AWS account that you want to add to Deep Security, you can use the manager instance role option to easily add the account.

Python

View source

def create_aws_connector_using_instance_role(api, configuration, api_version, api_exception, display_name, workspaces_enabled):
    """Creates an AWS Connector using the provided credentials.

    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Deep Security API exception module.
    :param display_name: The name to display for this connector in Deep Security.
    :param use_instance_role: Set to True to authenticate the account using Deep Security's instance role.
    :param workspaces_enabled: Whether WorkSpace computers should be synchronized with this account
    :return: An AWSConnectorsApi object that contains the ID of the created AWS Connector and its details.
    """

    aws_connectors_api = api.AWSConnectorsApi(api.ApiClient(configuration))
    aws_connector = api.AWSConnector()

    # Set the AWS Connector Properties
    aws_connector.display_name = display_name
    aws_connector.use_instance_role = True
    aws_connector.workspaces_enabled = workspaces_enabled

    api_response = aws_connectors_api.create_aws_connector(aws_connector, api_version)

    return api_response

JavaScript

View source

/**
 * Create an AWS connector using the manager instance role.
 * @param {ApiClient} api           The Deep Security API exports.
 * @param {String} displayName      The display name of the AWS connector.
 * @param {String} apiVersion       The API version to use.
 * @returns {Promise}               The promise contains the AWS connector object.
 */
exports.createAWSConnectorUsingInstanceRole = function(api, displayName, apiVersion){
    let apiInstance = new api.AWSConnectorsApi();
    let AWSConnector = new api.AWSConnector();

    // Set the AWS connector properties.
    AWSConnector.displayName = displayName;
    AWSConnector.useInstanceRole = true;

    return apiInstance.createAWSConnector(AWSConnector, apiVersion);
}

Java

View source

/**
    * Create an AWS connector using the manager instance role.
    * 
    * @param displayName       The name of the AWS connector to show in Deep Security
    * @param apiVersion         The version of the API to use.
    * @return                   Return the created AWS connector object.
    * @throws ApiException  Throw an exception if a problem occurs when creating a AWS connector on
    *                       Deep Security Manager.
    */
public static AWSConnector createAWSConnectorUsingInstanceRole(String displayName, String apiVersion)
        throws Exception {

    AwsConnectorsApi apiInstance = new AwsConnectorsApi();

    // Create an AWS connector object.
    AWSConnector AWSConnector = new AWSConnector();
    AWSConnector.setDisplayName(displayName);
    AWSConnector.setUseInstanceRole(true);

    // Add the AWS connector to Deep Security Manager.
    AWSConnector result = null;
    result = apiInstance.createAWSConnector(AWSConnector, apiVersion);

    return result;
}