Ecosystem Guardium Apps, User Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 35

Download
Open PDF In Browser	View PDF

IBM
Ecosystem

Ecosystem

Contents
Guardium Ecosystem . . . . . . . . . 1
Guardium app development overview. . . . . . 1
Working with the SDK . . . . . . . . . . . 2
SDK prerequisites. . . . . . . . . . . . 2
Installing the SDK . . . . . . . . . . . 4
Upgrading an SDK . . . . . . . . . . . 5
Uninstalling an SDK . . . . . . . . . . . 5
Software development kit overview. . . . . . 5
App file structure . . . . . . . . . . . 10
GUI Application Framework fundamentals . . . 16
Sample apps . . . . . . . . . . . . . 19

Support functions . . . . . . . .
Python helper library functions . . . .
Jinja2 templates . . . . . . . . .
App logs . . . . . . . . . . .
Checking app status, and deleting an app
Guardium system . . . . . . . .
App upgrades . . . . . . . . .
Application lifecycle in the GUI . . . .
Uploading and managing apps . . . .
Apps FAQs . . . . . . . . . . .
Resources . . . . . . . . . . . .

. .
. .
. .
. .
from
. .
. .
. .
. .
. .
. .

.
.
.
.

22
24
25
27

.
.
.
.
.
.

29
29
29
30
30
31

iii

Ecosystem

Guardium Ecosystem
Use Guardium ecosystem to extend and enhance your current Guardium
deployment with new data and ready-to-use use cases.
Guardium apps are the centerpiece of the ecosystem. A Guardium app is a means
to augment and enrich your current Guardium system with new data and
functionality. You can download and install other shared apps that are created by
IBM, its Business Partners, and other Guardium customers.
You create your own apps from Guardium by using the Guardium GUI
Application Framework software development kit (SDK). You can then package the
app and reuse it in other Guardium deployments. You can share your app on the
IBM Guardium App Exchange portal (https://exchange.xforce.ibmcloud.com/hub/
).
The functionality is entirely defined by the Flask framework apps that serve the
app endpoints from a secure container. (Flask is a micro web written in Python
and based on the Werkzeug toolkit and Jinja2 template engine.)

