Audit Log Analysis Tool for Security Enhanced Linux


Overview:
---------
This file contains basic help information for using seaudit, an audit
log analysis tool for Security Enhanced Linux (SELinux) audit
messages.

The tool does not need to be installed on an SELinux system; it will
work on 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 the following main functions:
  1) Browse and sort SELinux audit messages.
  2) Filter an audit log based on fields in the messages.
  3) Search the policy based on data from a given audit message.
  4) Export SELinux audit messages to a file.
  5) Generate reports in HTML or plain text format from an entire log
     or an seaudit view.


Log and Policy Files:
---------------------
The program provides you with the option of opening either a source,
monolithic binary, or modular policy file.  If a policy is not
specified at the command line, seaudit will attempt to use the default
policy location, as specified during configuration time (e.g.,
./configure --with-default-policy).

Note that seaudit does not require an opened policy; in this case the
user will not be able to use the search policy features of the tool.
Only one policy and one audit log can be open at a time, so if another
one is opened the current one will be closed.

When opening a log file the user may get the warning "Warning! One or
more invalid messages found in audit log."  This means that one or
more of the SELinux audit messages either was missing a standard
message field (e.g., time, hostname, or access type) or:

  1) A message had an unrecognized time stamp,
  2) An AVC message did not contain permissions,
  3) An AVC message was not labeled as "denied" or "granted",
  4) A load policy message was not in the correct form, such as
     missing a line or a data field, or
  5) A Boolean message did not contain a list of Booleans.
    
The seaudit program will still attempt to display the remaining data
from the SELinux audit message in question along with all the other
SELinux messages in the log, but only if one of the following
sub-strings is found within the message:

  "avc:" - an access denied or granted message,
  "security:" - a load policy message, or
  "committed booleans" - a change in one or more Boolean states.

All other messages will be ignored.


Menus:
------
Use the FILE menu to load a different audit log or a policy.  The file
menu also allows the user to change preferences including default log,
default policy, which columns to present when viewing audit logs, and
whether seaudit should enable real-time log monitoring upon start-up.
All of these settings will be saved and reloaded each time seaudit is
started.

The VIEW menu allows the user to display multiple views of a log.  A
default view is created automatically when an audit log is first
opened.  Additional views can be created by selecting View->New View.
A view has its own set of filters that limits which messages are
shown.  Use 'Save View' and 'Save View As...' menu items to save to
file the current view's settings.  'Export Messages' writes to a file
the messages within the current view; 'Export Selected Messages'
writes only those that are currently selected.  'View Selected
Message' will open a new window that shows all of the fields for the
selected log message or messages.

Use the SEARCH menu to find type enforcement rules within the policy.

The TOOLS menu presents seaudit's advanced features.  The first
option, 'Create Report...', is used to create report files in HTML or
plain text format using an entire audit log or an seaudit view.
'Monitor Log' enables and disables seaudit's real-time monitoring
feature.

Right-click on an audit message within a view to display a pop-up menu
that allows the user to:
  - View the entire message within a separate text box,
  - Find TE Rules within the policy using the message, or
  - Export selected messages to a file.


Sorting:
--------
By default the messages within a view are sorted in the order they
appear within the log file, typically chronologically.  To sort by a
particular field click on the column heading.  The only column that
cannot be used for sorting is the 'Other' column.  Only one level of
sorting can be performed.  The file KNOWN-BUGS describes a particular
instance where the sort order may be misleading.


Log Monitoring: 
---------------
Selecting 'Monitor Log' from the Tools Menu or clicking on the 'Toggle
Monitor' button turns on and off the real-time log monitoring feature.
When this feature is on, seaudit checks for new messages at a regular
interval, per second by default.  This interval can be configured from
the Preferences dialog.  As new messages are added to the currently
loaded log file, each view will be updated according to its filters
and sorting criterion.


Finding TE Rules:
-----------------
The 'Find TE Rules' button opens a new dialog box that contains two
tabs.  In the first tab, the user enters search criteria similar to
those in apol's TE Rules query.  If the user had right-clicked an
audit message and selected the second option, the search criteria will
be filled in automatically based on that message.  For each entry, the
user may enter a regular expression; he may also choose a entry from
the drop-down box.

