IBM Support

How to implement a Custom Alert Java application in Guardium

Question & Answer


Question

How to implement a Custom Alert Java application in Guardium

Answer


This article describes the steps needed to create a Custom Alert Java Application:-

The steps below assume that an Oracle Database is used to store an alert message when a certain Policy rule is triggered.
The database does not have to be Oracle - however an appropriate JDBC driver will be needed for the specific database being used to store alert information.

* Please note that it is necessary to ensure that the latest GPU and fixpacks are installed .
(There have been previous problems without the latest GPUs in place)

For v9.x - you may also need ad-hoc patch 9.0p1127 - Please contact IBM Technical Support if you are using v9.x
----
A typical scenario is:
1. A Client application accesses the DB Server, where the S-TAP is installed.
2. Once the S-TAP captures SQL statements (e.g. "select * from employee"), the S-TAP will send it to the Collector (Guardium Appliance).
3. A Custom Alert is installed in the Collector. It's invoked by the installed Policy, and will send a message to the designated DB server. In this example, the message will be stored into guardium_alert table in an Oracle server.
4. An Administrator connects to the Oracle server and checks the guardium_alert table.

These steps are thorough and should be followed methodically

1) Obtain the following module from IBM Technical Support before developing the Customer Alert application. guardAlertUtil.jar
2) Obtain the latest (or recent) Oracle JDBC driver. - For example ojdbc7.jar
(ojdbc6.jar ,ojdbc7.jar or ojdbc8.jar may be appropriate)

You may be able to download from oracle if you "Accept License Agreement" before downloading the module

[NOTE] If you're planning to write to /var/log/guard/messages from your Custom Alert Application, IBM Technical Support will be needed to add some entries into a specific table - For details the IBM Technical Support Engineer should see the Internal reference below

3) Custom Alert application development

This section will explain:


- Creating a test table and data on DB server where S-TAP is installed.
- Creating a guardium_alert table on DB server that Custom Alert will send alert to.
- Developing Custom Alert Java application and a unit test program.
 

3.1 Create a test table and data

Create a test table on the target DB server where the S-TAP is installed.the S-TAP will monitor this table.

DB Server (MSSQL example is used here )

C:\>sqlcmd

1> create table employee (id int, first varchar(32), last varchar(32))
2> go
1> insert into employee values (1, 'Smith', 'John')
2> select * from employee
3> go

(1 rows affected)
id          first                            last
----------- -------------------------------- --------------------------------
          1 Smith                            John

(1 rows affected)
1> quit

C:\>

 

3.2 Create a guard_alert table to store alert messages that will be sent by the Custom Alert.

DB Server (Oracle)

