SETools - Policy analysis tools for SELinux (C) 2001-2007

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 SVN checkout
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

1. 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 documentation. Please consult the file KNOWN-BUGS 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.20
• libselinux 1.30.27 or greater
• libsepol 1.12.27 or greater, but NOT libsepol 2.0.2
• libxml2
• sqlite 3.2.0 or greater

These packages are needed to build SETools's graphical tools:

• swig 1.3.28 or greater
• 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.

2.1. compiling from official distribution

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.2
  $ ./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.

2.2. compiling from SVN checkout

If you prefer the bleeding edge of SETools development, you could instead obtain the development version of SETools from the Subversion 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.

2.3. configure flags

SETools may be built a number of ways depending upon the flags given to configure. Here is a list of notable options:

--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, seachecker, 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. Use this flag when compiling against a development version of SELinux; see Section 2.4.

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

2.4. using development version of SELinux

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

2.5. Logwatch support

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.

2.6. doxygen support

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.

3.1. graphical tools

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

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

3.2. command-line tools

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

3.3. analysis libraries

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 Subversion repository. From the command line do:

  $ svn co http://oss.tresys.com/repos/setools/trunk/ setools

You may also browse the SVN repository at http://oss.tresys.com/projects/setools/browser.

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.