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 guide 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

• Fortanix DSM
  • Version 4.12 and above tested and recommended.
• Cortex XSOAR
  • Version 6.6.0 and above tested and recommended.

3.0 Authentication Methods

This integration supports the following authentication methods:

3.1 Username/Password or Certificate Authentication Method

These fields accept the username with the password or API key credentials corresponding to a Fortanix DSM application. Alternatively, the Fortanix DSM app may also be configured for certificate-based authentication using a client key and certificate. The client certificate may also be signed by a trusted CA if Fortanix DSM is configured accordingly. Copy the credentials of the Fortanix DSM app and keep it handy for configuration in Cortex XSOAR.
  Figure 1: Username and Password of a Fortanix DSM app

3.2 API Key Auth Method

An easy and quick way to test the integration is to specify the basic authentication token parameter from the Fortanix DSM App's API key. Create an App in Fortanix DSM and copy the API key of the app.
  Figure 2: App API key

4.0 Configure Data Security Manager 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.
     Figure 3: XSOAR marketplace - Fortanix DSM
2. Click the Install button on the top right corner of the screen. Figure 4: Install DSM
3. To find the Fortanix DSM instance, go to Settings > Integrations > Instances and filter by name or category. Figure 5: Find Fortanix DSM instance
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 DSMM app password. For client certificate authentication, the value is a non-encrypted PEM format of the private key.
   
   Figure 6: Configure new instance
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.
     Figure 7: Test instance Figure 8: Authentication error
   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

  Figure 9: Import new secret
• 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.
  Figure 10: List secrets Figure 11: List Secrets Figure 12: List Secrets 
• fortanix-fetch-secret
  Retrieve secret's confidential value based on a UUID.

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

  Figure 13: Retrieve secret value
• 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

  Figure 14: Update secret value
• 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

  Figure 15: Delete a secret
• fortanix-encrypt
  Protect sensitive information or data using a Fortanix DSM key with default cryptographic parameters.

  !fortanix-encrypt data="Hello World 123"

  Figure 16: Encryption
  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:
  

  Figure 17: Decryption
• 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=="}"