The 'Only show direct matches' checkbox alters the meaning of the
search.  By default the search returns rules that have either the
provided type or any of the type's attributes in the appropriate
field.  If this checkbox is enabled then the search will only find
that type; it ignores the type's attributes.

Click on 'Find TE Rules' button to perform the search and return a
list of matching rules.  If the currently opened policy file is
capable of showing line numbers, the displayed rules will contain
hyperlinks to the appropriate line in the Policy Source tab.

The second tab, 'Policy Source', provides a convenient display of the
text of the policy source file and is only available when opening a
source policy.  If a modular policy was opened, then this tab only
shows the base policy's source.

The seaudit program provides limited searching.  More thorough policy
searches and analyses may be conducted through the companion tool,
apol.


Log Views:
----------
The 'Modify View' button opens a dialog box that lets the user modify
the list of filters for the current view.  Filters are used to select
either messages to show or to hide; in addition messages can match
either any filter or all filters.


Modifying 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, and then 'Add'.  Within this new dialog, edit the
various properties of a filter such as its name, description, source
context, target context, object type, etc.

Use the 'Context' tab to enter values for part or all of the source
and target context, as well as the object class.  Either enter the
values manually with a comma between entries or click on the button
(e.g., Types) and to open another dialog that has a list of all valid
entries.  This list can be populated by values from the log, the
policy, or both the log and policy, by selecting the appropriate radio
button.

Use the 'Other' tab to filter by networking criteria (i.e., IP
address, port and/or interface) and other miscellaneous fields.  Many
of these fields accept either an exact match or a glob expression (see
Globbing Expressions below); the text entries' tool tips specify how
matching is performed.

The filter criteria are saved automatically when this dialog is
closed.


Globbing Expressions:
---------------------
Use glob expressions to construct more flexible search filters by
allowing for pattern expansion instead of just static strings.  There
are several different methods of glob syntax that are supported by
seaudit.

(1) Wildcard Matching

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

  (a) The '?' character matches any character.

      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 beginning 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

Complementation allows for searching using the complement of any given
character class or range.  The character '!' must be the first
character after '[' when one desires to use a complementation.  When
using complementations the complement of the 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 occurring between b
               and y (inclusive), and ending in z

      example: a[!c-ik-y]z matches all three-character string starting
               with a followed by any character not occurring between c
               and i (inclusive) or between k and y (inclusive), and
               ending in z


*** CAUTION ***

The seaudit program intersperses the use of regular expressions versus
glob expressions.  For example, 'Edit Filter' uses tool tips to
specify what type of matching is permitted.  The 'Find TE Rules'
dialog allows regular expressions, not glob expressions.
Additionally, note that all characters used in glob 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 loaded along with the
policy type.  In the middle it displays the number of log messages in
the current view and the total number of SELinux messages in the audit
log.  The next label shows the span of the dates in the audit log and
the right-most label shows the status of the real-time log monitor.


Creating Reports:
-----------------
From the Tools menu the user can create report files in HTML or plain
text format using an entire audit log or only those messages present
in the current view.  Select the 'Create Report' menu item to display
a dialog for making configurations to the report and then save the
report to a file.

Choose which messages to report using the input frame.  Messages may
come from the entire audit log file or only those in the current view.
If choosing the entire log, one may also include malformed messages
within the report.  See the previous 'Log and Policy Files' heading
for what makes up a malformed message in seaudit.

Choose the type to report, either plain text or HTML, in the output
frame.  If selecting an HTML file, an HTML style sheet may also be
included into the report.  A report configuration file specifies the
type and order of messages to report.  If the style sheet or the
configuration file is not specified, seaudit will use the appropriate
system default files; the default files may be changed from the
Preferences dialog.

The seaudit report configuration file may be configured to affect
information presented in reports; it is required for report
generation.  From this file, one can configure various sections for
the report, as well as create custom sections in the report through
the use of saved seaudit view files.  Review the default
seaudit-report.conf file that comes packaged with the SETools
distribution for more information.  This file can be located in the
shared data directory where seaudit was installed, typically
/usr/local/share/setools-<version>.
