Introduction

When you use the Cortex XSOAR API in your automations, playbooks or custom scripts, the first place you will start is the API documentation to see which API endpoints are available. But what if you cannot find an API Endpoint for the task you want to automate in the documentation?

In this blog post we will show you how to discover undocumented Cortex XSOAR API endpoints using the Firefox Developer Tools and how to craft HTTP requests with Curl.

Discover API Endpoints

The Cortex XSOAR API documentation can be found in Settings > Integrations > API Keys as a web page on the server, a PDF document or a Swagger file. It contains a list of API Endpoints with their description, HTTP method, return codes, parameters, request body schema and example responses.

When the you cannot find an API endpoint in the documentation with the required functionality you are looking for, the Cortex XSOAR API allows you to use the undocumented API endpoints which are used by the Cortex XSOAR web interface. You can use the developer tools of your browser to discover which API endpoint is used when performing a certain task and see what request body is required.

As an example, we discover which undocumented API endpoints are used when starting/stopping accounts on a multi-tenant Cortex XSOAR server using Firefox.

To start/stop a multi-tenant account, go to Settings > Accounts Management:

Here you can start/stop an account by selecting it and using the Start/Stop buttons.

To see which API endpoint is used by the Cortex XSOAR web interface, open the Firefox Developer Tools by pressing Ctrl + Shift + i:

When you now stop an account using the web interface, you will see all HTTP requests that are executed in the Network tab:

If you click the first entry, you will see the details of the HTTP request for stopping the account. In the Headers tab, you will see which API Endpoint is used,

The API endpoint used for stopping accounts is /accounts/stop.

In the Request tab, you will see the HTTP request body required for the HTTP POST request to the /accounts/stop API endpoint:

As a requests body for this API endpoint, you will need to pass the following JSON:

{
  "names": [
    "acc_Profit"
  ]
}

The account name should be in the format acc_<account_name> as an element of the names array.

To get the account name, we could also look at the second entry in the Network tab which is the response of the HTTP GET request to the /account API endpoint.

If you open the response tab in the request details, you will see the details of each account:

Next, we’ll see which API endpoint is used to start an account. In the Network tab of the Developer Tools, first click the trashcan button to clear all entries. Now let’s start the account from the Cortex XSOAR web interface by selecting the account and clicking the Start button.

You will now see the following HTTP Requests:

Click on the first HTTP POST request to see the request details:

The API endpoint used for starting accounts is /accounts/start.

In the Request tab, you will see the HTTP request body required for the HTTP POST request to the /accounts/start API endpoint:

As a requests body for this API endpoint, you will need to pass the following JSON:

{
  "accounts": [
    {
      "name": "acc_Profit"
    }
  ]
}

Now that we know the API endpoints and required request bodies for starting and stopping multi-tenant accounts, we can create the Curl commands.

With the following Curl command, you can stop an account:

curl -X 'POST' \
'https://demo-xsoar.westeurope.cloudapp.azure.com/accounts/stop' \
-H 'accept: application/json' \
-H 'Authorization: ********************************' \
-H 'Content-Type: application/json' -d '{"names": ["acc_Profit"]}'

In the Authorization header you will need to add an API key you created in Settings > Integrations > API Keys.

In the Accounts Management tab in Cortex XSOAR, you will now see that the account is stopped:

With the following Curl command, you can start an account:

curl -X 'POST' \
'https://demo-xsoar.westeurope.cloudapp.azure.com/accounts/start' \
-H 'accept: application/json' \
-H 'Authorization: ********************************' \
-H 'Content-Type: application/json' -d '{"accounts":[{"name":"acc_Profit"}]}'

In the Accounts Management tab in Cortex XSOAR, you will now see that the account is running:

You can now implement these HTTP requests in your own automation or playbook making use of the Demisto REST API integration or in your custom script.

By using the developer tools of your browser, you can discover any API endpoint used by the Cortex XSOAR web interface. This allows you to automate anything you could do manually in the web interface which greatly increases the possible use cases for automation.

About the author

Wouter is an expert in the SOAR engineering team in the NVISO SOC. As the SOAR engineering team lead, he is responsible for the development and deployment of automated workflows in Palo Alto Cortex XSOAR which enable the NVISO SOC analysts to faster detect attackers in customers environments. With his experience in cloud and devops, he has enabled the SOAR engineering team to automate the development lifecycle and increase operational stability of the SOAR platform.

You can contact Wouter via his LinkedIn page.

Want to learn more about SOAR? Sign- up here and we will inform you about new content and invite you to our SOAR For Fun and Profit webcast.
https://forms.office.com/r/dpuep3PL5W