[root@grddb11 ~]# su - oracle
[oracle@grddb11 ~]$ sqlplus system/********

SQL*Plus: Release 11.2.0.2.0 Production on Wed Nov 18 01:12:51 2015

Copyright (c) 1982, 2011, Oracle.  All rights reserved.


Connected to:
Oracle Database 11g Express Edition Release 11.2.0.2.0 - 64bit Production

SQL> create table guardium_alert (timestamp CHAR(20), message VARCHAR2(2048));

Table created.

SQL>

 

3.3 Develop Custom Alert

Use a Java Application Environment to build and compile the java code :- For example

Launch eclipse (or Rational Application Developer). Create a new Java project (e.g. Guardium) and import ojdbc7.jar and guardAlertUtiljar. In addition to that, add JavaSE-1.6 Library because Guardium assumes JRE 1.6. ( You can build your module with JRE1.7 but you fail to import the class to Guardium in the latter step.)

Here is an example screen shot of a Guardium project property. JRE 1.7 is remaining in this example but it can be deleted.


Then, create a Custom Alert Java application. Here is an example screen shot on eclipse.



Here is the example application. Please make sure to set your own JDBC_URL, JDBC_USER, JDBC_PASSWORD marked in bold.

MyCustomAlert.java

package com.guardium.custom;

import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.sql.*;
import java.io.*;
import com.guardium.custom.alerts.CustomerDefinedAlertingIfc;
import com.guardium.utils.AdHocLogger;


public class MyCustomAlert implements CustomerDefinedAlertingIfc {
    
    /* You need to set your own JDBC_URL, USER, and PASSWORD */
    private static final String JDBC_URL="jdbc:oracle:thin:@//grddb11.lab.japan.ibm.com:1521";
    private static final String JDBC_USER="system";
    private static final String JDBC_PASSWORD="***";
    
    private String _message = null;
    private Date _timeStamp = null;
    
    @Override
    public void processAlert(String message, Date timeStamp) {
        // TODO Auto-generated method stub
        setMessage(message);
        setTimeStamp(timeStamp);
        DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
        try {
            AdHocLogger.logDebug("Connection establishing...", AdHocLogger.LOG_DEBUG);
            Class.forName("oracle.jdbc.driver.OracleDriver");
            Connection conn = DriverManager.getConnection(JDBC_URL, JDBC_USER, JDBC_PASSWORD);
            AdHocLogger.logDebug("Connection established. conn = " + conn.toString(), AdHocLogger.LOG_DEBUG);
            Statement stmt = conn.createStatement();
            String sql = "insert into guardium_alert values ('" + df.format(getTimeStamp()) + "', '" + getMessage() + "')";
            if (stmt.execute(sql)) {
                AdHocLogger.logDebug("Succeded : '" + sql + "'", AdHocLogger.LOG_DEBUG);
            } else {
                AdHocLogger.logDebug("Failed : '" + sql + "'", AdHocLogger.LOG_DEBUG);
            }        
        } catch (Exception e) {
            e.printStackTrace();
            AdHocLogger.logDebug("Exception : " + e.getMessage(), AdHocLogger.LOG_DEBUG);
        }
    }

    @Override
    public void setMessage(String inMessage) {
        // TODO Auto-generated method stub
        _message = inMessage;

    }

    @Override
    public String getMessage() {
        // TODO Auto-generated method stub
        return _message;
    }

    @Override
    public void setTimeStamp(Date inDate) {
        // TODO Auto-generated method stub
        _timeStamp = inDate;
        

    }

    @Override
    public Date getTimeStamp() {
        // TODO Auto-generated method stub
        return _timeStamp;
    }
}

3.4 Develop a unit test program

The Custom Alert application is not allowed to have a main() method. You can define it and it actually works, but you can't import the class file to Guardium if it contains a main() method. So, create a unit test program which has a main() method.

MyCustomAlertTester.java

package com.guardium.custom;
import java.util.Date;

public class MyCustomAlertTester {

    /**
     * @param args
     */
    public static void main(String[] args) {
        // TODO Auto-generated method stub
        System.out.println("Test");
        //System.out.println(df.format(new Date()));
        MyCustomAlert obj = new MyCustomAlert();
        obj.processAlert("Hello! This is a test from MyCustomAlert.", new Date());
        System.out.println("Done! Check your guardium_alert table in Oracle.");    
    }

}

 

Run this application. You'll see the result in the console in eclipse like this.

 

Connect to the DB server (Oracle) to see if the test alert message is surely stored into guardium_alert table.

SQL> select * from guardium_alert;

TIMESTAMP
--------------------
MESSAGE
--------------------------------------------------------------------------------
2015-11-24 17:56:27
Hello! This is a test from MyCustomAlert.


SQL>

 

 

 

4. Import the Custom Alert Application and configure the Collector

 

4.1 Import MyCustomAlert.class to Guardium

Logon to the Guardium GUI and navigate to Administration Console > Custom Classes > Custom Alerts > Upload, then upload MyCustomAlert.class with meaningful description, then press Apply button.

The example shows a v9 view - the principle is the same in v10.

You'll see the following message on the screen.

Custom class My Custom Alert [com.guardium.custom.MyCustomAlert] successfully added

 

[NOTE] If your class has a main() method, a failure will occur with the following message.

Uploaded file is not a valid Custom Alerting class:
     java.lang.SecurityException: Custom classes must not have main method.

 

