Audit Log Analysis Tool for Security Enhanced Linux
seaudit, version 1.2
April 15, 2004
selinux@tresys.com

Overview:  
--------- 
This file contains basic help information for using seaudit, an audit
log analysis tool for Security Enhanced Linux (SE Linux) audit
messages.  This is the first generation of this tool so please use
with caution and report any bugs to selinux@tresys.com.

The tool does not need to be installed on an SE Linux system; it will 
work in any Linux machine.  The tool parses a given syslog and 
extracts all load policy messages, AVC messages and change of boolean 
messages from conditional policies.

As of version 1.2 the tool now has the ability to display multiple views of 
a log. The default view is created automatically once an audit log is opened.
Additional views can be created by selecting New -> Tab under the File menu 
(or by pressing Ctrl + T). Each tab can be sorted and filtered independently.

The tool has three main functions:
     1) Browse and sort SE Linux audit messages.
     2) Filter an audit log based on fields in the messages.
     3) Query the policy based on data from a given audit message.


Log and Policy Files:
--------------------
Seaudit accepts the following command line arguments to open files at
startup.  Zero, one, or both arguments will be accepted.
	-l[FILE], --log[=FILE]	       open log file named FILE
	-p[FILE], --policy[=FILE]      open policy file named FILE

Seaudit does not require you to open a policy.conf file; in this case 
you will not be able to use the query policy features of the tool. If 
a policy.conf file is opened it must be syntactically correct (i.e., 
it must not generate errors when run through checkpolicy).  If you 
choose not to open a policy.conf file your functionality will be 
limited. Only one policy.conf file and one audit log can be open at a 
time, so if you open another one of these files the current one will 
be closed.

If you get a warning when opening a log file that says "Warning! One
or more malformed messages found in audit log.", that means one or
more of the SE Linux audit messages either included unknown fields or
one of the required fields (source context, target context, and target
class) was missing.  But the remaining data from SE Linux audit
message in question will still be displayed with all the other SE
Linux messages in the log.

You can also receive a warning that states "Warning! One or more
invalid messages found in audit log."  You could receive this message
for several reasons:
    1) A message had an unrecognized time stamp.
    2) An AVC message didn't contain permissions.
    3) An AVC message wasn't labeled as denied or granted.
    4) A load policy message was not in the correct form, (i.e.,
       missing a line or a data field).
    5) A boolean message did not contain a list of booleans.
These messages will not be extracted from the SE Linux audit log.


Menus:
------
The File menu allows you to change the current policy.conf file and 
audit log.  It also shows a list of recently opened files.  The file 
menu also allows you to change certain preferences including your 
default log and policy files. You can also set which columns (audit 
log data fields) you would like present when you view an audit log. 
Both of these settings will be saved and reloaded each time seaudit is 
started.

The search menu allows you to filter the audit log (See Filter Log
below) or query the policy (See Query Policy below).

Sorting:
--------
By default the messages are sorted in chronological order.  To sort by
a particular field click on the column heading.  The only column that
you cannot sort on is the 'Other' column.  Only one level of sorting
can be performed at this time.


Log Monitoring: 
------------ 
The 'Monitor' button allows you to turn the real-time log monitoring feature
on or off.  When the monitor is off the button displays a red icon and the 
words 'Monitor off', when the monitor is on the button displays a green icon
and the words 'Monitor on'.  When this feature is on, seaudit checks for new 
messages once every second.  If new messages are found they are displayed 
according to the current filter and sorting selections.


Query Policy:
------------- 
The 'Query Policy' button opens a new dialog box that contains two
tabs.  The first tab, 'Query Policy', allows you to enter search
criteria similar to that in apol's TE Rules query.  If you have an
audit message highlighted when you click on this button, the search
criteria is filled in based on the message.  Otherwise, all the
criteria is blank.  You may enter regular expressions into the
source/target type dropdown boxes.  You may type a direct match for an
object into the object class box.  You may also scroll down and pick a
particular entry from the dropdown box.

The "Include Indirect Matches" checkbox alters the meaning of the
search.  The search finds rules that have either the provided type
or any of the type's attributes in the appropriate field.

Clicking on 'Query Policy' displays a hyperlinked list of all rules
fitting your criteria.  Clicking on any of the hyperlinks takes you to
the appropriate line in the policy.conf tab.

The second tab, 'policy.conf', provides a convenient display of the
raw policy.conf source file.  The 'Query Policy' tab supports a
hyperlink to the source policy.conf file.

Doubling clicking on a message is another way to get to the query
policy dialog box that is populated with the data.

For more extensive policy searches and analysis, use our companion 
policy analysis tool (apol).

Filter Log: 
----------- 
The 'Filter Log' button opens a dialog box that allows you to filter
messages in the audit log.  At the top of the dialog box is a dropdown
menu that has four different ways to filter.  You may choose to either
show or hide messages which match all or any of the criteria.

