SecOps Automation and Response—

Cortex XSOAR
D E P LOY M E N T G U I D E

AUGUST 2021
 Table of Contents

Table of Contents
Preface..................................................................................................................................................................... 1

Related Guides........................................................................................................................................................ 3
Other Resources.................................................................................................................................................................................... 3

Purpose of This Guide...........................................................................................................................................4

Objectives............................................................................................................................................................................................... 4

Audience................................................................................................................................................................................................. 4

Assumptions and Prerequisites.......................................................................................................................... 5

Deploying Cortex XSOAR......................................................................................................................................6

Installing the Cortex XSOAR Application.........................................................................................................................................6

Configuring Your Cortex XSOAR Deployment................................................................................................................................ 11

Creating and Running a Playbook.................................................................................................................... 18

Creating an Example Playbook......................................................................................................................................................... 18

Running the Playbook and Managing an Incident....................................................................................................................... 35

Palo Alto Networks

 Preface

Preface

GUIDE TYPES
Overview guides provide high-level introductions to technologies or concepts.

Reference architecture guides provide an architectural overview for using Palo Alto Networks® technologies
to provide visibility, control, and protection to applications built in a specific environment. These guides
are required reading prior to using their companion deployment guides.

Deployment guides provide decision criteria for deployment scenarios, as well as procedures for combining
Palo Alto Networks technologies with third-party technologies in an integrated design.

DOCUMENT CONVENTIONS

Notes provide additional information.

Cautions warn about possible data loss, hardware damage, or compromise of security.

Blue text indicates a configuration variable for which you need to substitute the correct value for your
environment.

In the IP box, enter 10.5.0.4/24, and then click OK.

Bold text denotes:

• Command-line commands.

# show device-group branch-offices

• User-interface elements.

In the Interface Type list, choose Layer 3.

• Navigational paths.

Navigate to Network > Virtual Routers.

• A value to be entered.

Enter the password admin.

Palo Alto Networks 1

 Preface

Italic text denotes the introduction of important terminology.

An external dynamic list is a file hosted on an external web server so that the firewall can import objects.

Highlighted text denotes emphasis.

Total valid entries: 755

ABOUT PROCEDURES
These guides sometimes describe other companies’ products. Although steps and screen-shots were
up-to-date at the time of publication, those companies might have since changed their user interface,
processes, or requirements.

GETTING THE LATEST VERSION OF GUIDES

We continually update reference architecture and deployment guides. You can access the latest version of
this and all guides at this location:

https://www.paloaltonetworks.com/referencearchitectures

WHAT’S NEW IN THIS RELEASE

Palo Alto Networks made the following changes since the last version of this guide:

• Changed the version of Cortex™ XSOAR to version 6.2.0

• Changed the version of Ubuntu server to version 20.04

• Changed the updating of content packs to use bulk updating

• Changed initial running of playbooks to use the playbook debugger

• Changed phrasing, terminology, and diagrams for clarity

Palo Alto Networks 2

 Related Guides

Related Guides
•

Cortex XSOAR is a security orchestration, automation, and response (SOAR) solution that manages alerts,
standardizes processes, and automates responses.

The SecOps Automation and Response—Cortex XSOAR suite of guides details how to use Cortex XSOAR, from
understanding its concepts and user interface through deployment and using playbooks to implement a
structured and automated incident response.

SecOps: Reference Architecture Guide—Provides solutions for prevention, detection,

investigation, and response to help security-operations teams prevent threats and
efficiently manage alerts.

SecOps Automation and Response—Cortex XSOAR: Concepts Guide—Describes concepts

and terminology essential to using Cortex XSOAR in order to automate responses to
security incidents.

SecOps Automation and Response—Cortex XSOAR: User Interface Guide—Describes user

interface components that are important when you use the operations guides.

SecOps Automation and Response—Cortex XSOAR: Deployment Guide—Provides detailed,

step-by-step instructions for deploying Cortex XSOAR, including post-installation tasks
such as the required integrations to external systems.

SecOps Automation and Response—Cortex XSOAR Phishing Investigation: Operations

Guide—Suggests a method for automatically investigating and responding to an email-
based phishing incident.

