❌

Normal view

There are new articles available, click to refresh the page.
Before yesterdayNVISO Labs

Cortex XSOAR Tips & Tricks – Creating indicator relationships in integrations

23 September 2022 at 08:00

Introduction

When a Threat Intelligence Management (TIM) license is present in your Cortex XSOAR environment, the feature to create relationships between indicators is available. This allows you to describe how indicators relate to each other and use this relationship in your automated analysis of a security incident.

In the previous blog post in this series, we gave a brief overview of the additional features available in Cortex XSOAR when a TIM license is imported. We also showed you how to create relationships between indicators from within automations by using the CommandResults class from CommonServerPython.

In this post, we will show you how to create relationships from within a Cortex XSOAR integration. This requires a different approach because there are different features available in an automation and an integration.

Threat Intelligence Integrations

The most common use case for creating indicators and their relationships from within an integration is related to threat intelligence. In general, these integrations import threat intelligence data as indicators into Cortex XSOAR. These indicators can either be used by the SOC analysts in their investigations of incidents or, after automated or manual curation, can be exported to other platforms for additional detection capabilities.

An example of such an integration would be the MITRE ATT&CK v2 integration created by Cortex XSOAR. This integration fetches the MITRE ATT&CK techniques from the MITRE TAXI feed and creates Attack Pattern indicators in Cortex XSOAR for each technique.

An Attack Pattern indicator layout is available after installing the MITRE ATT&CK v2 content pack which visualizes all the fetched data:

Attack Pattern Indicator
Attack Pattern Indicator

In the Relationships section of the Attack Pattern indicator layout, you can see all the related indicators:

Relationships of an Attack Pattern indicator

Besides the Attack Pattern indicators, the MITRE ATT&CK integration also creates indicators for the APT groups that use the technique, which malware is related to the technique and information about the how it can be mitigated.

In our SOC, we actively use these Attack Pattern indicators by associating them to the incident based on the MITRE ATT&CK technique IDs available in the incident data fetched from the SIEM or EDR platform. This allows the SOC analyst to quickly see which techniques are used in the incident and retrieve all relevant information at a click of a button.

Create Indicator Relationships

When creating your own custom integration which fetches data to create indicator relationships, you will not be able to use the same approach as we describe in the previous blog post in this series by using the CommandResults class from CommonServerPython.

To create indicator relationships from within an integration, you will need to use the createIndicators method of the demisto class. As when using the CommandResults, you will need to define the indicator relationship in an instance of the EntityRelationship class. Because the instance will be used by the createIndicators method, to_indicator() should be called when creating it.

indicator_relationships = []
 
indicator_relationships.append(
    EntityRelationship(
        name=EntityRelationship.Relationships.USES,
        entity_a="u4872",
        entity_a_type="Account",
        entity_b="pc135456.domain.local",
        entity_b_type="Host"
    ).to_indicator()
)

The createIndicators method takes a list of indicators to create as an argument and cannot create relationships without an indicator. We will need to use a dummy indicator which will have the list of EntityRelationship instances as a value of the indicator relationships argument:

dummy_indicator = [
    {
        "value": "$$DummyIndicator$$",
        "relationships": indicator_relationships
    }
]

This dummy indicator should be passed as the indicators_batch argument of the createIndicators method:

demisto.createIndicators(indicators_batch=dummy_indicator)

When calling the createIndicators method the dummy indicator will be created together with all the indicator relationships defined in the indicator relationships argument. The dummy indicators will remain present in Cortex XSOAR but will not be associated to any incident.

References

https://xsoar.pan.dev/docs/reference/api/common-server-python#commandresults

https://xsoar.pan.dev/docs/reference/integrations/mitre-attck-v2

https://attack.mitre.org/resources/working-with-attack/

https://xsoar.pan.dev/docs/reference/api/demisto-class#createindicators

https://xsoar.pan.dev/docs/reference/api/common-server-python#entityrelationship

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

Cortex XSOAR Tips & Tricks – Creating indicator relationships in automations

23 June 2022 at 08:00

Introduction

In Cortex XSOAR, indicators are a key part of the platform as they visualize the Indicators Of Compromise (IOC) of a security alert in the incident to the SOC analyst and can be used in automated analysis workflows to determine the incident outcome. If you have a Cortex XSOAR Threat Intelligence Management (TIM) license, it is possible to create predefined relationships between indicators to describe how they relate to each other. This enables the SOC analyst to do a more efficient incident analysis based on the indicators associated to the incident.

In this blog post, we will provide some insights into the features of Cortex XSOAR Threat Intelligence Management and how to create indicator relationships in an automation.

Threat Intelligence Management

