Audit Log Analysis Tool for Security Enhanced Linux
seaudit, version 1.2.1
June 02, 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.

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 provides you with the option of opening either a source or 
binary policy file. If you do not specify a policy to open at the 
command line, seaudit will attempt to use the system default source 
policy (/etc/security/selinux/src/policy/policy.conf), or if this is 
unavailable, the system default binary policy will be opened. 

Note that seaudit does not require you to open a policy file; in this 
case your functionality will be limited. For example, you will not be 
able to use the query policy features of the tool. If a policy file is 
opened it must be syntactically correct (i.e., it must not generate 
errors when run through checkpolicy). Only one policy 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 invalid messages found in audit log.", this means that one or 
more of the SE Linux audit messages either was missing a standard 
message field (e.g. time, hostname, access type, etc.) or:
    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.
    
Seaudit will still attempt to display the remaining data from the SE 
Linux audit message in question along with all the other SE Linux 
messages in the log, only if one of the following substrings is found 
within the message:
    "avc:" - indicates an access denied or granted message
    "security:" - indicates a load policy message
    "committed booleans" - indicates a committed boolean(s) message.
Otherwise, these messages will not be extracted from the SE Linux 
audit log.

Menus:
------
The FILE menu allows you to change the current policy file and/or 
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,
as well as specify whether you would like seaudit to enable real-time
log monitoring on startup. All of these settings will be saved and 
reloaded each time seaudit is started.

The VIEW menu allows you 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 View->New under the 
VIEW menu (or by pressing Ctrl + T). Each tab can be sorted and 
filtered independently.

The SEARCH menu allows you to filter the audit log (See Log Views
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. See Known Bugs below for additional
sorting limitations.

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 filter and sorting selections for the current view.

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 list of all rules fitting your 
criteria.  If the policy file you have opened is NOT a binary policy, 
then this list will contain hyperlinks to take you to the appropriate 
line in the policy.conf tab. Otherwise, hyperlinks will not be provided.
Double-clicking on a message is another way to get to the query policy 
dialog box that is populated with the data.

The second tab, 'policy.conf', provides a convenient display of the
raw  policy.conf source file and is only available when opening a 
policy.conf file.  

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

Log Views: 
----------- 
The 'Modify View' button opens a dialog box that allows you to modify 
a list of filters for the current view of the audit log.  At the top 
of the dialog box is a dropdown menu that has four different ways to apply 
the list of filters.  You may choose to either show or hide log entries 
that match any or all of the filters in the current filter set. The View 
window presents you with the option to add new filters, edit or remove 
any defined filters (see Create|Edit Filters below). You also have the 
option to save settings for the view to a file. Additionally, the View 
window allows you to import/export filters to a file.

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. 

When you click on the 'Apply' button it will apply the filters for the 
associated view. 

Create|Edit Filters Within A View: 
----------------------------------
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 'Modify View' 
button near the top of the main window. You are now preseneted with a View 
window which contains a list of filters for the view that was selected. 
Now click on the 'Add' button to create a new filter. You are now presented 
with 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 '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.

The information that you provide is saved automatically, so you can just 
close the window when you are done creating the filter in order to return 
to the previous View window. 

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. 

Clicking on the 'Clear Values' button at the bottom of either tab clears the 
values in the current tab only. 

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 along 
with the policy type (binary or source).  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.
