Introduction

Apps make security alerts instantly actionable, provides valuable intelligence and incident context, and enables adaptive response to complex cyber threats.

Use this guide to learn about writing apps that integrate the IBM Security® QRadar® SOAR Platform with your organization’s existing security and IT investments.

This guide is intended for programmers, testers, architects and technical managers interested in developing and testing apps with the SOAR Platform. It assumes a general understanding of the SOAR Platform, especially the playbook toolkit, message-oriented middleware (MOM) systems, and a knowledge of writing scripts in Python.

What is an app?

An app extends the capabilities of the SOAR Platform by providing access to remote code or applications.

An app is a collection of customizations, code executables or both that represent an end-to-end function. A customization is a tool within the playbook toolkit that can act upon, supplement or contain data. Customizations include functions, message destinations, tasks, notes, artifacts, and scripts.

Typically, an app is based on one or more functions. A function is an object that sends data to a remote function processor through a message destination. A function has the following properties:

Inputs. One or more fields whose values are sent to the function processor. The values can be provided by a user or specified by a script.
Message destination. Used to transport the function call.
Function processor. The code executable that you write. It is a Python class that implements function methods. These functions are called by the framework when the SOAR Platform invokes the function. The function processor performs an activity then sends the results to the process that invoked the function. Activities include access and return external data, interact or integrate with other security systems, or be a utility that performs a specific action.
Output. Result of the function processor and made available in the instance of the process that invoked the function. The result can be acted upon by playbooks, scripts, rules, or workflows to dynamically orchestrate the security incident response activities.

You should be familiar with how your app is to be used within a playbook when determining which customizations you need to provide with your app. For example, you might need custom fields and data tables to store data, and a new incident layout to organize the fields. You can also provide example scripts, rules and workflows to assist users in adapting the app into their playbooks. You create each customization in the SOAR Platform.

For more information about playbooks and customizations, see the Playbook Designer Guide.

SDK

The SOAR SDK allows you to create apps in the container and extension formats.

The SOAR SDK provides the template files to develop your app and specify how to run your app in a container. Containers run Python 3.9.18 and a framework that automatically manages authenticating and connecting to the STOMP connection and REST API in the SOAR Platform. It simplifies creating apps by allowing you to focus on writing the behavior logic.

The SOAR SDK provides the following features:

The Python environment and template files with which you write your code. Your code can take the form of a function processor, action processor, or a utility that acts upon data received from a SOAR organization but does not return data to the organization.
A dockerfile that provides all the information needed to build a container for the app. You can modify the file in those situations where your app requires additional operating system or Python components. The dockerfile is compatible with Docker or other container management solutions, such as Red Hat® Enterprise Linux® Podman.
An apikey_permissions.txt file with a list of permissions to choose from. You can easily select which permissions you need for your app. When your completed app is installed in a SOAR organization, the system automatically generates an API key account with the permissions you specified.
A documentation template that prompts you for the information need to generate installation and user instructions.
The ability to generate your app in the extension format for earlier versions of the SOAR Platform that do not support the app format.
The ability to convert existing extensions to the app format.

If you are familiar with the Resilient® Circuits framework used with extensions, Resilient Circuits is also used with apps but within the container. You do not interact with Resilient Circuits directly.

The SOAR SDK has the ability to create the app in the extension format with the same functionality but for earlier versions of the SOAR Platform that do not support the container-based apps. The SOAR SDK also has the ability to repackage existing extension apps into a container-based format.

REST API

The SOAR Platform has a full-featured REST API that sends and receives JSON formatted data. It has complete access to almost all features, including but not limited to: creating and updating incidents and tasks, managing users and groups, and creating artifacts and attachments. Custom behaviors are triggered by adding a message destination to a rule, workflow or function defined in the SOAR Platform and subscribing your code to that message destination.

The SOAR Platform contains an interactive Rest API browser that allows you to access the REST API and try out any endpoint on the system. When logged into the SOAR Platform, click on your account name at the top right and select Help/Contact. Here you can access the complete API Reference guide, including schemas for all of the JSON sent and received by the API, and the interactive Rest API.

Development overview

At a minimum, an app accesses data from the SOAR Platform.

You can develop an app that provides any or all of the following capabilities.

Access data from the SOAR Platform.
Send data to the SOAR Platform.
Present data directly to a user, such as a security analyst, in a custom field or data table.
Facilitate communication between the SOAR Platform and a security program.

The following procedure provides a high-level overview of the development process. The subsequent sections provide the details.

Set up your development environment, which includes installing the SDK.
Log in to the SOAR Platform and create the functions and other playbook components that are needed for your app.
Use the codegen utility provided by the SDK to export those components into your development environment and create a Python module.
Edit the .py file in the components directory to customize the app. The information in the .py file is the function processor.
Test the app, which includes connecting to the SOAR Platform and running the rule or playbook that uses the function. Make sure to code for and test the error conditions.
Update your app as needed.
Use the docgen utility provided by the SDK to create documentation for your app.
Package your app. Make sure to update the icons in the package and review the permission settings.
Publish your app.

An app is available in two formats. One format supports the App Host Kubernetes-based container environments. The other format supports the previously available integration format that would run on an Integration Server. The container-based format uses containers for improved usability, manageability, and security. An app in this format is installed directly to the App Host, which is paired to the SOAR Platform. An app in the extension format requires that the extension is loaded on to an integration server then deployed to the SOAR Platform. Earlier releases of the SOAR Platform support only integrations that run on the Integration Server.

The process of packaging your app creates the app in both formats.

Developer resources

Use these resources to learn more about creating apps and integrating them with IBM Security QRadar SOAR Platform.

Resource	Description
IBM® SOAR DeveloperWorks web site	Provides information for developing apps for use with IBM Security QRadar SOAR Platform, including use cases and the app development environment.
IBM Security Github	Provides access to library modules, community-provided apps, example scripts, and developer documentation for SOAR APIs.
IBM X-Force® App Exchange	Provides access to the IBM Security community apps on IBM X-Force.
IBM SOAR Resilient Circuits Framework in the Python Package Index (PyPI) repository.	Download the most recent version of the Resilient Circuits framework, which is used to run SOAR apps and integrations. Note: The `resilient-circuits` version is independent of the SOAR Platform version. For example, SOAR Platform 47 can run an app that uses `resilient-circuits == 49.0.4321`. To view information about other SOAR packages, see IBM SOAR Python Libraries.