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
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.
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:
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
Each API URL does provide some parameters. The most fundamental one is the
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.
This sections shows the available API commands of the AuditConsole and provides detailed information about the parameters supported by each API URL.
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
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.
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
# curl -u admin:admin \ http://localhost:8080/api/events/list?filter=REQUEST_METHOD+%3D+GET&limit=100 nPKnp38AAAEAAAgcGvUAAAAB Ho2-2H8AAAEAAEv1O8QAAAAG ...
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
# curl -u admin:admin \ "http://localhost:8080/api/events/delete?filter=REQUEST_METHOD+%3D+GET&limit=-1" 9
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... ...