Testing the app

You can test the functions separately and test the app as a whole for proper permissions and connectivity.

You can test your functions individually on the SOAR Platform before creating the app to ensure that the components are working as expected. The Testing a function topic in the Playbook Designer Guide includes an example of how to test functions.

Before you can test the app, you must build it as described in Packaging your app.

Once you build the app, you can create a container on your local system then connect with a SOAR organization. To do this, you must have access to a SOAR Platform with an account that has the permissions required by your app. This test is to ensure that the permissions have been set correctly and there is communication with the message destination. If your app uses API calls, you should attempt to make that call to exercise.

Before running the app, you must install this package. The most convenient way to install during development is with pip’s editable flag (or -e). Using this, you can edit your source files directly without needing to reinstall after any changes.

pip3 install --editable ./pckg_name/

Create your docker image. From within your development folder, run:

docker build . -t resilient/<fn_example>:1.0.0

Run the app code from the command-line, as follows. The framework reads your configuration file, connects to the SOAR Platform, finds and loads all the installed components, then subscribes to the message destination for each function processor component. Leave it running; when a function is invoked, the code handles it.

docker run -v /path/to/your/local/app.config:/etc/rescircuits/app.config resilient/fn_example:1.0.0

The -v flag in the command mounts your local app.config file into the container, so that Resilient® Circuits is aware of the settings that you have configured locally. When you run this command, you should see Resilient Circuits initialize, load the relevant functions for your app, subscribe to the message destination, and run successfully.

The app.config file contains parameters for your app that are subject to change or provide tuning of application settings such as timeout values. You may need to adjust those settings, as described in Configuration settings.

You can test connectivity by installing your app on the SOAR Platform. You do not need an App Host . Log in to the SOAR Platform as an administrator, go to Administrator Settings and click the Apps tab. Install the app. When done, click the app and click it's Configuration tab. Click app.config. At the bottom of the App Settings page, click the Test Configuration button. For details about navigating the Apps tab, see Managing SOAR apps.

NOTE: If you have an integration server, you can use this environment to test your app using the Resilient Circuits selftest command.

If there are any changes to your app, update the app as follows:

resilient-sdk codegen --reload -p <app_name>

If you wish to test it again, you need to run the docker command to reload the container.

docker run -v /path/to/your/local/app.config:/etc/rescircuits/app.config resilient/fn_example:1.0.0

Configuration settings

The resilient section of the app.config file contains the configuration settings that the app uses to interact with the IBM Security QRadar 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.

Documenting your app

IBM Security strongly recommends that you create an installation guide and a user guide, where the latter describes the function and all of its various components.

After you have tested your app, use the SOAR SDK docgen command, which guides you through the process of creating the installation and user guides. Enter the following command to start the process:

resilient-sdk docgen

The document files are placed in a subfolder called Docs.

If your package contains custom fields and data tables, make sure to document that the playbook designer should include these in the incident layouts, because the fields and data tables cannot be automatically added to layouts. When possible, provide details on the intended incident layouts, such as a New Incident Wizard or a specific incident tab.

You should also document that re-importing a function’s custom fields and custom data tables does not restore any layout changes made. Therefore, the layout changes might need to be recreated.