Appendix A. Appendix

Table of Contents

A.1. The JWall Tool-Box
A.1.1. Installation & Setup
A.1.2. ToolBox Commands
A.2. Reporting Variables
A.3. The AuditConsole API
A.3.1. API Authentication & Views
A.3.2. Standard parameters
A.3.3. API Commands

A.1. The JWall Tool-Box

The JWall Toolbox is a collection of small helper-tools which can be useful for handling ModSecurity audit-log data. It is available at jwall.org/ToolBox.

The Toolbox is an executable jar-archive, which can simply be run by issuing

# java -jar jwall-tools.jar

If you installed one of the jwall-tools packages (Debian or RPM), which include the small jwall wrapper script, the you will only need to issue

# jwall 

When being called with no arguments, it will provide a list of commands, which are available. Currently this list is rather short, but it will incorporate all the ModSecurity-related tools available at jwall.org in the future.

The currently provided commands are

  • count - counting events in an audit-log file
  • send - sending a serial audit-log file to the console
  • send-directory - sending a serial audit-log file to the console
  • console-update - provides an easy way to update the AuditConsole
  • config-tree - displays the inclusion-tree of an Apache configuration file
  • config-zip - creates a zip-archive of all files related to an Apache configuration file

The following section describes the commands in more detail.

A.1.1. Installation & Setup

The jwall-tools is distributed as part of the AuditConsole. In addition to that there are RPM and Debian packages available, which do provide a convenient access to the tools.

The simplest way to install the jwall-tools is by installing the appropriate package for your OS system. There are RPM and Debian packages available:

All packages are signed with my GPG key, with key ID C5C3953C. The key's fingerprint is:

pub   1024D/C5C3953C 2009-11-11
    Key fingerprint = 4324 5FA1 EA37 1C3E EFE3  0730 A5CE 7F45 C5C3 953C

Setup in RedHat/CentOS/Fedora

The RPM packages for the jwall-tools have been created and tested on a CentOS machine. They install all required files within /opt/modsecurity.

To install the tools, simply download the latest RPM package (see download link above) and run

 yum install jwall-tools-0.4-1.noarch.rpm

The RPM depends on the openjdk Java package.

Setup on Debian/Ubuntu

Installing the jwall-tools works similar to the RPM packages. The required .deb-packages are provided at the download location given above. To install the tools simply install the downloaded jwall-tools-0.4-1.deb by running

dpkg -i jwall-tools-0.4-1.deb

After that, you whould have the command jwall available on your system.

A.1.2. ToolBox Commands

The toolbox commands are simply attached to the basic startup command java -jar jwall-tools.jar additionally followed by one or more parameters - depending on the command to be called.

count /path/to/AUDIT_LOG

This command provides a simple way to count the number of events, contained within a serial audit-log file. An example for using this method is given by:

# jwall count /path/to/audit.log

send CONSOLE_URI /path/to/AUDIT_LOG

The send command provides a simple way to send serial audit-log files to the console as if these were sent from a sensor. Please note, that you will have to specify the sensor name and password within the CONSOLE_URI, e.g. call the send command by issuing:

# jwall send http://sensor:password@console-host:8080/rpc/auditLogReceiver \
	      /path/to/audit.log

send-directory CONSOLE_URI /path/to/AUDIT-DIRECTORY

This special send will recursively check all files in the specified AUDIT-DIRECTORY for audit-log event files and send them to the console. It is useful if trying to send all events from ModSecurity to the AuditConsole if ModSecurity is logging in concurrent mode. Assuming ModSecurity is writing concurrent events to /var/log/httpd/audit, then the following command will send all files in this directory:

# jwall send http://sensor:password@console-host:8080/rpc/auditLogReceiver \
		  /var/log/httpd/audit

config-tree /path/to/httpd.conf

Sometimes the Apache's configuration gets pretty large with lots of included files. This little commands will parse the specified httpd.conf and display the inclusion-tree.

config-zip /path/to/httpd.conf ARCHIV.ZIP

This commands behaves very similar to the config-tree command. Instead of printing out the inclusion tree it will create a ZIP archive of all the files related to the Apache configuration. This is helpful for zipping the entire Apache configuration.

console-update /opt/AuditConsole

This command can be used to upgrade to a new version of the AuditConsole. The console-updater checks the jwall.org-site for the latests versions of the AuditConsole and provides you with a list of versions, to which can be switched to:

# jwall console-update /opt/AuditConsole

Before updating your AuditConsole, you will need to manually stop the console and then run the console-updater. The console-update command will create a backup of your current version in a zip-file and preserve all of your current configuration. Thus, it is easily possible to switch back to your previous version in case of any errors.

convert PATTERN AUDIT_LOG

The 'convert' command of the jwall-tools is intended to extract parts of the audit-log entries and print them to the standard output or another file.

The 'convert' command takes at least 2 parameters, which are a PATTERN string and a file to read events from. Optionally one can also specify an OUTPUT file: jwall convert PATTERN AUDIT_LOG [OUTPUT_FILE] The first parameter PATTERN is an arbitrary format string, which may contain macros starting with the '%{' prefix and ending with '}'. Within the macro, any ModSecurity variables can be used.

The AUDIT_LOG parameter denots the file to read audit-event data from. This file is expected to be in ModSecurity 2.x serial audit-log format.

If you want to have the results written to a file instead of the standard output, simple specify an OUTPUT_FILE as last argument.

An example to simple extract all request URIs from a file, you may call the converter like:

		
    # jwall convert "uri=%{REQUEST_URI}" /path/to/audit.log
    [output.log]