table of contents
other versions
- wheezy 2.7.103-4
- jessie 2.9.0-3
- jessie-backports 2.10.95-4~bpo8+2
- testing 2.11.0-3
- unstable 2.11.0-3
APPARMOR.D(5) | AppArmor | APPARMOR.D(5) |
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 | MOUNT RULE |
FILE RULE | 'change_profile -> ' PROGRAMCHILD ) ... ] '}'
SUBPROFILE = [ COMMENT ... ] ( PROGRAMHAT | 'profile '
PROGRAMCHILD ) '{' [ ( 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 aa_change_hat(2)
for a description of how this "hat" is used.)
PROGRAMCHILD = SUBPROFILE name
MOUNT RULE = ( MOUNT | REMOUNT | UMOUNT | PIVOT
ROOT )
MOUNT = [ 'audit' ] [ 'deny' ] 'mount' [ MOUNT CONDITIONS ] [
SOURCE FILEGLOB ] [ -> [ MOUNTPOINT FILEGLOB ]
REMOUNT = [ 'audit' ] [ 'deny' ] 'remount' [ MOUNT CONDITIONS ]
MOUNTPOINT FILEGLOB
UMOUNT = [ 'audit' ] [ 'deny' ] 'umount' [ MOUNT CONDITIONS ]
MOUNTPOINT FILEGLOB
PIVOT ROOT = [ 'audit' ] [ 'deny' ] pivot_root [ OLD ABS PATH ] [
MOUNTPOINT ABS PATH ] [ -> PROGRAMCHILD ]
MOUNT CONDITIONS = [ ( 'fstype' | 'vfstype' ) ( '=' | 'in' ) MOUNT
FSTYPE EXPRESSION ] [ 'options' ( '=' | 'in' ) MOUNT FLAGS
EXPRESSION ]
MOUNT FSTYPE EXPRESSION = ( MOUNT FSTYPE LIST | MOUNT
EXPRESSION )
MOUNT FSTYPE LIST = Comma separated list of valid filesystem and virtual
filesystem types (eg ext4, debugfs, devfs, etc)
MOUNT FLAGS EXPRESSION = ( MOUNT FLAGS LIST | MOUNT
EXPRESSION )
MOUNT FLAGS LIST = Comma separated list of MOUNT FLAGS.
MOUNT FLAGS = ( 'ro' | 'rw' | 'nosuid' | 'suid' | 'nodev' | 'dev' |
'noexec' | 'exec' | 'sync' | 'async' | 'remount' | 'mand' | 'nomand' |
'dirsync' | 'nodirsync' | 'noatime' | 'atime' | 'nodiratime' | 'diratime' |
'bind' | 'move' | 'rec' | 'verbose' | 'silent' | 'load' | 'acl' | 'noacl' |
'unbindable' | 'private' | 'slave' | 'shared' | 'relative' | 'norelative' |
'iversion' | 'noiversion' | 'strictatime' | 'nouser' | 'user' )
MOUNT EXPRESSION = ( ALPHANUMERIC | AARE ) ...
AARE = ?*[]{}^ (see below for meanings)
FILE RULE = RULE QUALIFIER ( '"' FILEGLOB '"' |
FILEGLOB ) ACCESS ','
RULE QUALIFIER = [ 'audit' ] [ 'deny' ] [ 'owner' ]
FILEGLOB = (must start with '/' (after variable expansion), AARE
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' | 'cx ->
' PROGRAMCHILD | 'Cx -> ' PROGRAMCHILD | '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 = ('0', '1', '2', ... '9', 'a', 'b', 'c', ... 'z', 'A', 'B',
... 'Z')
All resources and programs need a full path. There may be any number of
subprofiles (aka child profiles) in a profile, limited only by kernel memory.
Subprofile names are limited to 974 characters. Child profiles can be used to
confine an application in a special way, or when you want the child to be
unconfined on the system, but confined when called from the parent. Hats are a
special child profile that can be used with the aa_change_hat(2) API
call. Applications written or modified to use aa_change_hat(2) can take
advantage of subprofiles to run under different confinements, dependent on
program logic. Several aa_change_hat(2)-aware applications exist,
including an Apache module, mod_apparmor(5); a PAM module,
pam_apparmor; and a Tomcat valve, tomcat_apparmor. Applications written or
modified to use change_profile(2) transition permanently to the
specified profile. libvirt is one such application.
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
- cx - transition to subprofile on execute
- Cx - transition to subprofile on 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.
- 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.
- ux - Unconfined execute mode
- Allows the program to execute the program without any
AppArmor profile being applied to the program.
- 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.)
- 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.
- 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.)
- cx - Transition to Subprofile execute mode
- This mode requires that a local security profile is defined
and forces an AppArmor domain transition to the named profile. If there is
no profile defined then the access will be denied.
- Cx - Transition to Subprofile execute mode -- scrub the environment
- 'Cx' allows the named program to run in 'cx' 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.)
- 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.
- 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.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
Mount Rules¶
AppArmor supports mount mediation and allows specifying filesystem types and mount flags. The syntax of mount rules in AppArmor is based on the mount(8) command syntax. Mount rules must contain one of the mount, remount, umount or pivot_root keywords, but all mount conditions are optional. Unspecified optional conditionals are assumed to match all entries (eg, not specifying fstype means all fstypes are matched). Due to the complexity of the mount command and how options may be specified, AppArmor allows specifying conditionals three different ways:- 1.
- If a conditional is specified using '=', then the rule only grants permission for mounts matching the exactly specified options. For example, an AppArmor policy with the following rule:
mount options=ro /dev/foo -> /mnt/,
$ mount -o ro /dev/foo /mnt
$ mount -o ro,atime /dev/foo /mnt
$ mount -o rw /dev/foo /mnt
- 2.
- If a conditional is specified using 'in', then the rule grants permission for mounts matching any combination of the specified options. For example, if an AppArmor policy has the following rule:
mount options in (ro,atime) /dev/foo ->
/mnt/,
$ mount -o ro /dev/foo /mnt
$ mount -o ro,atime /dev/foo /mnt
$ mount -o atime /dev/foo /mnt
$ mount -o ro,sync /dev/foo /mnt
$ mount -o ro,atime,sync /dev/foo /mnt
$ mount -o rw /dev/foo /mnt
$ mount -o rw,noatime /dev/foo /mnt
$ mount /dev/foo /mnt
- 3.
- If multiple conditionals are specified in a single mount rule, then the rule grants permission for each set of options. This provides a shorthand when writing mount rules which might help to logically break up a conditional. For example, if an AppArmor policy has the following rule:
mount options=ro options=atime
$ mount -o ro /dev/foo /mnt
$ mount -o atime /dev/foo /mnt
$ mount -o ro,atime /dev/foo /mnt
mount options=ro, mount options=atime,
are not equivalent to either of these mount rules:
mount options=(ro,atime),
mount options in (ro,atime),
To help clarify the flexibility and complexity of mount rules, here are some
example rules with accompanying matching commands:
- mount,
- the 'mount' rule without any conditionals is the most generic and allows any mount. Equivalent to 'mount fstype=** options=** ** -> /**'.
- mount /dev/foo,
- allow mounting of /dev/foo anywhere with any options. Some matching mount commands:
$ mount /dev/foo /mnt
$ mount -t ext3 /dev/foo /mnt
$ mount -t vfat /dev/foo /mnt
$ mount -o ro,atime,noexec,nodiratime /dev/foo /srv/some/mountpoint
- mount options=ro /dev/foo,
- allow mounting of /dev/foo anywhere, as read only. Some matching mount commands:
$ mount -o ro /dev/foo /mnt
$ mount -o ro /dev/foo /some/where/else
- mount options=(ro,atime) /dev/foo,
- allow mount of /dev/foo anywhere, as read only and using inode access times. Some matching mount commands:
$ mount -o ro,atime /dev/foo /mnt
$ mount -o ro,atime /dev/foo /some/where/else
- mount options in (ro,atime) /dev/foo,
- allow mount of /dev/foo anywhere using some combination of 'ro' and 'atime' (see above). Some matching mount commands:
$ mount -o ro /dev/foo /mnt
$ mount -o atime /dev/foo /some/where/else
$ mount -o ro,atime /dev/foo /some/other/place
- mount options=ro /dev/foo, mount options=atime /dev/foo,
- allow mount of /dev/foo anywhere as read only, and allow mount of /dev/foo anywhere using inode access times. Note this is expressed as two different rules. Matches:
$ mount -o ro /dev/foo /mnt/1
$ mount -o atime /dev/foo /mnt/2
- mount -> /mnt/**,
- allow mounting anything under a directory in /mnt/**. Some matching mount commands:
$ mount /dev/foo1 /mnt/1
$ mount -o ro,atime,noexec,nodiratime /dev/foo2 /mnt/deep/path/foo2
- mount options=ro -> /mnt/**,
- allow mounting anything under /mnt/**, as read only. Some matching mount commands:
$ mount -o ro /dev/foo1 /mnt/1
$ mount -o ro /dev/foo2 /mnt/deep/path/foo2
- mount fstype=ext3 options=(rw,atime) /dev/sdb1 -> /mnt/stick/,
- allow mounting an ext3 filesystem in /dev/sdb1 on /mnt/stick as read/write and using inode access times. Matches only:
$ mount -o rw,atime /dev/sdb1 /mnt/stick
- mount options=(ro, atime) options in (nodev, user) /dev/foo -> /mnt/,
- allow mounting /dev/foo on /mmt/ read only and using inode access times or allow mounting /dev/foo on /mnt/ with some combination of 'nodev' and 'user'. Matches only:
$ mount -o ro,atime /dev/foo /mnt
$ mount -o nodev /dev/foo /mnt
$ mount -o user /dev/foo /mnt
$ mount -o nodev,user /dev/foo /mnt
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. Alias rules must occur within the preamble of the profile. System-wide aliases are found in /etc/apparmor.d/tunables/alias, which is included by /etc/apparmor.d/tunables/global. /etc/apparmor.d/tunables/global is typically included at the beginning of an AppArmor profile.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
- [^a-c]
- will substitute for any single character not matching a, b or c
- {ab,cd}
- will expand to one rule to match ab, one rule to match cd
- /tmp/*
- Files directly in /tmp.
- /tmp/*/
- Directories directly in /tmp.
- /tmp/**
- Files and directories anywhere underneath /tmp.
- /tmp/**/
- Directories anywhere underneath /tmp.
Rule Qualifiers¶
There are several rule qualifiers that can be applied to permission rules. Rule qualifiers can modify the rule and/or permissions within the rule.- audit
- Specifies that permissions requests that match the rule should be recorded to the audit log.
- deny
- Specifies that permissions requests that match the rule should be denied without logging. Can be combined with 'audit' to enable logging.
- owner
- Specifies that the task must have the same euid/fsuid as the object being referenced by the permission check.
#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.
EXAMPLE¶
An example AppArmor profile:# a variable definition in the preamble @{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, /usr/bin/baz Cx -> baz, # a comment about foo's hat (subprofile), bar. ^bar { /lib/ld-*.so* rmix, /usr/bin/bar rmix, /var/spool/* rwl, } # a comment about foo's subprofile, baz. profile baz { #include <abstractions/bash> owner /proc/[0-9]*/stat r, /bin/bash ixr, /var/lib/baz/ r, owner /var/lib/baz/* rw, } }
FILES¶
- /etc/init.d/boot.apparmor
- /etc/apparmor.d/
KNOWN BUGS¶
Mount options support the use of pattern
matching but mount flags are not correctly intersected against specified
patterns. Eg, 'mount options=**,' should be equivalent to 'mount,', but it is
not. (LP: #965690)
The fstype may not be matched against when certain mount command flags are used.
Specifically fstype matching currently only works when creating a new mount
and not remount, bind, etc.
Mount rules with multiple 'options' conditionals are not applied as documented
but instead merged such that 'options in (ro,nodev) options in (atime)' is
equivalent to 'options in (ro,nodev,atime)'.
When specifying mount options with the 'in' conditional, both the positive and
negative values match when specifying one or the other. Eg, 'rw' matches when
'ro' is specified and 'dev' matches when 'nodev' is specified such that
'options in (ro,nodev)' is equivalent to 'options in (rw,dev)'.
SEE ALSO¶
apparmor(7), apparmor_parser(8), aa-complain(1), aa-enforce(1), aa_change_hat(2), mod_apparmor(5), and <http://wiki.apparmor.net>.2012-06-28 | AppArmor 2.7.103 |