Using Fortanix Data Security Manager with Cortex XSOAR

1.0 Introduction

This article describes how to integrate Fortanix-Data-Security-Manager (DSM) with Cortex XSOAR, which is a comprehensive security orchestration, automation, and response platform offered by Palo Alto Networks. This integration allows XSOAR users to fetch secrets from Fortanix DSM or perform other cryptographic operations in XSOAR through Fortanix DSM.

This article contains the information that an XSOAR administrator and/or user needs to:

• Configure a Fortanix DSM integration instance on Cortex XSOAR.

• Execute Fortanix DSM commands in the Cortex XSOAR Playground War Room.

• Reference: Cortex XSOAR Marketplace listing at https://cortex.marketplace.pan.dev/marketplace/details/FortanixDSM/ 

1.1 Why Use Fortanix DSM with Cortex XSOAR

Cortex XSOAR helps organizations streamline their security operations. In this capacity, there is often a need to leverage sensitive material like secrets in the form of credentials and encrypt or decrypt passwords. Fortanix DSM is a NIST-certified FIPS 140-2 Level 3 HSM and is designed for modern development, security, and operations (DevSecOps). XSOAR users can not only leverage secrets in their favourite Playground War Room but also perform advanced cryptographic operations like encryption and decryption using industry-standard AES-256 algorithms like GCM or tokenization using Format-Preserving Encryption (FPE). Unique to Fortanix is its ability to perform complex operations inside the HSM secure enclave using the Fortanix DSM plugin.

2.0 Prerequisites

Ensure the following:

• Fortanix DSM version 4.12 and above tested and recommended.

• Cortex XSOAR version 6.6.0 and above tested and recommended.

3.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

3.1 Signing Up

To get started with the Fortanix Data Security Manager (DSM) cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

3.2 Creating an Account

Access the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM.

3.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. Click the Groups menu item in the DSM left navigation bar and click the + button on the Groups page to add a new group.

   

2. On the Adding new group page, enter the following details:

   • Title: Enter a title for your group.

   • Description (optional): Enter a short description for the group.

3. Click the SAVE button to create the new group.

The new group has been added to the Fortanix DSM successfully.

3.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation bar and click the + button on the Apps page to add a new app.

   

2. On the Adding new app page, enter the following details:

   • App name: Enter the name of your application.

   • ADD DESCRIPTION (optional): Enter a short description for the application.

   • Authentication method: Select the default API Key as the method of authentication from the drop down menu. For more information on these authentication methods, refer to User's Guide: Authentication documentation.

   • Assigning the new app to groups: Select the group created in Section 3.3: Creating a Group from the list.

3. Click the SAVE button to add the new application.

The new application has been added to the Fortanix DSM successfully.

3.5 Copying the App UUID

Perform the following steps to copy the app UUID from the Fortanix DSM:

1. Click the Apps menu item in the DSM left navigation bar and click the app created in Section 3.4: Creating an Application to go to the detailed view of the app.

2. On the INFO tab, click the VIEW API KEY DETAILS button.

3. Click the USERNAME/PASSWORD tab.

4. From the Credentials Details dialog box, copy the Username (app UUID) and Password to be used in Section 4.0: Configure DSM on Cortex XSOAR.

4.0 Configure DSM on Cortex XSOAR

The following are the steps to configure Fortanix DSM within the Cortex XSOAR portal:

1. Log in as an XSOAR administrator and navigate to Marketplace. Narrow the search by Categories → Authentication and Identity Management and select Fortanix DSM.

   

2. Click the Install button on the top right corner of the screen.  

   

3. To find the Fortanix DSM instance, go to Settings → Integrations → Instances and filter by name or category.  

   

4. Add a new instance, and then use the following parameters to set up the Fortanix DSM connection and credentials:

   • Fortanix DSM server endpoint: This is the on-premises or SaaS Fortanix DSM URL. For SaaS use https://amer.smartkey.io, where “amer” may be replaced by your region.

   • Switch to credentials: Click this for API key authentication instead of username/password or certificate authentication.

   • Username/App UUID/Certificate: The Fortanix DSM app username. This may also be the client certificate in PEM format without any line breaks. Please copy the entire certificate chain if using a private Certificate Authority (CA).

   • Password/App Secret/Private Key: The Fortanix DSM app password. For client certificate authentication, the value is a non-encrypted PEM format of the private key.

   

5. Click the Test button to verify the Fortanix DSM App credentials. You may click the “Run advanced test and download a full report” link if the test fails to download the debug log and verify any authentication errors from the log messages.

   

   

   After you have had success configuring the integration instance, go ahead and click the Save and exit or Save button. You are now ready to use the Fortanix DSM integration within the Cortex XSOAR Playground War Room.
   Other optional settings are available for each integration instance as follows:

   • Trust any certificate (not secure): This allows for a private CA certificate used and presented by the Fortanix DSM server to be trusted by Cortex XSOAR.

   • Use system proxy settings: This allows for the leveraging of any system or environment HTTP proxy settings within the Cortex XSOAR server so the integration instance can connect to the Fortanix DSM URL.

   • Group UUID to list secrets from: Limit the scope of the integration commands to a single Fortanix DSM group. This may be helpful if there are multiple DSM groups and a default needs to be specified for Cortex XSOAR command execution.

   • Data protection key used for encryption and decryption: The Fortanix DSM Security-object corresponding to an AES-256 or FPE tokenization key name. This is relevant for the !fortanix-encrypt and !fortanix-decrypt.

   • Encryption and decryption mode: This is cipher mode, where options are FPE, CBC, and GCM based on the use case at hand.

