Audit Log Analysis Tool for Security Enhanced Linux
seaudit, version 1.0.1
December 18, 2003
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 and AVC messages.

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. You will be unable to filter an audit log or query the 
policy.  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 an invalid policy.conf file is opened the tool should be 
restarted; this is a known bug.

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).
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.


Refresh Log: 
------------ 
The 'Refresh Log' button allows you to refresh the audit log.  Any
messages that have been logged after the tool was started, or the last
refresh, are appended to the end of the list of log messages.  You can
see the new messages by scrolling to the bottom of the list.  The new
messages will follow any sorting or filtering rules you currently have
in place.


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 (filter in) or hide (filter out) messages.  You can also choose
to 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.  The list of entries is extracted from the opened
policy.conf file.  Therefore, if you click on 'Types:' you will get a
list of all valid types in the opened policy.  Also, when you you
perform a filter all entries will be verifies against the opened
policy.conf file and all invalid entries will be removed from the text
box and ignored.

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.


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.
