SETools - Policy analysis tools for SELinux (C) 2001-2014 Tresys Technology setools@tresys.com, http://oss.tresys.com/projects/setools

1. Overview

2. Installation 2.1. compiling from official distribution 2.2. compiling from git clone 2.3. configure flags 2.4. using development version of SELinux 2.5. Logwatch support 2.6. doxygen support

3. Features 3.1. graphical tools 3.2. command-line tools 3.3. analysis libraries

4. Obtaining SETools

5. Reporting bugs

6. Copyright license

7. Overview

This file describes SETools, developed by Tresys Technology. SETools is a collection of graphical tools, command-line tools, and libraries designed to facilitate SELinux policy analysis. Although SETools is primarily targeted for Red Hat-based systems, it should also work for Gentoo and Debian distributions. See the file KNOWN-BUGS for testing information.

SETools includes the following graphical tools, command-line tools, and libraries:

apol policy analysis tool libapol policy analysis library libpoldiff semantic policy difference library libqpol library that abstracts policy internals libseaudit parse and filter SELinux audit messages in log files libsefs open and search SELinux file contexts seaudit audit log analysis tools: seaudit and seaudit-report sechecker SELinux policy checking tool secmds command line tools: seinfo, sesearch, findcon, replcon, and indexcon sediff semantic policy difference tools: sediff and sediffx

Each of these components is in a subdirectory under the top-level source directory, along with supporting pieces in the following directories:

man manual pages for SETools commands packages miscellaneous support for external packages

In addition the top-level source directory contains various pieces of documentation. Please consult the file KNOWN-BUGS in this directory prior to filing any bug reports.

2. Installation

SETools uses the GNU build system to configure, compile, and install. As such it contains a configure script that will verify its dependencies. SETools requires the following development packages for compilation: flex bison pkg-config 0.23 or greater libselinux 2.0.87 or greater libsepol 2.0.38 or greater libsepol-static 2.0.38 or greater libxml2 sqlite 3.6.20 or greater

These packages are needed to build SETools's graphical tools: swig 1.3.28 or greater bwidget 1.8 or later tcl-devel 8.4.9 or greater tk-devel 8.4.9 or greater glib2-devel gtk2-devel 2.8 or greater libglade2-devel

To build additional SETools SWIG wrappers, these packages are required: Java JDK 1.2 or greater python-devel 2.3 or greater

Apol requires BWidget 1.7 or greater to run. The BWidget toolkit is part of the tcllib package and is often not present in Linux distributions; the toolkit may be freely downloaded at http://tcllib.sourceforge.net. The supplied configure script attempts to detect the version of BWidget installed. If it is not found then SETools will use the prepackaged one found within the 'packages' subdirectory. In some situations the toolkit will not be automatically found; if you are sure that BWidget is present then specify --disable-bwidget-check to the configure script.

The official, stable source distribution is available from http://oss.tresys.com/projects/setools/. Untar and uncompress the distribution, and perform the following.

$ cd setools-3.3.7 $ ./configure $ make $ make install

This will put the binaries in /usr/local/bin, data files in /usr/local/share/setool-3.3, and libraries in /usr/local/lib. Assuming that /usr/local/bin is in your $PATH and /usr/local/lib in $LD_LIBRARY_PATH everything should now work.

If you prefer the bleeding edge of SETools development, you could instead obtain the development version of SETools from the git repository (see Section 4).

$ cd setools $ autoreconf -i -s $ ./configure $ make $ make install

You will need a recent version of autoconf to create the configure script. SETools was written using autoconf-2.60, although autoconf-2.59 also seems to work correctly albeit with a build warning.

As SETools uses the GNU build system, other make targets are available. make install-strip' will strip unneeded symbols from installed binaries. make uninstall' removes files written by an earlier install.