5.0 Usage Commands

The integration supports the following Cortex XSOAR commands for execution:

• fortanix-new-secret
  Import a new secret, along with its confidential value, into the Fortanix DSM app's default or a specified group, if any.

  !fortanix-new-secret value="Top Secret !3$8" name=metasec metadata="key1=value1, key2=meta2,key3="whats that",key 4=nothin new" group_id=07f85883-adaf-4a6c-a040-ffed46dfd349

  

• fortanix-list-secrets
  Lists all secrets from the Fortanix DSM App's member groups or a specified group, if specified.

  !fortanix-list-secrets
  !fortanix-list-secrets group_id=aedc4bd0-2880-4191-8f38-043fce5ee97
  

  NOTE

  use the optional command parameters like state, group_id, or page to filter and locate specific secrets.

  

  

  

• fortanix-fetch-secret
  Retrieve secret's confidential value based on a UUID.

  !fortanix-fetch-secret kid=4bd14880-522d-4c34-8560-617e0fb6485b

  

• fortanix-get-secret-metadata
  Get the metadata of a single secret based on its name or UUID, as specified.

  !fortanix-get-secret-metadata name="Test Secret"
  !fortanix-get-secret-metadata kid=09299af7-0d69-4091-9dc7-27d426667847
  

• fortanix-rotate-secret
  Update an existing secret's confidential value by rotating out of it and obtaining a new UUID.

  !fortanix-rotate-secret value="Fib0nac!I !3$8" name=metasec metadata="key1=value01,key2=meta2a,key3="whats that",key 4=nothin new" group_id=07f85883-adaf-4a6c-a040-ffed46dfd349

  

• fortanix-delete-secret
  Delete an existing secret. This may be revocable if there is a Key Undo policy applied on the group.

  !fortanix-delete-secret kid=30d7286a-ad4c-4cb3-8bb1-0f9265e0adfc

  

• fortanix-encrypt
  Protect sensitive information or data using a Fortanix DSM key with default cryptographic parameters.

  !fortanix-encrypt data="Hello World 123"

  

  NOTE

  • If the key and mode are specified in the integration instance configuration, then these parameters may be skipped during the command execution, otherwise they need to be specified.

  • Also note that the resulting cipher encapsulates the key reference (Fortanix DSM Security Object UUID or KID) along with the cipher mode and the Initialization Vector (IV) or Nonce.

• fortanix-decrypt
  Reveal sensitive information or data using a Fortanix DSM key with default cryptographic parameters.

  !fortanix-decrypt cipher=eyJraWQiOiAiY2E5ZTJiMGYtNzFjNC00ZjNiLWJhYTYtNGM1YWY5YTM5N2YwIiwgImNpcGhlciI6ICJqcGxqVUk2S2tIb3drbHhhdG1MWXVBPT0iLCAiaXYiOiAidDFJczFWUTR3TlRFOThLZHR2aUlWZz09IiwgIm1vZGUiOiAiQ0JDIn0=
  !fortanix-decrypt cipher=u2KMcAUF1jsifJfh99uWqw== iv=r7HeHduHSZ1IrCC6s7MG0w==
  !fortanix-decrypt kid=ca9e2b0f-71c4-4f3b-baa6-4c5af9a397f0 cipher=u2KMcAUF1jsifJfh99uWqw== iv=r7HeHduHSZ1IrCC6s7MG0w== configuration:
  

  

• fortanix-invoke-plugin
  Execute Lua code through a Fortanix plugin running on Fortanix DSM using Confidential Computing. This requires the plugin's UUID and an arbitrary user input based on the plugin's functionality.

  !fortanix-invoke-plugin pid=3599796b-7b18-49c3-aad8-9758af24fbf9
  !fortanix-invoke-plugin pid=3599796b-7b18-49c3-aad8-9758af24fbf9 input="Hello World Oct 29"
  !fortanix-invoke-plugin pid=c6a5351e-d516-4099-b5c9-be00c6967a53 input=ewogICJjYV9rZXkiOiAiU1NIQ0EtUHJpdmF0ZS1LZXktRWQyNTUxOSIsCiAgInB1YmtleSI6ICJBQUFBRTJWalpITmhMWE5vWVRJdGJtbHpkSEF5TlRZQUFBQUlibWx6ZEhBeU5UWUFBQUJCQkt0R3dTeFhWdU4zbXFkaE9YNXozVjBNT243MkRJNWNQQThzSXBTemJSVjZnNTNRYW0yVzNNaW1JdlNaazkxL2x4aFNXRE82RmUxQXVqYy9VQ2VCc3lNPSIsCiAgImNlcnRfbGlmZXRpbWUiOiAzNjAwLAogICJ2YWxpZF9wcmluY2lwYWxzIjogInVidW50dSIsCiAgImNlcnRfdHlwZSI6ICJ1c2VyIiwKICAiY3JpdGljYWxfZXh0ZW5zaW9ucyI6IHt9LAogICJleHRlbnNpb25zIjogewogICAgInBlcm1pdC1wdHkiOiAiIgogIH0KfQo=
  !fortanix-invoke-plugin pid=3599796b-7b18-49c3-aad8-9758af24fbf9 input="{"iv":"DaRIkBoCaAPqpGSczBeVGQ==","kid":"3451bf0b-1728-4b9a-9859-f1c6bd0d8652","op":"decrypt","cipher":"ZmHxqmbgYGAtauvCnco7EA=="}"