App File Structure

Steps

The following list outlines the layout of files and sub directories that you can add to the root directory of your app. It also outlines the required nomenclature for app files and sub directories:

• App Root Folder
  • app/ - Main directory for application files
  • app/__init__.py - Main entry point into the web app.
  • app/views.py - File that contains view functions which respond to requests to your application
  • app/templates - Optional subdirectory that contains any Python Flask or Jinja templates that are required by the app.
  • app/static - Optional subdirectory that contains CSS, JavaScript, globalization, and other resource files.
    • app/static/css - Cascading style sheets used by the app.
    • app/static/js - Javascript files used by the app.
    • app/static/resources - Resource bundle properties files used by the app. Text strings for globalization are stored as key/value pairs in Java format properties files. If you configured text strings for globalization, they appear in QRadar when the user sets their preferences for the relevant locale. Note: If no matching resource bundle properties file is found it will default to the english translation if present.
  • container/ - Optional directory that can be added with any of the following subdirectories
    • container/pip - This contains any extra Python libraries that the app requires. See Source dependencies for more details
    • container/rpm - This contains any RPM dependencies that the app requires. RPMs must be RHEL 8 x86_64 compatible. See Source dependencies for more details.
    • container/build - This contains any dependencies that the app requires that are not RPMs or Python libraries. See Build and Runtime dependencies for more details.
    • container/run - This contains any dependencies that the app requires that are not RPMs or Python libraries. See Build and Runtime dependencies for more details.
    • container/clean - This contains cleanup.sh script a shell script that is executed during container shut down. This shell script can be used to shutdown app processes gracefully e.g. database connections.
    • container/service - This contains scripts that start background processes used in the app container.
    • container/conf - This contains configuration files for any services and general use.
    • container/conf/supervisord.d - This contains supervisord include files. The contents of this directory will be copied to /etc/supervisord.d/ and will be included as a part of the supervisord configuration at container startup
  • manifest.json - The application manifest description file. See Application manifest structure for more details

Application manifest structure

The manifest is a JSON file that describes to IBM QRadar the capabilities that the app provides.

The following table describes the fields that you can include in the manifest.json file.

Table 1. Application manifest fields

Source dependencies

If your app requires dependencies, such as RPMs or Python libraries

The container directory can contain these optional sub directories:

pip

Use the pip folder to install extra Python libraries. For example, if your application requires the observable-0.01.00 Python library, add the observable-0.01.00.tar.gz file to the pip folder.

Don't use .tar files for Python libraries that include extra C-based extensions. Instead, add libraries as Python wheel files (.whl), which have C-based extensions pre-compiled.

You must install Python wheel files on the same system architecture they were compiled upon. To work with IBM® QRadar® application framework v2, wheel files must be compiled on RHEL 8 x86_64. If it uses compatible architecture, you can use the Python bdist_wheel command to create wheel files from a library's source code on your own system. The command python setup.py sdist bdist_wheel creates the wheel file when you run it from within the root directory of the Python library's source folder.

A useful alternative to manually downloading Python packages for your app is the pip2pi Python package. It requires pip and you can install it on your development computer by using the pip install pip2pi command. After you install this package, you run the following command:

pip2tgz <target-directory> <Python package>

For example, the following command downloads the package's wheel, along with its dependencies, into the specified folder.

pip2tgz python_packages/pytest/ pytest==2.8.2

The == parameter is optional after pytest in the command above and is used to download a specific version of the package.

For Python libraries that have dependencies, you can include an optional ordering.txt file in the pip folder to specify the order in which Python libraries are installed. This text file must include the names of files that are in the pip folder. File names must be separated with a new line (UNIX line endings) in the order that you want them installed.

pytz-2020.1-py2.py3-none-any.whl
Babel-2.8.0-py2.py3-none-any.whl
speaklater-1.3.tar.gz
Flask-Babel-1.0.0.tar.gz

rpm

Use the rpm folder to install extra Red Hat Enterprise Linux (RHEL) RPMs. The RPMs must be RHEL 8 x86_64 compatible.

For RPMs that have dependencies, you can include an optional ordering.txt file in the rpms folder to specify the order in which RPMs are installed. This text file must include the names of files that are in the rpms folder. File names must be separated with a new line (UNIX line endings) in the order you want them installed.

nginx-1.17.8-1.el8.ngx.x86_64.rpm
nodejs-10.19.0-1.module+el8.1.0+5726+6ed65f8c.x86_64.rpm
npm-6.13.4-1.10.19.0.1.module+el8.1.0+5726+6ed65f8c.x86_64.rpm

Build and Runtime dependencies

If your app requires additional configuration dependencies at image build time or at container startup

The container directory can contain these optional sub directories:

Build

Use the build folder to perform additional configuration changes during the docker build process for the app. In order for your app to be available for use as quickly as possible after installation we recommend moving as many steps as possible to image build time. Similar to the source dependency folders an ordering.txt file needs to be created under this folder. This text file must include cli commands separated with a new line (UNIX line endings) in the order you want them executed.

For example:

Post configuration after installing nginx via an rpm install in a container, container/build - ordering.txt file contents:

/opt/app-root/container/build/deploy.sh

In the above ordering.txt file we are executing one shell script that will complete the configuration of nginx after the rpm installation

Example deploy.sh:

#!/bin/bash

rm /etc/nginx/conf.d/default.conf
cp ${APP_ROOT}/container/build/nginx.conf /etc/nginx/nginx.conf
cp ${APP_ROOT}/container/build/server.conf /etc/nginx/conf.d/server.conf

In the above example deploy.sh would be executed as part of the docker image build process. This is copying the app's version of nginx.conf and server.conf from the container build folder to the correct places inside the image for nginx.

1. APP_ROOT is available as an environment variable inside the container and can be used to refer to the app root directory
2. As the persistent store for the app i.e. /opt/app-root/store will only be available at container runtime you will not be able to alter anything in that directory using this method you would need to add commands to the run section outlined below

Runtime

Use the run folder to perform additional configuration changes during docker container startup. In order to specify which commands to run you need to create a file called ordering.txt under this folder. This text file must include cli commands separated with a new line (UNIX line endings) in the order you want them executed.

For example, loading certificates into the trusted ca certificate bundle previously uploaded via the app:

as_root ${APP_ROOT}/bin/update_ca_bundle.sh

In the above ordering.txt file we are executing a shell script that exists in the container by default for loading certificates stored under /opt/app-root/store/certs into the CA trust certificate bundle

1. All commands now execute as appuser by default and the above command requires root permissions so you need to execute it with a special script called as_root which is available during container startup. The as_root command should be used only when necessary
2. If as_root is not needed or potentially causes a security issue then the app may fail our validation