You can customize your SETools build using the flags given to `configure'. Notable options include:

--enable-debug All code will be compiled using static libraries and the gcc flags '-g3 -gdwarf-2 -O0'. This flag is useful for tracking down issues.

--disable-gui Build only the command-line tools: seinfo, sesearch, findcon, indexcon, replcon, sechecker, and sediff.

--disable-bwidget-check Assume that BWidget 1.8 is installed on the system. The configure script normally tries to launch a Tcl script that loads BWidget, which requires a running X session. You will need this flag if compiling in a non-X environment.

--disable-selinux-check Disable the build-time check for SELinux. In rare circumstances the build computer will not have SELinux running, resulting in 'configure' producing a warning and disable parts of SETools. By specifying this flag, 'configure' will not disable parts of SETools.

--enable-swig-java Build SWIG interfaces for Java. This permits third-party developers who prefer Java to use the SETools libraries for their own projects.

--enable-swig-python Build SWIG interfaces for Python. This permits third-party developers who prefer Python to use the SETools libraries for their own projects.

--enable-swig-tcl Build SWIG interfaces for Tcl. This is needed for the apol tool. By default this flag is enabled.

--enable-sepol-src=PATH Look for libsepol source files in PATH. Use this flag when compiling against a development version of SELinux (see Section 2.4). Note that if --enable-sepol-src and --with-sepol-devel are both specified then this flag takes precedence.

--with-tcl=PATH Look for Tcl development files in PATH. Debian users will need to specify this flag, as Tcl 8.4 is typically located at /usr/lib/tcl8.4.

--with-tk=PATH Look for Tk development files in PATH. Debian users will need to specify this flag, as Tk 8.4 is typically located at /usr/lib/tk8.4.

--with-sepol-devel=PATH Look for libsepol header files in PATH/include and library in PATH/lib64 and PATH/lib. Note that if --enable-sepol-src and --with-sepol-devel are both specified then --enable-sepol-src takes precedence.

--with-selinux-devel=PATH Look for libselinux header files in PATH/include and library in PATH/lib64 and PATH/lib.

--with-default-policy=PATH Explicitly use PATH as the default SELinux policy source file, instead of inferring its location based upon the return value of selinux_policy_root().

--with-test-policies=PATH Use the policies in PATH as input to the SETools tests; these tests are invoked upon `make check'.

Of course, `configure' accepts other usual flags such as --prefix.

As SELinux is a rapidly evolving project, you may wish to use a version of libsepol.so that is newer than the one installed to /usr/lib. To support different versions of libsepol, SETools can be configured to compile against a specific version of libsepol using the --enable-sepol-src flag. For example, suppose you have a SELinux SVN checkout and compilation like the following:

$ cd /home/gburdell $ svn co https://svn.sourceforge.net/svnroot/selinux/trunk selinux $ cd selinux/libsepol $ make

You can compile SETools against this particular copy of libsepol:

$ cd /home/gburdell/setools $ ./configure --enable-sepol-src=/home/gburdell/selinux/libsepol

Note that --enable-sepol-src will override the flag --with-sepol-devel.

Integrating SETools with Logwatch can provide an effective IDS solution by automating customized audit reports and having them emailed to a specific recipient(s) for further analysis. You can integrate SETools into Logwatch using the seaudit-report plugin by specifying the `make install-logwatch' target. This target installs the configuration necessary for having seaudit-report run as a Logwatch service. The configuration files are part of the SETools source distribution, located in the seaudit subdirectory, and include:

seaudit-report-group.conf: logfile group configuration file

seaudit-report-service.conf: service filter config file

seaudit-report-service: service filter script

Make sure the Logwatch program is installed before proceeding with using this install target.

All externally exported library functions include doxygen-style tags in the documentation. To produce your own HTML outputs when writing third-party tools, use the doxygen configuration file located in packages/Doxyfile; it directs generated output to /tmp/setools. From the top-level source directory do:

$ doxygen packages/Doxyfile

3. Features

SETools encompasses a number of tools, both graphical and command line, and libraries. Many of the programs have help files accessible during runtime.

The main emphasis of SETools is the graphical analysis tools.

apol: A Tcl/Tk graphical analysis tool. Use it to open a SELinux policy, examine the policy's components and rules, and perform various types of analyses.