4.2 Add Communication Permissions

Navigate to Administration Console > Custom Classes > Communication Permissions, then add your DB server (Oracle) host and port information, then press Save button.

You'll see the following message on the screen.

Your input for this instance is saved.

 

And you'll see the settings that you added.

 

4.3 Upload the Oracle JDBC driver.

Navigate to Administration Console > Configuration > Customer Uploads, then press Browse... button under Upload Oracle JDBC driver, then upload ojdbc7.jar. (or the latest oracle jar)

Then you'll see the following message on the screen. Restart the GUI as stated. You may need to logoff and logon to the GUI again.

File successfully uploaded. The GUI needs to be restarted:
Select Administration Console > Portal > press Restart.

 

4.4 Create a policy which uses the Custom Alert

Navigate to Tools > Config & Control > Policy Builder, then create a new policy. Let's say the policy name is "Custom Alert Test". Then define an access name, and send a customer alert when employee table is accessed. Make sure to check Cont. to next rule option.

Save this rule, and define another access rule for just LOG FULL DETAILS for everything.

So, there are two rules in the policy. One is to alert per match when employee table is accessed, followed by another rule that simply LOG FULL DETAILS for everything.

 

4.5 Install the policy

Navigate to Administration Console > Configuration > Policy Installation, then installed the policy that you created in the previous step (i.e. -- Custom Alert Test).

 

5. Test

Connect to the test DB server (i.e. grddb14 in this case, which is a Windows sever and MSSQL is running on it).

Run some SQL commands.

C:\>sqlcmd
1> select * from employee
2> go
id          first                            last
----------- -------------------------------- -----------
          1 Smith                            John

(1 rows affected)
1> select * from test1
2> go
Msg 208, Level 16, State 1, Server GRDDB14, Line 1
Invalid object name 'test1'.
1> quit

C:\>

 

So, we should get alert for "select * from employee" but not for "select * from test1", because "employee" is the target table which invokes the customer alert.

 

Let's check the guardium_alert table. You can see the alert message in red.

SQL> select * from guardium_alert;

TIMESTAMP
--------------------
MESSAGE
--------------------------------------------------------------------------------
2015-11-24 17:56:27
Hello! This is a test from MyCustomAlert.

2015-11-24 17:54:52
Alert based on rule ID Send a customer alert when employee table is accessed
Category:   Classification:    Severity INFO
Rule # 20688 [Send a customer alert when employee table is accessed ]
Request Info: [ Session start: 2015-11-24 17:54:46 Server Type: MS SQL SERVER Cl
ient: 9.68.240.144 (GRDDB14) Server: 9.68.240.144 (GRDDB14) Client PORT: 60261 S

TIMESTAMP
--------------------
MESSAGE
--------------------------------------------------------------------------------
erver Port: 2754 Service Name: MS SQL SERVER Net Protocol: WINDOWS NAMED PIPES D
B Protocol: TDS DB Protocol Version: 9.0 DB User: GUARDIUM\ADMINISTRATOR
Application User Name:
Source Program: SQLCMD.EXE Authorization Code: 0 Request Type: SQL_LANG Last Err
or:
SQL: select * from employee

 SQL Status:
 To add to baseline:

TIMESTAMP
--------------------
MESSAGE
--------------------------------------------------------------------------------


SQL>

 

Troubleshooting

If you don't see the alert in your target table (i.e. guardium_alert table), gather the Application Debug Log from the diag command and use fileserver to save and send the relevant file under debug-logs

Send the diagnostic logs to IBM Technical Support with a description of the problem .

* Internal Reference for IBM Technical Support staff - Please note further details are found within the Internal Reference.


[{"Product":{"code":"SSMPHH","label":"IBM Security Guardium"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"--","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"10.0;10.0.1;10.1;10.1.2;10.1.3;9.0;9.1;9.5","Edition":"","Line of Business":{"code":"LOB24","label":"Security Software"}}]

Document Information

Modified date:
16 June 2018

UID

swg22011758

Page Feedback