OTHER RESOURCES
Cortex XSOAR developer hub (https://xsoar.pan.dev)—Includes documentation and reference materials
about all Cortex XSOAR components.

Cortex XSOAR Administrator’s Guide—Serves as a comprehensive product reference and includes

information about the numerous supported methods for installing Cortex XSOAR.

Palo Alto Networks 3

 Purpose of This Guide

Purpose of This Guide

Cortex XSOAR is a security orchestration, automation, and response (SOAR) solution that manages
alerts, standardizes processes, and automates responses. This guide provides detailed steps for the
recommended installation method and associated post-installation tasks. It also provides an introduction
to writing and running playbooks. If you need to perform a more complex installation, the Cortex XSOAR
Administrator’s Guide serves as a general reference that includes information on the numerous supported
methods for installing Cortex XSOAR.

This deployment guide:

• Requires that you first read the SecOps Automation and Response‒Cortex XSOAR: Concepts Guide. The
reference architecture guide provides architectural guidance for using Cortex XSOAR to automate
the response to security incidents.

• Provides step-by-step details for deploying Cortex XSOAR.

• Provides step-by-step details for required post-installation tasks, including integrations with
external systems.

• Provides a step-by-step example configuration for a simple Cortex XSOAR playbook.

OBJECTIVES
Completing the procedures in this guide, you can successfully deploy Cortex XSOAR on Ubuntu Linux. The
main objectives are to:

• Install Cortex XSOAR.

• Complete post-installation tasks required for proper operation.

• Complete optional post-installation tasks that are relevant to your environment.

AUDIENCE
This deployment guide is for technical readers including solution architects, security engineers, and
security support staff, who want to orchestrate and automate the prevention, investigation, and response
to security threats. It assumes the reader is familiar with the basic concepts of threat prevention,
networking, and security operations, as well as possessing a basic understanding of automation, machine
learning, and analytics.

Palo Alto Networks 4

 Assumptions and Prerequisites

Assumptions and Prerequisites

This guide assumes you are deploying Cortex XSOAR on Ubuntu Server.

System requirements:

• An Ubuntu Server 20.04 instance that will host Cortex XSOAR.

• Your server meets the Cortex XSOAR minimum hardware requirements for a production
environment:

◦ CPU: 16 CPU cores

◦ Memory: 32GB RAM

◦ Storage: 1TB SSD

Palo Alto Networks Cortex XSOAR:

• The tested Cortex XSOAR version used in this deployment guide is 6.2.0.

Palo Alto Networks licensing:

• Your organization has either a Cortex XSOAR or Cortex XSOAR Threat Intel Management license.

Palo Alto Networks 5

 Deploying Cortex XSOAR

Deploying Cortex XSOAR

In this section, you install Cortex XSOAR on your Ubuntu 18.04 server. You can install Cortex XSOAR on a
virtual machine, a bare metal server, or a cloud instance. In this example, you install Cortex XSOAR as a
guest on a VMWare ESXi 6.7 server with the following attributes:

• You have installed Ubuntu from the ISO image downloaded from:
https://releases.ubuntu.com/20.04/ubuntu-20.04.2-live-server-amd64.iso

• Your Ubuntu server instance has:

◦ A static IP address.

◦ Its hostname added to your organization’s DNS. In this guide, you use xsoar.example.com.

◦ Access to the internet.

◦ The latest updates applied.

◦ A SSH server enabled for remote command-line access.

◦ A Python interpreter (normally installed as part of the default Ubuntu installation process).

Procedures

Installing the Cortex XSOAR Application

1.1 Run the Cortex XSOAR Installer

1.2 Apply a License to Cortex XSOAR

1.3 Update the Cortex XSOAR Default Content Packs

1.1 Run the Cortex XSOAR Installer

When super-user privileges are required, use the sudo command.

Step 1: Download the Cortex XSOAR installer. You should have an email from Cortex Customer Success
Bot (cortex-cs-bot@paloaltonetworks.com) that includes a specific download link for your organization.
If you do not have a Cortex XSOAR license, you can request download access to the Cortex XSOAR
Community Edition by filling out the request form at https://start.paloaltonetworks.com/sign-up-for-
community-edition.html.

Palo Alto Networks 6

 Deploying Cortex XSOAR

Step 2: After you obtain the Cortex XSOAR installer file, place it in the /tmp directory on the Ubuntu
server.
bash-3.2$ scp demistoserver-6.2-1321594.sh xsoar_admin@xsoar.example.com:/tmp/
xsoar_admin@xsoar.example.com’s password:
demistoserver-6.2-1321594.sh 100% 854MB 112.7MB/s 00:07

Step 3: From the /tmp directory on the Ubuntu server, enable execute permissions for the Cortex XSOAR
installer script.
xsoar_admin@xsoar:/tmp$ chmod +x demistoserver-6.2-1321594.sh

Step 4: The Cortex XSOAR installer script must have execute permissions. Verify permissions by
examining the output of the ls -l command. You should see an “x” in the permissions flags.
xsoar_admin@xsoar:/tmp$ ls -l
-rwxrwxr-x 1 xsoar_admin xsoar_admin 895587706 Jul 21 16:05
demistoserver-6.2-1321594.sh

Step 5: Run the Cortex XSOAR installer script. If prompted, enter your password. The Cortex XSOAR
server version appears. In this example, the version is 6.2.0.
xsoar_admin@xsoar:/tmp$ sudo ./demistoserver-6.2-1321594.sh
[sudo] password for xsoar_admin:
Verifying archive integrity... All good.
Uncompressing Cortex XSOAR Server Version 6.2-1321594 (6.2.0) 100%
Log file: /tmp/demisto_install.log

<Content deleted for brevity>

The product is subject to the Palo Alto Networks End User License Agreement.
Link: www.paloaltonetworks.com/legal/eula
eula (END)

Step 6: Press the q key to exit the End User License Agreement (EULA) screen.

Step 7: Accept the EULA by entering yes at the prompt.

Do you accept the terms of the End User License Agreement? [yes no] yes

The console shows various packages being installed and then prompts you for configuration input.

Step 8: Accept the default HTTPS port of 443 by pressing ENTER.

Enter server HTTPS port: (default: ‘443’)

Palo Alto Networks 7

 Deploying Cortex XSOAR

Step 9: Press ENTER. This accepts the default answer of no to using an elasticsearch database.
Is Cortex XSOAR connecting to an elasticsearch database? [yes no] (default: 'no')

Step 10: Accept the administrative username of admin by pressing ENTER.

Enter name for admin user: (default: ‘admin’)

Step 11: Enter a password for the admin user, and if the configuration settings are correct, enter yes.
Enter password for user ‘admin’: **********
Verify password: **********
Server (Secure) Web Port: 443.
Admin user name: `admin`
Are these configurations correct? [yes no] yes

The installer shows the status of pulling various Docker images and updating Git.

Step 12: When installation is complete, you are prompted to start the Cortex XSOAR server. When
prompted to start the server, enter yes.
Start the server? [yes no] yes

Step 13: Verify that the Cortex XSOAR server starts and that the installation finishes successfully.
Enabling Cortex XSOAR service...
Cortex XSOAR service enabled successfully.
Starting Cortex XSOAR server... Cortex XSOAR server started at
https://10.48.54.23:443 https://172.17.0.1:443
Finished Successfully.

1.2 Apply a License to Cortex XSOAR

This procedure assumes you have received an entitlement email from Cortex Customer Success Bot
(cortex-cs-bot@paloaltonetworks.com) and have saved the attached license file locally on your computer
(example: DemistoLicense12345abc67.lic).

Step 1: Log into the Cortex XSOAR portal (example: https://xsoar.example.com) with username admin
and the password you created in Procedure 1.1.

Step 2: Accept the SSL certificate warning.

Note

By default, the system uses a self-signed certificate. In a later procedure, you

install a trusted SSL certificate.

Palo Alto Networks 8

 Deploying Cortex XSOAR

When you log in for the first time, the Missing License window appears.

Step 3: In the Missing License window, click Drop license file here.

Step 4: Browse to the Cortex XSOAR license file (example: DemistoLicense14562fe6cb.lic).

Note

The Cortex XSOAR license applies when you upload the license file; however,
there are no confirmation or status messages.

Step 5: To verify you successfully applied the license to Cortex XSOAR, in your browser, go to https://
xsoar.example.com/#/settings/license and ensure that the customer name and license expiration date are
correct.

Palo Alto Networks 9

 Deploying Cortex XSOAR

1.3 Update the Cortex XSOAR Default Content Packs

Palo Alto Networks and their partners periodically update content packs with new features and fixes. In
this procedure, you update the content packs that come pre-installed with Cortex XSOAR. You should
periodically apply available updates for any installed content packs.

Step 1: Log into the Cortex XSOAR portal (example: https://xsoar.example.com).

Step 2: In the navigation pane, click Marketplace.

Step 3: On the Installed Content Packs tab, click the drop-down link next to Show, and then choose
Update available.

The Content Packs Library pane shows the content packs for which an update is available. You can click a
content pack name in order to view its details, such as its dependencies and version history.

Palo Alto Networks 10

 Deploying Cortex XSOAR

Step 4: Select all content packs in the list by clicking Sort by ABC, and then click Update.

Step 5: In the Update Content Packs dialog box, click Update.

Procedures

Configuring Your Cortex XSOAR Deployment

2.1 Configure the Cortex XSOAR Fully Qualified Domain Name

2.2 Install a Trusted SSL Certificate on the Cortex XSOAR Server

2.3 Install the EWS Mail Sender Content Pack

2.4 Configure the EWS Mail Sender Integration

2.5 Configure System Notifications to Use EWS Mail Sender

2.6 Create a User Account

Palo Alto Networks 11

 Deploying Cortex XSOAR

2.1 Configure the Cortex XSOAR Fully Qualified Domain Name

End users are provided a URL so that they can enter input through their web browser. This requires that
you configure a fully qualified domain name (FQDN) in the Cortex XSOAR settings.

This procedure assumes a FQDN has been created for your Cortex XSOAR server and added to your
organization’s DNS server.

Step 1: Log into the Cortex XSOAR portal (example: https://xsoar.example.com).

Step 2: In the navigation pane, click Settings.

Step 3: In Settings > About > Troubleshooting, in the External Host Name box, enter the FQDN for your
Cortex XSOAR deployment (example: xsoar.example.com), and then click Save.

2.2 Install a Trusted SSL Certificate on the Cortex XSOAR Server

The Cortex XSOAR installation process automatically installs a self-signed SSL certificate. To increase
security, you should install a trusted SSL certificate from your organization. In this procedure, you install
a trusted SSL certificate on the Cortex XSOAR server and require two files. The first file is composed of the
full certificate chain, with the server certificate at the top followed by any intermediate certificates. The
second file is the server private key file.

Palo Alto Networks 12

 Deploying Cortex XSOAR

This procedure assumes you have a valid server certificate and private key file.

Step 1: Use secure copy protocol (SCP) to transfer the trusted certificate and key files to the /tmp directory
on the Cortex XSOAR server.
bash-3.2$ scp fullchain.pem xsoar_admin@xsoar.example.com:/tmp/fullchain.pem
xsoar_admin@xsoar.example.com’s password:
fullchain.pem 100% 3578 62.0KB/s 00:00
bash-3.2$ scp privkey.pem xsoar_admin@xsoar.example.com:/tmp/privkey.pem
xsoar_admin@xsoar.example.com’s password:
privkey.pem 100% 1708 34.0KB/s 00:00

Step 2: Back up the self-signed server certificate and private key files to xsoar_admin’s home directory.
xsoar_admin@xsoar:~$ sudo cp /usr/local/demisto/cert.pem ~/self_signed_cert.pem
xsoar_admin@xsoar:~$ sudo cp /usr/local/demisto/cert.key ~/self_signed_key.key

Step 3: Copy the trusted certificate file from the /tmp directory, using sudo to overwrite the current
self-signed server certificate file.
xsoar_admin@xsoar:~$ sudo cp /tmp/fullchain.pem /usr/local/demisto/cert.pem

Step 4: Copy the trusted private key file from the /tmp directory, using sudo to overwrite the current
self-signed server key file.
xsoar_admin@xsoar:~$ sudo cp /tmp/privkey.pem /usr/local/demisto/cert.key

Step 5: Restart the Cortex XSOAR server.

xsoar_admin@xsoar:~$ sudo reboot

Step 6: Verify that the certificates have taken effect. When you log on to the portal (example: https://
xsoar.example.com), you should no longer see the certificate error message.

2.3 Install the EWS Mail Sender Content Pack

This procedure installs the EWS Mail Sender content pack. This pack enables Cortex XSOAR to send email
messages.

Step 1: Log into the Cortex XSOAR portal (example: https://xsoar.example.com).

Step 2: In the navigation pane, click Marketplace.

Step 3: On the Browse tab, in the Search in list, choose Content Packs.

Step 4: In the search box, enter EWS Mail Sender.

Palo Alto Networks 13

 Deploying Cortex XSOAR

Step 5: In the results pane, click EWS Mail Sender.

Step 6: On the Marketplace > EWS Mail Sender content pack page, click Install.

Step 7: In the cart pane, click Install.

Step 8: After Cortex XSOAR successfully installs the content pack, click Refresh content.

2.4 Configure the EWS Mail Sender Integration

In this procedure, you create an instance of the EWS Mail Sender integration. This integration is required
for Cortex XSOAR to send and receive email. These emails are typically for sending notifications or
requesting task input.

This procedure assumes you have access to an Exchange Web Services (EWS) instance and an active email
account.

Step 1: Log into the Cortex XSOAR portal (example: https://xsoar.example.com).

Step 2: In the navigation pane, click Settings.

Step 3: In Integrations > Servers & Services, in the Search integration box, enter EWS Mail Sender.

Note

If you do not see an entry for EWS Mail Sender, click the refresh button to force
your web browser to update the page.

Step 4: Click Add instance.

Step 5: In the Name box, enter EWS Mail Sender.

Step 6: In the Exchange URL or Server IP address box, enter https://outlook.office365.com/EWS/

Exchange.asmx/.

Step 7: In the Authentication: Email address (for Office 365) box, enter xsoar@example.com.

Step 8: In the Password box, enter the password for xsoar@example.com.

Palo Alto Networks 14

 Deploying Cortex XSOAR

Step 9: In the Server Version box, enter 2016.

Step 10: In the Authentication Type box, enter Basic.

Step 11: In the Sender Mailbox box, enter xsoar@example.com, and then click Test.

Step 12: Verify that you receive a Success message, and then click Save & exit.

2.5 Configure System Notifications to Use EWS Mail Sender

If you use multiple integrations that provide access to external email systems, you must specify which
integration instance the system should use to send email notifications.

Step 1: Log into the XSOAR portal (example: https://xsoar.example.com).

Step 2: In the navigation pane, click Settings.

Step 3: In About > Troubleshooting> Server Configuration, click Add Server Configuration.

Step 4: In the Key box, enter server.notification.using.send-mail.

Step 5: In the Value box, enter EWS Mail Sender, and then click Save.

Palo Alto Networks 15

 Deploying Cortex XSOAR

2.6 Create a User Account

Cortex XSOAR uses role-based access control (RBAC) for controlling access. You should create accounts
for each of the users that access Cortex XSOAR, allowing only the access necessary to fulfill their duties.
Cortex XSOAR uses roles to group access permissions applied to each user. In this procedure you create a
user named Brian assigned to the analyst role.

As a Cortex XSOAR administrator, you create a new user by generating an invitation. Cortex XSOAR emails
an invitation to the user and prompts the user to input a password.

Note

If you do not have Cortex XSOAR configured to send email, you can
alternatively access the invitation link from the Settings > Users and Roles >
Invites screen. You can then copy the link and deliver it to the end user
through another mechanism.
Example user-specific invitation link:
https://xsoar.example.com/invite/3e6495b6-f25f-4151-8485-40f9b0104d9a/
access

Step 1: Log into the Cortex XSOAR portal (example: https://xsoar.example.com).

Step 2: In the navigation pane, click Settings.

Step 3: In Users and Roles > Users, click Invite User.

Step 4: In the Invite User dialog box, in the Email box, enter the user’s email address (example: brian@
example.com).

Palo Alto Networks 16

 Deploying Cortex XSOAR

Step 5: In the Roles list, select the role you want to assign this user (example: Analyst).

Step 6: Click the Invite button. XSOAR emails an invitation to the user.

When the user clicks the Join Now link in the email and selects a password, the account is created.

Palo Alto Networks 17

 Creating and Running a Playbook

Creating and Running a Playbook

Procedures

Creating an Example Playbook

3.1 Create the “Resolve IP to Hostname” Playbook

3.2 Create “Get the IP Address” Task

3.3 Create the “IP to Hostname Lookup” Task

3.4 Create the “Is the Hostname the Same as the IP Address?” Task

3.5 Create the “Mark as Note - Name Resolution Failed” Task

3.6 Create the “Mark as Note - Name Resolution Successful” Task

3.7 Create a “Done” Task

This playbook uses automation to determine if Cortex XSOAR can resolve a hostname from an IP address.
The purpose of this playbook is to provide a working example that includes a variety of task types and
does not require any integrations to external systems.

Figure 1 Resolve IP To Hostname playbook

Palo Alto Networks 18

 Creating and Running a Playbook

3.1 Create the “Resolve IP to Hostname” Playbook

In this procedure, you create a playbook. Later, in Procedure 4.1 and Procedure 4.4, this guide provides
two options to run the playbook.

Step 1: In Cortex XSOAR, in the navigation pane, click Playbooks.

Step 2: Click New Playbook.

Step 3: In the New Playbook dialog box, in the Playbook name box, enter Resolve IP to Hostname, and
then click the Save button. A playbook workspace with a Playbook Triggered section-header task appears.

Note

The playbook workspace provides two save options:

Use Save Playbook to save the playbook with no audit trail.
Use Save version for current Playbook to add a message to the audit trail.

Step 4: If the Task Library dialog box obscures your view of the playbook workspace, then click x to close
the dialog box.

3.2 Create “Get the IP Address” Task

To gather analyst input for your playbook, you use a data collection task. When you create the task,
you configure a survey with one or more questions. By default, data collection tasks use all configured
communication methods (example: email or slack) to communicate with the Cortex XSOAR user that you
specify. In this example, you configure the task to communicate with the Cortex XSOAR user through the
workplan.

In this procedure, you do not perform any checks to ensure that the response is a valid IPv4 address. As a
best practice, in a production playbook you should include input validation.

Palo Alto Networks 19

 Creating and Running a Playbook

After you have run this data collection task, Cortex XSOAR adds Cortex XSOAR Data Collection context data
to the incident.

Step 1: Hover over the Playbook Triggered section-header task egress node. When the hand changes to a
crosshair, click-and-drag the task connector line to the playbook workspace, and then release to create an
Untitled Task below. The Edit Task dialog box appears.

Step 2: Select Data Collection.

Step 3: In the Task Name box, enter Get the IP address.

Step 4: In the Ask by section, click Email.

Step 5: In the dialog box, clear Email, and then click Done.

Palo Alto Networks 20

 Creating and Running a Playbook

Step 6: In the Message box, enter Enter an IP address to resolve..

Step 7: On the Questions tab, in the Web Survey Title box, enter Cortex XSOAR Data Collection.

Step 8: In the Short Description box, enter Cortex XSOAR investigates whether an IP address you provide
can be resolved to a hostname.

Step 9: In the Question box, enter What is an IP address that you want to resolve to a hostname?

Step 10: In the Answer Type list, choose Short text.

Palo Alto Networks 21

 Creating and Running a Playbook

Step 11: In the Placeholder box, enter 1.1.1.1, and then click OK.

Step 12: Verify that the task is now in your playbook.

Palo Alto Networks 22

 Creating and Running a Playbook

3.3 Create the “IP to Hostname Lookup” Task

In this procedure, you configure an automation task to perform an IP address to hostname resolution.

This task uses the IPToHost automation script, which uses the Cortex XSOAR Data Collection.Answers
context data as an input.

This automation script does not require any integrations to external systems.

After you have run this automation script, Cortex XSOAR adds Endpoint context data to the incident. If the
hostname resolution is successful, Cortex XSOAR sets the Endpoint.Hostname value to the hostname.

Otherwise, Cortex XSOAR sets the Endpoint.Hostname value to the IP address.

Step 1: From the Get the IP address task egress node, drag the task connector line to the playbook
workspace, and then release to create an untitled task below. The Edit Task dialog box appears.

Palo Alto Networks 23

 Creating and Running a Playbook

Step 2: In the Task Name box, enter IP to hostname lookup.

Step 3: In the Choose Automation section, click the down arrow. The search dialog box opens.

Step 4: In the search box, enter IPToHost and then choose IPToHost. The task fields update.

Step 5: In the ip box, click the {} button. The Select Source for IP dialog box appears.

Step 6: In the search box, enter Cortex XSOAR Data Collection.

Step 7: In the Cortex XSOAR Data Collection.Answers section, click 0, and then click Close.

Palo Alto Networks 24

 Creating and Running a Playbook

Step 8: Verify that the ip box is now correctly populated with ${Cortex XSOAR Data Collection.
Answers.0}, and then click OK.

Step 9: Verify that the task is now in your playbook.

3.4 Create the “Is the Hostname the Same as the IP Address?” Task

In this procedure, you perform a check to see if the IP address to hostname resolution that Cortex XSOAR
performed in Procedure 3.3 was successful. Your playbook executes different branches depending on the
results of the check.

If the hostname resolution failed, then Cortex XSOAR sets the Endpoint.Hostname context data value
to be the same as the original IP address that you provided as a task input. If the hostname resolution

Palo Alto Networks 25

 Creating and Running a Playbook

succeeded, then Cortex XSOAR sets the Endpoint.Hostname context data value to be the resolved hostname.

In both cases, Cortex XSOAR also sets the Endpoint.IP context data value to be the same as the original IP
address that you provided as input.

To perform the check, you need to create a conditional statement that compares the Endpoint.Hostname
context data value with the Endpoint.IP context data value. If the values are the same, then the hostname
resolution has failed.

Step 1: From the IP to hostname lookup task egress node, drag the task connector line to the playbook
workspace, and then release to create an untitled task below. The Edit Task dialog box appears.

Step 2: Select Conditional.

Step 3: In the Task Name box, enter Is the hostname the same as the IP address?

In this conditional task, you use a single conditional statement.

Step 4: In the left-side box, click the {} button. The Select Source For dialog box appears.

Step 5: In the search box, enter Endpoint.Hostname.

Palo Alto Networks 26

 Creating and Running a Playbook

Step 6: In the Endpoint section, click Hostname, and then click Close.

By default, the comparison uses the Equals comparison operator.

Step 7: Under the right-side box, click As value, and then choose From previous tasks.

Step 8: In the right-side box, click the {} button. The Select Source For dialog box appears.

Step 9: In the search box, enter Endpoint.IP.

Step 10: In the Endpoint section, click IP, and then click Close.

Palo Alto Networks 27

 Creating and Running a Playbook

Step 11: Verify that the conditional statement now compares Endpoint.Hostname and Endpoint.IP, and
then click the check.

Step 12: To complete the configuration of this task, click OK.

Palo Alto Networks 28

 Creating and Running a Playbook

Step 13: Verify that the task is now in your playbook.

3.5 Create the “Mark as Note - Name Resolution Failed” Task

This is the first procedure of a new branch of the playbook. The playbook selects this branch only if the IP
to hostname resolution failed, as determined by Procedure 3.4.

This task uses the Print automation script. You configure advanced settings for this task to mark the
results as an incident note.

You include Endpoint.IP context data as an input for this task.

Step 1: From the Is the hostname the same as the IP address? task egress node, drag the task connector
line to the playbook workspace, and then release to create an untitled task below and to the left.

Step 2: In the Choose Label Name for Condition dialog box, select yes.

Palo Alto Networks 29

 Creating and Running a Playbook

Step 3: Click Save. The Edit Task dialog box appears.

Step 4: In the Task Name box, enter Mark as note - name resolution failed.

Step 5: In the Choose Automation section, click the down arrow to open the search dialog box.

Step 6: In the search box, enter Print, and then choose Print. The task fields update.

Step 7: In the value box, enter The IP address ${Endpoint.IP} failed to resolve to a hostname..

Palo Alto Networks 30

 Creating and Running a Playbook

Step 8: On the Advanced tab, select Mark results as note, and then click OK.

Step 9: Verify that the task is now in your playbook.

3.6 Create the “Mark as Note - Name Resolution Successful” Task

This is the first procedure of a new branch of the playbook. The playbook selects this branch only if the IP
to hostname resolution succeeded, as determined by Procedure 3.4.

This task uses the Print automation script. You configure advanced settings for this task to mark the
results as an incident note.

You include Endpoint.IP and Endpoint.Hostname context data as an input for this task.

Step 1: From the Is the hostname the same as the IP address? task egress node, drag the task connector
line to the playbook workspace, and then release to create an untitled task below and to the right.

Palo Alto Networks 31

 Creating and Running a Playbook

Step 2: In the Choose Label Name for Condition dialog box, select Mark as 'else' case.

Step 3: Click Save. The Edit Task dialog box appears.

Step 4: In the Task Name box, enter Mark as note - name resolution successful.

Step 5: In the Choose Automation section, click the down arrow to open the search dialog box.

Step 6: In the search box, enter Print, and then choose Print. The task fields update.

Palo Alto Networks 32

 Creating and Running a Playbook

Step 7: In the value box, enter The IP address ${Endpoint.IP} successfully resolved to hostname
${Endpoint.Hostname}.

Step 8: On the Advanced tab, select Mark results as note, and then click OK.

Step 9: Verify that the task is now in your playbook.

3.7 Create a “Done” Task

As a best practice, you should create a Done section-header task that ends the playbook.

Palo Alto Networks 33

 Creating and Running a Playbook

Step 1: From the Mark as note - name resolution failed task egress node, drag the task connector line to
the playbook workspace, and then release to create an untitled blank task below and to the center.

Step 2: Select Section Header.

Step 3: In the Task Name box, enter Done, and then click OK.

Step 4: From the Mark as note - name resolution successful task egress node, drag the task connector
line to the Done section-header task ingress node to create an additional connection to the Done task.

Palo Alto Networks 34

 Creating and Running a Playbook

Step 5: Verify that the task is now in your playbook.

Step 6: To save the playbook, click Save Playbook.

Procedures

Running the Playbook and Managing an Incident

4.1 Run the Playbook in the Cortex XSOAR Playbook Debugger

4.2 Review Playbook Execution Information in the Cortex XSOAR Playbook Debugger Panel

4.3 Re-Run the Playbook in the Cortex XSOAR Playbook Debugger

4.4 Run the Playbook within an Incident

4.5 Review Incident Information

4.6 Re-Run the Playbook in an Incident

To execute the Resolve IP to Hostname playbook, you have two options:

• Cortex XSOAR playbook debugger—The playbook debugger enables you to run and troubleshoot
playbooks right from the playbook workspace, providing visibility into task execution and control
over test data.

• Cortex XSOAR incident—You can fully validate all aspects of your playbook by creating a Cortex
XSOAR incident.

While developing your playbook, you typically use the Cortex XSOAR playbook debugger for testing. Later,
to validate a finished playbook, you create a test incident to complete the testing.

Palo Alto Networks 35

 Creating and Running a Playbook

4.1 Run the Playbook in the Cortex XSOAR Playbook Debugger

The Cortex XSOAR playbook debugger uses test data to execute a playbook. By default, the debugger runs
using an empty mock data incident that will be used to test the Resolve IP to Hostname playbook. For
more complicated playbooks, you can configure the playbook debugger to use playground or incident data.

Step 1: In Cortex XSOAR, in the navigation pane, click Playbooks.

Step 2: In the Search in playbooks box, enter "Resolve IP to Hostname"

Note

For the search to work, you must include the quotes.

Palo Alto Networks 36

 Creating and Running a Playbook

Step 3: In the Resolve IP to Hostname playbook workspace, click Edit.

Palo Alto Networks 37

 Creating and Running a Playbook

Step 4: Click Run to execute the Resolve IP to Hostname playbook.

Tasks in orange are awaiting input.

Step 5: Click the Get the IP address task. The Task Details dialog box appears.

Palo Alto Networks 38

 Creating and Running a Playbook

Step 6: In the What is an IP address that you want to resolve to a hostname? box, enter an IP address
(example: 192.168.5.6), and then click Submit Answers.

The dialog box closes, and Cortex XSOAR resumes playbook execution.

4.2 Review Playbook Execution Information in the Cortex XSOAR Playbook

Debugger Panel

In the Cortex XSOAR playbook debugger panel, you can view input, output, and results in real time for a
playbook run-through.

Palo Alto Networks 39

 Creating and Running a Playbook

Step 1: From a running playbook, click Debugger Panel.

The Debugger Panel appears.

Step 2: To expand the Cortex XSOAR Debugger Panel context data, click the Cortex XSOAR Data Collection
row.

Step 3: To expand the Endpoint context data, click the Endpoint row.

Palo Alto Networks 40

 Creating and Running a Playbook

Step 4: To search for a keyword in the context data, in the search box, enter the keyword (example:
Hostname), and then press ENTER.

The Context Data Explorer search is case sensitive and highlights any matches in the context data. The
search also expands any rows in the context data that contain case-insensitive matches but does not
highlight them.

Step 5: Verify that all playbook tasks completed execution without errors. Successful tasks display a green
check. Tasks with errors display a red caution symbol.

4.3 Re-Run the Playbook in the Cortex XSOAR Playbook Debugger

By default, the playbook debugger does not keep context data between playbook runs, which simplifies
testing of task changes.

Step 1: If the Stop button is displayed, click it to ensure that the current debug session is ended.

Palo Alto Networks 41

 Creating and Running a Playbook

Step 2: To re-run your playbook, on the playbook workspace, click Run.

4.4 Run the Playbook within an Incident

After you have completed the development of your playbook, you run it within an incident. In this
example, you manually assign the playbook after you create a new incident.

Step 1: In the navigation pane, click Incidents.

Step 2: Click New Incident.

Step 3: On the New Incident dialog box, in the Name box, enter a descriptive incident name (example:
Test example playbook).

Step 4: In the Playbook section, click Choose playbook.

Step 5: In the search box, enter Resolve IP to Hostname, and then choose Resolve IP to Hostname.

Palo Alto Networks 42

 Creating and Running a Playbook

Step 6: Click Create new incident.

Cortex XSOAR creates the new incident and immediately begins running the playbook.

Step 7: To access the incident information, in the ID column, click the incident ID number (example: #1).

Palo Alto Networks 43

 Creating and Running a Playbook

Step 8: Change to the Work Plan tab.

Step 9: Click the Get the IP address task. The Task Details dialog box appears.

Palo Alto Networks 44

 Creating and Running a Playbook

Step 10: In the What is an IP address that you want to resolve to a hostname? box, enter an IP address
(example: 8.8.4.4), and then click Submit Answers.

The dialog box closes, and Cortex XSOAR resumes playbook execution.

4.5 Review Incident Information

At any time while your playbook is running, or after the playbook has completed running, you can view
the context data for the incident or review task results in the War Room.

Palo Alto Networks 45

 Creating and Running a Playbook

Step 1: On the War Room tab or the Work Plan tab, click the menu, and then choose Context Data.

The Context Data Explorer appears.

Step 2: To expand the Cortex XSOAR Data Collection context data, click the Cortex XSOAR Data Collection
row.

Step 3: To expand the Endpoint context data, click the Endpoint row.

Palo Alto Networks 46

 Creating and Running a Playbook

Step 4: To search for a keyword in the context data, in the search box, enter the keyword (example:
Hostname), and then press ENTER.

The Context Data Explorer search is case-sensitive and highlights any matches in the context data. The
search also expands any rows in the context data that contain case-insensitive matches but does not
highlight them.

Step 5: On the workplan tab, verify that all playbook tasks completed execution without errors. Successful
tasks display a green check. Tasks with errors display a red caution symbol.

Palo Alto Networks 47

 Creating and Running a Playbook

Step 6: On the War Room tab, review task results. The war room provides a complete record of all
activities related to the incident.

In the war room, you can filter for specific task results, such as when the playbook creates notes.

Step 7: Click the icon, and in the Actions column, select Notes. Cortex XSOAR applies the filter.

Palo Alto Networks 48

 Creating and Running a Playbook

Step 8: To close the filter dialog box, click the icon. You can now review the filtered task results.

4.6 Re-Run the Playbook in an Incident

The war room provides a chronological journal of all activities related to the incident. To ensure integrity,
there is no method for removing entries. When re-running your playbook, Cortex XSOAR appends all task
information to the war room.

If you want to re-run your playbook, you should delete the context data.

Note

Each time you run a playbook, Cortex XSOAR adds new context data to the
existing context data. Unless you configure your playbook tasks to properly
parse context data, such as arrays, playbook tasks could fail when you re-run
them.

Step 1: Clear the context data before you re-run your playbook. In the Cortex XSOAR CLI, enter:
!DeleteContext all=yes

Step 2: To re-run your playbook, on the Work Plan tab, click Run again.

Palo Alto Networks 49

 Creating and Running a Playbook

Step 3: On the Change playbook dialog box, click Yes I know what I am doing. Cortex XSOAR immediately
begins running the playbook again.

Continue interacting with your playbook as you did in the previous sections.

Palo Alto Networks 50

HEADQUARTERS
Palo Alto Networks Phone: +1 (408) 753-4000
3000 Tannery Way Sales: +1 (866) 320-4788
Santa Clara, CA 95054, USA Fax: +1 (408) 753-4001
http://www.paloaltonetworks.com info@paloaltonetworks.com

© 2021 Palo Alto Networks, Inc. Palo Alto Networks is a registered trademark of Palo Alto Networks. A list of our
trademarks can be found at http://www.paloaltonetworks.com/company/trademarks.html. All other marks mentioned
herein may be trademarks of their respective companies. Palo Alto Networks reserves the right to change, modify,
transfer, or otherwise revise this publication without notice.

You can use the feedback form to send comments

about this guide.

B-000240P-1-21b