Cortex XSOAR Deployment Checklist - Administrator Guide - 6.8 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR Administrator Guide
Product
Cortex XSOAR
Version
6.8
Creation date
2022-09-28
Last date published
2024-04-08
End_of_Life
EoL
Category
Administrator Guide
Abstract

Overview of the deployment process, including best practices for Cortex XSOAR installation and maintenance.

The Cortex XSOAR Deployment Checklist provides an overview of the deployment process, including best practices for installation and maintenance. Unless otherwise specified, instructions apply to on-premise deployments with BoltDB or Elasticsearch, as well as hosted deployments. Each section includes links to more extensive documentation.

Installation (On-Premise Deployments)

We recommend deploying both development and production environments. The following is an overview of the installation process, with links to detailed instructions.

Note

Multi-tenant deployments have separate requirements and configurations. See the Multi-Tenant Guide for more information.Multi-Tenant Deployments

Note

NOTE: To install Cortex XSOAR on a server without internet connectivity, see Install Cortex XSOAR Offline.

BoltDB

  1. Review the System Requirements and provision servers to at least the recommended minimums.

  2. Follow instructions for Single Server installation.

  3. Perform the Server Post-Installation Health Check.

Elasticsearch

  1. Review the Elasticsearch Overview and Elasticsearch Best Practices.

  2. Review the Elasticsearch System Requirements and provision to at least the recommended minimums.

  3. Follow instructions for Single Server Elasticsearch installation.

  4. Perform the Server Post-Installation Health Check.

Elasticsearch with High Availability

  1. Review the High Availability Overview and Elasticsearch Best Practices.

  2. Set up and configure the Elasticsearch cluster and ensure network connectivity between application servers and Elasticsearch.

  3. Verify the Elasticsearch cluster meets the minimum sizing requirements for Cortex XSOAR.

  4. Create a user or API key for Cortex XSOAR to authenticate with the appropriate permissions.

  5. Provision the Cortex XSOAR application servers, ensuring each application server meets the minimum system requirements.

  6. Create and mount the shared file system for the Cortex XSOAR application servers. Verify the shared file system meets the minimum requirements.

  7. Verify that latency between the application servers, Elasticsearch cluster, and shared file system is 100 ms or below. For optimal performance, 10 ms or below is recommended.

  8. Follow instructions for Single Server Elasticsearch installation.

  9. Migrate the shared directory if it is not mounted at /var/lib/demisto.

  10. (Recommended) - Install a load balancer.

    Set the following server configurations to the url of the load balancer under Settings → About → Troubleshooting

    Base URL

    External Hostname

  11. Install Additional App Servers

  12. Validate Additional App Servers

  13. Perform the Server Post-Installation Health Check.

Default Admin Account

When you install Cortex XSOAR for the first time, you are prompted for the default admin password. You should store this password securely for use in an emergency. If the default admin password is lost, the administrator password can be reset.

Note

The email for the admin user can be set as the distribution list for multiple administrators of the Cortex XSOAR system. This can be useful when configuring system notifications.

Authentication and Roles

After installation, one of your first steps is configuring user authentication and appropriate roles and permissions for your users.

There are three options for authentication to Cortex XSOAR.

Authentication Method

Details

SAML

SAML 2.0 is the recommended method to authenticate and authorize users to Cortex XSOAR, as it allows for multi-factor-authentication. We strongly recommended implementing MFA and the appropriate conditional access policies at the identity provider. View the SAML 2.0 video for more information.

Active Directory

Users can log in to Cortex XSOAR with their Active Directory username and passwords, and their permissions in Cortex XSOAR are set according to the groups and mapping set in Active Directory. View the Active Directory video for more information.

Local Users

If SAML or Active Directory are not available options, local users can be provisioned. Local users are not the recommended option.

Roles

We recommend setting up role-based access for users. You can use group memberships from SAML or Active Directory, or assign roles when creating local users.

Roles define permissions for users, including but not limited to:

The most common updates to the out-of-the-box Analyst Role when deploying a new system include:

  • Removing the permission to delete incidents.

  • Removing the permissions to install and contribute Marketplace content.

  • Configuring default dashboards, queries, and shifts.

Docker Hardening

Follow the Docker Hardening Guide and Docker Network Hardening Guide to efficiently and securely run Docker containers according to best practices.

Server Configurations

The following are recommended server configurations for new Cortex XSOAR deployments. If you have multiple application servers, each server configuration needs to be added to each Cortex XSOAR server.

Server Configuration

Description

instance.execute.external = true

Makes External Dynamic Lists (EDLs) or Export Indicators available via port 443 on the server.

