Create an agent installation package ↗

To install the Cortex XDR agent on the endpoint for the first time, create an agent installation package. Review Where can I install the Cortex XDR agent for supported versions and operating systems.

To install the Cortex XDR agent software, you must use a valid installation package that exists in your Cortex XSIAM management console. If you delete an installation package, new agents installed from this package are not able to register to Cortex XSIAM, however, existing agents may re-register using the Agent ID generated by the installation package.

From Cortex XSIAM, select Inventory → Endpoints → Agent Installations.
Click Create to create a new installer.
Select the Package:
- Standalone: Use for fresh installations and to upgrade agents on a registered endpoint that is connected to Cortex XSIAM.
- (Linux only) Kubernetes: Use for fresh installations and upgrades of Cortex XDR agents running on Kubernetes clusters. #guidelines-for-kubernetes-installer
- Helm: Use this package for fresh installations and upgrades of Cortex XDR agents running on Kubernetes clusters.
- CaaS: Create the Cortex XSIAM container-embedded agent Dockerfile. For installer instructions and guidelines see CaaS workloads.
- Amazon ECS EC2: Create an installation package to deploy the agent on Amazon ECS clusters with EC2 launch types. Guidelines for Amazon ECS EC2 installer
- Serverless: Create an installation package for serverless function to deploy to your runtime platform. #guidelines-for-serverless-installer

Guidelines for Kubernetes installer

Installer configuration:

Settings for the Kubernetes installer cannot be changed after you create the installation package.
For Version, select the desired Cortex XDR agent version.

If the option Always deploy the latest agent version is displayed, do not select it.
For the Agent Daemonset Namespace, it is recommended to use the default cortex-xdr namespace.
For a more granular deployment, enter any labels or selectors in the Node Selector. The Cortex XDR agent will be deployed only on these nodes.
To configure the Cortex XDR agent to communicate through a proxy, enter either the IP address and port number or enter the FQDN and port number. When you enter the FQDN, you can use both lowercase and uppercase letters. Avoid using special characters or spaces. Use commas to separate multiple addresses.

Guidelines for Amazon ECS EC2 installer

When you create a Cortex XDR agent installation package for Linux on AWS ECS EC2 clusters, the package downloads as a JSON task definition file that you deploy to your cluster. Once running, the agent provides the same protection as a standard Cortex XDR agent for Linux.

Cortex issues a license for every node running the agent and revokes it when you remove the agent or delete the node. The Cortex management console identifies processes running within containers, including the container name, ID, and image.

Prerequisites

Requirement	Description
System Architecture	<ul><li>Supports X86_64 and ARM64 architectures. Hybrid clusters and Windows are unsupported.</li><li>Cortex XDR agent 9.1 or later.</li></ul>
AWS IAM Roles	<p>The following roles and policies are required for communication and logging:</p><ul><li>ecsTaskExecutionRole: Required to pull images and send logs to CloudWatch.</li><li>AmazonECSTaskExecutionRolePolicy: Grants the ECS agent permission to act for your task. This includes pulling container images from Amazon ECR and sending logs to Amazon CloudWatch.</li><li>CloudWatchLogsFullAccess: Recommended for viewing container standard output.</li><li>ecsInstanceRole: Grants the ECS agent on the EC2 instance permission to communicate with the ECS service.</li><li>AWSServiceRoleForECS: Allows ECS to manage resources, such as load balancers and container instances.</li></ul>

Requirement

Description

System Architecture

<ul><li>Supports X86_64 and ARM64 architectures. Hybrid clusters and Windows are unsupported.</li><li>Cortex XDR agent 9.1 or later.</li></ul>

AWS IAM Roles

<p>The following roles and policies are required for communication and logging:</p><ul><li>ecsTaskExecutionRole: Required to pull images and send logs to CloudWatch.</li><li>AmazonECSTaskExecutionRolePolicy: Grants the ECS agent permission to act for your task. This includes pulling container images from Amazon ECR and sending logs to Amazon CloudWatch.</li><li>CloudWatchLogsFullAccess: Recommended for viewing container standard output.</li><li>ecsInstanceRole: Grants the ECS agent on the EC2 instance permission to communicate with the ECS service.</li><li>AWSServiceRoleForECS: Allows ECS to manage resources, such as load balancers and container instances.</li></ul>

