Apparmor.d (5) Linux Manual Page

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

AppArmor policy is written in a declarative language, in which the order of rules within a given section or block does not matter. Policy is by convention written so that it is contained in multiple files, but this is not a requirement. It could just as easily be written in a single file. The policy language is compiled to a architecture independent binary format that is loaded into the kernel for enforcement.

The base unit of AppArmor confinement is the profile. It contains a set of rules which are enforced when the profile is associated with a running program. The rules within the profile provide a whitelist of different permission that are allowed, along with a few other special rules.

The text in AppArmor policy is split into two sections, the preamble and the profile definitions. The preamble must occur at the head of the file and once profile definitions begin, no more preamble rules are allowed (even in files that are included into the profile). When AppArmor policy (set of profiles) is split across multiple files, each file can have its own preamble section, which may be the same or different from other files preamble. Files included within a profile section can not have a preamble section.

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).

PROFILE FILE = ( [ PREAMBLE ] [ PROFILE ] )*

PREAMBLE = ( COMMENT | VARIABLE ASSIGNMENT | ALIAS RULE | INCLUDE | ABI )*
Variable assignment and alias rules must come before the profile.

VARIABLE ASSIGNMENT = VARIABLE (‘=’ | ‘+=’) (space separated values)

VARIABLE = ‘@{‘ ALPHA [ ( ALPHANUMERIC | ‘_’ ) … ] ‘}’

ALIAS RULE = ‘alias’ ABS PATH ‘->’ REWRITTEN ABS PATH ‘,’

