Customers can store their secrets (passwords, API keys, certificates, etc) in an external vault (such as Cyberark) and then pull them into the Chronicle SOAR platform.

The external vault can be configured to pull credentials in the following places: Integrations, Connectors and Jobs

The external vault is supported in two deployments: 

  • Cloud vault instance

  • On-prem vault instance (using remote agent)

Currently the SOAR platform only supports CyberArk PAM 

Use Cases

  • An Enterprise organization would like to pull their credentials from the organizational vault to prevent unauthorized use of passwords.

  • MSSP would like to pull their customer's credentials from the customer’s vault so that the MSSP won’t be exposed to the passwords.

How to download and configure the vault integration:

  1. Navigate to the Marketplace and install the relevant vault integration. In this example, we will use Cyberark PAM integration.
  2. Either configure the integration via the Marketplace just for the Default Environment. Or navigate to the Settings > Integration screen and configure it there for whichever environment you need.
  3. When working with an on-prem vault over a remote agent - all the 3rd party integrations (on-prem or cloud) need to be configured under the same remote agent (to make sure the agent has access to the on-prem vault).
    When working with cloud vault and on-prem integrations over agent - the agents need to have access to the cloud vault.

  4. Once saved, see below for further details as to how to use the vault credentials within other integrations. 

Details for adding Vault Secrets

In all the places where you want to use secrets, the following formula will be used:

Secrets Formula:

[EnvironmentName:::VaultIntegrationName:::VaultIntegrationInstanceName:::PasswordID]

Environment Name = the environment that you configured it on - you can find this information in Settings > Integrations

VaultIntegrationName = the name of the Vault Integration that you downloaded from the Marketplace

VaultIntegrationInstanceName = the name of the Vault Instance (ie the name of the integration on the environment)- which you can find on Settings > Integrations

PasswordID = this is copied from the Vault directory itself

Example: [Default Environment:::CyberArkPAM:::CyberArkPAM_1:::33_3]

Configure Integration with Vault password

For this example, we will use the Email integration which has been installed from the Marketplace. 

  1. Navigate to Settings > Integrations.
  2. Choose the required environment that you want to configure the integration on.
  3. On the right of the screen, click the plus icon and select the Email integration from the drop down list.
  4. Configure the parameters according to your needs. In the password section, add the following:
    [DefaultEnvironment:::CyberArkPAM:::CyberArkPAM_1:::33_3].
    Please note that the password field censors the password and therefore it is recommended to create the syntax on a plain text field first and copy it to the password field

  5. Make sure to select the Remote Agent Run Remotely checkbox as CyberArk PAM is an on-prem vault. 
  6. Click Save. During run time the platform will take the corresponding password from the external vault.

    Please note  
    • If you are working with an on-prem vault and on-prem integration OR on-prem vault and cloud integration - make sure both of them are configured as “run remote” using the same agent.

    • If you are working with a cloud vault and on-prem integration - make sure that remote agent has access to the cloud vault.

Configure Connector with Vault password

  1. Navigate to Settings > Connectors.
  2. Click the plus icon and create a new Connector. Let's choose the Generic Email connector.
  3. Configure the Connector with the relevant parameters. In the password field add [Default Environment:::CyberArkPAM:::CyberArkPAM_1:::33_3]

Configure Job with Vault password

  • Navigate to Settings > Jobs.
  • Click the plus icon and create a new Job with the relevant integration. For this example, we selected the Google Chronicle Sync Job.
  • Configure the job as usual. In the API Root field use the Vault parameters.

To create a custom integration to work with an external vault

Actions can pull credentials from external vault by configuring the relevant integration parameter with the external vault syntax

Use the following snippet on your code (Param A should contain the vault pattern) 

integration_param = siemplify.extract_configuration_param(provider_name=INTEGRATION_NAME,param_name="Param A")

Connectors can pull credentials from external vault by configuring  the relevant connector parameters with the external vault syntax.

Use the following snippet on your code (Param B should contain the vault pattern) 

connector_param = siemplify.extract_connector_param("Param B", default_value=None, input_type=str)

Jobs can pull credentials from external vault by configuring the relevant job param with the external vault syntax.

Use the following snippet on your code (Param C should contain the vault pattern) -

job_param = siemplify.extract_job_param(param_name="Param C", print_value=True)

If you have configured the vault configuration as integration in “Shared instances” - you can pull the credentials from the integration configuration instead of the job configuration using the following snippet (Param A should contain the vault pattern)   

integration_param = siemplify.extract_configuration_param(provider_name=INTEGRATION_NAME,param_name="Param A")

Additional information 

  • The external vault can work only with a commercial vault integration downloaded from the Chronicle SOAR marketplace.

  • If you update the vault settings (vault instance configuration), the actions, jobs and connectors will be updated as well with the new credentials automatically.

  • There is a server validation for the vault placeholder. You will be able to use the placeholder and save it only if there is an existing vault instance, and you have permissions to the vault instance environment. 

  • External vault over agent is supported only in agent version greater than 1.4.1.52

Known Limitations

For users creating their own custom vault integration using the vault credential feature, the version of dependencies being used must be exactly as stated in the table below: 

DependenciesPython 2.7 / Python 3.7
requests
2.25.1
urllib3
1.26.2
six1.15.0
requests_toolbelt
0.10.1
pyOpenSSL
19.1.0
pycparser
2.20
idna2.10
cryptography
3.3.1
chardet
4.0.0
cffi
1.14.4
certifi
2020.12.5
importlib-metadata
2.1.3 (Python 2.7), 4.12.0
(Python 3.7)