ignore.default.in.playbooks = true

When configuring an integration instance, you can select Do not use by default to prevent commands from exceeding API quotas. The ignore.default.in.playbooks = true configuration enables the same option for playbooks.

playbook.willnotexecute.old.eval = false

Prevents repeated task checks in playbooks. Repeated task checks can impact performance in large playbooks with many tasks.

ui.summary.page.hide.empty.fields = false

Shows empty fields in the incident summary tab.

demisto.audits.purge = true

Enables automatic rolling of the audit logs.

demisto.audits.purge.retention = 365

Sets the retention period, in days, for the audit logs.

To add server configurations, go to Settings → About → Troubleshooting. Server configurations are added as key value pairs. After adding a server configuration, click Save to commit. Server configurations take effect immediately unless otherwise specified.

Note

Some server configurations are restricted for Hosted Service deployments. If you need to add a server configuration that is not allowed via the UI, open a support ticket specifying the server URL, server environment (development or production), and the requested server configuration.

Limit Workers for Searching

For performance optimization, we recommend limiting the number of workers used to search the database. This ensures that as system usage increases, analyst or playbook searches for incidents do not overburden server resources required for running playbooks.

To limit the number of workers, edit the /etc/demist.conf file and then restart Cortex XSOAR.

Note

For high availability deployments, the server configuration must be added to each application server.

Edit Config File to Limit Workers

  1. Create a backup of /etc/demisto.conf before making modifications.

  2. Add "workers.count.search":"3" to the file. Example:

    {
	"Server": {
		"HttpsPort": "443"
	},
	"db": {
		"index": {
			"entry": {
				"disable": true
			}
		}
	},
	"password": {
		"policy":{
			"default":{
				"Enabled": false
			}
		}
	},
	"workers.count.search": "3"
}

  3. Restart Cortex XSOAR.

    sudo systemctl restart demisto

System Diagnostics

The System Diagnostics page enables you to monitor and improve system performance and resilience. You can view the System Diagnostics page at Settings → About → System Diagnostics. System diagnostics thresholds can be customized for your deployment through server configurations, and you can also enable and disable email notifications and change the recipients.

Server Monitoring

We recommend setting up system monitoring using both Cortex XSOAR tools and independent monitoring tools not run on the Cortex XSOAR server. Monitoring tools should generate alerts for sustained CPU, sustained high memory usage, and high disk usage (operating system and Cortex XSOAR data disk).

In addition, the /workers/status API endpoint provides information about the number of available workers and running workers consumed by automations in playbooks. Workers are consumed as required. If the number of busy workers = available workers for extended periods of time, this could indicate an issue with a playbook or integration. The /workers/status API endpoint shows the tasks that are holding workers; this information can be used for troubleshooting.

Server Upgrades

To upgrade your server, download the latest version via the download link you received in your welcome email. If you have lost your download link, request a new one through the Palo Alto Support Portal.

You can subscribe to the release announcements via our Live Community to be notified when new versions are available. Notifications include a link to the release notes.

If you have engines deployed, upgrade deployed engines after upgrading the server. If the engine was deployed using the Shell installer, upgrading can be done via the UI from Settings → Engines.

Engines

Cortex XSOAR engines are installed in a remote network and allow communication between the remote network and the Cortex XSOAR server. You can run scripts and integration commands on an engine to offload work from the Cortex XSOAR server. Engines also act as a go-between, allowing connections to integrations that the server may not be able to access directly. For hosted service deployments, engines enable connectivity between the hosted Cortex XSOAR server and on-premise infrastructure.

You can deploy one or more engines depending on your requirements and the integration(s) you are connecting to. Please review the engine requirements and network requirements for engines.

Engine installers can be created via Settings → Engines. We recommend installing engines using the Shell script as the install method, if available for your operating system, as this enables you to later upgrade your engine from within the UI.

After updating your servers to a new version and/or build, you must upgrade your engine(s) as well. If the engine was deployed using the Shell installer, this can be done via the UI from Settings → Engines.

Cortex XSOAR Marketplace

The Cortex XSOAR Marketplace is the central location for installing, exchanging, contributing, and managing all of your content, including playbooks, integrations, automations, fields, layouts, and more.

The Marketplace allows you to:

  • Leverage content from the Cortex XSOAR community: Continuously extend Cortex XSOAR with proven use cases contributed by SecOps users and Cortex XSOAR partners.

  • Discover top rated, validated content: Identify the best premium and free content offerings recommended by your peers and validated by the world’s leading cybersecurity company. Discover how to increase automation with the tools you already have and browse through community best practices.

  • Solve your toughest security use cases: Deploy turn-key security workflows that span integrations, playbooks, dashboard layouts, and reports with a single click.

