Skip to main content

Overview

This integration lets you protect incident data inside the Cortex XSOAR platform.

Use Cases#

Protecting incidents inside the Cortex XSOAR platform.

You can protect incidents of any type based on configured schemas for a specific source brand. Mapping schema specifies mapping of sensitive data to TitaniamProtect data types. See Titaniam Panther Configuration Guide for more information about schemas, mapping and available data types and their use.

Set up#

You will be setting up in two places.

  1. Outside Cortex XSOAR: Install and Configure Panther (Encryption API Service) and
  2. Within Cortex XSOAR: Install Content Pack, create integration instance and configure it.

Installing and Configuring Panther.#

  1. Install Panther by following the panther installation instruction. Panther is a Restful API service and accepts JSON payloads.
  2. Create a schema in Panther for each source brand from which you currently import incidents. A schema is a listing of fields that you want to secure for a given source, and how to secure. For example if your splunk event feed has 40 fields, and you just want to secure three fields, say IP and host name, just add these two fields and state how you want to secure. Refer to panther configuration guide for data types. We recommend using "tangled_keyword2, as it produces searchable artifact" for text fields, tangled_ip, tangle_date and tangled_integer for those fields respectively.

Install and Configure TitaniamProtect Contentpack within Cortex XSOAR#

Basic Configuration Steps#

  • Install “TitaniamProtect” content pack from Market Place into your instance of Cortex XSOAR.

  • Installation includes:

    • TitaniamProtect integration

    • “Titaniam Protect” incident type

    • ProtectedFields custom field

    • “Titaniam Protect” custom layout

    • TitaniamProtectIncident Automation (python script)

    • TitaniamFindIncidents Automation (python script)

    • TitaniamSync playbook

    • TitaniamRollback playbook

    • TitaniamProtect playbook

  • Configure Integration instance

  • Create mapping schema for the type of data/incidents that need to be protected.

    • Example for schema that correspond to manually created incidents (source brand – Manual) is shown in the appendix to this document.

    • You may create additional schemas per your needs (see documentation for Titaniam Panther/Panther service for in-detail information about creation and management of mapping schemas).

  • Navigate to Settings > Advanced > Lists. Click on “Add a List” button to create new list.

Setup Account

  • Set mapping schema list with schemas created at Titaniam Panther service.

    • Name list “TitaniamMappingSchema”

    • Copy/paste following Json content into “Data” text area field. You will update this mapping of brands to schema names and versions according to the type of incident or version of schema you create. Schema defined here would correspond to schema used to protect manually created incidents in Cortex. Example of that schema is given in the appendix to this document.

[{

"brand" : "Manual",

"schemaName" : "ManualIncidentSchema",

"schemaVersion" : "1.0"

}]

  • Click “Save” button to save changes to the list.

  • Create and configure a new Job that will periodically execute TitaniamSync playbook and rectify unprotected incidents.

Configure Integration Instance (in details)#

Titaniam Protect Content Pack requires connectivity to an external service (Titaniam Panther service). See above for instructions on installing and configuring Panther.

Configure XSOAR to Connect to Panther and Test Connectivity#

There are several options when connecting to the service. They are described in details below.

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for TitaniamProtect.

