The QRadar App Framework SDK provides utilities to develop, package, and deploy an application for QRadar.
QRadar App Framework SDK
This README contains the following sections:
New in v2
App base imageThe app base image is now derived from Red Hat Universal Base Image rather than CentOS.
More specifically, the app base image is the RHEL8 ubi-minimal image plus a number of add-ons including Python 3, OpenSSL, systemd, and SQLite.
App containerProcesses within the app container now run as a non-privileged user, not as root. The same non-privileged user owns all app-related files and directories inside the container.
SDK installationUnlike the SDK v1 installer, root privileges are not required to run the SDK v2 install script.
Installation includes the creation of a Python 3 virtual environment. Any existing Python installation on the user’s machine is left untouched, as is any installation of SDK v1.
Running apps locallyPackaged with SDK v2 is the latest app base image, based on Red Hat UBI.
To enable local build and run, you must have Docker installed and running on your machine.
On Linux, your user must be in a docker group so that the SDK can interact with Docker without requiring elevated privileges. More information on configuring Docker on Linux can be found here.
SDK entry pointSDK v2 actions are invoked using the command qapp rather than the v1 entry point qradar_app_creator.
SDK version coexistenceThe combination of different install locations and different entry points means that SDK v1 and v2 can coexist. This allows developers to maintain an older CentOS version of an app while working on a newer Red Hat UBI version.
Removing SDK v1If you wish to delete SDK v1 from your machine, you need to manually remove these items:
App layoutThe src_deps directory for defining app dependencies and scripts has been replaced by a directory named container. For more details see the Create and Build actions.
SDK v2 has a new example app where the Python code better reflects Flask recommended practices such as using an application factory, and defining routes using blueprints.
qpylibThe source code for qpylib is no longer included in the SDK example app. Instead, qpylib is pre-installed as a Python package in the app base image. You do not need to (and should not) bundle qpylib source code with your app.
For more information, refer to the documentation and code at https://github.com/IBM/qpylib.
SDK version checkThe first invocation of qapp each day performs a check to determine if there is a newer version of the SDK on the X-Force App Exchange. If there is a newer version, a message is displayed advising you to update. This is to ensure your environment is up to date with the latest fixes, features, and base image version.
Server communicationA number of SDK actions (e.g.
status) communicate with a QRadar server via the QRadar Application Framework REST API. Connection to a QRadar server needs certificate verification, and, depending on your development environment, a proxy may also be required.
/etc/pki/tls/certs/ca-bundle.crtfrom the server.
The retrieved certificate bundle and the server connection details are stored locally, making this a one-time-only process for a given QRadar server. The location of the stored files is a directory named
.qradar_app_sdk/<server_ip_address>under your home directory.
App deploymentBefore deploying a UBI-based app to a QRadar server, the manifest.json file must contain an entry like this:
where <version> corresponds to the app base image version bundled with the SDK, e.g. 2.0.0. This ensures that the deployed app will execute in the same container environment as was used to develop it locally.
Installing the SDK
- SDK v2 runs on Linux and MacOS. It does not provide native support for Microsoft Windows (see Using Windows Subsystem for Linux).
- Python 3.6.8 or later is required, so that a Python virtual environment can be created during the installation process.
Using Windows Subsystem for LinuxIf you wish to use the SDK on Windows, you must first configure the Windows Subsystem for Linux (WSL).
Instructions for installing WSL 2, including pre-requisites for your Windows environment, can be found at https://docs.microsoft.com/en-us/windows/wsl/install-win10.
When choosing your Linux distribution, the latest Ubuntu version is recommended.
SDK installation processExtract the contents of the SDK zip archive to an empty directory.
Do not use sudo to execute the install script. Elevated privileges are not required.
SDK v2 is installed under your home directory. The default location is a sub-directory named qradarappsdk. The install script will ask if you want to choose a different location. If your chosen directory is not empty, the install script will warn you that the directory will be wiped, and ask for confirmation before proceeding.
qappcommand, which should be available on your path.
qapp -hwill display all of the actions you can perform. These actions are described in the following sections.
CreateTo develop your own app, you can use the SDK’s example app as your starting point. To do this, populate a new app workspace using the create action.
For simplicity throughout this document, examples like the one above involving the app workspace show qapp being called inside the workspace directory. This is not obligatory, as any action related to an app workspace allows you to specify a -w option to identify the workspace location.
The components of the example app include:
- manifest.json: a JSON manifest file that describes the app and defines what it does.
- app: a directory containing Python source code and files for rendering web content.
- container: a placeholder directory for app dependencies, scripts and configuration files.
- store: a directory for persisting app data, particularly log files.
- qenv.ini: an SDK-specific configuration file where app container environment variables are defined.
Running an app locally consists of two steps:
- Build an app image, if one does not already exist.
- Run a container using the app image.
With the base image in place, your app is combined with it to create a new image in your registry. If the name of your app workspace is, for example, myapp, then your app image will be tagged in your registry as myapp:latest.
The actual processing performed by qapp build depends on:
- The content of your app’s container directory. For more details, see container/README.txt in the example app.
- The content of manifest.json. This is used to generate program entries in the supervisord.conf file which will be placed in directory /etc in the built image. Having a program entry for Flask depends on the manifest’s load_flask field: this defaults to true. Other program entries are generated for each service in the manifest.
- The SDK does not automatically rebuild an app image when you make changes to container dependencies and scripts. You must do this yourself. Running qapp clean -i is the easiest way to remove everything Docker-related before rebuilding.
- Any build-time scripts that you provide cannot access the app and store directories, because those directories are only available after being mounted into the running container - see the Run section.
- The manifest.json field dependencies is no longer supported. You cannot override the locations container/pip and container/rpm.
Finally, the app container is started with these modifications:
- The following items from your app workspace are mounted into the container under /opt/app-root:
- app directory
- store directory
- Any environment variables defined in qenv.ini are set in the container.
- Any scripts in container/run are executed.
Flask run environment
qapp run -d
In development mode, Flask will detect any changes you make to your app’s Python code and dynamically reload your app, letting you see the effect of your changes without needing a container restart.
Another feature of Flask development mode is the stack trace viewer/debugger which is displayed in your browser when you make a request to an app endpoint and that request encounters an error in your Python code.
The package action will exclude from the zip any files which it knows are not required, such as Python compiled files (.pyc).
qapp package -p com.mycompany.myapp.zip
qapp deploy -q <QRadar server> -u <QRadar user> -p com.mycompany.myapp.zip
Deployment will assign a unique numeric identifier to your app, e.g. 1105. Any other SDK actions relating to your app require you to supply this identifier.
If your app manifest includes an entry for authentication, you must supply to the deployment the name of a QRadar user who has the capabilities requested by your app. If you already know which user you want to use for authorization, you can supply that user’s name via the -o option. Otherwise, the deployment will prompt you to select an entry from a list of users who have the required capabilities.
If you choose to stop the deployment without choosing an authorization user, your app will remain in a state where it is waiting for authorization. You can subsequently authorize or cancel the app deployment.
StatusUse the status action to check the status of your app:
qapp status -q <QRadar server> -u <QRadar user> -a <app ID>
AuthorizeUse the authorize action to complete an app deployment that is waiting for authorization:
qapp authorize -q <QRadar server> -u <QRadar user> -a <app ID>
qapp cancel -q <QRadar server> -u <QRadar user> -a <app ID>
DeleteThe delete action removes your app from the QRadar server:
qapp delete -q <QRadar server> -u <QRadar user> -a <app ID>
2.0.0See section New in v2.
Was this topic helpful?
13 November 2020