Threat Intelligence Management (TIM) is a new feature in Cortex XSOAR which requires an additional license on top of your Cortex XSOAR user licenses. It is created to improve the use of threat intel in your SOC. Using TIM, you can automate threat intel management by ingesting and processing indicators sources to export the enriched intelligence data to the SIEMs, firewalls, and other security platforms.

Cortex XSOAR TIM is a Threat Intelligence Platform with highly actionable Threat data from Unit 42 and not only identify and discover new malware families or campaigns but ability to create and disseminate strategic intelligence reports.

https://www.paloaltonetworks.com/cortex/threat-intel-management

When the TIM license is imported into your Cortex XSOAR environment, all built-in indicator types will have a new Unit 42 Intel tab available:

Unit 42 Intel

This tab contains the threat intelligence data for the specific indicator gathered by Palo Alto and makes it directly available to your SOC analysts.

For Cortex XSOAR File indicators, the Wildfire analysis (the cloud-base threat analysis service of Palo Alto) is available in the indicator layout providing your SOC analysts a detailed analysis of malicious binaries if its file hash is known:

Wildfire Analysis

The TIM license also adds the capability to Cortex XSOAR to create relationships between indicators.

If you for example have the following indicators in Cortex XSOAR:

  • Host: ict135456.domain.local
  • MAC: 38-DA-09-8D-57-B1
  • Account: u4872
  • IP: 10.15.62.78
  • IP: 78.132.17.56

Without a TIM license, these indicators would be visible in the indicators section in the incident layout without any context about how they relate to each other:

By creating relationships between these indicators, a SOC analyst can quickly see how these indicators have interacted with each other during the detected incident:

Indicator Relationships

EntityRelationship Class

To create indicator relationships, the EntityRelationship class is available in the CommonServerPython automation.

CommonServerPython is an automation created by Palo Alto which contains Python code that can be used by other automations. Similar to CommonServerUserPython, CommonServerPython is added to all automations making the code available for you to use in your own custom automation.

In the Relationships subclass of EntityRelationship, you can find all the possible relationships that can be created and how they relate to each other.

