Audit logging

Audit logging provides a command-line interface to manage audit logging and view audit logs. Audit logs provide a history of changes to objects in the system. They are stored in a full-text index.

If audit logging is used, then for the objects it tracks, its logging replaces the messaging that otherwise would be visible in Administration > Messages.

Important: Audit logging works only on operations that are performed directly on a running system. It does not work on data imported into the system. The bfimport facility updates the database directly and does not interact with the audit logging facility.

Managing Audit Policy

An audit policy controls how much auditing is done. It is determined by the setting of the Audit Policy system configuration setting.
NONE
No auditing information is recorded.
SECURITY
Only security-related are recorded. Examples: access group creation and user session activity.
BASIC
This is the default setting. It is also used if there is an invalid Audit Policy value. Only minimal information is recorded, such as user, object type, uuid, and action.
DETAILED
Records detailed information about what properties changed, including the old value and the new value. Not all objects can provide this information. For those that cannot, there is no difference between BRIEF and DETAILED policy. The Audit Max String Length system configuration setting can be used to limit the amount of data stored.

The Audit Max String Length system configuration setting controls how much information can be recorded for a DETAILED change by capping the length of string data fields. If the audit item exceeds this number of characters, then an SHA message digest is stored instead of the string value. For fields that contain sensitive information, such as passwords, the message digest is used regardless of the string length.

Displaying audit information

A command-line interface allows you to specify what information to display and how to format it.

The View All Audit Logs permission is required. It is assigned by default to the Security and Build Engineer access groups.

Usage: bfauditlog [connection-options][command-options][query]

The literal executable is as follows:

Connection options

-H hostname | --hostname=hostname
The remote host name for the connection. The default is localhost.
-P port | --port=port
Communications port for the connection. The default is 3966.
-d domain | --domain=domain
The domain or realm for authentication. Default: none.
-u login | --user=login
The user name to use for authentication. The default is root.
-p password | --password=password
The password for the authentication user. The default is root.
-E encoding | --encoding=encoding
The output character set encoding to use. If an invalid encoding is specified, then all available encodings are listed and the program exits. Note that the ability to display text in the requested encoding depends on the capabilities of the terminal software used on the client. The default depends on your operating system and JVM support.

Command options

-h
Display help.
-b | --bare
Display less information in the output (bare). The exact effect depends on the output format (see -t). For example, in XML output, the opening tags, ending tags, and row count are omitted. In CSV, the row count and the column names are omitted.
-c auditClass[,auditClass ...] | --audit.class=class-list
Specifies a list of audit classes to use in the query. Separate multiple class names with commas. If specified multiple times, then the union of all audit classes specified is used. If the option is not specified, then all audit classes that the user can specify are used. Use the -L option to list available audit classes. The default is all audit classes that the user is authorized to view.
-f field[,field ...] | --field=field-list
Specifies the fields to include in the output. Separate multiple field names with commas. Use the -L option to list available fields.
-s field[+|-][,field[+|-] ...] | --field=field-list
Lists the fields to use for sorting the output. By default the output is sorted in descending order of the audit.stamp. The + marker specifies ascending order. The - marker specifies descending order. Separate multiple field names with commas. The default is -audit.stamp.
-l [offset,]count | --limit=[offset,]count
Used to paginate the results. The offset and count are expressed in numbers of entries. For example, "-l 100,50" means show 50 entries, after the 100th entry. Output formats that are not bare will include the total number of matching entries in the output.
-a user[,user ...] | --audit.user=user-list
Limits output to entries associated with the specified user or users. Separate multiple user names with commas. If you use multiple -a options, the command uses the union of all users specified in the options. The users may be specified by login IDs or UUIDs. If -–audit-user is specified without a user argument, then the user that is used for authentication is used.
-t format | --format=format
The format to use for output, one of CSV, XML, JSON, or TEXT. The default is TEXT.
-L | --list
Lists available audit classes for the user. Audit classes that are marked with a asterisk (*) are available for the user to access. If used with -c (list of audit classes), then a list of fields available for each class is displayed instead. Other command options have no effect with when this option is specified. Users with ViewAllAudits permission can view audit logs from any class. Other users can use the -a option to view only their own audit logs.

Query