Download public apps
All apps and security product enhancements are hosted on the IBM X-Force
Exchange portal (https://exchange.xforce.ibmcloud.com/).
You can see a list of available apps on the IBM Security App Exchange
(https://exchange.xforce.ibmcloud.com/hub). Filter apps by selecting the
Application check box.
The Guardium apps are packaged as an archive (.zip) file, which you can deploy
on Guardium. See “Application lifecycle in the GUI” on page 29.

Guardium app development overview
Use the Guardium GUI Application Framework to develop new application
modules that integrate with Guardium and provide new capabilities.
Applications, or apps, are small plug-in modules to the GUI Application
Framework. Apps serve endpoints from within a secure container to inject the
content directly into the Guardium web interface.
Each app has its own dedicated memory allocation and a defined amount of CPU
resources that are allocated to it.
The main web language that is used to author an application is Python, and the
Flask framework is integrated and available for use by the application.

How an application runs and interacts with Guardium
Guardium applications run inside an isolated Python Flask environment that is
independent of the Guardium user interface.
The application can also use static images, scripts, and HTML pages.

All interaction with the application is proxied through the Guardium user
interface. No direct access to network ports or web services is usually permitted.
Figure 1. Application Framework

Related concepts:
“Python helper library functions” on page 24
The Guardium Python helper library (gpylib) contains several useful functions that
you can use to add logging, make REST API calls, and convert JSON objects to
Python dictionaries.
“GrdAPI and GdrConnection classes” on page 25

Working with the SDK
SDK prerequisites
Review and perform these prerequisites before installing the SDK.
The following operating system versions are supported for installing and working
with the SDK:
v Windows 7
v Ubuntu 17.10
v CentOS 7.4
v RHEL 7
v macOS 10.11, Sierra 10.12.6
Before installing the SDK:
v Install the latest Python 2 version (2.7.9 or above). Python 3 is not supported.
To find out which version of Python is installed on your Guardium instance, use
SSH to log in to your Guardium and use the python --version command. The
Windows version of the SDK installation script uses c:\Python26\python.exe for
the installation location of the Python executable file is installed at
c:\Python26\python.exe.
You can download Python from Python Downloads (https://www.python.org/
downloads/).
v Install Docker CE, if you want to test your app locally before sending it to your
Guardium system.
Related tasks:
“Installing the SDK” on page 4
The Guardium Application Framework SDK can be installed on Windows, Linux,
or macOS operating system.

Installing Python 2.7.9 or higher on Linux
Install Python 2.7.9 or higher (but lower than Python 3) to run Guardium
Application Framework SDK on the Linux operating system.

About this task
Procedure
1. Log in as root or use sudo.
2. Verify your system is up to date: yum update

Ecosystem

3. Install development tools: yum groupinstall -y "development tools"
4. Install development tools and extra libraries (not strictly needed to compile
Python but required for the Python interpreter):
v Ubuntu: yum install -y zlib-devel bzip2-devel openssl-devel
ncurses-devel sqlite-devel readline-devel tk-devel gdbm-devel
db4-devel libpcap-devel xz-devel expat-devel
v CentOS: yum install -y zlib-devel, openssl-devel, openssl,
libffi-devel
v
5. If you have a clean "minimal" install of CentOS, install the wget tool:yum
install -y wget
6. Download, compile and install Python.

# Python 2.7.0:
wget http://python.org/ftp/python/2.7.0/Python-2.7.0.tar.xz
tar xf Python-2.7.0.tar.xz
cd Python-2.7.0
./configure --prefix=/usr/local --enable-unicode=ucs4 --enable-shared LDFLAGS="-Wl,-rpath /usr/
make && make altinstall

The newly installed Python interpreter is available as /usr/local/bin/
python2.7. The system version of Python 2.6.6 continues to be available as
/usr/bin/python, /usr/bin/python2 and /usr/bin/python2.6.
7. To strip symbols from the shared library to reduce the memory footprint, enter:
strip /usr/local/lib/libpython2.7.so.1.0
8. Make sure Python command points to the latest Python you installed. For
example, . Then, to make the latest Python installation the default Python
engine, run source ~/.bash_profile

Installing Python 2.7.9 on macOS
You must install Python 2.7.9 or higher (but lower than Python 3) to run the
Guardium Application Framework SDK on the macOS operating system.

Before you begin
Log in to your mac and run the command: $ xcode-select --install

About this task
macOS usually comes with Python 2.7.x. Do not use the macOS version of Python.
Instead, install the latest Python 2 version using, for example, the Homebrew
package manager. This installs an alternative Python, in addition to the existing
Python.
Make sure Python command points to the latest Python you installed. For
example, If you installed Python using Homebrew on macOS , edit ~/.
bash_profile with export PATH="/usr/local/opt/python/libexec/bin:$PATH".
Then, to make the latest Python installation the default Python engine, run source
~/.bash_profile

Procedure
1. To install using the Homebrew package manager, type this command:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/
install/master/install)"

Guardium Ecosystem

a. Open or create the ~/.bash_profile file in a text editor and add the
following lines: export PATH="/usr/local/opt/python/libexec/bin:$PATH"
b. Set the latest Python installation to the default Python engine: run source
~/.bash_profile
c. Make sure Python command points to the latest Python you installed with
which python
d. Check that your installed Python version is running, enter python
--version
The system should respond with the version number, 2.7.9 and higher.
2. Alternatively, you can install Python with pyenv.
a. Install pyenv pip install pyenv
b. Install Python pyenv install , for example pyenv install 2.7.9
c. Check that the Python version was installed, by entering pyenv versions
d. Use Python locally, enter pyenv global 2.7.9
e. Check that your installed Python version is running, enter python
--version

Installing Python 2.7.9 on Windows
About this task
You must install Python 2.7.9 or higher (but lower than Python 3) to run the
Guardium Application Framework SDK on the Windows operating system.

Procedure
1. Download the latest Python 2 (64-bit) installer from Python downloads for
Windows, usually named Windows x86-64 MSI installer. The SDK does not
support the 32-bit Python interpreter.
2. Install Python 2:
a. Installation path: Install to a path without spaces, otherwise the Python
installer does not install its Scripts folder, for example C:\Program
Files\Python27.
b. What to install: Scroll down and check to install the environment variable.
This ensures that the python command is recognized.
3. Check Python was installed correctly, by opening a command prompt and
typing python The output for this command should state that the Python
version is 2.7.9 or above, and that the version has 64-bit. For example:

Python 2.7.9 (v2.7.9:84471935ed, Sep 16 2017, 20:25:58) [MSC v.1500 64 bit (AMD64)] on w
Type "help", "copyright", "credits" or "license" for more information.
>>
4. Exit the Python interpreter by entering Ctrl+Z.

Installing the SDK
The Guardium Application Framework SDK can be installed on Windows, Linux,
or macOS operating system.

Before you begin
Verify all “SDK prerequisites” on page 2. To run the application on a Docker
container, you must install Docker and start its service prior to installing the SDK.

Ecosystem

Procedure
1. Download and extract the Guardium Application Framework SDK archive (.zip
file).
Download the SDK (https://developer.ibm.com/quardium/)
2. Install the SDK:
v Windows without Docker, as Administrator, right-click install.bat to run
the installation process. The SDK installs to the c:\GuardiumAppSDK folder.
Close the terminal window and re-open, so the grd_sdk command is
available.
v Windows with Docker:
a. Install the Docker Toolbox, install it now on your development machine,
see installation process (https://docs.docker.com/toolbox/
toolbox_install_windows/)
b. Start Docker.
c. Extract the contents of the SDK zip archive.
d. Open a Docker Quickstart Terminal, and run the install.bat script as
Administrator by entering ./install.bat. During the SDK installation, the
new Docker is added to the local Docker repository.
v Linux, Unix, macOS:
a. Extract the contents of the SDK zip archive.
b. From within the SDK folder, run the install.sh script as root:
./install.sh.
If you have permission problems, install using sudo ./install.sh

What to do next
“Creating your Guardium application” on page 6.

Upgrading an SDK
Use this procedure to upgrade an SDK.

Procedure
Install the SDK, see “Installing the SDK” on page 4. The Guardium apps SDK
removes the existing folder and reinstalls the app.

Uninstalling an SDK
Use this procedure to uninstall an SDK from your developer system.

Procedure
1. On a Linux or Mac server, delete the folder /usr/local/etc/GuardiumAppSDK.
2. On a Windows server, delete the folder c:\GuardiumAppSDK.

Software development kit overview
The Guardium application framework comes with its own software development
kit (SDK).
Use the Guardium Application Framework software development kit (SDK) to do
the following application development tasks:
Create a development workspace
Guardium Ecosystem

The Guardium Application Framework SDK installs a development
workspace that has a sample application that you use as a template to
build your own application.
Run your app locally for test purposes
You don't need to upload your application code to a live Guardium system
to test your app. The Guardium application framework SDK includes a
virtual development environment that you can use to run your application
locally.
If your app uses Guardium API endpoints, you can configure the virtual
environment to connect to the API on the Guardium system and test
locally. You do not need to upload to Guardium.
Package your app
The Guardium Application Framework SDK includes a packaging utility
that you use to create an archive (.zip file) that contains your application
files.
Deploy your app to Guardium
The Guardium Application Framework SDK includes a deployment utility
that you can use to upload your packaged app directly to a live Guardium
system.

Creating your Guardium application
Use the Guardium GUI Application Framework SDK to create a basic development
environment for your app. Build on the sample template app that comes with the
SDK to create your own app.

Procedure
Create a folder on your computer for the Guardium sample app by entering the
command grd_sdk create -w , for example: grd_sdk create -w
./myApp, where is the path to the local folder you want to create
for your apps.
Note: Folder and file names in paths must not contain spaces.
Note: On Linux, keep the absolute path to your app short. File paths might be
truncated due to the BINPRM_BUF_SIZE kernel constant (79 or 127 characters,
depending on kernel version), leading to failure of this command.

Results
When you run the development environment script, the following folders and files
are added to your app development folder.

Ecosystem

Table 1. Guardium App files and folders in development folder
Files/Folders

Description

app

The main directory for application files. Contains the following
files:
The views.py file is the main entry point into the web app. This
file and the manifest.json file are the only files that are required
for every app. This file contains sample code for the "Hello World"
application.
The gpylib folder contains the Python library files that your app
uses to perform Guardium operations. You can use the gpylib
library to connect to API endpoints, get the storage path, and so
on.

grd_appfw_venv

Contains the Python virtual environment for running your app
locally .

manifest.json

Describes what the sample "Hello World" app does.

run.py

Default Python script for running your app locally.

What to do next
You are now ready to begin coding your app. Familiarize yourself with the source
dependencies for the app and manifest file structures.
Related concepts:
“App file structure” on page 10
A Guardium app that you create is distributed within a compressed file.
“Sample apps” on page 19
Related tasks:
“Running your application locally”
Run your application to test it locally, in a browser window, before you package
and deploy the app.

Running your application locally
Run your application to test it locally, in a browser window, before you package
and deploy the app.

About this task
The Guardium GUI Application Framework includes a virtual environment that
you can use to run your application locally for testing purposes.

Procedure
1. Enter the command: grd_sdk run -w
The first time you run the app, you are prompted for the Guardium appliance
hostname or IP, the CLI user password, and for Guardium user credentials.
These are used to create an authentication token especially created for that
computer. The credentials are saved in an encrypted file within your
application folder (.guard_config). If you need to change the Guardium
machine your app communicates with, or update the credentials used, run
grd_sdk regenerate_token to generate a new authentication token.

Guardium Ecosystem

2. Open a browser and type http://localhost:5000 in the address bar. If your
app has REST endpoints you can call them at this URL. Your app is displayed
in the browser window, and the application output is sent to the command line
or to your terminal.
3. To stop your application, press Ctrl+C on macOS or Ctrl+C Ctrl+C (twice) on
Windows.

Running your application locally in a container (Windows)
Use a container for testing locally on a Windows server, to run the application in
an environment that is similar to the production environment. The SDK creates a
base image, which is identical to the base image that will run on the Guardium
production environment.

Before you begin
To run the application on a Docker container, you must install Docker and start its
service prior to installing the SDK. See “Installing the SDK” on page 4.
Verify that Docker is running.

Procedure
1. After you create and run your application locally (“Running your application
locally” on page 7), open the Docker Quickstart terminal.
2. Run the application locally using a Docker CentOS container by entering the
command grd_sdk.bat run -d -w in the Docker Quickstart
Terminal. Write the workspace path in Linux bash style (../My Documents/app)
or in Windows style, but surrounded with quotes ("C:\My Documents\app"). The
system prompts you for authentication details.
3. Enter your Guardium appliance IP, using the CLI password and credentials of
the admin GUI user. The terminal responds with Running on
http://0.0.0.0:5000/ (Press CTRL+C to quit)
4. Open the application URL in the browser to see the sample application output:
”Hello World!”. Use the container instance internal IP address in the URL that
appears in the top row of the container Quick Start Terminal (when the
terminal is started). The internal IP in the example below is 192.168.99.100. The
application URL is http://192.168.99.100:5000
5. To stop your application, press Ctrl+C Ctrl+C (twice).

Running your application locally in a container (Linux)
Use a container for testing locally on a Linux server, to run the application in an
environment that is similar to the production environment. The SDK creates a base
image, which is identical to the base image that will run on the Guardium
production environment.

Before you begin
To run the application on a Docker container, you must install Docker and start its
service prior to installing the SDK. When one wishes to run an app locally using
Docker he must either use sudo or run it using root. This is because the Docker
daemon uses a socket which by default is owned by root. This can be solved with
what is described here: https://docs.docker.com/engine/installation/linux/linuxpostinstall/.

Ecosystem

If you didn't install the Docker Toolbox, install it now on your development
machine, see installation process (https://docs.docker.com/toolbox/
toolbox_install_windows/), and reinstall the SDK. See “Installing the SDK” on
page 4.
Verify that Docker is running.

Procedure
1. After you create and run your application locally (“Running your application
locally” on page 7), run the application locally using a Docker CentOS
container by entering the command grd_sdk run -d -w , for
example grd_sdk run -d -w ./testapp. If your get permission errors, try sudo
grd_sdk run -d -w
2. Open your browser and test https://127.0.0.1:5000/.
3. To stop your application, press Ctrl+C.

Packaging and deploying your app
Use the Guardium GUI Application Framework to package your app as an archive
(.zip file) and deploy it to your Guardium test environment.

Before you begin
Guardium is running v10.5 and higher.

Procedure
1. Open a shell prompt and use the cd command to go to the bin sub folder of
your SDK installation folder.
2. Package your app by entering a command with syntax: grd_sdk package -w
-p .zip.
3. Deploy your app (extension) to your Guardium system by entering: grd_sdk
deploy -p .zip -g .

What to do next
Open the Guardium instance, and watch the app run.

Developing apps in Eclipse
After you set up your development environment, you import it into Eclipse to use
that Eclipse integrated development environment (IDE) features to develop your
app.

About this task
For Python development, install PyDev, the Eclipse IDE that is used in Python
development.
The latest version of Eclipse can be found on the Eclipse website
https://eclipse.org/downloads/ (https://eclipse.org/downloads/).

Procedure
1. Install PyDev into Eclipse.
v To install from the Eclipse Marketplace, click Help > Eclipse Marketplace on
the main Eclipse Help panel.

Guardium Ecosystem

v To install the PyDev repository from (http://pydev.org/updates), click Help
> Install New Software on the main Eclipse Help panel.
2. After you install PyDev, switch the perspective to PyDev.
3. In the PyDev perspective, click File > New > PyDev project and the following
information in the PyDev Project dialog and click Next.
a. Enter a project name.
b. Select 2.6 from the Grammar Version list.
c. Select Create links to existing sources
d. To configure the interpreter to use the virtual environment in the SDK, click
Click here to configure an interpreter not listed.
e. Click New in the Python Interpreters dialog and enter a name and path to
the Python executable file on your system.
f. Click OK.
Ensure that the site-packages folder path (...//grd_appfw_venw/
lib/python2.7/site-packages) check box is selected when you select the
folders to be added to the system python path.
g. Click Apply, and OK to return to the PyDev Project dialog.
h. Click Create links to existing sources, and then click Next.
i. Click Add external source folder and go to the root directory of your
development environment, click OK, and then click Finish.
The new Eclipse PyDev project that contains your development environment
appears in your Package Explorer.

App file structure
A Guardium app that you create is distributed within a compressed file.
The Hello World sample app that is created when you set up your development
environment is a basic template that you can use for your application. However,
the application file structure can be more complex.
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:

Ecosystem

main directory for application files

app/views.py

The main entry point into the web app.

app/templates

An optional subdirectory that contains any Python
Flask of Jinja templates that are required by the app.

app/static

An optional subdirectory.

css

CSS files

JavaScript files

resources

resource files

application_.properties

The application_.properties file is a
Globalization resource bundle for the specified
language code. 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
Guardium when the user sets their preferences for the
relevant locale.

manifest.json

The application manifest description file.

src_deps

An optional directory that contains source
dependencies.

pip

Optional subdirectory that contains any extra Python
libraries that the app requires.

rpms

Optional subdirectory that contains any RPM
dependencies that the app requires. RPMs must be
CentOS 6.7 x86_64 compatible.

init

Optional subdirectory that contains any dependencies
that the app requires that are not RPMs or Python
libraries.

Source dependencies
If your app requires dependencies, such as RPMs or Python libraries, you can add
them in the src_deps sub directory of the app folder.
The src_deps directory can contain these optional sub directories:

pip
Use the pip folder to install extra Python libraries.
There is an empty python requirements file (python standard) created in this
directory for each created app. List all python packages the app requires in this
file. The same directory must contain all the listed packages and all dependencies
these packages have. The packages must be compatible with the system the app is
running on. This is applicable when running locally on Windows (tested win7) or
Linux (tested Ubuntu 16.04) whether with or without Docker. This directory can
hold the packages for different distributions and operating systems, allowing the
app to be shared among developers that work on different platforms (the
requirements file remains the same for all platforms).
File names must be separated with a new line (UNIX line endings) in the order
that you want them installed.
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.
In addition to adding the libraries, list the packages (for example observable ==
0.01.00) in the following text file: /src_deps/pip/
APP_CUSTOM_REQUIREMENTS.txt
Use Python Wheel packages, whenever they exist. Not that tar.gz packages may
contain third-party code in C, which can cause compilation problems in other file
systems.
You must install Python wheel files on the same system architecture they were
compiled upon. To work with Guardium application framework, wheel files must
be compiled on Centos 6.7 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.

Guardium Ecosystem

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

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 pytest parameter is optional and you can use it to download specific versions
of a package.

rpms
Use the rpms folder to install extra Red Hat Enterprise Linus (RHEL) RPMs. The
RPMs must be CentOs 7 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.
When the app is run locally without the docker, the dependencies in this directory
are only echoed to screen to let the user know what system dependencies might be
required. When the app is run locally on the docker, the RPMs are installed.

init
Add dependencies files that do not fit into the pip or rpms folders to the init
folder. You must also include an ordering.txt file in the init folder. The lines in
this text file (UNIX line endings) are run as shell commands during the installation
of the app.
For example, you might want to install a collection of RPMs that has a complex
dependency chain that is not explicitly known. In this use case, you add a .tar file
that is called dependant_rpms.tar.gz to the init folder. You add the following
commands to the ordering.txt file:
mkdir /src_deps/init/dependant_rpms
cd /src_deps/init
tar -xzvf dependant_rpms.tar.gz
yum -y localinstall --disablerepo=*dependant_rpms/*rpm
rm -rf dependant_rpms

Note: The --disablerepo=* switch in this example is used to prevent the yum from
attempting to contact remote repositories on Guardium consoles that have no
internet access.
This example uses yum's RPM auto-dependency resolution that installs a set of
specified RPMs in the required order. If the RPMs are included in the rpms folder,
you must specify the installation order.

Ecosystem

Application manifest structure
The manifest is a JSON file that describes to Guardium the capabilities that the app
provides.
The following table describes the fields that you can include in the manifest.json
file.
Table 2. Application manifest fields
Field

Required

Type

Description

name

Yes

String

The user-readable name of the app. If the
app is globalized this field can optionally
point at a resource bundle key.

description

Yes

String

The user-readable description of the app. If
the application is globalized, this field can
optionally point at a resource bundle.

version

Yes

String

A version string for the app. You can use
any format that you want here.

uuid

Yes

String

An RFC 4122-compliant universally unique
identifier for the application.
The create command uses the Python UUID
package to generate a random 128-bit
number for the uuid value.
If you do not use the SDK to create the app
manifest file, you must manually enter a
unique value in the uuid field.

console_ip

Yes
(automatically
derived)

String

The IP address of the Guardium system that
you want your application to communicate
with. If not specified, the value of this field
defaults to 127.0.0.1.

authentication

Yes

String

Authorization for the app to access
Guardium. The only mandatory entry is
"requested_capabilities": [""].
For example, admin is a commonly used
user capability.
Enter at least one supported Guardium user
capability. The installation fails if any of the
requested_capabilities are not defined in
Guardium.

load_flask

Boolean

node_only

Boolean

Set to false when you don't want to make
Python Flask framework available to your
app. Typically, you might disable Flask when
you want your app to use a different web
application framework.
If not specified, this field defaults to true.
If you want your app to be installed on an
app node only and not on the Guardium
system, set to true.
Useful when your app is resource-intensive.
When you use this field, inform your users
that your app runs only on an app node
appliance (unmanaged host).
If not specified, this field defaults to true.and
later.

debugging

Boolean

Set to true to turn on logging for your app.
If not specified, this field defaults to false.

Guardium Ecosystem

Table 2. Application manifest fields (continued)
Field

Required

Type

Description

areas

Array of Area
Type

One or more Area objects describe new
complete pages of the application. In
Guardium, Area objects are represented as
tabs.

rest_methods

Array of REST One or more REST Method objects describe
Method Type
REST methods that the app exposes. REST
Method objects are required parameters for
Dashboard Items and Metadata Providers,
and are optional for Actions.

dashboard_items

Array of
Dashboard
Item Type

One or more Dashboard Item objects
describe the contents of new items that you
want to expose to the Guardium dashboard.

configuration_pages

Array of
Configuration
Page Type

One or more Configuration Page objects
describe new complete pages of the app that
represent configuration. In Guardium,
configuration pages are opened from the
Admin tab.

gui_actions

Array of GUI
Action Type

One or more GUI Action objects describe
new actions that can be performed on items
in the user interface by page toolbars or by
right-click menus.

page_scripts

Array of Page
Script type

One or more Page Script objects describe
new JavaScript files that you want included
within an existing page in Guardium. By
default, these scripts run in their own
namespace.

metadata_providers

Array of
Metadata
Provider type

One or more Metadata Provider objects
describe REST methods that can be called to
fetch new metadata information for certain
data types in Guardium. Metadata is shown
in tooltips when a mouse is hovered-over an
item.

resource_bundles

Array of
Resource
Bundle type

One or more Resource Bundle objects. Use
these objects for language locales and locale
properties file locations.

dev_opts

Array of
Developer
Options type

One or more Developer Option objects. Use
these objects to specify values that are used
when you develop locally.

resources

Integer

One or more Resource objects. Use these
objects to configure the amount of memory
in megabytes that is available for the app to
use.

fragments

Array of
Fragments
type

Use these objects to determine the injection
point in the Guardium UI where content is
added and the rest endpoint that is used to
retrieve the content.

custom_columns

Array of
Custom
Columns type

One or more Custom column objects. Use
these objects to identify the context (the page
and table in the Guardium UI) where a
custom column is added, a label for the
column header, the type of data to be added,
and the rest endpoint that is used to add the
column content.

Installing Node.js as a source dependency
You can install Node.js as a web application framework to replace the Flask
framework that is included with the IBM Guardium GUI Application Framework
SDK.

Ecosystem

Procedure
1. Download the Node.js archive (.tar) that you want to use, and copy it to
app/src_deps/init directory.
2. Create an installation script that is similar to the following example in the same
folder that references the archive node-v6.3.0-linux-x64.tar.gz that you want
to use (in this case):
#!/bin/bash
##
## install node and npm from source tarball, and make available on the path
##
cd /usr/local
tar --strip-components 1 -xzf /src_deps/init/node-v6.3.0-linux-x64.tar.gz

3. Create a file ordering.txt in the same folder as the following content:
/src_deps/init/install_nodejs_npm.sh

The ordering.txt notifies IBM Guardium to run the Node.js installation script.

Optimize app memory usage
Tune the Guardium application framework to optimize app memory usage.
Apps that run on the Guardium Console are limited 200 MB of memory. When an
application exceeds this threshold, logs are generated in the /var/log/
guardium.error file. Eventually, the container that hosts the app shuts down and is
restarted if the application continues to use even more memory beyond this
threshold.
You can help prevent your app from exceeding the 100 MB threshold in three
ways:
v Avoid allocating large amounts of memory by chunking up (or staggering) the
work into small memory footprints.
v Change the memory model used by the application framework.
v Call for garbage collection when finished with code that uses large amounts of
memory

Changing the application framework memory model
By default, the application framework configures the Werkzeug WSGI web
application server that Flask uses to run as a single process. Threads are used to
handle each request. You can configure the application server to create a separate
process to handle each new request. When the request is completed, the process is
destroyed. All memory that is allocated by the Python interpreter to process this
request is released.
To override this behavior, edit the run.py file and set threading=False and
process=N where N is greater than 1. For example, a value of process=3 allocates
approximately 25 MB per interpreter and so leaves some room for growth.
__author__ = ’IBM’
from app import app
from app.gpylib import gpylib
gpylib.create_log()
app.run(debug = True, host=’0.0.0.0’,
threaded=False,
process=3)

Guardium Ecosystem

Include the source to the run.py in the template folder within your application ZIP
archive file. The run.py that is created during the installation is then overwritten
with your settings.
For more information about parameters that can be passed to the Werkzeug WSGI
web application server, see http://werkzeug.pocoo.org/docs/0.11/serving/.

Calling for garbage collection
Python might not know when to free the memory. You can speed up garbage
collection by placing the following code right after sections where large amounts of
memory are no longer needed:
import gc
gc.collect()

Note: Python does not guarantee that any memory that your code uses gets
returned to the OS. All that garbage collection guarantees is that the memory used
by an object that is collected is free to be used by another object at some future
time. Changing the application framework memory model option that is noted in
the previous section is important for applications that run for a long time. Killing
the process always guarantees the memory is freed for use by other components.

Tools
Some tools that can help you identify memory problems:
Memory Profiler
A Python module for monitoring memory consumption of a process. For
more information, see https://pypi.python.org/pypi/memory_profiler.
Linux utilities
The command line utility top can be used to monitor all Python processes
running on the machine:
top -p $(pgrep -d’,’ python)

You can also use the following command to get the total MB used by all
Python interpreters on your system:
ps -e -o pid,comm,rss |
grep python | awk ’/python/{print $3}’ |
awk ’{sum+=$1} END

Resource Module
You can log the amount of memory your process uses by adding the
following code to your module:
import resource
print ’Memory usage: %s (kb)’ % resource.getrusage
(resource.RUSAGE_SELF).ru_maxrss

GUI Application Framework fundamentals
Guardium GUI Application Framework apps are stand-alone web applications that
run on the Flask micro-framework, and are served from the Flask web server.

Installation overview
Every app runs in its own unique Flask server. Each Flask server, in turn, runs
within a secure Linux container. The container is the implementation stack for the
secure containment of the Flask app codebase.

Ecosystem

Each app is installed by using the RESTful API endpoints. The installation
endpoint handles these tasks:
v Validates the app's manifest
v Asynchronous task-bound:
– Registers the app with Guardium to enable web traffic proxy and the HTTP
request/response lifecycle from Guardium to the app
– Automatically creates a container image with the app code bundled within it
– Automatically runs a container from the container image, which is bound to a
data-only secondary container that is used for persistent storage
Table 3. GUI Application Framework REST API endpoints
Endpoint

Parameters

Description

GET /gui_app_framework/
application_creation_task

Application ID

Retrieves a list of status details
for all asynchronous requests to
create apps.

GET /gui_app_framework/
application_creation_task/
{application_id}

Application ID

Retrieves a list of status details
of an asynchronous request to
create apps.

POST /gui_app_framework/
application_creation_task

Application (.zip)
bundle file

Creates an app within the
application framework, and
registers it with Guardium. The
app is created asynchronously. A
reference to the application_id
is returned and must be used in
subsequent API calls to
determine the status of the app
installation.

POST /gui_app_framework/
application_creation_task/
{application_id}

Application ID, cancel
status

Updates a new app installation
within the application
framework. The application_id
and a status parameters are
required.

GET /gui_app_framework/
applications

Retrieves a list of apps that are
installed on the Guardium
console, and their manifest
JSON structures and status.

GET /gui_app_framework/
applications/{application_id}

Application ID

Retrieves a specific app that is
installed on the console and its
manifest JSON structure and
status.

POST /gui_app_framework/
applications/{application_id}

Application ID,
start/stop status

Updates an app. Starts or stops
an app by setting status to
RUNNING or STOPPED
respectively.

DELETE /gui_app_framework/
applications/{application_id}

Application ID

Deletes an application.

Python
You must use Python 2.7.9 to develop your Guardium apps.
For more information, go to the Python website (https://www.python.org/doc/).

Guardium Ecosystem

Flask
Flask is a micro web application framework that is written in Python.
Flask is the web server from which the app-coded endpoints are served. You use
Python functions to deliver use cases. You can use route annotations for each
Python method in the Flask application. After the Flask web server starts,
HTTP/HTTPS-bound requests are serviced by Flask for that route, and the Python
functions are run.
Each Flask server that is run from within the Docker container uses port 5000.
Outwardly from the container, Docker maps that internal port 5000 to the next free
port from the 49152-65535 ephemeral range. During the registration phase, this
outward mapped port is stored by Guardium so that web requests for an app,
through Guardium are proxied to the correct container.
The following code is a sample Python route:
@app.route(’/’)
def hello_world():
return ’Hello World!’

In a standalone Flask web server, a web request through a browser to
http://localhost:5000 returns: Hello World!
The following table outlines the specific version of Flask, and its dependencies:
Packages

Version

Description

Flask

0.10.1

Microframework, or micro web application
framework

itsdangerous

0.24

Utility package for signing and encrypting
data

jinja2

2.7.3

Template engine for python

markupsafe

0.23

Unicode escape library used alongside
Jinja2

Werkzeug

0.96

WSGI (Web Server Gateway Interface)
utility library for Python

For more information, see the Flask website (http://flask.pocoo.org/).

Jinja2
Jinja2 is a Python library that enables you to create templates for various output
formats from a core template text file. HTML is the format that is used for
Guardium apps. Jinja2 has a rich API, and large array of syntactic directives
(statements, expressions, variables, tags) that you use to dynamically inject content
into the template file.
Flask's in-built render_template() method is the easiest way to inject data from a
Python method, served by the route, into a Jinja2 HTML template, as shown in the
following example.
@app.route(’/’)
def hello_world():
return render_template(’hello.html’, title=’Guardium’)

Ecosystem

The template hello.html contains the following code:

Hello from Flask
Hello {{ title }}!

The following HTML output is produced:

Hello from Flask
Hello guardium!

For more information, see the Jinja2 website (http://jinja.pocoo.org/docs/dev/).

HTTP request response lifecycle
When an app is successfully installed, requests to the app are proxied only by
using an established connection to Guardium. The app cannot be directly accessed
by using direct URL requests or any other method.
Apps can establish a secure authenticated and authorized session to Guardium.
Any authorization tokens that are created to verify that the integrity of session can
be reused. The app obtains all the capabilities, security, and authenticity facets of
Guardium. The app can use the user session state to get access to all of
GuardiumGuardium RESTful API endpoints to pull or push data to or from the
Guardium system.

Containerized apps and the network
With the GUI Application Framework, traffic flows from container to container,
from container to host on its public IP address (not localhost), and from containers
to the outside world.
When each app is passed as an archive (.zip file) of source code to the Guardium
endpoints, Guardium builds the initial image specific to your app codebase. Each
image runs as an individual container. As the container is run or started,
Guardium maps the internal flask server port (5000) to an external ephemeral port.
This external ephemeral port is registered to Guardium so that proxied requests to
your app code are routed to the correct container.

Python threading
Threads that perform background tasks, like sending keepalive packets, or
performing periodic garbage collection, must have thread.daemon=True. By setting
them as daemon threads, they are killed automatically when the program quits.

Sample apps
The Hello World sample app
When you add an app in the Application Development Manager window, a simple
"Hello World" sample app is also created.
The Hello World sample app adds a Hello World tab to Guardium. Navigate to
Guardium Applications > Hello World
You can use this sample app as a simple template from which to build your own
apps that require tabs. When you run the development environment script, the
following files are added to your application development folder:
Guardium Ecosystem

Table 4. Application development files
Files/Folders

Description

app

The root directory contains the following files:
gpylib contains the Python library files that your app uses to
connect to the Guardium API endpoints.
__init__.py a sample initialization file that creates a Flask
instance, imports views from the views.py script and functions
from the gpylib library.
views.py the main entry point into the web application. This file
and the manifest.json file are the only files that are required in
every app. Contains sample code for the Hello World app.

guardium_appfw_venv

Contains the Python virtual environment where the dependencies
are installed.

__init__.py

Creates an instance of the Flask micro-framework that is used to
serve content to Guardium.

manifest.json

Describes to Guardium what the sample Hello World app does.

run.py

Contains instructions to run the code that is stored in the app sub
directory.

manifest.json
The manifest.json file contains the following code:
{
"name":"Hello World",
"description":"Application to display hello world",
"version":"1.0",
"uuid":"558d7935-f00b-42da-a278-c82abdb12b34",
"areas": [
{
"id":"QHelloWorld",
"text":"Hello World",
"description":"A Hello World app",
"url":"index",
"required_capabilities":["ADMIN"]
}
],
"dev_opts": [
{
"console_ip":""
}
]
}

The first four objects, name, description, version, and uuid provide basic app
information.
The areas object describes the capabilities of the Hello World app. The Guardium
GUI Application Framework uses areas objects to describe new complete pages of
the app. Areas objects are represented as tabs in the user interface.
The areas block contains the fields that are described in the following table:

Ecosystem

Table 5. Areas block
Name

Description

Value

The ID of the new tab

QHelloWorld

text

The name of the tab that is displayed in the
user interface.

Hello World

description

A description of the tab that is displayed.

A Hello World
app

url

Describes the route that is defined in the
views.py script that Guardium uses so it can
display the "Hello, World!" text in the body of
the new tab.

index

required_capabilities

Instructs Guardium to display the Hello World
tab only to users with Administrator privileges.

["ADMIN"]

The dev_opts block is used to provide the IP address of networked instance of
Guardium GUI for testing purposes. This block is not required for this sample app.

views.py
The views.py file contains the following code:
__author__ = ’IBM’
from app import app
@app.route(’/’)
@app.route(’/index’)
def index():
return "Hello, World!"

The code creates the default ’/’ and ’/index’ routes, both of which return a
simple string. The index route is declared in the url field of the manifest.json file.
Note: You do not have to include the __author__ tag, but it is considered good
practice to use it.

App startup
When Guardium starts your app, it calls the run.py and _init_.py scripts. The
_init_.py file creates an instance of the Flask microframework environment that
imports your views module. Your views module defines all the necessary
endpoints and routes that serve content back to Guardium.
__author__ = ’IBM’
from flask import Flask
app = Flask(__name__)
from app import views

The run.py file creates a new Flask application (by starting the Flask web server),
from the app directory.
__author__ = ’IBM’
from app import app
app.run(debug = True, host=’0.0.0.0’)

Guardium Ecosystem

What can you do with the Hello World sample app?
You can use the Hello World sample app to test the Guardium SDK in these ways:
v Run the Hello World app locally.
v If you have a test instance of Guardium, you use the SDK to package and
upload the Hello World app to it.
However, most importantly you can use the Hello World sample app files as a
template to start developing your own Guardium apps.

REST API sample app
This simple application demonstrates how to interact with Guardium by using
Guardium REST API.
Specifically, it requests a Guardium login report from a Guardium system.
The sample application is located in GuardiumAppSDK/sample_apps/sampleREST.zip.
Explore the sample code in ./app/views.py.
Run the application by entering:
cd
sudo grd_sdk run -w ./
Typical output is presented here. Failed logins print in red.

Support functions
The Guardium GUI Application Framework comes with several built-in routes,
custom Jinja2 Flask functions, and other helper utilities that support app
development.

Overview
All HTTP requests from client-side browsers that go to an app use the following
format:
https:///console/plugins/{application_id}/app_proxy/{my_route}

The application_id is the integer value that is assigned during the process of using
the installation RESTful endpoints for GUI app creation. The application_id value is
recorded in the Application Creation Task state output that is returned when
you run the grd_app_creator deploy command.
In the following example, the application ID is 1023.
Application Creation Task state:
{’status’: ’COMPLETED’, ’application_id’: ’1023’, ’error_messages’: ’[]’}

Routes
You can create your own targeted web requests to the app for the routes in the
following table:

Ecosystem

Table 6. Request routes
Route

Format

Description

GET /debug

GET https:///console/plugins/
{application_id}/app_proxy/debug

Download your /store/log/app.log file from inside
the container for inspection.

GET /debug_view

GET https:///console/plugins/
{application_id}/app_proxy/debug_view

Display the contents of the /store/log/app.log file
inside your browser window.

POST /log_level

POST https:///console/plugins/
{application_id}/app_proxy/log_level
form body: level = ’INFO’
’DEBUG’
’ERROR’
’WARNING’
’CRITICAL’

Dynamically define the level of logging that you want
your app to capture. Post a form, with an attribute
level that is set to one of the log level values to this
endpoint. Guardium dynamically resets the log
collection levels in your /store/log/app.log file.

Accessing your Flask endpoints in views.py
You must use relative paths for your endpoints. Do not use the utility methods
q_url_for and get_console_ip to create URLs to access your Flask endpoints. If a
console uses a web URL instead of an IP address, all the Flask requests are denied
because the request is cross-domain. In that case, your app might not work. If you
want to access an endpoint from the main app template level, for an AJAX call, for
example, to return some JSON data, use the following URL format:
url_cpu_data = ’cpu_data’

This format routes the method in views.py:
@app.route(’/cpu_data’, methods=[’GET’])

If you are working from a folder at a deeper level, for example, use ../cpu_data to
go back a level to reach this endpoint.
Do not use the following format to create a URL to access your endpoint:
url_cpu_data = "{{ q_url_for(’cpu_data’) }}"

As before, if you go from a web URL to an IP address, this request might be
denied because the request is cross-domain and so your app might not work.
If you begin the URL with a slash, it starts the URL from this root:
https://g-machineIPaddress/

Custom Flask methods
The following table describes the Flask custom methods that you can use:
Table 7. Custom Flask methods
Method

Format

Description

q_url_for()

def q_url_for(endpoint, **values):

Use this Python method inside your routes in your app's
views.py or your Jinja2 templates. It hides and abstracts the
Guardium proxy addresses that are needed to link together
endpoints (routes) or resources (static files and images, for
example).
The method is essentially a wrapper around the Flask url_for(..)
method. It applies a prefix that pertains to the correct
application-specific proxy path URL portion to get to your app's
endpoint.
The following snippet shows how to use the method in a Jinja2
template to hide the Guardium proxy address of an image
resource.

For more information about the Flask url_for(..) method, go to
the Flask website.

Guardium Ecosystem

Table 7. Custom Flask methods (continued)
Method

Format

Description

getAppBaseURL()

def getAppBaseUrl():

Function to get the full URL through Guardium, that will proxy
any request to the appropriate application plug-in servlet. This
routine returns a URL string that can be appended to create a
URL to reference resources in the application. Typically, the
q_url_for() function is used for this purpose but
getAppBaseURL() is also supplied for convenience.

Guardium CSRF token
The Guardium CSRF (cross-site request forgery) token is generated by Guardium
to prevent cross-site scripting attempts. For applications that are developed by
using IBM Guardium support libraries such as gpylib the use of the CSRF token is
seamless.
If you create an app that does not use Guardium gpylib support, you must harvest
the token from any application endpoints, or routes, and place it in your own
HTTP headers before a REST or exported method call is made in Guardium.

Python helper library functions
The Guardium Python helper library (gpylib) contains several useful functions that
you can use to add logging, make REST API calls, and convert JSON objects to
Python dictionaries.
All functions that you import into your app's views.py file can be called globally.
The following table describes functions that you can import into your app's
views.py file.
Function

Format

Description

log(0)

def log(message, level=’info’):
Import the gpylib helper library
into your app's views.py to use the
Here's an example:
log() function. This function writes
messages at your chosen log level
from gpylib import gpylib
to the /store/log/app.log file. By
..
#in precedence order from lowest
level
to highest
default,
logging
is turned on and
log(’debug message’ ,’debug’)set to INFO level. Lower level
log(’info message’ ,’info’) logging messages are ignored. Use
log(’warning message’ ,’warning’)
the POST /log_level endpoint to
log(’error message’ ,’error’)
change
log(’critical message’ ,’critical’)| Copy Copy

set_log_level(log_level) def set_log_level(log_level=’info’):
Set the current log level. Used by
the POST /log_level endpoint but
can also be called
programmatically.
REST()

Ecosystem

def REST( RESTtype, requestURL,
Import
headers={},
the gpylib library to use
data=None, params=None, json=None,
version=None
): to the
this function
to make calls
Guardium REST API endpoints.
for example
The endpoint takes care of
authentication and authorization
try:
headers = {’content-type’ :by’text/plain’}
reusing the security tokens that
arielOptions = gpylib.REST(are’get’,
passed on the request from
’/api/ariel/databases’,
headers = headers )
Guardium.
except Exception as e:
gpylib.log( "Error " + str(e) )
raise

Function

Format

Description

to_json_dict(JSON)

def to_json_dict(python_obj):Converts a JSON object in to a
Python dictionary.

GrdAPI and GdrConnection classes
The GRDApi auto generated python APIs are located in the file
\myNewApp\app\guardapi\GRDApi.py.
The GrdConnection class holds an active connection to a Guardium machine.
The GrdApi class holds all the available Guardium operations the SDK enables a
user to perform.
Before you can use the GrdAPI functions, establish a connection to the Guardium
system with the commands:
grd_connection = GrdConnection(GMachineIP, GMachinePort, username,
password, client_secret, client_id)
grd_api = GRDApi(grd_connection)
If you create a GrdConnection instance with no arguments, all the required
information is requested in the command line the first time the app is run on its
environment.
Now you can use the GRDApi functions by accessing the grd_api object. For
example, if you want to invoke the create_online_report() API function and create a
'Guardium Logins' report, you enter:
result = grd_api.create_online_report(’Guardium logins’, reportParameter=report_parameters)

Here is an example of running a report, output as JSON:
sql_errors = grd_api.create_online_report('SQL Errors', 'NOW -10 HOUR',
'NOW +3 HOUR')
For a working example, see the REST API sample application.
Advanced users only
The command regenerate_grd_api_lib rebuilds the GrdAPI class, overwriting the
existing library. Use this command when you write an app in one Guardium
version, and want to use it in another version. For example:
regenerate_grd_api_lib-w workspace
Related information:
GuardAPI Reference

Jinja2 templates
Jinja2 is a Python library that you can use to construct templates for various
output formats from a core template text file. It can be used to create HTML
templates for Guardium applications.

Guardium Ecosystem

Jinja2 has a rich API, and large array of syntactic directives (statements,
expressions, variables, tags) that allow the dynamic injection of content into the
templated file.
Use the Flask render_template() method in the app's views.py file to inject data
from your Python method, served by the route, into a Jinja2 templated HTML file.
For example:
__author__ = ’IBM’
from flask import render_template
from app import app
@app.route(’/’)
def hello_world():
return render_template("hello.html", title = "Guardium")

The hello.html template must be stored in the /app/templates folder. The
hello.html file is described in the following section:

Hello from Flask
Hello {{ title }}!

The template produces the following output:

Hello from Flask
Hello Guardium

Note: Do not use the Flask-Jinja2-mandated url_for functionality within your app
Jinja2 template. The Guardium GUI Application Framework uses relative
addressing for request paths. If you use url_for, it creates an absolute request path
from the container itself.
For more information about Jinja2 templates, see the Jinja2 documentation.

Edit Jinja2 templates in Eclipse
You can use the Django template editor plug-in in Eclipse to develop Jinja2
templates.
PyDev Eclipse does not come with a Jinja2 template editor by default. The Django
template editor plug-in offers useful features that you can employ to develop Jinja2
templates for your app.
Install the Django repository (http://pydev.org/updates) by clicking Help > Install
New Software on the main Eclipse Help panel.
This plug-in offers useful syntax-highlighting and auto-completion features for
Jinja2 template development.

Integrate JavaScript libraries into your template
Add CSS and JavaScript libraries to your HTML templates to style and enhance
your apps user interface.
You can use the Dojo and JQuery JavaScript libraries that are integrated into
Guardium to add CSS styling, widgets, and other UI features to your app.

Ecosystem

Dojo
To integrate the Dojo JavaScript toolkit into your app's HTML template, add the
following tags to your template's HEAD element:

My app!

Guardium uses Dojo 1.9.3.

JQuery
To integrate the JQuery JavaScript library into your app's HTML template, add the
following tag to your template's HEAD element:

My app!

App logs
App logs are stored in the /store/log directory of your application's container.
The /store/log directory contains 2 log files:
v startup.log is the initial start-up log for the application. This log is useful for
checking the installation of dependencies added to your app's app/src_deps/
folder.
v app.log is the log file that is created by the gpylib library. Logging calls to the
gpylib.log() method are written in the app.log file.

Adding logging to your app
The Guardium Python helper library (gpylib) contains two useful functions that
you can use to add logging to your app.

Guardium Ecosystem

The log() function
Import the gpylib helper library into your app's views.py to use the log() function.
This function writes messages at your chosen log level to the /store/log/app.log
file.
By default, logging is turned on and set to INFO level. Lower level logging
messages are ignored. Use the POST /log_level endpoint to change log level.
The log() function uses the following format:
def log(message, level=’info’):

For example:
from gpylib import gpylib
..
#in precedence order from lowest level to highest
gpylib.log(’debug message’ ,’debug’)
gpylib.log(’info message’ ,’info’)
gpylib.log(’warning message’ ,’warning’)
gpylib.log(’error message’ ,’error’)
gpylib.log(’critical message’ ,’critical’)

Note:
All gpylib functions that you import into your app's views.py file can be called
globally. For that reason, it is a good idea to add a namespace to the gpylib
functions you import to prevent clashes with other functions.

The set_log_level() function
You can use this function to set the current log level. This function is used by the
POST /log_level endpoint but can also be called programmatically.
def set_log_level(log_level=’info’):

Viewing your app logs
Use the fileserver CLI command to allow connection to the Guardium appliance
from a web browser so that you can download your app files.

About this task
Attention: While the file server is running, Guardium logs and other
product-specific files are available on the Guardium server without any
requirement to log in. Turn off the file server as soon as you are done
downloading your files.
Tip: The file server automatically stops after 800 seconds. To change the timeout
value, use the CLI command: store timeout fileserver_session M, where M is
the number of seconds, from 60 to 1200, after which the file server will time out.

Procedure
1. Log in to the CLI.

Ecosystem

2. Enter the command fileserver , where IP is the IP address of the
computer from which you want to open a connection to the file server. If no IP
address is entered, only the computer from which you opened the connection
to the CLI is permitted to connect to the file server. If you access the CLI in the
physical Guardium appliance, the IP address is required. The system should
respond:
xxxx.ibm.com> fileserver Creating the index file. Starting the file
server. You can find it at http://xxxx.ibm.comPress ENTER to stop the
file server
A web server launches on your collector, and you can access the log files
directory from your browser.
3. Click Sqlguard logs. You'll see the file list in the appliance's log directory. You
can download any file by clicking on it. Do not click the link in the top line
/var/log/guard, which is the current page. Other links to the files and
directories work fine.

Results
Attention: While the file server is running, Guardiumlogs and other
product-specific files are available on the Guardium server without any
requirement to log in. Turn off the file server as soon as you are done
downloading your files.

Checking app status, and deleting an app from a Guardium
system
Enter these commands to either check the status of your app, or delete your app
from your Guardium system.

Procedure
1. To check the status of your app, enter: grd_sdk status -q -u -a
2. To stop a running application in your development environment, use
Ctrl/Cmd+C (Ctrl/Cmd+Z does not stop the server service and you won't be
able to restart the app properly).
3. To delete an app, enter: grd_sdk delete -q -u
-a

App upgrades
Upgrade your app by .
Note: As a best practice, store your app configuration and data in /store because
data in this directory is protected during app upgrades.
Important: If you want to upgrade an installed app that uses a lot of memory, you
might need to stop the app before you do the upgrade to avoid memory resource
issues, and then restart the app after you complete the upgrade.

Application lifecycle in the GUI
Understand how to upload, manage your apps, and view output.

Guardium Ecosystem

Uploading and managing apps
Deploy your app to one or more Guardium systems, and run and manage your
apps.

Procedure
1. Navigate to Setup > Tools and Views > Application Lifecycle
2. Upload an app.
a. Click , browse to and select your app .zip or .gz file.
b. Enter your admin user and password.
c. Under Where to install, select one or more Guardium systems.
d. Click Upload
3. Start or stop the app by clicking Start or Stop
4. Update to a later version of the app.
a. Click Update.
b. Browse to and select the .zip or .gz file.
c. Enter your admin user and password, and click Upload.
d. Check the installation status in the Status column.
5. Add roles.
a. Make sure the app is stopped, and click Assign roles.
b. Select the app and click Assign roles.
c. Select the roles and click OK.
6. Click Action log
7. Modify credentials by selecting the app, clicking Update Credentials and
entering the new user and password.

Apps FAQs
Can I run my application work on multiple Guardium appliances
simultaneously ?
No. You can run the app on one Guardium system at any point in time.

My application does not stop when I run it through Docker
container. Why?
Threads that perform background tasks, like sending keepalive packets, or
performing periodic garbage collection, must have thread.daemon=True. By setting
them as daemon threads, they are killed automatically when the program quits.

"[Error -2] Name or service not known" occurs while running an
app using DockerTollbox in Windows.
There is a DNS resolving problem in your DockerToolbox environment. Please fix
your DNS service or use the Guardium machine IP address instead of hostname.

Ecosystem

See error "keyring.backends._OS_X_API.Error: (-25293, "Can't
fetch password from system") when I run an application.
This error indicates that the SDK can't reach your password manager.
Perform these steps.
1. Uninstall any non-used python packages, enter pip2 uninstall
2. Uninstall python, enter brew uninstall python
3. Enable dev tools, enter xcode-select --install
4. Reinstall python, enter brew install python
5. Reinstall the SDK. See “Installing the SDK” on page 4.
Alternatively: Mark the SDK Python environment as trusted, by typing codesign
-f -s - /usr/local/etc/GuardiumAppSDK/guard_sdk_venv/bin/python

Resources
Use various resources to help you to build apps with the IBM Guardium GUI
Application Framework

Flask API
v http://www.flaskapi.org/ (http://www.flaskapi.org/)
v Flask Tutorials (https://blog.miguelgrinberg.com/post/the-flask-mega-tutorialpart-i-hello-world)

Jinja2 templates
v http://jinja.pocoo.org/docs/dev/ (http://jinja.pocoo.org/docs/dev/)

Guardium Ecosystem

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
XMP Toolkit                     : Adobe XMP Core 5.6-c015 84.159810, 2016/09/10-02:41:30
Instance ID                     : uuid:897e677e-611e-4084-a353-8afbb4674416
Document ID                     : uuid:DC033BAE-627A-967C-3B98-D12AA6DDBE80
Create Date                     : 2018:02:08 06:39:56-05:00
Modify Date                     : 2018:02:08 14:12:04+02:00
Creator Tool                    : XPP
Metadata Date                   : 2018:02:08 14:12:04+02:00
Producer                        : PDFlib+PDI 9.0.5 (AIX)
Keywords                        : 
Format                          : application/pdf
Description                     : 
Creator                         : IBM
Title                           : Ecosystem
Page Mode                       : UseOutlines
Page Count                      : 35
Author                          : IBM
Subject                         :

EXIF Metadata provided by EXIF.tools

Ecosystem Guardium Apps, User Guide

Hello {{ title }}!

Hello guardium!

Hello {{ title }}!

Hello Guardium

Navigation menu

Versions of this User Manual:

Views

Navigation