diff options
Diffstat (limited to 'seaudit/seaudit_help.txt')
| -rw-r--r-- | seaudit/seaudit_help.txt | 293 |
1 files changed, 293 insertions, 0 deletions
diff --git a/seaudit/seaudit_help.txt b/seaudit/seaudit_help.txt new file mode 100644 index 0000000..3959f02 --- /dev/null +++ b/seaudit/seaudit_help.txt @@ -0,0 +1,293 @@ +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>. |