INCLUDE = ( ‘#include’ | ‘include’ ) [ ‘if exists’ ] ( ABS PATH | MAGIC PATH )

ABI = ( ‘abi’ ) ( 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 = ( PROFILE HEAD ) [ ATTACHMENT SPECIFICATION ] [ PROFILE FLAG CONDS ] ‘{‘ ( RULES )* ‘}’

PROFILE HEAD = [ ‘profile’ ] FILEGLOB | ‘profile’ PROFILE NAME

PROFILE NAME ( UNQUOTED PROFILE NAME | QUOTED PROFILE NAME )

QUOTED PROFILE NAME = ‘"’ UNQUOTED PROFILE NAME ‘"’

UNQUOTED PROFILE NAME = (must start with alphanumeric character (after variable expansion), or ‘/’ AARE have special meanings; see below. May include VARIABLE. Rules with embedded spaces or tabs must be quoted.)

ATTACHMENT SPECIFICATION = [ PROFILE_EXEC_COND ] [ PROFILE XATTR CONDS ]

PROFILE_EXEC_COND = FILEGLOB

PROFILE XATTR CONDS = [ ‘xattrs=’ ] ‘(‘ comma or white space separated list of PROFILE XATTR ‘)’

PROFILE XATTR = extended attribute name ‘=’ XATTR VALUE FILEGLOB

XATTR VALUE FILEGLOB = FILEGLOB

PROFILE FLAG CONDS = [ ‘flags=’ ] ‘(‘ comma or white space separated list of PROFILE FLAGS ‘)’

PROFILE FLAGS = PROFILE MODE | AUDIT_MODE | ‘mediate_deleted’ | ‘attach_disconnected’ | ‘chroot_relative’

PROFILE MODE = ‘enforce’ | ‘complain’ | ‘kill’ | ‘unconfined’

AUDIT MODE = ‘audit’

RULES = [ ( LINE RULES | COMMA RULES ‘,’ | BLOCK RULES )

LINE RULES = ( COMMENT | INCLUDE ) [ ‘
’ ] ‘
’

BLOCK RULES = ( SUBPROFILE | HAT | QUALIFIER BLOCK )

SUBPROFILE = ‘profile’ PROFILE NAME [ ATTACHMENT SPECIFICATION ] [ PROFILE FLAG CONDS ] ‘{‘ ( RULES )* ‘}’

HAT = (‘hat’ | ‘^’) HATNAME [ PROFILE FLAG CONDS ] ‘{‘ ( RULES )* ‘}’

HATNAME = (must start with alphanumeric character. See aa_change_hat(2) for a description of how this “hat” is used. If ‘^’ is used to start a hat then there is no space between the ‘^’ and HATNAME)

QUALIFIER BLOCK = QUALIFIERS BLOCK

ACCESS TYPE = ( ‘allow’ | ‘deny’ )

QUALIFIERS = [ ‘audit’ ] [ ACCESS TYPE ]

CAPABILITY RULE = [ QUALIFIERS ] ‘capability’ [ CAPABILITY LIST ]

CAPABILITY LIST = ( CAPABILITY )+

CAPABILITY = (lowercase capability name without ‘CAP_‘ prefix; see capabilities(7))

NETWORK RULE = [ QUALIFIERS ] ‘network’ [ DOMAIN ] [ TYPE | PROTOCOL ]

PROTOCOL = ( ‘tcp’ | ‘udp’ | ‘icmp’ )

MOUNT RULE = ( MOUNT | REMOUNT | UMOUNT )

MOUNT = [ QUALIFIERS ] ‘mount’ [ MOUNT CONDITIONS ] [ SOURCE FILEGLOB ] [ ‘->’ [ MOUNTPOINT FILEGLOB ]

REMOUNT = [ QUALIFIERS ] ‘remount’ [ MOUNT CONDITIONS ] MOUNTPOINT FILEGLOB

UMOUNT = [ QUALIFIERS ] ‘umount’ [ MOUNT CONDITIONS ] MOUNTPOINT FILEGLOB

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 EXPRESSION = ( ALPHANUMERIC | AARE ) …

MQUEUE_RULE = [ QUALIFIERS ] ‘mqueue’ [ MQUEUE ACCESS PERMISSIONS ] [ MQUEUE TYPE ] [ MQUEUE LABEL ] [ MQUEUE NAME ]

MQUEUE ACCESS PERMISSIONS = MQUEUE ACCESS | MQUEUE ACCESS LIST

MQUEUE ACCESS LIST = ‘(‘ Comma or space separated list of MQUEUE ACCESS ‘)’

MQUEUE TYPE = ‘type’ ‘=’ ( ‘posix’ | ‘sysv’ )

MQUEUE LABEL = ‘label’ ‘=’ ‘(‘ ‘"’ AARE ‘"’ | AARE ‘)’

MQUEUE NAME = AARE

PIVOT ROOT RULE = [ QUALIFIERS ] pivot_root [ oldroot=OLD PUT FILEGLOB ] [ NEW ROOT FILEGLOB ] [ ‘->’ PROFILE NAME ]

SOURCE FILEGLOB = FILEGLOB

MOUNTPOINT FILEGLOB = FILEGLOB

OLD PUT FILEGLOB = FILEGLOB

PTRACE_RULE = [ QUALIFIERS ] ‘ptrace’ [ PTRACE ACCESS PERMISSIONS ] [ PTRACE PEER ]

PTRACE ACCESS PERMISSIONS = PTRACE ACCESS | PTRACE ACCESS LIST

PTRACE ACCESS LIST = ‘(‘ Comma or space separated list of PTRACE ACCESS ‘)’

PTRACE PEER = ‘peer’ ‘=’ AARE

SIGNAL_RULE = [ QUALIFIERS ] ‘signal’ [ SIGNAL ACCESS PERMISSIONS ] [ SIGNAL SET ] [ SIGNAL PEER ]

SIGNAL ACCESS PERMISSIONS = SIGNAL ACCESS | SIGNAL ACCESS LIST

SIGNAL ACCESS LIST = ‘(‘ Comma or space separated list of SIGNAL ACCESS ‘)’

SIGNAL SET = ‘set’ ‘=’ ‘(‘ SIGNAL LIST ‘)’

SIGNAL LIST = Comma or space separated list of SIGNALS

SIGNAL PEER = ‘peer’ ‘=’ AARE

DBUS RULE = ( DBUS MESSAGE RULE | DBUS SERVICE RULE | DBUS EAVESDROP RULE | DBUS COMBINED RULE )

DBUS MESSAGE RULE = [ QUALIFIERS ] ‘dbus’ [ DBUS ACCESS EXPRESSION ] [ DBUS BUS ] [ DBUS PATH ] [ DBUS INTERFACE ] [ DBUS MEMBER ] [ DBUS PEER ]

DBUS SERVICE RULE = [ QUALIFIERS ] ‘dbus’ [ DBUS ACCESS EXPRESSION ] [ DBUS BUS ] [ DBUS NAME ]

DBUS EAVESDROP RULE = [ QUALIFIERS ] ‘dbus’ [ DBUS ACCESS EXPRESSION ] [ DBUS BUS ]

DBUS COMBINED RULE = [ QUALIFIERS ] ‘dbus’ [ DBUS ACCESS EXPRESSION ] [ DBUS BUS ]

DBUS ACCESS EXPRESSION = ( DBUS ACCESS | ‘(‘ DBUS ACCESS LIST ‘)’ )

DBUS BUS = ‘bus’ ‘=’ ‘(‘ ‘system’ | ‘session’ | ‘"’ AARE ‘"’ | AARE ‘)’

DBUS PATH = ‘path’ ‘=’ ‘(‘ ‘"’ AARE ‘"’ | AARE ‘)’

DBUS INTERFACE = ‘interface’ ‘=’ ‘(‘ ‘"’ AARE ‘"’ | AARE ‘)’

DBUS MEMBER = ‘member’ ‘=’ ‘(‘ ‘"’ AARE ‘"’ | AARE ‘)’

DBUS PEER = ‘peer’ ‘=’ ‘(‘ [ DBUS NAME ] [ DBUS LABEL ] ‘)’

DBUS NAME = ‘name’ ‘=’ ‘(‘ ‘"’ AARE ‘"’ | AARE ‘)’

DBUS LABEL = ‘label’ ‘=’ ‘(‘ ‘"’ AARE ‘"’ | AARE ‘)’

DBUS ACCESS LIST = Comma separated list of DBUS ACCESS

AARE = ?*[]{}^
See below for meanings.

UNIX RULE = [ QUALIFIERS ] ‘unix’ [ UNIX ACCESS EXPR ] [ UNIX RULE CONDS ] [ UNIX LOCAL EXPR ] [ UNIX PEER EXPR ]

UNIX ACCESS EXPR = ( UNIX ACCESS | UNIX ACCESS LIST )

UNIX ACCESS LIST = ‘(‘ UNIX ACCESS ( [‘,’] UNIX ACCESS )* ‘)’

UNIX RULE CONDS = ( TYPE COND | PROTO COND )
Each cond can appear at most once.

TYPE COND = ‘type’ ‘=’ ( AARE | ‘(‘ ( ‘"’ AARE ‘"’ | AARE )+ ‘)’ )

PROTO COND = ‘protocol’ ‘=’ ( AARE | ‘(‘ ( ‘"’ AARE ‘"’ | AARE )+ ‘)’ )

UNIX LOCAL EXPR = ( UNIX ADDRESS COND | UNIX LABEL COND | UNIX ATTR COND | UNIX OPT COND )*
Each cond can appear at most once.

UNIX PEER EXPR = ‘peer’ ‘=’ ( UNIX ADDRESS COND | UNIX LABEL COND )+
Each cond can appear at most once.

UNIX ADDRESS COND ‘addr’ ‘=’ ( AARE | ‘(‘ ‘"’ AARE ‘"’ | AARE ‘)’ )

UNIX LABEL COND ‘label’ ‘=’ ( AARE | ‘(‘ ‘"’ AARE ‘"’ | AARE ‘)’ )

UNIX ATTR COND ‘attr’ ‘=’ ( AARE | ‘(‘ ‘"’ AARE ‘"’ | AARE ‘)’ )

UNIX OPT COND ‘opt’ ‘=’ ( AARE | ‘(‘ ‘"’ AARE ‘"’ | AARE ‘)’ )

RLIMIT RULE = ‘set’ ‘rlimit’ [RLIMIT ‘<=’ RLIMIT VALUE ]

RLIMIT VALUE = ( RLIMIT SIZE | RLIMIT NUMBER | RLIMIT TIME | RLIMIT NICE )

RLIMIT SIZE = NUMBER ( ‘K’ | ‘M’ | ‘G’ )
Only applies to RLIMIT of ‘fsize’, ‘data’, ‘stack’, ‘core’, ‘rss’, ‘as’, ‘memlock’, ‘msgqueue’.

RLIMIT NUMBER = number from 0 to max rlimit value.
Only applies to RLIMIT of ‘ofile’, ‘nofile’, ‘locks’, ‘sigpending’, ‘nproc’, ‘rtprio’.

RLIMIT NICE = a number between -20 and 19.
Only applies to RLIMIT of ‘nice’.

FILE RULE = [ QUALIFIERS ] [ ‘owner’ ] ( ‘file’ | [ ‘file’ ] ( FILEGLOB ACCESS | ACCESS FILEGLOB ) [ ‘->’ EXEC TARGET ] )

FILEGLOB = ( QUOTED FILEGLOB | UNQUOTED FILEGLOB )

QUOTED FILEGLOB = ‘"’ UNQUOTED FILEGLOB ‘"’

UNQUOTED 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’ | ‘a’ | ‘l’ | ‘k’ | ‘m’ | EXEC TRANSITION )+ (not all combinations are allowed; see below.)

EXEC TRANSITION = ( ‘ix’ | ‘ux’ | ‘Ux’ | ‘px’ | ‘Px’ | ‘cx’ | ‘Cx’ | ‘pix’ | ‘Pix’ | ‘cix’ | ‘Cix’ | ‘pux’ | ‘PUx’ | ‘cux’ | ‘CUx’ | ‘x’ )
A bare ‘x’ is only allowed in rules with the deny qualifier, everything else only without the deny qualifier.

EXEC TARGET = name
Requires EXEC TRANSITION specified.

LINK RULE = QUALIFIERS [ ‘owner’ ] ‘link’ [ ‘subset’ ] FILEGLOB ‘->’ FILEGLOB

ALPHA = (‘a’, ‘b’, ‘c’, … ‘z’, ‘A’, ‘B’, … ‘Z’)

ALPHANUMERIC = (‘0’, ‘1’, ‘2’, … ‘9’, ‘a’, ‘b’, ‘c’, … ‘z’, ‘A’, ‘B’, … ‘Z’)

CHANGE_PROFILE RULE = ‘change_profile’ [ [ EXEC MODE ] EXEC COND ] [ ‘->’ PROFILE NAME ]

EXEC_MODE = ( ‘safe’ | ‘unsafe’ )

EXEC COND = FILEGLOB

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.

Profile Head

The profile head consists of a required name that is unique and optional attachment conditionals and control flags.

Name

The name of the profile is its identifier. It is what is displayed during introspection (eg. ps -Z), and defines how the profile is referenced by policy rules for any policy interaction via ipc or domain changes. It is recommended that the name be kept short and have meaning for the application it is being applied eg. firefox for the firefox web browser or its functional role eg. log_admin.

If the name is an applications full absolute path name eg. /usr/bin/firefox and an exec attachment conditional is not specified the name is also used as the profile’s exec attachment conditional. This use however has been deprecated and is discouraged as it makes for long names that can make profile rules difficult to understand, and may not be fully displayed by some introspection tools.

Attachment Conditionals

The attachment conditionals are used during profile changes to determine whether a profile is a match for the proposed profile transition. The attachment conditionals are optional, how and when they are applied is determined by the specific condition(s) used.

When attachment conditionals are used, the attachment conditionals for all profiles in the namespace will be evaluated. The profile with the set of attachments that result in the best match will become the new profile after a transition operation. Attachments that don’t match will result in the profile not being available for transition.

If no conditionals are specified the profile will only be used if a transition explicitly specifies the profile name.

Exec Attachment Conditional

The exec attachment conditional governs how closely the profile matches an executable program. This conditional is only used during an exec operation when the matching exec rule specifies either a px or cx (or their derivatives) transition type. The exec attachment conditional will also be used by tasks that are unconfined as they use a pix transition rule.

If there are no attachment matches then it is up to the exec rule to determine what happens (fail or a fallback option).

Note: see profile Name for information around using the profile name as an attachment conditional.

Exec attachment conditionals can contain variable names and pattern matching. They use a longest left match heuristic to deterime the winner in the case of multiple matches at run time. The exact implementation of this resolution is kernel specific and has improved over time, while retaining backwards compatibility. If the heuristic can not determine a winner between multiple matches the exec will be denied.

Extended Attributes Attachment Conditional

AppArmor profiles have the ability to target files based on their xattr(7) values in addition to their path. For example, the following profile matches files in /usr/bin with the attribute “security.apparmor” and value “trusted”:

 /usr/bin/* xattrs(security.apparmor="trusted") {
 # ...
 }

See apparmor_xattrs(7) for further details.

Flags

The profile flags allow modifying the behavior of the profile. If a profile flag is specified it takes priority over any conflicting flags that have been specified by rules in the profile body.

Profile Mode

The profile mode allow controlling the enforcement behavior of the profile rules.

If no mode is specified the profile defaults to enforce mode.

enforce For a given action, if the profile rules do not grant permission the action will be denied, with an EACCES or EPERM error code returned to userspace, and the violation will be logged with a tag of the access being DENIED.
kill This is a variant of enforce mode where in addition to returning EACCES or EPERM for a violation, the task is also sent a signal to kill it.
complain For a given action, if the profile rules do not grant permission the action will be allowed, but the violation will be logged with a tag of the access being ALLOWED.
unconfined This mode allows a task confined by the profile to behave as though they are unconfined. This mode allow for an unconfined behavior that can be later changed to confinement by using profile replacement. This mode is should not be used under regular deployment but can be useful during debugging and some system initialization scenarios.

Audit Mode

The audit mode allows control of how AppArmor messages are are logged to the audit system.

audit This flag causes all actions whether allowed or denied to be logged.

Misc modes

mediate_deleted This forces AppArmor to mediate deleted files as if they still exist in the file system.
attach_disconnected This forces AppArmor to attach disconnected objects to the task’s namespace and mediate them as though they are part of the namespace. WARNING this mode is unsafe and can result in aliasing and access to objects that should not be allowed. Its intent is a debug and policy development tool.
chroot_relative This forces file names to be relative to a chroot and behave as if the chroot is a mount namespace.

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
pix: – discrete profile execute with inherit fallback
Pix: – discrete profile execute with inherit fallback — scrub the environment
cix: – transition to subprofile on execute with inherit fallback
Cix: – transition to subprofile on execute with inherit fallback — scrub the environment
pux: – discrete profile execute with fallback to unconfined
PUx: – discrete profile execute with fallback to unconfined — scrub the environment
cux: – transition to subprofile on execute with fallback to unconfined
CUx: – transition to subprofile on execute with fallback to unconfined — scrub the environment
deny x: – disallow execute (in rules with the deny qualifier)
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.