Create a Broker VM Amazon Machine Image (AMI) - Administrator Guide - Cortex XDR - Cortex - Security Operations

Cortex XDR Pro Administrator Guide

Cortex XDR
Creation date
Last date published
Administrator Guide

After you download your Cortex XDR Broker VMDK image, you can convert the image to Amazon Web Services (AWS) AMI using the AWS CLI. The task below explains how to do this on Ubuntu Linux.

You need to set up an AWS VM Import role (vmimport) before you continue with the steps to convert the image as it is required for the import-image CLI command. You can use a different role, if the role vmimport doesn't exist or doesn't have the required permissions. For more information on setting up an AWS VM Import role and the permissions required, see Required service role.

To convert the image:

Create an IAM User with Proper Permissions

You need to log in using an AWS Identity and Access Management (IAM) user, where the permissions are defined in the IAM policy to use the virtual machine Import and export.

  1. Log in to the AWS IAM Console, and in the navigation pane, select Access ManagementUsersAdd Users.

  2. Select Access key - Programmatic access as the AWS credential type, and click Next: Permissions.

  3. Select Attach Existing Policies directlyCreate Policy,

  4. In the JSON tab, copy and paste the following syntax to define the policy:

    "Statement": [
    "Resource": ["arn:aws:s3:::mys3bucket","arn:aws:s3:::mys3bucket/*"]
    "Action": [
  5. Click Next until you can specify the Policy name, and then click Create Policy.

  6. Select the policy that you created above based on the syntax you added.

  7. Complete the user creation process.

  8. After confirmation that the user is created, record the following user information, which you will need later.

    • User name

    • Access key ID

    • Secret access key

Setup AWS CLI in Ubuntu 18

Install the AWS CLI and configure it with the IAM user that you created.

  1. Login to the server with admin privilege and install the AWS CLI.

    # sudo bash
    # apt install awscli
  2. Run the following command to configure the AWS CLI:

    # aws configure

    You need to specify the proper configurations for the following:

    • AWS Access Key ID—The Access key ID for the IAM user you created.

    • AWS Secret Access Key—The Secret access key for the IAM user you created.

    • Default region name—The Region where you've defined the IAM user you created.

    You are now ready to implement commands in the AWS CLI.

Create an AMI Image

To create an AMI image, you need to download Broker VM VMDK file from the Cortex XDR Web Console, import this file to your S3 bucket, and then convert the VMDK file in the S3 bucket into an AMI Image.

  1. In the Cortex XDR Web Console , select SettingsConfigurationsData BrokerBroker VMsAdd BrokerVMDK.

  2. Download the VMDK file, such as broker-vm-<broker-vm-version>.vmdk, to you ubuntu computer.

  3. Navigate and log in to your AWS account.

  4. In the AWS Console, navigate to ServicesStorageS3Buckets.

  5. In the S3 buckets page, + Create bucket to upload your Broker VM image to this bucket.

    Specify a unique name for the S3 bucket and use the default configurations.

  6. Upload the Broker VM VMDK you downloaded from Cortex XDR to the AWS S3 bucket.


    # aws s3 cp ~/<path/to/broker-vm-version.vmdk> s3://<your_bucket/broker-vm-version.vmdk>

  7. Prepare the following configurations files on your hard drive.

    • configuration.json

      1. Run the following command in Ubuntu:

        # vi configuration.json
      2. Copy and paste the following syntax into the json file.

        In S3Bucket, replace <your_bucket> with the Bucket Name and not its ARN Name. S3Key is the VMDK filename, which you should replace instead of <broker-vm-version.vmdk>.

        		"Description":"Cortex XDR Broker VM <version>",
    • trust-policy.json

      1. Run the following command in ubuntu:

        # vi trust-policy.json
      2. Copy and paste the following syntax into the json file.

           "Version": "2012-10-17",
           "Statement": [
                 "Effect": "Allow",
                 "Principal": { "Service": "" },
                 "Action": "sts:AssumeRole",
                 "Condition": {
                       "sts:Externalid": "vmimport"
    • role-policy.json

      1. Run the following command in Ubuntu:

        # vi role-policy.json
      2. Copy and paste the following syntax into the json file. Replace the <disk-image-file-bucket> and <export-bucket> with the correct bucket name. You can specify * to configure access to all your S3 buckets.

                 "Effect": "Allow",
                 "Action": [
                 "Resource": [
                 "Effect": "Allow",
                 "Action": [
                 "Resource": [
                 "Effect": "Allow",
                 "Action": [
                 "Resource": "*"
  8. Use the create-role command to create a role named vmimport and grant VM import and export access to the trust-policy.json file.

    # aws iam create-role --role-name vmimport --assume-role-policy-document "file://trust-policy.json"

  9. Use the put-role-policy command to attach the policy to the vmimport role created above.

    # aws iam put-role-policy --role-name vmimport --policy-name vmimport --policy-document "file:// role-policy.json"

  10. Create an AMI image from the VMDK file.


    # aws ec2 import-image --description "Cortex XDR Broker VM <Version>" --disk-containers "file://configuration.json"


    Creating an AMI image can take up to 60 minutes to complete.

    To track the progress, use the task id value from the output and run:

    # aws ec2 describe-import-image-tasks --import-task-ids import-ami-<task-id>

    Completed status output example:

    { "ImportImageTasks":[ { "...", "SnapshotDetails":[ { "Description":"Broker VM version", "DeviceName":"/dev/<name>", "DiskImageSize":2976817664.0, "Format":"VMDK", "SnapshotId":"snap-1234567890", "Status":"completed", "UserBucket":{ "S3Bucket":"broker-vm", "S3Key":"broker-vm-<version>.vmdk" } } ], "Status":"completed", "..." } ]}

    Once the task is complete, the AMI Image is ready for use.

  11. (Optional) After the AMI image has been created, you can define a new name for the image.

    Select ServicesEC2IMAGESAMIs and locate your AMI image using the task ID. Select the pencil icon to specify a new name.

Launch a Broker VM Instance in AWS EC2

You can launch the a Broker VM instance in AWS EC2 using the AMI Image created.

  1. To view the AMI image that you added, select ServicesEC2ImagesAMIs.

  2. Select EC2Instances, search for your AMI image, and Launch the file.

  3. In the Launch Instance Wizard define the instance according to your company requirements and Launch.

  4. (Optional) In the Instances page, locate your instance and use the pencil icon to rename the instance Name.

  5. Define HTTPS and SSH access to your instance.

    Right-click your instance, and select NetworkingChange Security Groups.

    In the Change Security Groups pop-up, select HTTPS to be able to access the Broker VM Web UI, and SSH to allow for remote access when troubleshooting. Make sure to allow these connections to the Broker VM from secure networks only.


    Assigning security groups can take up to 15 minutes.

  6. Verify the Broker VM has started correctly.

    Locate your instance, right-click, and select Instance SettingsGet Instance Screenshot.

    You are directed to your Broker VM console listing your Broker details.

Register the Broker VM

Registration of the Broker VM to Cortex XDR is performed from the Broker VM Web Console.

  1. Obtain a registration token from the Cortex XDR Web Console by selecting SettingsConfigurationsData BrokerBroker VMsAdd BrokerGenerate Token.

  2. Determine the IP Address of the EC2 instance and use it to open the Broker VM Web Console, such as https://<ip_address>.

  3. Complete the registration process by entering the token information.