seaudit: A GTK+ graphical audit log analysis tool for SELinux. This tool allows users to sort and filter the system's audit log, query the policy based on audit messages, and export audit log messages to a file. The tool can also create reports in HTML or plaintext format using an entire audit log or an seaudit view. Note that this program is installed in $(PREFIX)/sbin because its main function is to analyze /var/log/audit/audit.log.

sediffx: A GTK+ graphical tool to semantically compare two policies. Use sediffx to open two SELinux policies, find differences between them, and then show those results.

Some tools in the SETools suite may be run in a non-windowing environment. The first six tools listed below are located in the secmds subdirectory; the rest are in their own directories.

seinfo: A tool to quickly get a list of components from a SELinux policy.

sesearch: A tool to search rules (allow, type_transition, etc.) and constraints within a SELinux policy.

findcon: A tool to search files with a matching SELinux file context. The tool can search a filesystem directly, a file_contexts file, or a database as created by indexcon.

replcon: A tool to search the filesystem, replacing a matched file's context with a different one.

indexcon: A tool to create a database that indexes the security contexts of a SELinux filesystem.

sechecker: A tool for performing modular checks on an SELinux policy. Sechecker supports configuration profiles to specify multiple modules and generates a report of potential issues within a policy.

seaudit-report: A tool for generating reports on SELinux audit messages in plaintext or HTML format. Reports generated by this tool can be configured to include standard report sections such as policy load messages, enforcement toggles messages, policy boolean messages, etc. A key feature of the tool is that reports can be further customized through the use of saved seaudit view files. The tool can effectively be used as a plugin to other audit log analysis tools, such as the Logwatch daemon.

sediff: A tool to load two SELinux policies, find differences between them, and then show those results. The tool provides a command-line interface to libpoldiff.

The SETools support libraries (libapol, libpoldiff, libqpol, libseaudit, and libsefs) are available for use in third-party applications. Although they are not officially supported (and thus subject to change between SETools releases), we will do our best to maintain compatibility beginning with SETools version 3.0.

libqpol: Abstract the internals of an SELinux policy behind a consistent interface, such that changes to the policy representation (as governed by libsepol) do not affect analysis tools.

libapol: Work with libqpol to perform higher-order analyses of a policy. A typical sequence for an analysis tool is: open a policy via apol_policy_open() execute some query via apol/policy-query.h obtain detailed results via qpol/policy_query.h close the policy via apol_policy_destroy()

libseaudit: Parse and store SELinux audit messages. Its chief users are seaudit and seaudit-report.

libpoldiff: Accept two SELinux policies and finds differences between them. Its main users are sediff and sediffx.

libsefs: Create a represention of file contexts, by reading contexts directly from a filesystem, from a file_contexts file, or from a specially formatted database. Queries can then be created and executed against those file contexts

These libraries have SWIG wrappers that are built if --enable-swig-java, --enable-swig-python, and/or --enable-swig-tcl are given during configuration time. The generated Java wrappers will be in placed $PREFIX/lib; symlinks to jar files will be in $PREFIX/share/java. Python wrappers will be installed to Python's site-packages directory. Tcl wrappers are built as Tcl packages (e.g., `package require apol') and placed in $PREFIX/lib/setools.

4. Obtaining SETools

Official releases of SETools may be freely downloaded from Tresys's Open Source Software website, http://oss.tresys.com/projects/setools.

Tresys builds RPM packages of SETools. They may also be obtained from the website listed above.

SETools source code is maintained within a git repository. From the command line do:

$ git clone https://github.com/TresysTechnology/setools3.git

You may also browse the git repository at https://github.com/TresysTechnology/setools3

Other binary releases SETools are available for your favorite Linux packaging system from third-party sources. Gentoo users have an ebuild script for SETools. Debian maintains the dpkg "setools" in section admin, priority optional.

5. Reporting bugs

If you found a bug, have a suggestion, or otherwise would like to comment upon SETools, please email setools-bugs@tresys.com. We will respond to you as soon as possible.

6. Copyright license

The intent is to allow free use of this source code. All programs' source files are copyright protected and freely distributed under the GNU General Public License (see COPYING.GPL). All library source files are copyright under the GNU Lesser General Public License (see COPYING.LGPL). Absolutely no warranty is provided or implied.