The query is a string that uses the format commonly used by web search engines: a space-separated list of specifications. Specifications are in the form 'field:value' to search for value in the specified field. If no query is specified but at least one option is specified, then all matching audit logs are displayted. The audit user and audit class cannot be specified in the query. Use the command options to specify them.

Note: Use double quotes on Windows systems and single quotes on UNIX and Linux systems.

Examples

  1. This example lists all known query fields for the Project and Step audit classes.
    • Windows
      $ bfauditlog.bat -c Project,Step -L
    • UNIX and Linux
      $ bfauditlog.sh -c Project,Step -L 
  2. This example shows the 10 most recent audit logs for project creations using a comma-separated variables output format and without the column headings or total row count. Only the project's unique identifier and name will be given for each record.
    • Windows
      $ bfauditlog.bat -c Project -t CSV -f audit.target,
        sxProjectName --bare -l 10 "audit.type:Create"
    • UNIX and Linux
      $ bfauditlog.sh -c Project -t CSV -f audit.target,
        sxProjectName --bare -l 10 'audit.type:Create' 
  3. This example retreives the 100 most recent audit logs from the installation on the machine 'buildforge.example.com' after logging in with the domain, username, and password provided.
    • Windows
      $ bfauditlog.bat -H buildforge.example.com 
        -d ExampleLDAP -u apiuser -p "My$ecret" -l 100
    • UNIX and Linux
      $ bfauditlog.sh -H buildforge.example.com 
        -d ExampleLDAP -u apiuser -p 'My$ecret' -l 100
  4. This example retrieves the audit logs that were recorded from the beginning of May 23, 2011 to the end of May 27, 2011, according to the time zone settings of the user that authenticated the connection.
    • Windows
      $ bfauditlog.bat "audit.stamp:[2011/05/23 TO 2011/05/27]"
    • UNIX and Linux
      $ bfauditlog.sh 'audit.stamp:[2011/05/23 TO 2011/05/27]'
  5. This example retrieves the audit logs for projects whose access group levels were changed from the old value of 4, 5, or 6 to the new value 3. Note that square brackets are used to indicate an inclusive range, so '[4 TO 6]' means that the values 4 and 6 will match. Also note that the old and new level values will only be available to search if the auditing policy has been set to 'DETAILED'.
    • Windows
      $ bfauditlog.bat -c Project "ioLevel:[4 TO 6] AND inLevel:3"
    • UNIX and Linux
      $ bfauditlog.sh -c Project 'ioLevel:[4 TO 6] AND inLevel:3'
  6. This example retrieves the audit logs for projects whose access group levels were changed from the old value of 4 or 5 to the new value 2 or 3. Note that curly braces are used to indicate an exclusive range, so '{3 TO 6}' means that the values 3 and 6 will not match. Also note that the old and new level values will only be available to search if the auditing policy has been set to 'DETAILED'.
    • Windows
      $ bfauditlog.bat -c Project "ioLevel:{3 TO 6} AND inLevel:(2 OR 3)"
    • UNIX and Linux
      $ bfauditlog.sh -c Project 'ioLevel:{3 TO 6} AND inLevel:(2 OR 3)'
  7. This example constrains the query to results for audit users root and sv and produces output in a CSV file. It returns data for the Project and Step classes and includes information for the class, type, target, user, and timestamp:
    • Windows
      $ bfauditlog.bat -c Project,Step -f audit.class,
        audit.type,audit.target,audit.user,audit.stamp
      	  -a root,sv -l 10,5 -t CSV
    • UNIX and Linux
      $ bfauditlog.sh -c Project,Step -f audit.class,
        audit.type,audit.target,audit.user,audit.stamp
      	  -a root,sv -l 10,5 -t CSV

Classes

Classes are labels for audit log entries. Use the -L option to list the classes available to you.

Fields

Fields represent information assigned to each audit log record.

Some fields in an audit log record will reflect their state (o for old, n for new, x for extended) and their data type (s for string, i for integer). Example:

  soDescription: Old project description (string)
	snDescription: New project description (string)
	soSelectorUuid:  Old selector's UUID (string)
	snSelectorUuid:  New selector's UUID (string)
	ioRunLimit:  Old run limit (integer)
	inRunLimit:  New run limit (integer)

Feedback