NAME
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 AppArmor 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
'"' | PROGRAM ) [ 'flags=(complain)' ]'{' [ ( RESOURCE RULE |
COMMENT | INCLUDE | SUBPROFILE | 'capability ' CAPABILITY | NETWORK
RULE ) ... ] '}'
SUBPROFILE = [ COMMENT ... ] PROGRAMHAT '{' [ ( FILE RULE | COMMENT
| INCLUDE ) ... ] '}'
CAPABILITY = (lowercase capability name without 'CAP_' prefix; see
capabilities(7))
NETWORK RULE = 'network' [ [ DOMAIN ] [ TYPE ] [ I <PROTOCOL> ] ]
','
DOMAIN = ( 'inet' | 'ax25' | 'ipx' | 'appletalk' | 'netrom' |
'bridge' | 'atmpvc' | 'x25' | 'inet6' | 'rose' | 'netbeui' |
'security' | 'key' | 'packet' | 'ash' | 'econet' | 'atmsvc' | 'sna'
| 'irda' | 'pppox' | 'wanpipe' | 'bluetooth' ) ','
TYPE = ( 'stream' | 'dgram' | 'seqpacket' | 'rdm' | 'raw' |
'packet' )
PROTOCOL = ( 'tcp' | 'udp' | 'icmp' )
PROGRAM = (non-whitespace characters except for '^', must start
with '/'. Embedded spaces or tabs must be quoted.)
PROGRAMHAT = '^' (non-whitespace characters; see change_hat(2) for
a description of how this "hat" is used.)
FILE RULE = ( '"' FILEGLOB '"' | FILEGLOB ) ACCESS ','
FILEGLOB = (must start with '/' (after variable expansion), ?*[]{}^
have special meanings; see below. May include VARIABLE. Rules with
embedded spaces or tabs must be quoted. Rules must end with '/' to
apply to directories.)
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)
ALIAS RULE = ABS PATH '->' REWRITTEN ABS PATH ','
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, limited only by kernel memory.
Subprofile names are limited to 974 characters. Not all profiles
benefit from subprofiles --- applications must either be written or
modified to use change_hat(2) to take advantage of subprofiles. Several
change_hat(2)-aware applications exist, including an Apache module,
mod_apparmor(5); a PAM module, pam_apparmor; and a Tomcat valve,
tomcat_apparmor.
Access Modes
File permission access modes consists of combinations of the following
modes:
r - read
w - write -- conflicts with append
a - append -- conflicts with write
ux - unconfined execute
Ux - unconfined 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
k - lock
Access Modes Details
r - Read mode
Allows the program to have read access to the file or directory
listing. Read access is required for shell scripts and other
interpreted content.
w - Write mode
Allows the program to have write access to the file. Files and
directories must have this permission if they are to be unlinked
(removed.) Write mode is not required on a directory to rename or
create files within the directory.
This mode conflicts with append mode.
a - Append mode
Allows the program to have a limited appending only write access to
the file. Append mode will prevent an application from opening the
file for write unless it passes the O_APPEND parameter flag on
open.
The mode conflicts with Write mode.
ux - Unconfined 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
unconfined 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 - unconfined 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 program. 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 permissions 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 new link MUST have a subset of
permissions as the original file (with the exception that the
destination does not have to have link access.) If there is an 'x'
rule on the new link, it must match the original file exactly.
k - lock mode
Allows the program to be able lock a file with this name. This
permission covers both advisory and mandatory locking.
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 capabilities(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 operations 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.
Network Rules
AppArmor supports simple coarse grained network mediation. The network
rule restrict all socket(2) based operations. The mediation done is a
course grained check on whether a socket of a given type and family can
be created, read, or written. There is no mediation based of port
number or protocol beyond tcp, udp, and raw.
AppArmor network rules are accumulated so that the granted network
permissions are the union of all the listed network rule permissions.
AppArmor network rules are broad and general and become more
restrictive as further information is specified.
eg.
network, #allow access to all networking network
tcp, #allow access to tcp network inet tcp, #allow access to
tcp only for inet4 addresses network inet6 tcp, #allow access to tcp
only for inet6 addresses
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 @{HOMEDIRS} are defined
in the AppArmor policy provided, in the /etc/apparmor.d/tunables/home
file; these variables are used in many of the abstractions described
later. You may also add files in /etc/apparmor.d/tunables/home.d for
site-specific customization of @{HOMEDIRS}.
Alias rules
AppArmor also provides alias rules for remapping paths for site-
specific layouts. They are an alternative form of path rewriting to
using variables, and are done after variable resolution.
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
When AppArmor looks up a directory the pathname being looked up will
end with a slash (e.g., /var/tmp/); otherwise it will not end with a
slash. Only rules that match a trailing slash will match directories.
Some examples, none matching the /tmp/ directory itself, are:
/tmp/*
Files directly in /tmp.
/tmp/*/
Directories directly in /tmp.
/tmp/**
Files and directories anywhere underneath /tmp.
/tmp/**/
Directories anywhere underneath /tmp.
#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 specified 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/abstractions/ 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 associated 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 @{HOMEDIRS}. 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 @{HOMEDIRS} 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* rmix,
/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* rmix,
/usr/bin/bar rmix,
/var/spool/* rwl,
}
}
FILES
/etc/init.d/boot.apparmor
/etc/apparmor.d/
SEE ALSO
apparmor(7), apparmor_parser(8), complain(1), enforce(1),
change_hat(2), mod_apparmor(5), and
<http://forge.novell.com/modules/xfmod/project/?apparmor>.