Advanced configuration settings

The [resilient] section of the app.config file contains the settings that the app uses when it interacts with the SOAR Platform. You can also configure each specific app to skip the default SSL verification on the app's REST connection to a third party endpoint.

Configuring default SSL verification for apps

You can change the default SSL verification on an app's REST connection to a third party endpoint to handle a self-signed certificate.

For each app, you can change the certificate verification behavior from the default certificate authority chain to a custom chain, or to skip verification entirely. Use the verify option in the app's app.config file to change the certificate verification behavior. By default, when verify is unset or set to True, the Python certifi's PEM chain is used to verify connections. This allows connections to any server with SSL that has a certificate signed by a trusted, well-known certificate authority.

In the upper part of the app's app.config file, set the verify option to specify the path to PEM file that provides the list of trusted certificate authorities for SSL verification when the SOAR Platform is using trusted self-signed certificates. If you are not using a trusted certificate, set the verify parameter to False.

CAUTION:

Use verify=False with caution as this might allow untrusted endpoints to receive SSL requests from apps, without verifying the identity of the endpoint.

The following example shows the verify setting in an app.config file.

Note: The cafile settings in the [resilient] section of the app.config file, described below, is used for the same purpose as the verify setting, but for connecting to the SOAR Platform rather than a third party endpoint.

Configuring app settings for interaction with the SOAR Platform

Configure the [resilient] section of the app.config file for the settings that the app uses to communicate with the SOAR Platform.

To edit the configuration file, follow these steps:

Using a text editor of your choice, open the app.config file.
If you are using a Windows system and you edit the file with Notepad, save the file as type All Files. Using this file type prevents the editor from appending an extra app to the app.config file name. Also, use UTF-8 encoding.
Update the [resilient] section with your SOAR Platform hostname or IP address, credentials, and the absolute path to the logs directory you created.
Use the following table to set other configuration parameters.

The following table describes all the required and optional values that can be included in the [resilient] section of the app.config file.

Parameter	Description
api_key_id	The ID for the API key account that is used for authenticating to the SOAR Platform. The ID is a long string, which is provided by the system administrator. It is a required parameter, unless you are using a user account. If you enter values for both the user account fields and the API Key account fields, the API key account is used by default. The parameter is available only with V33 or later of the SOAR Platform and `resilient-circuits`. It is not valid for integration servers that are connected to the SOAR Platform by using the SOAR for MSSPs add-on.
api_key_secret	The secret for the API key account. The secret is provided by the system administrator and must be entered in the app.config file.
cafile	The path and file name of the PEM file that provides the list of trusted certificate authorities for SSL verification when the SOAR Platform is using untrusted self-signed certificates. If not using a trusted certificate, the `cafile` parameter must be set to `False`. If a PEM file exists, use a second instance of `cafile`: If set to `False`, the PEM file is used and certificates are not verified. If set to `True` (default), only trusted certificates are allowed.
client_auth_cert	The path to the client-side certificate. You need a client-side certificate when you use a reverse proxy or other security components to secure the SOAR Platform REST API with client certificate authentication.
client_auth_key	The path to the private key that is associated to the client-side certificate. The Integration Server does not support combined certificate and private key files for client-side certificate authentication.
componentsdir	The path to the directory that contains extra Python modules. Typically, this option is used only by app developers. `resilient-circuits` can load extra components from this directory.
email	The user account that is used for authenticating to the SOAR Platform. For best results, use an account that is dedicated to the app. This parameter is required, unless you are using a user account.
heartbeat_timeout_threshold	The value, in seconds, between the current `HeartbeatTimeout` event and the first `HeartbeatTimeout` event. If the time is greater than the `heartbeat_timeout_threshold`, the `resilient-circuits` process stops and initiates a restart.
host	(Required) The IP address or hostname for the SOAR Platform.
logfile	The name of the rotating `logfile` that is written to the `logdir` directory. The default value is `app.log`.
logdir	The path to the directory to store the log files. If the logdir parameter is not specified, the environment variable `DEFAULT_LOG_DIR` is used to set the path. If the `DEFAULT_LOG_DIR` environment variable is not set, the system defaults to a directory called log that is located wherever `resilient-circuits` is started.
loglevel	The level of log messages that are written to `stdout` and the `logfile`. Levels are `CRITICAL`, `ERROR`, `WARN`, `INFO` (default), and `DEBUG`.
max_connection_retries	The number of attempts to retry when connection to the SOAR Platform. The default value is `-1`, which indicates unlimited retries.
noload	(Optional) A comma-separated list of the components, and the module names in the `componentsdir`, that are not to be loaded. For example, the noload list might include the `my_module`, `my_other_module`, `InstalledComponentX` components.
no_prompt_password	Specifies whether the user is prompted for a password. If set to `False` and the password parameter is not set, the user is prompted for a password. If set to `True`, the user is not prompted. The default value is `False`.
num_workers	Specifies the number of functions that are processed concurrently by the integration server. The range is 1 - 500, and the default is 50. Setting the value too high can cause performance issues. Increase the value only in situations where the app must wait several minutes to receive a message from its message destination.
org	(Required) The name or UUID of the SOAR organization. For IBM Cloud Pak® for Security customers, this parameter also supports the cloud account ID.
password	The password for the user account.
proxy_host	The IP address or hostname for Proxy to use for STOMP connection. By default, no proxy is used.
proxy_password	The password for authentication to Proxy to use for STOMP connection. Used with the proxy_user parameter.
proxy_port	The port number for Proxy to use for STOMP connection. By default, no proxy is used.
proxy_user	The username for authentication to Proxy to use for STOMP connection. If proxy_host is specified and no proxy_user is specified, then it is assumed that no authentication is needed.
request_max_retries	The maximum number of attempts to retry a request to SOAR Platform before exiting. The default value is `5`.
request_retry_delay	The number of seconds to wait between repeated attempts to connect to the SOAR Platform. The default value is `2`.
request_retry_backoff	The multiplier that is applied to delay between repeated attempts to connect to the SOAR Platform. The default value is `2`.
selftest_timeout	Specifies the number of seconds to wait for a response from the SOAR Platform. This value includes the time that it takes for `resilient-circuits` to start, authenticate with the platform, and subscribe to a message destination. The default value is 10 seconds. Increase the time only if the network experiences delays and you see `Could not subscribe to any message destinations` errors, or an exit error code of 33.
stomp_port	The port number for STOMP. The default port is 65001.
stomp_timeout	The time, in seconds, to wait for a connection to be established. This parameter is useful if your SOAR Platform is experiencing delayed responsiveness. The default value is 120.
trap_exception	Specifies whether a playbook or function is stopped when an app raises an exception error. When set to `True`, the playbook or function does not stop. It sends a status message and logs the error. When set to `False`, the function or playbook stops.

Setting parameters by using environment variables

You can use environment variables to set parameter values in the resilient section of the app.config file.

For example, to set the api_key_secret parameter to the same value as the resilient_secret environment variable, follow these steps:

Define resilient_secret as an environment variable by typing this command on the command line or by using it in a shell script:
```
export resilient_secret=Passw0rd
```
Add the following entry to the app.config file:
```
[resilient]
api_key_secret=$resilient_secret
```

The $ indicates to resilient-circuits that it needs to convert the environment variable and use its value to set the api_key_secret parameter.