Skip to main content

TitaniamProtect

This Integration is part of the TitaniamProtect Pack.#

Overview#

This integration lets you protect incident data inside the Cortex XSOAR platform. This documentation explains how to install and setup Titaniam Protect Content Pack. The process involves two steps.

  1. Install and configure Titaniam Translation Service (aka 'Panther'). This is done outside Cortex XSOAR. Reach out to your Titaniam support contact to get the installation artifacts and license file.
  2. Install Titaniam Protect Content Pack. Create an integration instance and configure it to communicate to the Titaniam Translation Service.

Install Titaniam Translation Service.#

To install API Service follow ONE of these two installation instructions:

  1. Trial: If you are evaluating Titaniam Protect Content Pack, install Titaniam Server by following this Quick Installation Guide. Follow the non-BYOK path. Choose keystore as Hashicorp Vault, AWS Secrets Manager or Azure Blob.
  2. Production: If you are installing Titaniam Translation Service for production purposes, follow the Production Installation Guide. The key difference is Production Installations are highly-available.

Note down the URL of the Translation Service instance. In the subsequent sections this is referred to as <baseURL>.

Configure Titaniam Translation Service#

Titaniam Translation service allows you to encrypt and decrypt JSON documents based on pre-defined schemas. See Titaniam API Guide for more information on how to create schema.

Create a schema in the Translation Service for each class of incidents you want to secure. A schema in Translation Service is nothing but a list of fields that need to be encrypted or decrypted.

For each type of incident you want to secure identify the set of fields you want to secure. For example the feed from your Splunk Enterprise Server or Microsoft Outlook may create an incident with 100s of fields. But you may just want to secure a small subset of them - i.e. the sensitive ones, say just two or three fields. Identify which fields are sensitive. Create a schema with just these fields. Example:

curl --location --request POST '<baseURL>:8080/schema/emailtest/1.0' \
--header 'Content-Type: application/json' \
--data-raw '
{ "mappings":
{ "properties":
{
"email-from": {"type": "encrypted_keyword"},
"email-to": {"type": "encrypted_keyword"},
"email-cc": {"type": "encrypted_keyword"},
"email-body": {"type": "encrypted_keyword"},
"email-date": {"type": "tangled_date"}
}
}
}'

Install and Configure TitaniamProtect Content Pack within Cortex XSOAR#

Install “TitaniamProtect” Content Pack from Marketplace#

Installation includes:

  • TitaniamProtect integration

  • “Titaniam Protect” incident type

  • ProtectedFields custom field

  • “Titaniam Protect” custom layout

  • TitaniamProtectIncident Automation (python script)

  • TitaniamFindIncidents Automation (python script)

  • TitaniamProtectField Automation (python script)

  • TitaniamPreProcessRule Automation (python script)

  • TitaniamSync playbook

  • TitaniamRollback playbook

  • TitaniamProtect playbook

    Configure Integration instance.#

    Note: This is just a broad overview. There is a detail section below for your reference.

  • Specify URL for Titaniam Translation Service (for example: https://<baseURL>.com:8080 or https://<baseURL>.com:8443).

  • Specify credentials (certificate information, if any).

  • Authentication

    • If you are evaluating, check the "Trust any certificate" box.
    • If it is production installation and if you are securing the Translation Service with a MTLS authentication, then add the certificates and uncheck the "Trust any certificate" box.

  • Test connection.

Map XSOAR Incident Type to Translation Service Schemas#

In this configuration you would be declaring what types of incidents should be protected using which schema in translation service. In essence this is a mapping table.

In the mapping, you can refer to incidents by its

  • Source Brand OR
  • Source Brand and Source Instance OR
  • Source Brand, Source Instance and Incident Type

Source Brand is the type of system (essentially an integration pack) which is used to import incidents. There may be multiple instances of this integration. For example you may use one Elasticsearch content pack to import incidents from multiple Elasticsearch instances (i.e. different source instances). And it is possible to create incidents of different types within a source brand. Titaniam Protect content packs allows you to be most generic (just specify source brand) or most specific (specify all three - source brand, source instance and incident type) when associating schemas. The following are valid combinations of the fields.

  • All three: If "brand, sourceInstance and type" are matched -> Super High priority
  • Two of three: If "brand, sourceInstance" are matched -> High priority
  • Two of three: If "brand, type" are matched -> Medium priority
  • Only one: If only "brand" is matched -> Low priority
  • Navigate to Settings > Advanced > Lists. Click on “Add a List” button to create new list.

Setup Account

  • Create a new List .

    • Name the list as “TitaniamMappingSchema”
    • Copy/paste following placeholder JSON content into “Data” text area field. Update it to reflect your reality.
    [
    {
    "brand": "Manual",
    "schemaName": "titaniamPhishingContextSchema",
    "schemaVersion": "1.0",
    "contextSchemaName": "titaniamPhishingContextSchema",
    "contextSchemaVersion": "1.0"
    },
    {
    "brand": "Mail Listener v2",
    "schemaName": "mail_listener_phishing_incident",
    "schemaVersion": "1.0",
    "contextSchemaName": "mail_listener_phishing_incident",
    "contextSchemaVersion": "1.0"
    },
    {
    "brand": "Mail Listener v2",
    "type": "Phishing",
    "sourceInstance": "TitaniamPanIntegration",
    "schemaName": "mail_listener_phishing_incident",
    "schemaVersion": "2.0",
    "contextSchemaName": "mail_listener_phishing_incident",
    "contextSchemaVersion": "2.0"
    }
    ]

Each incident has two DOM (Document Object Model) graphs - Incident data and Incident context data. Sometimes there are more fields in the context data that are not present in the incident data. To make the protection comprehensive the content pack allows you to specify different encryption schemas for the two.

The Schema Version by convention needs to be integers that end with a '.0'. So "1.0" and "2.0" are valid schema numbers. Whereas "10" or "1.1" are not valid schema numbers.

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 the Roles that can Decrypt the Protected Data#

TitaniamProtect Content Pack is typically configured to encrypt sensitive incidents as soon as they are created using Pre-processing rules. Later on you can enable privileged users (like administrators) to decrypt the protected incidents. You can declare the application roles that can decrypt protect incident in a List. To do this:

  • Create a list with name: “TitaniamAllowedRoles” Setup Account

  • Add the application roles (such as "Administrator" and "Analyst") who should be able to decode and see the values in clear text

    {
    "decode": ["Administrator", "Analyst"]
    }

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
ignore_failureFlag to ignore decryption failure on Panther (true | false). By default false.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}\"}" ignore_failure=true

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.

Report an Issue