Setup Account

  1. Click Add instance to create and configure a new integration instance.

    ParameterRequired
    Service URL (e.g. https://panther-host:8443, or http://panther-host:8080)True
    API KeyTrue
    Trust any certificate (not secure)False
    Use system proxy settingsFalse
    Content of the client certificate used for 2-way TLS authentication.False
    Content of the client key used for 2-way TLS authentication.False
    Content of the server certificate used for 2-way TLS authentication.False

Click Add instance to create and configure a new integration.

Enter following information:

  • Name: Name for the integration instance (defaults to “TitaniamProtect_instance_1”).

  • TitaniamProtect Panther Service URL: URL address of an instance of Titaniam Protect Panther (Panther) Service. For example: or . Note that Panther connection on port 8443 requires MTLS (Mutual TLS) authentication and license registration, while port 8080 has MTLS authentication disabled.

  • Trust any certificate (not secure): Skips verification of the CA certificate (not recommended for production settings).

  • Use system proxy settings: Uses the system’s proxy settings.

  • API Key: Enter “test” here (this is a placeholder, since API key is currently not used as a way of authentication).

  • Client certificate: copy paste client certificate in PEM format (note that this certificate must be installed on the Titaniam Protect Panther service side), or leave this field empty if not using MTLS.

  • Client key: copy paste client key in PEM format, or leave this field empty if not using MTLS.

  • Titaniam Protect CA Certificate: CA Certificate used by Titaniam Protect. Copy the certificate retrieved from the Titaniam Protect Panther service (or leave this field empty if not using MTLS).

Note that you can:

  • Check “Trust any certificate” (not recommended) to skip verification of certificate sent by Panther service server and still perform client authentication to server using client certificate.

  • Leave “Trust any certificate” unchecked, which will trigger verification of the server certificate sent by the Titaniam Protect Panther service. This certificate will be checked in one of two ways:

    • If “Titaniam Protect CA Certificate” is provided, value of that certificate will be used to verify what server sent.

    • If “Titaniam Protect CA Certificate” is not provided, Panther service certificate will be verified against certificates stored in the cert store.

  1. Click Test to validate the URLs, token, and connection.

Commands#

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

titaniamprotect-encode#


Encode a JSON document per specified schema

Base Command#

titaniamprotect-encode

Input#

Argument NameDescriptionRequired
schema_nameSchema name used for encoding incident data.Required
schema_versionSchema version used for encoding incident data.Required
encode_valueJSON value to encode per specified schema.Optional

Context Output#

There is no context output for this command.

Command Example#

!titaniamprotect-encode schema_name="ElasticsearchSchema" schema_version="1.0" encode_value="{\"hostname\" : \"ACME-SERVER-01\"}"

Human Readable Output#

{ "hostname" : "03[oD06HS_[D>06j>;E;V..." }

titaniamprotect-decode#


Decode JSON document per specified schema

Base Command#

titaniamprotect-decode

Input#

Argument NameDescriptionRequired
schema_nameSchema name used for encoding incident data.Required
schema_versionSchema version used for encoding incident data.Required
encoded_valueJSON value encoded to decode based on specified schema.Required
decode_formatFormat to return decoded results in (cleartext | masked | tangled). If not specified, cleartext is assumed.Optional

Context Output#

There is no context output for this command.

Command Example#

!titaniamprotect-decode schema_name="ElasticsearchSchema" schema_version="1.3" encoded_value="{\"hostname\" : \"03[oD06HS_[D>06j>;E;V06L/K<>$06<pKL3*06@GY3-V0668o,_e06F:jgA[06.*/N0J06r5Qx('06nbc;d106339b0L06S(z#<|06X8sIq}\"}"

Human Readable Output#

{ "hostname : "ACME-SERVER-01" }

5.Click Done to save the integration instance.

Using the integration and scripts#

The integration ships with incident type “Titaniam Protect” which can be assigned to incidents at the time they are fetched from an external system, or can be applied on incidents already present in the Cortex XSOAR system (either “Unclassified” or incidents of other types).

The “Titaniam Protect” incident type has “Titaniam Protect” layout associated with it, providing a convenient way of viewing incident sensitive data in either cleartext or encoded format.

Note that in the case you have your own specific incident type and do not want to use provided “Titaniam Protect” type, you can still re-use the “Titanim Protect” layout and assign it to your incident type. “Titaniam Protect” layout is a default Cortex XSOAR layout, with addition of a new “Titaniam Protect” tab which includes a section with a custom grid/table field and two buttons to allow showing incident data in cleartext or encoded format.

The two buttons included: “Show Cleartext” and “Protect Data” will only appear in case user logged into system has Administrator or Analyst privileges.

Python script associated with these buttons (“TitaniamProtectIncident”) acts upon current incident, passing incident id (value \${incident.id}) and operation (protect, protect-masked, protect-tangled or unprotect) as its parameters. As stated above, this script can be run only by a user with Administrator or Analyst role.

Protecting Incidents Data#

There are several different ways how one can protect incident data inside the Cortex XSOAR platform.

  • Running TitaniamProtect playbook

  • Running TitaniamSync playbook through a Job. TitaniamSync looks for unprotected incidents first and then executes TitaniamProtectIncident script against list of found incidents.

  • Executing TitaniamProtect playbook by changing incident type to “Titaniam Protect” incident type. “Titaniam Protect” incident type has “TitaniamProtect playbook” assigned to run automatically. Playbook will be executed in the context of current incident.

  • Running TitaniamProtectIncident script manually.

  • Using TitaniamProtect integration commands directly.

  • Executing pre-processing rule.

  • Integrating TitaniamProtectIncident script inside your own Playbook.

  • Creating a wrapper Playbook that will call your own playbook and TitaniamProtect playbook in sequence.

TitaniamProtectIncident Script#

TitaniamProtectIncident script is used to apply encode/decode operation on one or more incidents.

TitanamProtectIncident script has following parameters:

  • incident_id - Zero or more incident IDs comma separated (if omitted, will protect current incident)

  • operation - protect | protect-masked | protect-tangled | unprotect

Examples of invoking this script:

!TitaniamProtectIncident incident_id=”225,226,227,228” operation=”protect-masked”

Encode list of incidents, specified with comma-separated values incidents IDs (225,226,227,228). Display format for protected fields of encoded incidents is a mask in the form of “xxx”. When invoked on already encoded incidents this command doesn’t have an effect.

!TitaniamProtectIncident operation=”protect-masked”

Encode current incident. Display format for protected fields of encoded incident is a mask in the form of “xxx”. When invoked on already encoded incident this command doesn’t have an effect.

!TitaniamProtectIncident incident_id=”225,226,227,228” operation=”protect-tangled”

Encode list of incidents, specified with comma-separated values incidents IDs (225,226,227,228). Display format for protected fields of encoded incidents is encoded value. When invoked on already encoded incidents this command doesn’t have an effect.

!TitaniamProtectIncident operation=”protect-tangled”

Encode current incident. Display format for protected fields of encoded incident is encoded value. When invoked on already encoded incident this command doesn’t have an effect.

!TitaniamProtectIncident incident_id=”225,226,227,228” operation=”unprotect”

Decode list of incidents, specified with comma-separated values incidents IDs (225,226,227,228). Protected fields will be decoded back to cleartext. When invoked on already decoded incidents this command doesn’t have an effect.

!TitaniamProtectIncident operation=”unprotect”

Decode current incident. Protected fields will be decoded back to cleartext. When invoked on already decoded incident this command doesn’t have an effect.

TitaniamProtect Playbook#

The integration includes TitaniamProtect playbook which is used as a default playbook for “Titaniam Protect” incident type.

  • Run manually, or

  • Run automatically when changing incident type to “Titaniam Protect”

  • Scheduled to run as a Job on recurrent base

Calling TitaniamProtect from a custom Playbook#

You can incorporate TitaniamProtect into your custom playbook in two different ways:

  • Add a wrapper playbook that will call your own playbook and then call TitaniamProtect playbook in the sequence.

  • Call TitaniamProtectIncident script inside your own custom playbook.

Example 1:

Suppose you are using your own custom incident type which has associated playbook “Foo” that will be executed on a new incident automatically. Switching Foo for TitaniamProtect playbook would make us lose the operations which we want to run on an incident automatically. However, we also want to have the incident data protected, which require calling TitaniamProtect playbook. To solve this, we can create a new wrapper playbook “FooProtect” that will call Foo playbook on the incident, to perform any operations that we intend to run on the incident, and then add a call to TitaniamProtect playbook after Foo playbook is called. We would then re-assign FooProtect playbook as a default playbook that will be run automatically instead of Foo playbook (see figure below).

Setup Account

Operations on Protected Fields#

Any operations on protected fields are not possible while fields are in encoded format. TitaniamProtect allows for searches based on encoded fields, but this feature is not yet directly integrated inside Cortex XSOAR platform. Thus, any operation that relies on fields that are encoded would require first running decode operation on the incident (or incidents), performing desired operations, and then running encode operation. You can utilize TitaniamProtectIncident script to call it inside your own script or your own playbook to achieve desired result or call TitaniamProtect playbook from inside your own playbook workflow.

Use Case 1:

From inside your own script, you would call command:

dArgs = {

'operation': 'unprotect'

}

res = dmst.executeCommand("TitaniamProtectIncident", dArgs)

This command would decode all encoded fields on the protected incident (current incident) and allow you to perform desired operations inside your code. Similarly, you could call the same command with list of incidents that you want to decode:

dArgs = {

'operation': 'unprotect',

'incident_id': '225,226,227,228'

}

res = dmst.executeCommand("TitaniamProtectIncident", dArgs)

Use Case 2:

You have a playbook (Foo playbook) that you need to run operations on cleartext incident data and you have incident in encoded format. You would create a wrapper playbook that will run TitaniamProtect playbook with decode parameter first, then run your own Foo playbook, then run TitaniamProtect playbook with encode parameter, to return incident back to encoded format (see figure below).

Setup Account

TitaniamSync Playbook#

The integration includes TitaniamSync playbook which sole purpose is to “find” and “rectify” incidents accidentally left as unprotected. This playbook can be used in two ways:

  • Run manually, or

  • Scheduled to run as a Job on recurrent base

The playbook consists of three tasks:

  • Task 1, invoking script to find unprotected incidents (TitaniamFindIncidents script)

  • Task 2, used as a decision point to check if any unprotected incidents are found

  • Task 3, invoking script to iterate over list (comma-separated values) of found incident IDs and protect each corresponding incident (TitaniamProtectIncident script).

Python script TitaniamFindIncidents has following parameters:

  • time_frame_in_hours : int – time in hours to look back, when searching for incidents (default 24h)

  • incident_type : str – incident type to search on (0 or more incident types specified as a comma-separated values, default is “Titaniam Protect”)

  • source_brand : str – source brand to search on (0 or more source brands specified as a comma-separated values, default empty string)

  • max_results : int – number of incidents matching search criteria to return in one search (default 50)

  • timeField : str – time field to use when searching for unprotected incidents (default “created”).

  • protect_op: str – “protected” or “unprotected” value. For TitaniamSync playbook, this parameter is set to “unprotected”.

Examples of invoking this script:

!TitaniamFindIncidents time_frame_in_hours=”96” incident_type=”Titaniam Protect” protect_op=”unprotected”

Search for un-protected incidents of “Titaniam Protect” type in last 96 hours.

!TitaniamFindIncidents time_frame_in_hours=”24” incident_type=”Titaniam Protect” source_brand=”SplunkPy” max_result=”50” time_field=”created” protect_op=”unprotected”

Search for un-protected incidents of “Titaniam Protect” type, which source brand is “SplunkPy” in last 48 hours, based on “created” date/time field. Maximum of 50 results will be returned in a single search.

Both examples of execution of the script will generate output TitaniamProtect.Incidents, with incidents IDs as comma-separated values.

Output \${TitaniamProtect.Incidents} is fed into TitaniamProtectIncidents script which will run on the list of found incidents and protect them.

Note that last valid (active) schema for the Source Brand will be used in the process of applying protection.

TitaniamRollback Playbook#

#

The integration includes TitaniamRollback playbook used to rollback all protections on incidents in the system. Intent of this playbook is to allow users to go to clear-text version of incident data. This playbook can be used in two ways:

  • Run manually, or

  • Scheduled to run as a Job

The playbook consists of three tasks:

  • Task 1, invoking script to find protected incidents (TitaniamFindIncidents script, with parameter protect_op value set to “protected”).

  • Task 2, used as a decision point to check if any protected incidents are found.

  • Task 3, invoking script to iterate over list (comma-separated values) of found incident IDs and remove protection for each corresponding incident (TitaniamProtectIncident script with parameter op value set to “unprotect”).

Python script TitaniamFindIncidents has following parameters:

  • time_frame_in_hours : int – time in hours to look back, when searching for incidents (default 24h)

  • incident_type : str – incident type to search on (0 or more incident types specified as a comma-separated values, default is “Titaniam Protect”)

  • source_brand : str – source brand to search on (0 or more source brands specified as a comma-separated values, default empty string)

  • max_results : int – number of incidents matching search criteria to return in one search (default 50)

  • timeField : str – time field to use when searching for unprotected incidents (default “created”).

  • protect_op: str – “protected” or “unprotected” value. For TitaniamRollback playbook, this parameter is set to “protected”.

Examples of invoking this script:

!TitaniamFindIncidents time_frame_in_hours=”96” incident_type=”Titaniam Protect” protect_op=”protected”

Search for protected incidents of “Titaniam Protect” type in last 96 hours.

!TitaniamFindIncidents time_frame_in_hours=”24” incident_type=”Titaniam Protect” source_brand=”SplunkPy” max_result=”50” time_field=”created” protect_op=”protected”

Search for protected incidents of “Titaniam Protect” type, with source brand “SplunkPy” in last 48 hours, based on “created” date/time field. Maximum of 50 results will be returned in a single search.

!TitaniamFindIncidents incident_type=”Titaniam Protect” protect_op=”protected”

Search for protected incidents of “Titaniam Protect” type.

All examples of execution of the script will generate output TitaniamProtect.Incidents, with incidents IDs as comma-separated values.

Output \${TitaniamProtect.Incidents} is fed into TitaniamProtectIncidents script which will run on the list of found incidents and unprotect them.

Note that last valid (active) schema for the Source Brand will be used in the process of rolling back protection.

Create Job#

Navigate to Jobs and click on “New Job” button

Setup Account

Assign “TitaniamSync” playbook from the Playbook drop down list:

Setup Account

Add following description under Details field: “Executes TitaniamSync playbook to protect incidents accidentally left unprotected.”.

Click on “Create new job” button to create job. In this case, job will run every 2h, 7 days a week, starting with 8:00PM.

Setup Account

Manual Incidents#

One can protect manually created incidents by assigning “Titaniam Protect” incident type to them. Example:

  • In Cortex XSOAR, navigate to Incidents menu and click on New Incident button.

  • Under Basic Information:

    • Enter: “Test Incident – 10” for Name, pick current Date/Time for Occurred, Set Severity to Medium, Assign Administrator Role, Enter a sample text in Details.

Setup Account

  • Under Custom Fields enter values for following fields:

    • Agent ID:

    • Source Hostname

    • Source IP

    • Source Network

    • Source Port

    • Source Username

Setup Account

  • Click on Create new incident button.

Setup Account

  • Click on the incident ID and navigate to Titaniam Protect tab. You will notice that custom fields Source hostname, Source IP, Source network, Source port, Source username have been all encoded. This encoding is done based on schema setup for incidents created Manually (ManualIncidentSchema).

Setup Account

  • You can elect to create a different mapping schema, based on what custom fields you want to protect. By default, TitaniamProtect encodes all incident labels and custom fields which are specified in the mapping schema.

  • As an Administrator or Analyst (or other custom dedicated role) you have access to two buttons (Show Cleartext and Protect Data), which can be used to decode encoded fields.

Setup Account

  • Once you are done with reviewing incident information, click on Protect Data button to encode back sensitive fields.

Appendix A – Sample Mapping Schemas#

Sample Manual Schema#

This schema is a sample schema defined for manually created incidents (using New Incident button in the Incidents section of Cortex XSOAR UI).

Put below content in the manualSchema.json file:

{ "mappings": { "properties": { "details": { "type": "tangled_keyword2" }, "sourcehostname": { "type": "tangled_keyword2" }, "sourceip": { "type": "tangled_ip" }, "sourcenetwork": { "type": "tangled_keyword2" }, "sourceport": { "type": "tangled_integer" }, "sourceusername": { "type": "tangled_keyword2" } } } }

Execute:

curl --header "Content-Type: application/json" --request POST \

-d @manualSchema.json

Response generated shows that schema has been successfully created:

{"code":"SUCCESS","message":"success","result":{"mappings":{"properties":{"details":{"type":"tangled_keyword2"},"sourcehostname":{"type":"tangled_keyword2"},"sourceip":{"type":"tangled_ip"},"sourcenetwork":{"type":"tangled_keyword2"},"sourceport":{"type":"tangled_integer"},"sourceusername":{"type":"tangled_keyword2"}}}}}

You can also verify existence of the schema in Panther/Panther service by checking:

curl

{"code":"SUCCESS","message":"success","result":{"mappings":{"properties":{"details":{"type":"tangled_keyword2"},"sourcehostname":{"type":"tangled_keyword2"},"sourceip":{"type":"tangled_ip"},"sourcenetwork":{"type":"tangled_keyword2"},"sourceport":{"type":"tangled_integer"},"sourceusername":{"type":"tangled_keyword2"}}}}}

Note that you can use a client of your choice (curl, postman, etc.) to manage and update mapping schemas. Refer to Panther/Panther service documentation for complete list and applicability of titaniam protect field types.