diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 456 |
1 files changed, 456 insertions, 0 deletions
@@ -0,0 +1,456 @@ +SETools - Policy analysis tools for SELinux (C) 2001-2010 +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 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 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 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 +-------------------- + +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 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. |