App packages

The integration server uses the Resilient® Circuits framework as the runtime environment for apps. After Resilient Circuits is installed and running, you can install app packages on your integration server.

App packages can help you augment and extend the functionality of the IBM Security® QRadar® SOAR Platform.

Installing the app creates a new section in the app.config file. After the app is installed, you must update the configuration file as specified in the app documentation. After the app is configured, you deploy it to the SOAR Platform. The app documentation also provides information on how to customize and use the app after it is deployed.

Installing an app package on the SOAR Platform

You can install app packages on your IBM Security QRadar SOAR Platform integration server.

Note: In an MSSP environment, you must install the app on the integration server that deploys to configuration organization. The app is also required on each integration server that is connected to a child organization that runs that app.

Before you begin

Download the app package that you want to install. You can download packages from either the IBM Security SOAR Community or IBM X-Force® App Exchange. Typically, the packages are in tar.gz format.

Note: Some app packages might require a newer version of resilient-circuits than what is installed on the integration server.

When you install the app, resilient-circuits on the integration server is automatically upgraded, which might cause older apps to behave unexpectedly. Before you install the app, you can upgrade resilient-circuits on the integration server and test your existing apps.

You can upgrade resilient-circuits by typing this command: pip3 install -U resilient-circuits

Procedure

If you are not logged in using the integration user account, you need to run the following commands by using sudo.

Use SSH to connect to the integration server.
Go to the folder where the package is located and extract the file.
Install the package.
```
pip3 install -–user <package_filename>.tar.gz
```
The --user parameter ensures that the libraries are installed in the home directory of the integration user that you are logged in as. Installing the libraries in the home directory avoids conflicts with other Python libraries in the system directory.
Verify that the component is installed.
```
pip3 list
```
After you install the package, run the following command to update the app configuration.
This command adds a section with default values in the app.config file.
```
resilient-circuits config –u
```
Alternately, you can specify which packages to update in the app.config file.
```
resilient-circuits config –u –l <package1> <package2>
```
If you are using an alternative file location for your app.config file, you need to specify the path when you run the update command.
```
resilient-circuits config –u /<folder_path>/app.config
```
Follow the instructions in the app documentation to edit the app.config file.
Depending on the requirements of the app, you might need to modify the default values to fit your environment, such as credentials to a third-party system.

What to do next

Deploy the application to the SOAR Platform. For more information, see Deploying an app package on the SOAR Platform.

Upgrading an app package on the SOAR Platform

Upgrading a package is similar to installing a new package, except that you use the –U option in the install command.

Procedure

If you are not logged in using the integration user account, you need to run the following commands by using sudo.

Use SSH to connect to the integration server.
Go to the folder where the package is located and extract the file.
Install the package.
```
pip3 install -U -–user <package_filename>.tar.gz
```
The --user parameter ensures that the libraries are installed in the home directory of the integration user that you are logged in as. Installing the libraries in the home directory avoids conflicts with other Python libraries in the system directory.
Verify that the component is installed.
```
pip3 list
```
After you install the package, run the following command to update the app configuration.
This command adds a section with default values in the app.config file.
```
resilient-circuits config –u
```
Alternately, you can specify which packages to update in the app.config file.
```
resilient-circuits config –u –l <package1> <package2>
```
If you are using an alternative file location for your app.config file, you need to specify the path when you run the update command.
```
resilient-circuits config –u /<folder_path>/app.config
```
Follow the instructions in the app documentation to edit the app.config file.
Depending on the requirements of the app, you might need to modify the default values to fit your environment, such as credentials to a third-party system.

Deploying an app package on the SOAR Platform

Use the customize command to deploy a package. If you make changes and redeploy a package, the deployment overwrites the existing components.

Note: In an MSSP environment, you must use the integration server that deploys to the configuration organization. The system administrator then pushes to app to the appropriate child organizations.

To run and test the app, you use the integration server that is connected to the child organization. If more than one child organization uses the app, you must test each one individually by using that organization’s integration server.

Procedure

To deploy the components in a package to the SOAR Platform, type this command.
```
resilient-circuits customize
```
Alternatively, you can install a specific package.
```
resilient-circuits customize –l <package_name>
```
You are prompted to deploy the components, such as functions, message destinations, workflows, and rules. If you do not want to be prompted, you can use the -y parameter.
If your package has multiple functions, you can specify which functions to deploy.
```
resilient-circuits customize –l <function_name1> <function_name2>
```