Working with an external Vault system

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)

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.
    externalvault1
  2. Either configure the integration via the Marketplace just for the Default Environment. Or, from the left navigation, navigate to Response > Integrations Setup 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. From the left navigation, navigate to the Integrations screen by clicking on Response > Integrations Setup.
  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.
    externalvault2
  4. Configure the parameters according to your needs. In the password section, add the following:
    [DefaultEnvironment:::CyberArkPAM:::CyberArkPAM_1:::33_3].
  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 > Ingestion > 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]

externalvault3

Configure Job with Vault password

  • From the left navigation, navigate to Response > Jobs Scheduler.
  • 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.
    externalvault4

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:

Dependencies Python 2.7 / Python 3.7
requests
 2.25.1
urllib3
 1.26.2
six 1.15.0
requests_toolbelt
 0.10.1
pyOpenSSL
 19.1.0
pycparser
 2.20
idna 2.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)