Configuration

Once installed, you need to edit the configuration file, which defines essential configuration settings for all Resilient® Circuits components running on the system. There is a [resilient] section in the configuration file that controls how the core Resilient Circuits and SOAR packages access the SOAR Platform.

As you install apps on the integration server, each app creates its own section within the configuration file, as described later in this guide.

NOTE: If the APP_CONFIG_FILE environment variable is not set, Resilient Circuits looks for a file called “app.config” in the local directory where the run command is launched.

Configuring proxy authentication

You can configure proxy server connections for both the integration server and apps.

You can configure a connection to a proxy server between the integration server and the SOAR Platform, and between an app and the SOAR Platform.

To set authentication, you need to know your proxy server settings, such as DNS name or IP address, port number, and account name (if necessary).

Integration server

You can configure integration server proxy connection with environmental variables. The environmental setting supersedes the proxy settings in the [resilient] section of the app.config files.

Configure the environment.

At the system that hosts the integration server, edit the environmental file to add the following variables.
```
HTTP_PROXY=<proxy>
HTTPS_PROXY=<proxy info>
NO_PROXY=<localhost and other ips that don't need proxy>
```
The following command is an example.
```
HTTP_PROXY=http://proxy.corp.com:8080
HTTPS_PROXY=http://proxy.corp.com:8080
NO_PROXY=localhost,127.0.0.1,0.0.0.0,localaddress,corp.com,10.0.0.0/8
```
The HTTP_PROXY and HTTPS_PROXY are redirects. You can have the HTTPS_PROXY redirect HTTPS traffic to an HTTP URL.

If you use the --no-proxy option to ignore the proxy server when connecting to your SOAR Platform, specify the fully qualified domain name (FQDN) or the IP address that is specified as the host in the app.config file. Wildcard and IP address ranges are not supported between the integration server and SOAR Platform.
At the SOAR Platform, update the system's cacerts to trust the CA certificate from the proxy itself by adding the certificate in PEM encoding to /etc/pki/ca-trust/source/anchors then run the following command.
```
sudo update-ca-trust
```
Restart the system.

Apps

To overwrite the environmental variables for a specific app, add the following code to the app’s section in the app.config file. Refer to the app's documentation for the detailed procedure.

[fn_my_app]
# To override, add any parameter to your specific integration section
http_proxy=<PROXY URL>
https_proxy=<PROXY URL>
timeout=120

Editing the configuration file

The resilient section of the app.config file contains the configuration settings that the app uses to interact with the IBM Security® QRadar® SOAR.

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.

Monitoring the config file for changes

You can configure Resilient Circuits to monitor the app.config file for changes. When it detects a change has been saved, it updates its connection to the SOAR Platform and notifies all components of the change. To enable this option, install the “watchdog” package.

pip3 install watchdog

Now you can run with:

resilient-circuits run –r

Without the –r option, changes to the app.config file have no impact on a running instance of Resilient Circuits. Note that not all components currently handle the reload event and may continue using the previous configuration until Resilient Circuits is restarted.

Configuring servers in an MSSP deployment

When the SOAR Platform has the MSSP add-on, there is a single configuration organization and multiple child organizations. You deploy all app packages to the configuration organization. An administrator then pushes to all the child organizations the apps and any additional SOAR components, such as functions, rules, workflows, custom fields, data tables, any layout changes needed for the apps.

You need to configure one integration server for the configuration organization and one integration server for each child organization, as follows:

Install and configure one integration server to connect to the SOAR configuration organization. This is the integration server that you use to deploy every app package used by any child organization. Specifically, this is the only integration server where you use the Resilient Circuits customize command.
Install and configure one integration server for each child organization. If you have five child organization then you need five integration servers, assuming that each child organization is running an app. This includes configuring the integration server’s app.config file to point to the correct SOAR organization and its dedicated SOAR account.
Install an app package on the integration server for the configuration organization.
Install an app package on each integration server whose child organization will be running that app.

Once you deploy an app from the integration server to the configuration organization, the system administrator pushes the app to all child organizations. You then use the integration server for each child organization to run and test the app.

NOTE: If you deploy an app to a child organization or change any SOAR component, such as a custom field, rule, workflow or function, your changes will be lost the next time the administrator performs a configuration push. Only make changes to the components in the configuration organization.

Updating your environment

When Resilient Circuits is updated, you can make sure you have the latest tools and Resilient Circuits framework by entering the following commands:

sudo pip3 install --upgrade pip
sudo pip3 install --upgrade setuptools
sudo pip3 install --upgrade resilient-circuits

Configuring SSL Certificates to use with the SOAR Platform

If the SOAR Platform does not have a trusted TLS certificate, you must provide the SOAR certificate in a file.

If you are in a production setting, get the certificate from a trusted source and confirm its fingerprint.

You can provide the untrusted certificate in a file, such as cacerts.pem by using openssl or the Java™ keytool command-line utilities.

If you are using openssl, use the following command to create the cacerts.pem file when on a Linux® or Mac system.

openssl s_client -connect SERVER:443 -showcerts -tls1 < /dev/null > cacerts.pem 2> /dev/null

If you are using keytool, use the following command on a Linux, Mac, or Windows system.

keytool -printcert -rfc -sslserver SERVER:443 > cacerts.pem

When the integration server connects to a SOAR Platform with the Python libraries, the hostname you specify must match exactly the name in the server certificate. If the names do not match, the permanent solution is to either change your DNS server or change the server certificate so it matches. It is also possible to modify your 'hosts' file temporarily, but that is not a permanent solution.