Developing a portlet application on compliance reporting for IBM Tivoli Security Compliance Manager

This article provides an example of how to develop a portlet application on compliance reporting for IBM™ Tivoli® Security Compliance Manager (SCM). As recent events indicate, security is a growing concern of enterprises. Enterprises need to address security compliance with an increasing number of government and corporate security policies, standards and regulations.

Hui Guo (, Software Engineer, IBM

Hui Guo is a software engineer in IBM China Development Lab. His focus is Tivoli security products. You can reach him at

Wei Zhang (, Advisory IT Specialist, IBM

Wei Zhang is an information security specialist in IBM China Development Lab. Currently his concentration is information security technology and management. You can reach him at

30 October 2007


  • Introduction
  • Architecture design
  • Prerequisites
  • Portlet development
    1. Query SCM data
    2. Call SCM admin CLI in portlet
    3. Get SCM client List
    4. Retrieve detailed Cclient information
    5. Integrate with Inventory Collector
    6. Perform SCM scans
  • Screenshots
  • Conclusion
  • Resources


IBM Tivoli Security Compliance Manager (SCM) is a policy-driven data collection facility designed to provide security compliance management. SCM allows organizations to define consistent security policies and to monitor compliance with the defined security policies. SCM also provides a reporting capability in the administration console. Each report contains the result of a single snapshot and lists the violations and the corresponding client details. The SCM administrator can schedule a report to run on a periodic basis and configure SCM to automatically send the results to specified e-mail addresses.

We can develop a portlet application to retrieve the data and provide reporting functionality, instead of using the SCM Admin graphical user interface (GUI) or developing operational reports with Crystal Enterprise 9. The portlet application provides Web-based interfaces for system administrators to check compliance status of their systems more easily. They don't need to install the SCM Admin GUI on their workstations, but can use a Web browser to access SCM reports together with detailed client information, and even perform SCM scans. Furthermore, we can integrate SCM with other portlet applications. For example, by associating the asset owner (system administrator) information with SCM clients in the portlet and using Tivoli Common Inventory Technology 1.1, we can establish a system inventory for hardware management. So, it is a very flexible solution.

Architecture design

The architecture design is illustrated in Figure 1. We set up an SCM server, and deploy SCM clients to multiple client systems with different operating systems. Security policies are applied to SCM clients, depending on the classification and operating system of the client. Then, the SCM server distributes Java™-based collectors to those clients. The collectors collect required data from clients and send it back to the SCM server. The collection information, as well as policies and snapshots, are stored in the SCM database on DB2 Universal Database™. A violation can be reported when the collected data is determined not compliant with the applied security policies.

There are three roles in this architecture:

(1) SCM administrator. An SCM administrator manages SCM via the Admin GUI or command line interface (CLI), such as importing or updating polices, creating client groups and so on.

(2) System administrator. We set up a WebSphere® Portal server and developed a portlet application for general users (that is, system administrators) to monitor security compliance of their client systems. The information regarding to SCM clients can be pulled directly from the SCM database and displayed in the portlet. The Admin CLI is also called in the portlet to perform some actions. For example, system administrators can re-scan their systems to check if vulnerabilities have been fixed. Such functions can be implemented through calling an SCM Admin CLI command in the portlet application.

(3) IT Auditor. An IT auditor audits the IT environment and verifies the compliance of all systems. IT auditors have similar privileges to System administrators. They both use the portal interface. The difference is that an IT auditor has privileges to view all systems, while a system administrator can only view and operate on their own systems.

Figure 1. Architecture design
Architecture Design

We will focus on the development of the portlet application in this article. Let's start by talking about the development environment.


The following software is required to set up the runtime and development environments described above. The installation of the software is described in the software manual. Here we used standard installations and configurations.


We installed SCM server, WebSphere Portal server and DB2 server on a single Linux® machine. The default installation directories were used. For example, the installation for SCM server is “/opt/IBM/SCM”. This is important because we needed to specify the CLI command directory in our portlet. The SCM server included SCM administration utilities, which were needed by our portlet.

  • Tivoli SCM Server v5.1 FixPack2
  • WebSphere Portal Server v5.1
  • DB2 v8.1 Fix Pack 2

SCM client:

  • SCM client v5.1 and Fix Pack 2. We deployed SCM clients on many type of systems.

Development machine:

  • Rational® Application Developer v6.0 (for development)

Portlet development

After deploying SCM infrastructure following the steps described in Deployment Guide Series: IBM Tivoli Security Compliance Manager, we start to develop the portlet application using Rational Application Developer. We chose IBM Portlet API for the portlet development. Here is the general approach. We used JDBC to retrieve compliance information stored in the SCM database, and invoke SCM Admin CLI commands to perform some SCM actions, such as registering a client, creating snapshots, and re-scanning compliance status of a client. Those CLI commands are described in Tivoli Security compliance Manager Administrator Guide. You can find these documents in the Resources section.

The following information details the implementation of the main functions of this portlet.

1. Query SCM data

A query operation consists of establishing a DB2 connection, performing an SQL statement query, and terminating the DB2 connection. We use JDBC to connect to the SCM database, and pull data directly. In order to use JDBC, a DB2 JDBC driver is required . Refer to the JDBC article in the Resources section. Here are some code samples. First, we defined some constants as shown in Listing 1.

Listing 1. Constant Definition
 * SCM DB (JAC) related constants
// DB2 JDBC driver name
private static final String DB2_JDBC_DRIVER = "";
// the db name of JAC database, the jac database might be a alias of remote db
private static final String SCM_DB_URL = "jdbc:db2:jac"; 
private static final String SCM_DB_USER = "USERNAME"; // db username
private static final String SCM_DB_PASS = "PASSWORD"; // db password
public Connection con; // DB connection

Next we need establish a JDBC connection to the SCM database. Since establishing the JDBC connection is the most time consuming operation, a global variable con is used to make the connection exist globally. We don't need to connect to DB2 every time before running an SQL statement.

Listing 2. Establish JDBC connection
 * Connect to DB
public void connectToDB() {
	//DB2 connection
	try {
	} catch(java.lang.ClassNotFoundException e) {
		System.err.print("ClassNotFoundException: "); 
	try {
		// Notice: The DB2 connection variable does not close distinctly
		con = DriverManager.getConnection(SCM_DB_URL, SCM_DB_USER, SCM_DB_PASS);
	} catch (SQLException ex) {
		System.err.println("SQLException: " + ex.getMessage());

Here we run a simple query to the SCM database. The clientID is a parameter, which is an integer number.

Listing 3. Perform SQL statement query
String sql;
sql = "select cli_id from jac_idata.cit_computer_v1 where cli_id = " + clientID;

try {
	stmt = con.createStatement();
	ResultSet rs = stmt.executeQuery(sql);
		return true;
} catch(SQLException ex) {
	System.err.println("SQLException: " + ex.getMessage());

After the query is performed, we close the JDBC connection to the SCM database.

Listing 4. Terminate JDBC connection
 * Close db connection
public void Destructor() {
	try {
	} catch (SQLException ex) {
		System.err.println("SQLException: " + ex.getMessage());

2. Call SCM Admin CLI in portlet

The portlet interacts with the SCM server through the SCM Admin CLI. This operation is performed by a Java exec command, as shown in the following sample codes. Note: in order to run the SCM CLI in the portlet, we need to install SCM administration utilities in the WebSphere Portal server machine. For details of how to prepare the WebSphere Portal server to run the provided portlet at the end of this article, carefully read the ReadMe file in Resources carefully.

The policyName and clientID parameters are passed in.

Listing 5. Call SCM Admin CLI in portlet
private static final String SCM_ADMIN_COMMAND_PATH = "/opt/IBM/SCM/admin/";
private static final String SCM_RUN_POLICY_COLLECTORS_COMMAND = "scmrunpolicycollectors";
private static final String SCM_COMMAND_AUTH_INFO = " -u admin -pw 

	+ SCM_COMMAND_AUTH_INFO + " -c " + clientID + " -pol " + policyName;
try {
	Process process = Runtime.getRuntime().exec(cmd);
	InputStreamReader ir=new InputStreamReader(process.getInputStream()); 
	LineNumberReader input = new LineNumberReader(ir);
	while (input.readLine() != null);// NOOP while, do nothing until this command stop
} catch (IOException ex) {
	System.err.println("IO Exception: " + ex.getMessage());

3. Get SCM client list

All SCM clients are found in the SCM database. However, the client's activity status was not stored in the database. So in order to get the status, we need to call the SCM CLI scmlistclients command. Following the method described above, we can call this SCM admin CLI command “scmlistclients” to list all the clients currently registered on SCM. The command will return the client information, in one line per each client. We can get two important things from the returned information: client ID and status (active or inactive). Then, we can use the client ID to retrieve the client's detailed information from the CLIENTS table in the SCM database.

The SCM CLIENTS table is defined as below:

Figure 2. The CLIENT table definition
The CLIENT table defination

SCM server deploys Java collectors to clients, to collect system and security information. The collected information is then stored in the SCM database. The SCM server saves the collected information as a copy that is called a snapshot. It shows historical time-stamped security data of clients. This snapshot data is stored in a table named SNAPSHOT. Once a snapshot is taken, the policy is compared to the snapshot data, and the violations of clients are then stored in the VIALOTIONS table. The compliance information is determined by the collected information and the security policy. Therefore, the compliance or non-compliance information about a client can be found from these two related tables: VIOLATIONS, SNAPSHOT.

4. Retrieve detailed client information

The following detailed information, which is collected by the Java collectors and stored in the SCM database, is listed out when user enter the SCM client information page.

1) Basic information

The following information is obtained from the CLIENTS table.


2) Compliance

The snapshot action will check compliance status of a client and store that information in VIOLATIONS, SNAPSHOTS and some other tables. So the portal needs to just read data from the following tables to determine the violations of a client.







If we relate the VIALOTIONS, NAPSHOTS and POLICIES tables, using the VIALOTIONS.SNA_ID=SNAPSHOTS.ID and SNAPSHOTS.POL_ID=POLICIES.ID, then we can get a violation of a client and its warning information, as shown in Figure 3. If the returned result for a clientID is NULL, the client is compliant, otherwise the violation information will be returned.

Figure 3. The relationship between violation, snapshots and policies table
The Relationship bewteen Violation, Snapshots and Policies table

5. Integrate with Inventory Collector

Tivoli Common Inventory Technology 1.1 provides a common scanner that provides enhanced hardware and software recognition functionality. This common scanner is designed to be independent of Tivoli infrastructure, so that it can run in any environment, including as a stand-alone executable.

By wrapping the common Inventory scanner within an SCM collector, SCM can collect hardware-specific information (and software information) not currently obtained by existing SCM collectors (such as the system serial number). The results of the scan are available in MIF and XML format. This information is valuable for checking compliance as well as for providing identity information against a client system. The collected information is also sent back to the SCM server and stored in SCM database.

The inventory collector is available on Tivoli product support site and is able to collect additional information that:

1) Uniquely identifies a system (serial number, hostname, SCM fingerprint, etc.) and storing it in the SCM database, so that mapping reconfigured or re-imaged systems to system information already in the database will be easier to facilitate.

2) Input and update the inventory information automatically to an asset management system.

This information is collected by Inventory Collector and stored in CIT_* tables.

















6. Perform SCM scans

If a system administrator finds a vulnerability of the client system, the administrator should perform some remediation actions to fix it. After it is fixed, the administrator clicks the button "Check Again" to re-scan the client and check to see if the vulnerability still exists.

There are three steps to perform this action.

a. The portlet calls the SCM Admin CLI command to run the related collectors, which is described in the policies, to collect information.

b. The portlet calls an SCM Admin CLI command scmcreatesnapshot to take a new snapshot;

c. The portlet gets new data from the SCM database and refreshes the display.


Now, we have a portlet application that can show the compliance report of all clients registered on the SCM server, as shown in Figure 4.

You can see that each client takes one row. For each client, all related information such as hostname, IP type and operating system are displayed. There is a column for inventory information. A link is provided, from which the detailed inventory information can be displayed. The WARNING column shows the number of security warnings of a client. If the value is 0, it means the client is compliant. If a none-zero number is shown, it means the client has security vulnerabilities. System administrators can click the link and check the detailed information. If “NA” is shown, it means the client's compliance status is not available. It might be that the client is inactive or that no snapshots were taken on the client. The final column is two operational links: Edit Client Information and Delete Client.

Figure 4. SCM Clients List
SCM Client List

Click the "Register Client" button to register a new client, as shown in Figure 5. Here groups are defined per each operating system via the SCM Admin GUI. Security policies and the Inventory Collector, which can be downloaded from the SCM support Web site (see Resources), are applied on those groups.

Figure 5. Register new SCM Client
Register New SCM Client

Click a client link on the client list page. The client abstract will be displayed, as shown in Figure 6:

Figure 6. SCM Client abstract
SCM Client Abstract

Click the hardware details link, the client hardware info will be displayed, as shown in Figure 7:

Figure 7. Client hardware details
Client Hardware Details

Click the warning details link, the client warning information will be displayed, as shown in Figure 8:

Figure 8. Client warning details
Client Warning Details

If you want to delete a client, click "Unregister Client", then the client will be removed after confirmation. As shown in Figure 9:

Figure 9. Unregister client
Unregister Client


Now we have described the steps to develop a portlet application for system administrators to monitor security compliance status of their systems. Because the portlet can call SCM Admin CLI, we can certainly develop more functions, such as security policy management and compliance report notification. With this methodology, we can integrate other Tivoli products into the portal to support more enterprise IT management requirements.


Instructions to set up portal server environmentReadMe.txt2KB
SCM portlet configuration fileSCMPortlet.conf91B
SCM portlet WAR fileSCMPortal.war779KB
SCM portlet source codesourcecode.zip7.47MB



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Tivoli (service management) on developerWorks

Zone=Tivoli (service management), Tivoli, Java technology, Security
ArticleTitle=Developing a portlet application on compliance reporting for IBM Tivoli Security Compliance Manager