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