Updating Marketplace Content

When a Content Pack is available for update, you see a notification next to the Marketplace icon. You can update to the latest content version or to a specific version. All dependent Content Packs update automatically with the Content Pack. We recommend periodically reviewing your installed Marketplace packs for any available updates, and updating as required.

Integrations

Integrations are configured on the Settings > Integrations page. We recommend configuring an email integration during your initial set up. An email integration enables the server to send emails and can be used for system notifications and playbooks. The following are the most frequently used integrations for email:

Credentials

When applicable, use the Cortex XSOAR Credentials page at Settings → Integrations → Credentials to store credentials used for integrations. Credentials are stored encrypted in the database and can be updated on the Credentials page. Changes made on the Credentials page apply automatically to all integrations that are configured to use the credential.

Integrations that support credentials have an option to Switch to Credentials and allow you to pick the credential from the list.

Troubleshooting and Support

When creating a support ticket, include the Cortex XSOAR logs.

Change Log Level and Download Logs

  1. Go to Settings → About → Troubleshooting and set the log level to Debug.

  2. Reproduce the issue.

  3. Go back to Settings → About → Troubleshooting and download the logs.

  4. Attach the logs to the support ticket.

  5. Go back to Settings → About → Troubleshooting and change log level back to desired setting. The default level is Info.

Audit Logs

The audit trail displays a log of all administrative user interactions with Cortex XSOAR. The log is sorted by date and shows which users interacted with system objects and associated data and the details of these interactions.

The audit trail does not include actions performed in the War Room. These actions are documented only in the War Room.

You can search the audit trail log for user interactions based on free text. To view the audit trail, navigate to Settings → Users and Roles → Audit Trail. You also have the option to send the audit log to an external syslog service.

By default, audit logs are stored indefinitely. We recommend automatically purging the audit trail logs, by adding the demisto.audits.purge and demisto.audits.purge.retention server configurations, as listed in the ???.

Backups

Cortex XSOAR BoltDB deployments have an option for automated backups, configured at Settings → Advanced → Backups. By default, the backups are stored at /var/lib/demisto/backup, but should also be copied to a separate storage solution/server offline using appropriate enterprise backup software.

Cortex XSOAR Elasticsearch deployments use Elasticsearch snapshots, which can be configured through the Elasticsearch API.

Install Slack Content Pack

If your organization uses Slack, we recommend installing the Slack content pack. The Slack content pack enables you to send messages and notifications to your Slack team and integrates with Slack's services to execute create, read, update, and delete operations for employee lifecycle processes.

Integrations & Incidents Health Check

The Integrations and Incidents Health Check content pack enables users to review all of the failed integrations, incidents, and playbooks.

This pack is available from the Cortex XSOAR Marketplace and works in tandem with System Diagnostics to enable Cortex XSOAR Administrators to manage their deployments.

The Integrations and Incidents Health Check content pack includes out-of-the-box layouts, dashboards, an incident type, and incident fields. All of these are customizable to suit the needs of your organization.

You can configure the job on an hourly/daily/weekly basis to perform the health check. The job will run the checkup playbook that tests all enabled integrations and searches for open incidents with errors to get their status and retrieve error information.

Content Management in Cortex XSOAR

Cortex XSOAR provides three options for content management: manual, remote repositories and CI/CD. Custom content includes the following custom items and does not apply to content installed from marketplace packs.

  • Automations

  • Playbooks

  • Integrations

  • Classifiers

  • Mappers

  • Incident fields

  • Indicator fields

  • Evidence fields

  • Incident layouts

  • Incident types

  • Pre-processing rules

  • Indicator types

  • Reports

  • Dashboards

  • Widgets

Note

Configuration settings, such as integration instance configurations including URLs, usernames, passwords, etc., are not considered content and must be manually updated for each Cortex XSOAR environment.

In addition to remote repositories and CI/CD, you can also manually export custom content from one Cortex XSOAR server to another. In this case, you export either a single content item (download from the content item page) or all custom content (via Settings → About → Troubleshooting Export Custom Content) and then either upload the single item or import all custom content (via Settings → About → Troubleshooting Import Custom Content) on the destination machine. The community supported XSOAR - Simple Dev to Prod content pack enables you to create a custom content bundle with only selected items from the server’s custom content. If you are not using a remote repository or CI/CD, marketplace packs must be installed and maintained on each Cortex XSOAR environment and manually synced as needed.