The 'Context' tab allows you to enter values for part or all of the
source and target context, as well as the object class.  Only exact
matches are accepted, no regular expressions.  You can either enter
the values manually with a comma between entries or click on the
button (i.e., Types:) and get another dialog that has a list of all
valid entries.  This list can be populated by values from the log, the 
policy, or the union of the log and policy, by selecting the appropriate
radio button specification.

The 'Other' tab allows you to filter by networking criteria and/or
executable and path.  You can filter IP addresses by regular
expression but Port and Interface are by exact match only.

When you click on the 'Filter Log' button it performs a search on
all of the audit messages (not just those displayed) based on the
criteria you entered.  Clicking on the 'Clear Values' button at the
bottom of either tab clears the values in the current tab only.
Click on "Clear Values" on both tabs and then "Filter log" to show all
the SE Linux messages.

As of version 1.2 the ability to use multiple filters is now available. Now 
upon clicking the 'Filer Log' button you are presented with a window which 
displays a list of all filters that have been created for the current view. 
You have the option to add a new filter, edit or remove any defined filters
and apply the filters to the current view. The list of filters can be applied 
in various ways. They can be configured to show or hide log entries that match 
any or all of the filters in the current filter set by making the appropriate 
selections from the two drop down boxes. 

With the addition of support for multiple filters the processes used to manipulate 
filters have changed slightly. The following is an explanation on how to use the
new various functions of filters.

To add a new filter first select the view for which the filter is needed, by clicking 
on the corresponding tab. Then, click on the 'Filter Log' button near the top of the 
window. You are now preseneted with a window with a list of all filters that have been 
created for the view that was selected. Now click on the 'Add' button to create a new 
filter. You are now shown a window in which you can edit the various properties of a 
filter such as: its name, description, source context, target context, object type, etc.
The information that you provide is saved automatically, so you can just close the window 
when you are done creating the filter to return to the filter list window. You can now 
click the 'apply' button to apply the filter to its associated view.

To edit a previously created filter simply select the filter that needs to be
changed and press the 'Edit' button. All the information that had been previously
added to the filter is now displayed in a window where you can edit any of the
properties of the filter that need to be changed. The changes are saved automatically,
so you can just close the window once you are done editing the filter. The 'Apply'
button must be clicked in order to apply the changes made to the filter to the view.

To export a filter click on the name of the desired filter and press the 'Export'
button. You are now presented with a window where you can indicate where you want
the filter saved, and the name for it to be saved as. Once you have selected a 
destination and name for the filter click 'OK' button to save the filter to disk.

To import a filter click on the 'Import' button in the filter list window. Navigate
to the directory where the stored filter is located, and select it. Now, click on the
'OK' button to add the saved filter to your list of filters that were previously
available for the current view. 

Also in version 1.2 is the ability to use shell globbing expressions in 
filters. This functionality is described below.

Globbing Expressions:
---------------------
Using globbed expressions allows one to construct more flexible search filters 
by allowing for pattern expansion instead of just static strings. There are 
several different methods of globbing syntax that are supported by SEAudit.

(1) Wildcard Matching

String containing the characters '?' and  '*' are said to contain widcard characters. 
While, both are considered wildcards they allow for different functionality.

    (a) The '?' character matches any charcter 

	example: ?at matches the strings- aat, bat, cat, etc.

    (b) The '*' matches any string

	example: sys* matches the strings- system, sysadmin, etc.

(2) Character Classes

Character classes are used when one desires to find certain characters, at a certain 
position within a string. The '[' character is used to begin a character class and the 
']' character is used to end the class. The characters in the string contained between 
the two brackets comprise the character class, which can NOT be empty.
	
	example: e[abz]x matches the strings- eax, ebx, ezx

(3) Ranges

Ranges are an extension of character classes which allow one to allow for finding a certain 
sequential set of characters at any point in the string. The '-' character is used to indicate 
a range of characters, where the character to the  left of the '-' is the beggining, and the 
character to the right of the '-' is the end. Multiple ranges can be used within the same 
character class.
	
	example: a[b-e]f matches the strings- abf, acf, adf, aef
	example: 1[2-36-8]9 matches the strings- 129, 139, 169, 179, 189

(4) Complementation

Complementaion allows for searching using the complement of any given character class or range.
The character '!' must be the first character after '[' when one deisres to use a complementation. 
When using complementations the whole complement of the whole string enclosed in the brackets after 
the '!' character is used.

	example: a[!b-y]z matches all three character strings starting with a followed by any character not
		 occuring after b and before y, and ending in z
	example: a[!c-ik-y]z matches all all three character string starting with a followed by any character
		 not occuring after b and before i or after k and before y, and ending in z 

*** Note: all charcters used in globbing expressions are case sensitive ***

Status Bar: 
----------- 
At the bottom of seaudit is a status bar.  In the left corner it
displays the approximate version of the policy you have loaded.  The
middle displays the number of log messages displayed "/" the total
number of SE Linux messages in the audit log.  The right corner shows
the span of the dates in the audit log.

Known Bugs: 
----------- 
See setools/KNOWN-BUGS for a list of current bugs.
