From Linux Man Pages
apparmor.d - syntax of security profiles for AppArmor.
DESCRIPTION
AppArmor profiles describe mandatory access rights granted to given programs and are fed to the AppArmor policy
enforcement module using apparmor_parser(8). This man page describes the format of the AppArmor configuration
files; see apparmor(7) for an overview of AppArmor.
FORMAT
The following is a BNF-style description of AppArmor policy configuration files; see below for an example AppAr-
mor policy file. AppArmor configuration files are line-oriented; # introduces a comment, similar to shell
scripting languages. The exception to this rule is that #include will include the contents of a file inline to
the policy; this behaviour is modelled after cpp(1).
INCLUDE = '#include' ( ABS PATH | MAGIC PATH )
ABS PATH = '"' path '"' (the path is passed to open(2))
MAGIC PATH = '<' relative path '>' (the path is relative to /etc/apparmor.d/)
COMMENT = '#' TEXT
TEXT = any characters
PROFILE = [ COMMENT ... ] [ VARIABLE ASSIGNMENT ... ] PROGRAM [ 'flags=(complain)' ]'{' [ ( RESOURCE RULE |
COMMENT | INCLUDE | SUBPROFILE | 'capability ' CAPABILITY ) ... ] '}'
SUBPROFILE = [ COMMENT ... ] PROGRAMHAT '{' [ ( FILE RULE | COMMENT | INCLUDE ) ... ] '}'
CAPABILITY = (lowercase capability name without 'CAP_' prefix; see capabilities(7))
PROGRAM = (non-whitespace characters except for '^', must start with '/')
PROGRAMHAT = '^' (non-whitespace characters; see change_hat(2) for a description of how this "hat" is used.)
RESOURCE RULE = ( FILE RULE | NETWORK RULE ) ','
FILE RULE = ( FILENAME | FILEGLOB ) ACCESS
FILENAME = (non-whitespace characters except for ?*[]{}^, must start with '/'. May include VARIABLE.)
FILEGLOB = (non-whitespace characters, must start with '/', ?*[]{}^ have special meanings; see below. May
include VARIABLE.)
ACCESS = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'm' ) [ ACCESS ... ] (not all combinations
are allowed; see below.)
VARIABLE = '@{' ALPHA [ ALPHANUMERIC ... ] '}'
VARIABLE ASSIGNMENT = VARIABLE ('=' | '+=') (space separated values)
ALPHA = ('a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')
ALPHANUMERIC = ('1', '2', '3', ... '9', 'a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')
All resources and programs need a full path. There may be any number of subprofiles ("hats") in a profile, lim-
ited only by kernel memory. Subprofile names are limited to 974 characters. Not all profiles benefit from sub-
profiles --- applications must either be written or modified to use change_hat(2) to take advantage of subpro-
files. (An Apache module, mod_apparmor(5) has been provided to use change_hat(2).)
Access Modes
File permission access modes consists of combinations of the following modes:
r - read
w - write
ux - unconstrained execute
Ux - unconstrained execute -- scrub the environment
px - discrete profile execute
Px - discrete profile execute -- scrub the environment
ix - inherit execute
m - allow PROT_EXEC with mmap(2) calls
l - link
Access Modes Details
r - Read mode
Allows the program to have read access to the file. Read access is required for shell scripts and other
interpreted content, and determines if an executing process can core dump or be attached to with ptrace(2).
(ptrace(2) is used by utilities such as strace(1), ltrace(1), and gdb(1).)
w - Write mode
Allows the program to have write access to the file. Files must have this permission if they are to be
unlinked (removed.)
ux - Unconstrained execute mode
Allows the program to execute the program without any AppArmor profile being applied to the program.
This mode is useful when a confined program needs to be able to perform a privileged operation, such as
rebooting the machine. By placing the privileged section in another executable and granting unconstrained
execution rights, it is possible to bypass the mandatory constraints imposed on all confined processes. For
more information on what is constrained, see the apparmor(7) man page.
WARNING 'ux' should only be used in very special cases. It enables the designated child processes to be run
without any AppArmor protection. 'ux' does not scrub the environment of variables such as LD_PRELOAD; as a
result, the calling domain may have an undue amount of influence over the callee. Use this mode only if the
child absolutely must be run unconfined and LD_PRELOAD must be used. Any profile using this mode provides
negligible security. Use at your own risk.
Incompatible with 'Ux', 'px', 'Px', 'ix'.
Ux - unconstrained execute -- scrub the environment
'Ux' allows the named program to run in 'ux' mode, but AppArmor will invoke the Linux Kernel's unsafe_exec
routines to scrub the environment, similar to setuid programs. (See ld.so(8) for some information on
setuid/setgid environment scrubbing.)
WARNING 'Ux' should only be used in very special cases. It enables the designated child processes to be run
without any AppArmor protection. Use this mode only if the child absolutely must be run unconfined. Use at
your own risk.
Incompatible with 'ux', 'px', 'Px', 'ix'.
px - Discrete Profile execute mode
This mode requires that a discrete security profile is defined for a program executed and forces an AppArmor
domain transition. If there is no profile defined then the access will be denied.
WARNING 'px' does not scrub the environment of variables such as LD_PRELOAD; as a result, the calling domain
may have an undue amount of influence over the callee.
Incompatible with 'Ux', 'ux', 'Px', 'ix'.
Px - Discrete Profile execute mode -- scrub the environment
'Px' allows the named program to run in 'px' mode, but AppArmor will invoke the Linux Kernel's unsafe_exec
routines to scrub the environment, similar to setuid programs. (See ld.so(8) for some information on
setuid/setgid environment scrubbing.)
Incompatible with 'Ux', 'ux', 'px', 'ix'.
ix - Inherit execute mode
Prevent the normal AppArmor domain transition on execve(2) when the profiled program executes the named pro-
gram. Instead, the executed resource will inherit the current profile.
This mode is useful when a confined program needs to call another confined program without gaining the per-
missions of the target's profile, or losing the permissions of the current profile. There is no version to
scrub the environment because 'ix' executions don't change privileges.
Incompatible with 'Ux', 'ux', 'Px', 'px'. Implies 'm'.
m - Allow executable mapping
This mode allows a file to be mapped into memory using mmap(2)'s PROT_EXEC flag. This flag marks the pages
executable; it is used on some architectures to provide non-executable data pages, which can complicate
exploit attempts. AppArmor uses this mode to limit which files a well-behaved program (or all programs on
architectures that enforce non-executable memory access controls) may use as libraries, to limit the effect
of invalid -L flags given to ld(1) and LD_PRELOAD, LD_LIBRARY_PATH, given to ld.so(8).
l - Link mode
Allows the program to be able to create a link with this name. When a link is created, the file that is
being linked to MUST have the same access permissions as the link being created (with the exception that the
destination does not have to have link access.)
Comments
Comments start with # and may begin at any place within a line. The comment ends when the line ends. This is the
same comment style as shell scripts.
Capabilities
The only capabilities a confined process may use may be enumerated; for the complete list, please refer to capa-
bilities(7). Note that granting some capabilities renders AppArmor confinement for that domain advisory; while
open(2), read(2), write(2), etc., will still return error when access is not granted, some capabilities allow
loading kernel modules, arbitrary access to IPC, ability to bypass discretionary access controls, and other oper-
ations that are typically reserved for the root user.
The only operations that cannot be controlled in this manner are mount(2), umount(2), and loading new AppArmor
policy into the kernel, which are always denied to confined processes.
Variables
AppArmor's policy language allows embedding variables into file rules to enable easier configuration for some
common (and pervasive) setups. Variables may have multiple values assigned, but any variable assignments must be
made before the start of the profile.
The parser will automatically expand variables to include all values that they have been assigned; it is an error
to reference a variable without setting at least one value.
At the time of this writing, only @{HOME} and @{HOMEDIR} are defined in the AppArmor policy provided with SUSE
Linux, in the /etc/apparmor.d/tunables/home file; these variables are used in many of the abstractions described
later.
Globbing
File resources may be specified with a globbing syntax similar to that used by popular shells, such as csh(1),
bash(1), zsh(1).
* can substitute for any number of characters, excepting '/'
** can substitute for any number of characters, including '/'
? can substitute for any single character excepting '/'
[abc]
will substitute for the single character a, b, or c
[a-c]
will substitute for the single character a, b, or c
{ab,cd}
will expand to one rule to match ab, one rule to match cd
#include mechanism
AppArmor provides an easy abstraction mechanism to group common file access requirements; this abstraction is an
extremely flexible way to grant site-specific rights and makes writing new AppArmor profiles very simple by
assembling the needed building blocks for any given program.
The use of '#include' is modelled directly after cpp(1); its use will replace the '#include' statement with the
specified file's contents. #include "/absolute/path" specifies that /absolute/path should be used. #include
"relative/path" specifies that relative/path should be used, where the path is relative to the current working
directory. #include <magic/path> is the most common usage; it will load magic/path relative to a directory spec-
ified to apparmor_parser(8). /etc/apparmor.d/ is the AppArmor default.
The supplied AppArmor profiles follow several conventions; the abstractions stored in /etc/apparmor.d/abstrac-
tions/ are some large clusters that are used in most profiles. What follows are short descriptions of how some of
the abstractions are used.
abstractions/audio
Includes accesses to device files used for audio applications.
abstractions/authentication
Includes access to files and services typically necessary for services that perform user authentication.
abstractions/base
Includes files that should be readable and writable in all profiles.
abstractions/bash
Includes many files used by bash; useful for interactive shells and programs that call system(3).
abstractions/consoles
Includes read and write access to the device files controlling the virtual console, sshd(8), xterm(1), etc.
This abstraction is needed for many programs that interact with users.
abstractions/fonts
Includes access to fonts and the font libraries.
abstractions/gnome
Includes read and write access to GNOME configuration files, as well as read access to GNOME libraries.
abstractions/kde
Includes read and write access to KDE configuration files, as well as read access to KDE libraries.
abstractions/kerberosclient
Includes file access rules needed for common kerberos clients.
abstractions/nameservice
Includes file rules to allow DNS, LDAP, NIS, SMB, user and group password databases, services, and protocols
lookups.
abstractions/perl
Includes read access to perl modules.
abstractions/user-download
abstractions/user-mail
abstractions/user-manpages
abstractions/user-tmp
abstractions/user-write
Some profiles for typical "user" programs will use these include files to describe rights that users have in
the system.
abstractions/wutmp
Includes write access to files used to maintain wtmp(5) and utmp(5) databases, used with the w(1) and associ-
ated commands.
abstractions/X
Includes read access to libraries, configuration files, X authentication files, and the X socket.
The abstractions stored in /etc/apparmor.d/program-chunks/ are intended for use by specific program suites, and
are not generally useful.
Some of the abstractions rely on variables that are set in files in the /etc/apparmor.d/tunables/ directory.
These variables are currently @{HOME} and @{HOMEDIR}. Variables cannot be set in profile scope; they can only be
set before the profile. Therefore, any profiles that use abstractions should either #include <tunables/global> or
otherwise ensure that @{HOME} and @{HOMEDIR} are set before starting the profile definition. The autodep(8) and
genprof(8) utilities will automatically emit #include <tunables/global> in generated profiles.
EXAMPLE
An example AppArmor profile:
# a variable definition
@{HOME} = /home/*/ /root/
# a comment about foo.
/usr/bin/foo {
/bin/mount ux,
/dev/{,u}random r,
/etc/ld.so.cache r,
/etc/foo.conf r,
/etc/foo/* r,
/lib/ld-*.so* x,
/lib/lib*.so* r,
/proc/[0-9]** r,
/usr/lib/** r,
/tmp/foo.pid wr,
/tmp/foo.* lrw,
/@{HOME}/.foo_file rw,
# a comment about foo's subprofile, bar.
^bar {
/lib/ld-*.so* x,
/usr/bin/bar ix,
/var/spool/* rwl,
}
}
FILES
/etc/init.d/boot.apparmor
/etc/apparmor.d/
RELATED
apparmor(7), apparmor_parser(8), complain(1), enforce(1), change_hat(2), mod_apparmor(5), and <http://forge.nov-
ell.com/modules/xfmod/project/?apparmor>.
CATEGORY