Installer configuration

For Version, select Cortex XDR agent 9.1 or later.
For Family, enter the AWS task definition name.
For Cluster, enter the ECS cluster name.
Download the installer as a valid JSON task definition file. Use it to deploy the agent in AWS ECS.

Deploy the agent task definition and service

In the AWS ECS console, go to Task Definitions.
Select Create new task definition with JSON.
Paste the JSON from the Cortex XDR installer. Save the new revision.
Go to your ECS cluster and select the Services tab.
Select Create.
In Deployment Configuration, set Launch type to EC2.
Important: Select Daemon as the service type. This runs one Cortex XDR agent task on every container instance in the cluster.
Complete the creation process. AWS runs a CloudFormation stack in the background to deploy the service.

When the service is stable, verify the deployment:

In the Cortex management console, check the All Endpoints table. The endpoint type appears as Amazon ECS EC2.
The Protection Status column shows Protected.

Guidelines for serverless installer

Installer configuration:

For Version, select the required Cortex agent version.
For Cloud Provider, AWS is configured for this release.
For Runtime, select one of the environments:
- node.js
- python
For Deployment Type, select the type:
- Embedded
- AWS Layers
If node.js and the deployment type, AWS Layers are selected, select one of the Modules:
- ECMAScript
- CommonJS
For Embed Default Profile From, select from the profile rules configured for serverless functions.

The profile will be applied if the security policy cannot be retrieved in real-time.

The package is created and ready to be deployed.

Deploy the package to your runtime environment

From Cortex XSIAM, go to Inventory+Endpoints+Installations and from the Agent Installations page, right click and select View Installation Instructions.
Depending on the runtime environment, the instructions are slightly different.
- Agent installation package for embedded python:
  1. Download the serverless agent bundle.
  2. Log in to your AWS Management Console.
  3. Navigate to the AWS Lambda service, and unzip the serverless agent bundle in the main folder.
  4. Add the serverless agent to the function by importing the Cortex library and wrapping the function’s handler.
    
    The Cortex serverless library must be imported after other libraries to activate the hooks that enable auditing.
- Agent installation package for embedded node.js:
  1. Download the serverless agent bundle.
  2. Log in to your AWS Management Console.
  3. Navigate to the AWS Lambda service, and unzip the serverless agent bundle in the main folder.
  4. Add the serverless agent to the function by importing the Cortex library and wrapping the function’s handler.
- Agent installation package for node.js using AWS Layers in ECMAScript (JavaScript) runtime/Agent installation package for node.js in AWS Lambda using AWS Layers with CommonJS module format:
  1. Download the serverless agent bundle.
  2. Log in to your AWS Management Console.
  3. Navigate to the AWS Lambda service, and upload the layer and add it to the function’s configuration.
  4. Save the current Lamba handler setting in the ORIGINAL_HANDLER environment variable.
  5. Change the Lambda handler setting to cortex.handler.
- Agent installation package for python using AWS Layers in python runtime/Agent installation package for python in AWS Lambda using AWS Layers with python module format:
  1. Download the serverless agent bundle.
  2. Log in to your AWS Management Console.
  3. Create a new AWS layer with the downloaded bundle, copy the new layer ARN value, and add the new layer using the copied ARN.
  4. Save the current Lamba handler setting in the ORIGINAL_HANDLER environment variable.
  5. Change the Lambda handler setting to cortex.handler.
In Parameters, enter a unique name and an optional description to identify the installation package.

The package name can contain letters, numbers, hyphens, underscores, commas, and spaces, and should not exceed 100 characters.
In Metadata, define the appropriate settings for the package type, and then click Create.
Download your installation package.

When the status of the package shows Completed, right-click the package, and click Download.

For the Kubernetes Connect instructions see Onboard the Kubernetes Connector