Current File : //usr/share/doc/setools-libs-3.3.8/README
SETools - Policy analysis tools for SELinux (C) 2001-2014
Tresys Technology
setools@tresys.com, http://oss.tresys.com/projects/setools
TABLE OF CONTENTS
-----------------
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
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 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.
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.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.
2.2. compiling from git clone
--------------------------------
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.
2.3. configure flags
--------------------
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.
2.4. Using a 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 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/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.
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.) 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.
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 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.
Mini Shell