RELATIONSHIPS_NAMES = {'applied': 'applied-on',
                       'attachment-of': 'attaches',
                       'attaches': 'attachment-of',
                       'attribute-of': 'owns',
                       'attributed-by': 'attributed-to',
                       'attributed-to': 'attributed-by',
                       'authored-by': 'author-of',
                       'beacons-to': 'communicated-by',
                       'bundled-in': 'bundles',
                       'bundles': 'bundled-in',
                       'communicated-with': 'communicated-by',
                       'communicated-by': 'communicates-with',
                       'communicates-with': 'communicated-by',
                       'compromises': 'compromised-by',
                       'contains': 'part-of',
                       .......

You can define a relationship between indicators by creating an instance of the EntityRelationship class:

indicator_relationship = EntityRelationship(
    name=EntityRelationship.Relationships.USES,
    entity_a="u4872",
    entity_a_type="Account",
    entity_b="ict135456.domain.local",
    entity_b_type="Host"
)

In the name attribute, you add which relationship you want to create. Best to use the Relationships Enum subclass in case the string values of the relationship names change in a future release.

In the entity_a attribute, add the value of the source indicator.

In the entity_a_type attribute, add the type of the source indicator.

In the entity_b attribute, add the value of the destination indicator.

In the entity_b_type attribute, add the type of the destination indicator.

When initializing the EntityRelationship class, it will validate all the required attributes to see if all information is present to create the relationship. If not, a ValueError exception will be raised.

Create Indicator Relationships

Now we know which class to use, let’s create the indicator relationships in Cortex XSOAR.

For each relationship we want to create, an instance of the EntityRelationship which describes the relationship between the indicators should be added to a list :

indicator_relationships = []

indicator_relationships.append(
    EntityRelationship(
        name=EntityRelationship.Relationships.USES,
        entity_a="u4872",
        entity_a_type="Account",
        entity_b="ict135456.domain.local",
        entity_b_type="Host"
    )
)

indicator_relationships.append(
    EntityRelationship(
        name=EntityRelationship.Relationships.BEACONS_TO,
        entity_a="78.132.17.56",
        entity_a_type="IP",
        entity_b="ict135456.domain.local",
        entity_b_type="Host"
    )
)

indicator_relationships.append(
    EntityRelationship(
        name=EntityRelationship.Relationships.ATTRIBUTED_BY,
        entity_a="38-DA-09-8D-57-B1",
        entity_a_type="MAC",
        entity_b="ict135456.domain.local",
        entity_b_type="Host"
    )
)

indicator_relationships.append(
    EntityRelationship(
        name=EntityRelationship.Relationships.USES,
        entity_a="10.15.62.78",
        entity_a_type="IP",
        entity_b="ict135456.domain.local",
        entity_b_type="Host"
    )
)

To create the relationships in Cortex XSOAR, the list of EntityRelationship instances needs to be returned in an instance of the CommandResults class using the return_results function:

return_results(
    CommandResults(
        relationships=indicator_relationships
    )
)

If you now open the relationship view of the Host indicator in Cortex XSOAR, you will see that the relationships have been created:

Indicator Relationships

References

https://docs.paloaltonetworks.com/cortex/cortex-xsoar/6-8/cortex-xsoar-threat-intel-management-guide

https://xsoar.pan.dev/docs/reference/api/common-server-python#entityrelationship

https://xsoar.pan.dev/docs/reference/api/common-server-python#relationshipstypes

https://xsoar.pan.dev/docs/reference/api/common-server-python#relationships

https://xsoar.pan.dev/docs/reference/api/common-server-python#commandresults

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

Cortex XSOAR Tips & Tricks – Discovering undocumented API endpoints

7 June 2022 at 08:00

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

Cortex XSOAR Tips & Tricks – Exploring the API using Swagger Editor

1 June 2022 at 08:00

Introduction

When using the Cortex XSOAR API in your automations, playbooks or custom scripts, knowing which API endpoints are available and how to use them is key. In a previous blog post in this series, we showed you where you could find the API documentation in Cortex XSOAR. The documentation was available on the server itself, as a PDF, or as a Swagger file.

Swagger is a set of developer tools for developing and interacting with APIs. It is also a former specification for documenting APIs on which the OpenAPI specification is based.

In this blog post we will show you how to setup a Swagger Editor instance together with the Cortex XSOAR API Swagger file to visualize and interact with the Cortex XSOAR API. This will allow you to easily explore it’s capabilities, craft HTTP requests and view the returned data without the need to write a single line of code.

Swagger Editor

The Swagger Editor is an open source editor to design and document RESTful APIs in the OpenAPI (formaly Swagger) specification.

To install Swagger Editor we will be using the official docker image available on Docker Hub. If Docker is not yet installed, please follow the Docker installation documentation.

Start the docker image with the following commands:

docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor

The Swagger Editor will now be available in your browser on address http://localhost

Swagger Editor

Before we can start interacting with the Cortex XSOAR API, we will need to bypass CORS restrictions in your browser.

Cross-Origin Resource Sharing (CORS) is a mechanism that allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource was served. In Firefox, CORS is only allowed when the server returns the Access-Control-Allow-Origin: * header which we are going to set using a Firefox extension.

In Firefox, the extension CORS Everywhere is available for installation in the Firefox Add-ons. Once installed, a new icon will be available in the Firefox toolbar. To bypass CORS restrictions, click the CorsE icon and it will turn green.

Explore Cortex XSOAR API

To start exploring the Cortex XSOAR API from the Swagger Editor, we will need to create an API key and download the REST Swagger file. Open Cortex XSOAR > Settings > Integration > API Keys:

Cortex XSOAR API Keys

Click Get Your Key to create an API key and copy the key.

Download the REST Swagger file, copy the content of the downloaded JSON file and paste it into the Swagger Editor.

Click OK to convert the JSON to YAML:

After importing the JSON, an error will be shown which can be ignored by clicking Hide:

On line 36 of the imported YAML file, replace hostname with the URL of your Cortex XSOAR server:

host: dev.xsoar.eu:443

Click Authorize to add authentication credentials:

Paste your API key and click Authorize:

Now you are ready to start exploring the Cortex XSOAR API. For each available API endpoint you will see an an entry in the Swagger Editor together with its supported HTTP method.

We are going to use the /incidents/search API Endpoint as an example.

When you expand the /incident/search entry, you will see it’s description:

Next you will see the required and optional parameters, together with their required data models, either in JSON or XML:

Finally you will see the possible response codes, content types and example data returned by the API endpoint:

All this information will allow you to craft the HTTP request to the Cortex XSOAR API for your automation or custom script. But the Swagger Editor also allows you to interact with an API directly from its web interface.

In the entry of the /incident/search API endpoint, click on Try it out:

You will see that you can now edit the value of the filter parameter. We will be searching for an incident in Cortex XSOAR based on its ID:

{
  "filter": {
    "id": [
      "12001"
    ]
  }
}

After pasting the JSON in the filter value, click Execute:

The API request will now be executed against the Cortex XSOAR API.

In the Responses section, you will see the Curl request of the executed API request. You can use this command in a terminal to execute the API request again.

The response body of the API request can be seen in the Server response section.

By using the Swagger Editor to interact with the Cortex XSOAR API, you can explore the available API requests and their responses without implementing any code. This allows you to see if the Cortex XSOAR API supports the functionality for your automated workflow case before you start development.

References

https://editor.swagger.io/

https://hub.docker.com/r/swaggerapi/swagger-editor/

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

❌
❌