A.3. The AuditConsole API

Starting with the AuditConsole version 0.4.3 a simple stateless web-service API has been added to the AuditConsole. The purpose of this API is to allow a simple interaction with the data stored (audit events, logs) by just using command line tools such as curl or wget.

The API provides a set of URLs, starting with /api and requires proper authentication, either by using basic HTTP authentication or by providing an authentication token, that can be created on per-user basis.

By far the most simple API call currently supported is /api/events/count which simply returns the count of audit-events with the current user's view. Example:

# curl -u admin:admin http://localhost:8080/api/events/count

The currently provided API URLs are

  • /api/events/count - counting the number of audit-events
  • /api/events/list - return the list of TX_IDs of all events matching a filter
  • /api/events/delete - delete events by filter
  • /api/events/get - retrieve a raw events from the database

The following section describes the commands in more detail.

A.3.1. API Authentication & Views

The API calls require a valid authentication. This can either be done using HTTP basic authentication, i.e. by using curl's parameter -u username:password or by specifying an authentication token called _jwall_token in the URL:

        /api/events/count?filter=...&_jwall_token=ABCDE

The authentication token can be created on per-user basis in the user setup of the AuditConsole.

The API calls act upon the user-view of the user that authenticated with the request. Thus, if you execute a delete command as user chris, you can only delete events that are within the view of that user.

A.3.2. Standard parameters

Each API URL does provide some parameters. The most fundamental one is the filter parameter, which can be any filter expression in the syntax of the AuditConsole filter language. As a simple example, the following filter matches all POST requests with a response status of 200:

REQUEST_METHOD = POST AND RESPONSE_STATUS = 200

To send this filter to the API using curl, we need to URL encode the filter string first and then simply append it to the URL:

# curl -u admin:admin \
  "http://.../api/events/count?filter=REQUEST_METHOD+%3D+POST+AND+RESPONSE_STATUS+=+200"
9

Another important parameter is the limit parameter. This lets you limit the number of events the call should act upon. The limit parameter takes an integer value.

A.3.3. API Commands

This sections shows the available API commands of the AuditConsole and provides detailed information about the parameters supported by each API URL.

/api/events/count

This very basic command simply counts the number of events that are matching a specified filter expression. If no filter expression is given, then the count of all events in the calling user's view is returned.

A simple example for this call is:

# curl -u admin:admin \
  http://localhost:8080/api/events/count?filter=REQUEST_METHOD+%3D+GET
12

Counting by Variable

The count command also allows for the specification of an optional variable parameter, which allow for a group-by counting. E.g. to return the number of events for all methods, you need to call:

# curl -u admin:admin \
  http://localhost:8080/api/events/count?variable=REQUEST_METHOD
REQUEST_METHOD;COUNT
GET;342
POST;23
HEAD;103

As you see in this example, the result is a CSV formatted table in plain text.

/api/events/list

This command allows you to obain a list of transaction IDs of all events matching a given filter. If no filter is specified, the list returns all events of the calling user's view.

# curl -u admin:admin \
  http://localhost:8080/api/events/list?filter=REQUEST_METHOD+%3D+GET
-MtehX8AAAEAACuthp0AAAAJ
exVHyn8AAAEAAAgeHgoAAAAD
...

By default the URL returns a maximum of 10 elements as result. In order to obtain a larger set of results, you need to specify the limit parameter:

# curl -u admin:admin \
  http://localhost:8080/api/events/list?filter=REQUEST_METHOD+%3D+GET&limit=100
nPKnp38AAAEAAAgcGvUAAAAB
Ho2-2H8AAAEAAEv1O8QAAAAG
...
/api/events/delete

This command allows for the deletion of events that match a specific filter. Please note, that this command by default deletes only the first event matching that filter. This is intentionally to limit the danger of deleting all events.

# curl -u admin:admin \
  http://localhost:8080/api/events/delete?filter=REQUEST_METHOD+%3D+GET
1

The command returns the number of events deleted.

You can use the limit parameter to delete more than one element at once. To really delete all events matching a filter you can specify a limit of -1:

# curl -u admin:admin \
  "http://localhost:8080/api/events/delete?filter=REQUEST_METHOD+%3D+GET&limit=-1"
9
/api/events/get

The get command is used to download the raw data of an event from the AuditConsole. The event needs to be specified by its transaction ID:

# curl -u admin:admin \
  http://localhost:8080/api/events/get?exVHyn8AAAEAAAgeHgoAAAAD
--4af823a-A--
[2011/09/23 18:39:02+0200] exVHyn8AAAEAAAgeHgoAAAAD 192.168.10.1 32311...
...