mirror of
https://gitlab.com/apparmor/apparmor.git
synced 2025-03-04 08:24:42 +01:00

and Glob with Ext putting duplicate entries in the list. The fix introduced a Perl 5.10.1 or higher dependency, so start documenting minimum required versions of packages. Acked-By: Christian Boltz <apparmor@cboltz.de>
218 lines
5.9 KiB
Text
218 lines
5.9 KiB
Text
------------
|
|
Introduction
|
|
------------
|
|
AppArmor protects systems from insecure or untrusted processes by
|
|
running them in restricted confinement, while still allowing processes
|
|
to share files, exercise privilege and communicate with other processes.
|
|
AppArmor is a Mandatory Access Control (MAC) mechanism which uses the
|
|
Linux Security Module (LSM) framework. The confinement's restrictions
|
|
are mandatory and are not bound to identity, group membership, or object
|
|
ownership. The protections provided are in addition to the kernel's
|
|
regular access control mechanisms (including DAC) and can be used to
|
|
restrict the superuser.
|
|
|
|
The AppArmor kernel module and accompanying user-space tools are
|
|
available under the GPL license (the exception is the libapparmor
|
|
library, available under the LGPL license, which allows change_hat(2)
|
|
and change_profile(2) to be used by non-GPL binaries).
|
|
|
|
For more information, you can read the techdoc.pdf (available after
|
|
building the parser) and by visiting the http://apparmor.net/ web
|
|
site.
|
|
|
|
|
|
-------------
|
|
Source Layout
|
|
-------------
|
|
|
|
AppArmor consists of several different parts:
|
|
|
|
changehat/ source for using changehat with Apache, PAM and Tomcat
|
|
common/ common makefile rules
|
|
desktop/ empty
|
|
kernel-patches/ compatibility patches for various kernel versions
|
|
libraries/ libapparmor source and language bindings
|
|
parser/ source for parser/loader and corresponding documentation
|
|
profiles/ configuration files, reference profiles and abstractions
|
|
tests/ regression and stress testsuites
|
|
utils/ high-level utilities for working with AppArmor
|
|
|
|
--------------------------------------
|
|
Important note on AppArmor kernel code
|
|
--------------------------------------
|
|
|
|
While most of the kernel AppArmor code has been accepted in the
|
|
upstream Linux kernel, a few important pieces were not included. These
|
|
missing pieces unfortunately are important bits for AppArmor userspace
|
|
and kernel interaction; therefore we have included compatibility
|
|
patches in the kernel-patches/ subdirectory, versioned by upstream
|
|
kernel (2.6.37 patches should apply cleanly to 2.6.38 source).
|
|
|
|
Without these patches applied to the kernel, the AppArmor userspace
|
|
will not function correctly.
|
|
|
|
------------------------------------------
|
|
Building and Installing AppArmor Userspace
|
|
------------------------------------------
|
|
|
|
To build and install AppArmor userspace on your system, build and install in
|
|
the following order.
|
|
|
|
|
|
libapparmor:
|
|
$ cd ./libraries/libapparmor
|
|
$ sh ./autogen.sh
|
|
$ sh ./configure --prefix=/usr --with-perl # see below
|
|
$ make
|
|
$ make check
|
|
$ make install
|
|
|
|
[optional arguments to libapparmor's configure include --with-python
|
|
and --with-ruby, to generate python and ruby bindings to libapparmor,
|
|
respectively.]
|
|
|
|
|
|
Utilities:
|
|
$ cd utils
|
|
$ make
|
|
$ make check
|
|
$ make install
|
|
|
|
|
|
parser:
|
|
$ cd parser
|
|
$ make
|
|
$ make check
|
|
$ make install
|
|
|
|
|
|
Apache mod_apparmor:
|
|
$ cd changehat/mod_apparmor
|
|
$ make # depends on libapparmor having been built first
|
|
$ make install
|
|
|
|
|
|
PAM AppArmor:
|
|
$ cd changehat/pam_apparmor
|
|
$ make # depends on libapparmor having been built first
|
|
$ make install
|
|
|
|
|
|
Profiles:
|
|
$ cd profiles
|
|
$ make
|
|
$ make check # depends on the parser having been built first
|
|
$ make install
|
|
|
|
|
|
[Note that for the parser and the utils, if you only with to build/use
|
|
some of the locale languages, you can override the default by passing
|
|
the LANGS arguments to make; e.g. make all install "LANGS=en_US fr".]
|
|
|
|
-------------------
|
|
AppArmor Testsuites
|
|
-------------------
|
|
|
|
A number of testsuites are in the AppArmor sources. Most have documentation on
|
|
usage and how to update and add tests. Below is a quick overview of their
|
|
location and how to run them.
|
|
|
|
|
|
Regression tests
|
|
----------------
|
|
For details on structure and adding tests, see
|
|
tests/regression/apparmor/README.
|
|
|
|
To run:
|
|
$ cd tests/regression/apparmor (requires root)
|
|
$ make
|
|
$ sudo make tests
|
|
$ sudo bash open.sh -r # runs and saves the last testcase from open.sh
|
|
|
|
|
|
Parser tests
|
|
------------
|
|
For details on structure and adding tests, see parser/tst/README.
|
|
|
|
To run:
|
|
$ cd parser/tst
|
|
$ make
|
|
$ make tests
|
|
|
|
|
|
Libapparmor
|
|
-----------
|
|
For details on structure and adding tests, see libraries/libapparmor/README.
|
|
$ cd libraries/libapparmor
|
|
$ make check
|
|
|
|
Utils
|
|
-----
|
|
There are some simple tests available, including basic perl syntax
|
|
checks for the perl modules and executables. There are also minimal
|
|
checks on the python utilities and python-based tests in the test/
|
|
subdirectory.
|
|
$ cd utils
|
|
$ make check
|
|
|
|
The aa-decode utility to be tested can be overridden by
|
|
setting up environment variable APPARMOR_DECODE; e.g.:
|
|
|
|
$ APPARMOR_DECODE=/usr/bin/aa-decode make check
|
|
|
|
Profile checks
|
|
--------------
|
|
A basic consistency check to ensure that the parser and aa-logprof parse
|
|
successfully the current set of shipped profiles. The system or other
|
|
parser and logprof can be passed in by overriding the PARSER and LOGPROF
|
|
variables.
|
|
$ cd profiles
|
|
$ make && make check
|
|
|
|
Stress Tests
|
|
------------
|
|
To run AppArmor stress tests:
|
|
$ make all
|
|
|
|
Use these:
|
|
$ ./change_hat
|
|
$ ./child
|
|
$ ./kill.sh
|
|
$ ./open
|
|
$ ./s.sh
|
|
|
|
Or run all at once:
|
|
$ ./stress.sh
|
|
|
|
Please note that the above will stress the system so much it may end up
|
|
invoking the OOM killer.
|
|
|
|
To run parser stress tests (requires /usr/bin/ruby):
|
|
$ ./stress.sh
|
|
|
|
(see stress.sh -h for options)
|
|
|
|
-----------------------------------------------
|
|
Building and Installing AppArmor Kernel Patches
|
|
-----------------------------------------------
|
|
|
|
TODO
|
|
|
|
|
|
-----------------
|
|
Required versions
|
|
-----------------
|
|
|
|
The AppArmor userspace utilities are written with some assumptions about
|
|
installed and available versions of other tools. This is a (possibly
|
|
incomplete) list of known version dependencies:
|
|
|
|
AppArmor.pm (used by aa-audit, aa-autodep, aa-complain, aa-disable,
|
|
aa-enforce, aa-genprof, aa-logprof, aa-unconfined) requires minimum
|
|
Perl 5.10.1.
|
|
|
|
Python scripts require minimum Python 2.7. Some utilities may require
|
|
Python 3.3. Python 3.0, 3.1, 3.2 are largely untested.
|
|
|
|
Most shell scripts are written for POSIX-compatible sh. aa-decode expects
|
|
bash, probably version 3.2 and higher.
|