APPARMOR.D(5)

💖 apparmor.d(5) — AppArmor profile syntax (bestie edition) 💖

🌸 NAME 🌸

apparmor.d — it's literally the syntax of security profiles for AppArmor. No cap.

✨ DESCRIPTION ✨

Okay so AppArmor profiles? They describe the mandatory access rights that get handed to specific programs, and you feed them to the AppArmor policy enforcement module using apparmor_parser(8). This man page is all about the format of the AppArmor configuration files — if you want the big-picture overview of AppArmor itself, go peek at apparmor(7).

🦋 FORMAT 🦋

AppArmor policy? Written in a declarative language, which means the order of rules inside any given section or block does NOT matter — it's giving chaos-friendly. By convention policy lives in multiple files, but that's not a requirement at all; you could absolutely write it all in a single file. The policy language gets compiled to an architecture-independent binary format that then gets loaded into the kernel for enforcement. Periodt.

AppArmor compiled policy is stored in a cross-platform container format. When it's loaded into the kernel, it gets verified and converted into the best format for the host. Technically you can convert host policy back to the load format, but recreating the exact format, layout, and sha256sum is not feasible. So if userspace wants to obtain the currently enforced policy from the kernel (for example, criu support needs to do this), AppArmor has to hold onto the originally loaded policy. To reduce the memory that the loaded policy uses, AppArmor compresses the policy with two different types of compression: an internal state layout compression, and a policy container level compression.

The policy state layout compression? That one is only done in the compiler, and the kernel doesn't change it during the unpack — it's natively part of the state machine used for mediation. The policy container compression can be done by the kernel or by the policy compiler to reduce how much memory the policy container uses, all to support CRIU and policy introspection. If you disable introspection of policy and CRIU support, the kernel will not retain the compressed container data. Goodbye, data 💀.

The policy compiler gives you the option to pre-compress the policy container, so the kernel won't have to do it after the policy is loaded. That gives better control over the compression level used, letting userspace make speed/size trade-offs. Plus, policy only gets compressed once at compile time instead of every single time it's loaded. So subsequent policy loads that rely just on the cache are faster: the kernel only needs to decompress (which is 4-5x faster) at the start of the load, instead of compressing at the end. Efficiency? Slay 💅.

When enabled, the default compression level for userspace compression of the policy is higher than the level the kernel uses. That can make the first load slightly slower, for a better compression. However subsequent loads will be faster. Wanna adjust the default compression level? Set the zstd-compress-level parameter in parser.conf.

The base unit of AppArmor confinement is the profile. It contains a set of rules that are enforced when the profile is associated with a running program. Those rules are basically a whitelist of different permissions that are allowed, plus a few other special rules. Main character energy, honestly 👑.

AppArmor policy text is split into two sections: the preamble and the profile definitions. The preamble must be at the head of the file, and once profile definitions begin, no more preamble rules are allowed (even in files that get included into the profile — sorry bestie). When AppArmor policy (a 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' preambles. But files included within a profile section cannot have a preamble section. Blocked 🙈.

Okay, the following is a BNF-style description of AppArmor policy configuration files; there's an example AppArmor policy file further down. AppArmor config files are line-oriented; # introduces a comment, just like in shell scripting languages. The one exception is that #include will include the contents of a file inline to the policy — that behaviour is modelled after cpp(1).

Here's the whole grammar, verbatim, because we do not skip details in this house:

           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 | BOOL_VAR ) ('=' | '+=' | '?=' |
           ':=' ) (space separated values)

           VARIABLE = '@{' ALPHA [ ( ALPHANUMERIC | '_' ) ... ] '}'

           BOOL_VAR = '${' 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 | '<kernel>' | '<default>' )
           ','

           ABS PATH = '"' path '"' (the path is passed to open(2))

           MAGIC PATH = '<' relative path '>'
             The path is relative to /etc/apparmor.d/.

           COMMENT = '#' TEXT [ '\r' ] '\n'

           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' | 'attach_disconnected.path='ABS PATH |
           'chroot_relative' | 'attach_disconnected.ipc' |
           'attach_disconnected.ipc='ABS PATH | 'debug' | 'interruptible' |
           'kill.signal='SIGNAL | 'error='ERROR CODE

           ERROR CODE = (case insensitive error code name starting with 'E';
           see errno(3))

           PROFILE MODE = 'enforce' | 'complain' | 'kill' | 'default_allow' |
           'unconfined' | 'prompt'

           AUDIT MODE = 'audit'

           RULES = [ ( LINE RULES | COMMA RULES ',' | BLOCK RULES )

           LINE RULES = ( COMMENT | INCLUDE ) [ '\r' ] '\n'

           COMMA RULES = ( CAPABILITY RULE | NETWORK RULE | MOUNT RULE | PIVOT
           ROOT RULE | UNIX RULE | FILE RULE | LINK RULE | CHANGE_PROFILE RULE
           | RLIMIT RULE | DBUS RULE | MQUEUE RULE | IO_URING RULE | USERNS
           RULE | ALL RULE)

           BLOCK RULES = ( SUBPROFILE | HAT | QUALIFIER BLOCK | IF_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

           INTEGER = (+ | -)? [[:digit:]]+

           IF_BLOCK = 'if' EXPR BLOCK [ ( 'else' 'if'  EXPR BLOCK )* ] [ 'else'
           BLOCK ]

           EXPR = ( EXPR ( 'and' | 'or' ) EXPR | 'not' EXPR | '(' EXPR ')' |
           FACTOR )

           FACTOR = ( 'defined' VARIABLE | [ 'defined' ] BOOL_VAR | ( TEXT |
           VARIABLE ) OPERATOR ( TEXT | VARIABLE ) )

           OPERATOR = ( 'in' | '==' | '!=' | '>' | '>=' | '<' | '<=' )

           BLOCK = '{' ( RULES )* '}'

           ACCESS TYPE = ( 'allow' | 'deny' )

           QUALIFIERS = [ 'priority' '=' <INTEGER> ] [ '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' [ NETWORK ACCESS EXPR ] [
           DOMAIN ] [ TYPE | PROTOCOL ] [ NETWORK LOCAL EXPR ] [ NETWORK PEER
           EXPR ]

           NETWORK ACCESS EXPR = ( NETWORK ACCESS | NETWORK ACCESS LIST )

           NETWORK ACCESS = ( 'create' | 'bind' | 'listen' | 'accept' |
           'connect' | 'shutdown' | 'getattr' | 'setattr' | 'getopt' | 'setopt'
           | 'send' | 'receive' | 'r' | 'w' | 'rw' )
             Some access modes are incompatible with some rules.

           NETWORK ACCESS LIST = '(' NETWORK ACCESS ( [','] NETWORK ACCESS )*
           ')'

           DOMAIN = ( 'unix' | 'inet' | 'ax25' | 'ipx' | 'appletalk' | 'netrom'
           | 'bridge' | 'atmpvc' | 'x25' | 'inet6' | 'rose' | 'netbeui' |
           'security' | 'key' | 'netlink' | 'packet' | 'ash' | 'econet' |
           'atmsvc' | 'rds' | 'sna' | 'irda' | 'pppox' | 'wanpipe' | 'llc' |
           'ib' | 'mpls' | 'can' | 'tipc' | 'bluetooth' | 'iucv' | 'rxrpc' |
           'isdn' | 'phonet' | 'ieee802154' | 'caif' | 'alg' | 'nfc' | 'vsock'
           | 'kcm' | 'qipcrtr' | 'smc' | 'xdp' | 'mctp' ) ','

           TYPE = ( 'stream' | 'dgram' | 'seqpacket' |  'rdm' | 'raw' |
           'packet' )

           PROTOCOL = ( 'tcp' | 'udp' | 'icmp' )

           NETWORK LOCAL EXPR = ( NETWORK IP COND | NETWORK PORT COND |
           INTERFACE COND | LABEL_COND | LABEL ASSIGN )*
             Each cond can appear at most once.

           NETWORK PEER EXPR = 'peer' '=' '(' ( NETWORK IP COND | NETWORK PORT
           COND )+ | LABEL COND | LABEL ASSIGN ')'
             Each cond can appear at most once.

           NETWORK IP COND = 'ip' '=' ( 'none' | NETWORK IPV4 | NETWORK IPV6 )

           NETWORK PORT COND = 'port' '=' ( NETWORK PORT | NETWORK PORT '-'
           NETWORK PORT )

           NETWORK IPV4 = IPv4, represented by four 8-bit decimal numbers
           separated by '.'

           NETWORK IPV6 = IPv6, represented by eight groups of four hexadecimal
           numbers separated by ':'. Shortened representation of contiguous
           zeros is allowed by using '::'

           NETWORK PORT = 16-bit number ranging from 0 to 65535

           INTERFACE COND = 'interface' '=' '(' '"' AARE '"' | AARE ')'

           LABEL COND = 'label' '=' '(' '"' AARE '"' | AARE ')'

           LABEL ASSIGN = 'label' ':=' LABEL NAME

           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

…and that's the grammar for part 1! More parts incoming, don't go anywhere 💅✨

okay so back to the grammar tea ☕️ first up, the mount rules. they're giving conditional energy:

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' | 'noatime' | 'atime' | 'nodiratime' | 'diratime' |
'bind' | 'rbind' | 'move' | 'verbose' | 'silent' | 'loud' | 'acl' |
'noacl' | 'unbindable' | 'runbindable' | 'private' | 'rprivate' |
'slave' | 'rslave' | 'shared' | 'rshared' | 'relatime' |
'norelatime' | 'iversion' | 'noiversion' | 'strictatime' |
'nostrictatime' | 'lazytime' | 'nolazytime' | 'nouser' | 'user' |
'symfollow' | 'nosymfollow' )

MOUNT EXPRESSION = ( ALPHANUMERIC | AARE ) ...

so MOUNT CONDITIONS is like, "hey, check the fstype or vfstype and optionally the options" — it's giving conditional queen 💅. MOUNT FSTYPE LIST is just a comma-separated list of valid filesystem types like ext4, debugfs, devfs, etc. MOUNT FLAGS LIST is a comma-separated list of MOUNT FLAGS. and MOUNT FLAGS is a whole vibe with all those flags — it's literally every mount flag you can think of. MOUNT EXPRESSION is just alphanumeric or AARE, so you know it's flexible. periodt.

next up, mqueue rules for all your message queue needs:

MQUEUE_RULE = [ QUALIFIERS ] 'mqueue' [ MQUEUE ACCESS PERMISSIONS ]
[ MQUEUE TYPE ] [ LABEL_COND ] [ MQUEUE NAME ]

MQUEUE ACCESS PERMISSIONS = MQUEUE ACCESS | MQUEUE ACCESS LIST

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

MQUEUE ACCESS = ( 'r' | 'w' | 'rw' | 'read' | 'write' | 'create' |
'open' | 'delete' | 'getattr' | 'setattr' )

MQUEUE TYPE = 'type' '=' ( 'posix' | 'sysv' )

MQUEUE NAME = AARE

mqueue is all about message queues. MQUEUE ACCESS is the tea ☕️ — you can read, write, create, open, delete, getattr, setattr, or the shorthand r/w/rw. MQUEUE TYPE is either posix or sysv. and MQUEUE NAME is just an AARE. got it? 💖

then userns, which is simple:

USERNS RULE = [ QUALIFIERS ] 'userns' [ USERNS ACCESS PERMISSIONS ]

USERNS ACCESS PERMISSIONS = ( 'create' )

userns is simple — you just need create permission. that's it. iconic.

io_uring is next, giving async energy:

IO_URING RULE = [ QUALIFIERS ] 'io_uring' [ IO_URING ACCESS
PERMISSIONS [ LABEL COND ]

IO_URING ACCESS PERMISSIONS = ( 'sqpoll' | 'override_creds' )

you can have sqpoll or override_creds. (and yes, the bracket situation is a little unhinged, but we copy exactly. no cap.)

pivot_root is for changing the root filesystem:

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

you can specify oldroot, new root, and a profile name to transition to. slay.

ptrace is for debugging and tracing:

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 ACCESS = ( 'r' | 'w' | 'rw' | 'read' | 'readby' | 'trace' |
'tracedby' )

PTRACE PEER = 'peer' '=' AARE

you can read, write, readby, tracedby, or the shorthand. PTRACE PEER lets you specify a peer with an AARE. big brother vibes 👀.

signal rules are for sending signals:

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 ACCESS = ( 'r' | 'w' | 'rw' | 'read' | 'write' | 'send' |
'receive' )

SIGNAL SET = 'set' '=' '(' SIGNAL LIST ')'

SIGNAL LIST = Comma or space separated list of SIGNALs

SIGNAL = ( 'hup' | 'int' | 'quit' | 'ill' | 'trap' | 'abrt' | 'bus'
| 'fpe' | 'kill' | 'usr1' | 'segv' | 'usr2' | 'pipe' | 'alrm' |
'term' | 'stkflt' | 'chld' | 'cont' | 'stop' | 'stp' | 'ttin' |
'ttou' | 'urg' | 'xcpu' | 'xfsz' | 'vtalrm' | 'prof' | 'winch' |
'io' | 'pwr' | 'sys' | 'emt' | 'exists' | 'rtmin+0' ... 'rtmin+32' )

SIGNAL PEER = 'peer' '=' AARE

you can read, write, send, receive. SIGNAL SET lets you list specific signals, and there are a ton of them — from hup to rtmin+32. that's a whole alphabet of signals, bestie. SIGNAL PEER is just an AARE.

dbus rules are next, and they're giving communication energy:

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 ] [ LABEL COND ] ')'

DBUS NAME = 'name' '=' '(' '"' AARE '"' | AARE ')'

DBUS ACCESS LIST = Comma separated list of DBUS ACCESS

DBUS ACCESS = ( 'send' | 'receive' | 'bind' | 'eavesdrop' | 'r' |
'read' | 'w' | 'write' | 'rw' )

also, bestie, some accesses are incompatible with some rules; see below 💅.

unix rules are for UNIX domain sockets:

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 = ( 'create' | 'bind' | 'listen' | 'accept' | 'connect'
| 'shutdown' | 'getattr' | 'setattr' | 'getopt' | 'setopt' | 'send'
| 'receive' | 'r' | 'w' | 'rw' )

UNIX ACCESS LIST = '(' UNIX ACCESS ( [','] UNIX ACCESS )* ')'

UNIX RULE CONDS = ( TYPE COND | PROTO COND )

TYPE COND = 'type' '='  ( AARE | '(' ( '"' AARE '"' | AARE )+ ')' )

PROTO COND = 'protocol' '='  ( AARE | '(' ( '"' AARE '"' | AARE )+
')' )

UNIX LOCAL EXPR = ( UNIX ADDRESS COND | LABEL COND | UNIX ATTR COND
| UNIX OPT COND )*

UNIX PEER EXPR = 'peer' '=' ( UNIX ADDRESS COND | UNIX LABEL COND )+

UNIX ADDRESS COND 'addr' '=' ( AARE | '(' '"' AARE '"' | AARE ')' )

UNIX ATTR COND 'attr' '=' ( AARE | '(' '"' AARE '"' | AARE ')' )

UNIX OPT COND 'opt' '=' ( AARE | '(' '"' AARE '"' | AARE ')' )

ngl, some access modes don't vibe with certain rules or need extra parameters, so watch out 🫣. Also, each cond can show up at most once, periodt. That goes for UNIX RULE CONDS, UNIX LOCAL EXPR, and UNIX PEER EXPR.

rlimit rules are for setting resource limits:

RLIMIT RULE = 'set' 'rlimit' [RLIMIT '<=' RLIMIT VALUE ]

RLIMIT = ( 'cpu' | 'fsize' | 'data' | 'stack' | 'core' | 'rss' |
'nofile' | 'ofile' | 'as' | 'nproc' | 'memlock' | 'locks' |
'sigpending' | 'msgqueue' | 'nice' | 'rtprio' | 'rttime' )

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

RLIMIT SIZE = NUMBER ( 'K' | 'M' | 'G' )

RLIMIT NUMBER = number from 0 to max rlimit value.

RLIMIT TIME = NUMBER ( 'us' | 'microsecond' | 'microseconds' | 'ms'
| 'millisecond' | 'milliseconds' | 's' | 'sec' | 'second' |
'seconds' | 'min' | 'minute' | 'minutes' | 'h' | 'hour' | 'hours' |
'd' | 'day' | 'days' | 'week' | 'weeks' )

RLIMIT NICE = a number between -20 and 19.

RLIMIT SIZE only applies to RLIMIT of 'fsize', 'data', 'stack', 'core', 'rss', 'as', 'memlock', 'msgqueue'. RLIMIT NUMBER only applies to RLIMIT of 'ofile', 'nofile', 'locks', 'sigpending', 'nproc', 'rtprio'. RLIMIT TIME only applies to RLIMIT of 'cpu' and 'rttime'. RLIMIT 'cpu' only allows units >= 'seconds'. RLIMIT NICE only applies to RLIMIT of 'nice'. got all that? 💖

file rules are the big ones:

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

AARE = ?*[]{}^

ACCESS = ( 'r' | 'w' | 'a' | 'l' | 'k' | 'm' | EXEC TRANSITION )+

EXEC TRANSITION =  ( 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'cx' | 'Cx'
| 'pix' | 'Pix' | 'cix' | 'Cix' | 'pux' | 'PUx' | 'cux' | 'CUx' |
'x' )

EXEC TARGET = name

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 RULE = 'all'

so UNQUOTED FILEGLOB must start with '/' after variable expansion, AARE have special meanings (see below), may include VARIABLE, rules with spaces or tabs must be quoted, and rules must end with '/' to apply to directories. AARE is just ?*[]{}^ — check the "Globbing (AARE)" section below for meanings. ACCESS is r, w, a, l, k, m, or an EXEC TRANSITION. not all combinations are allowed; see below. EXEC TRANSITION has a ton of options, and a bare 'x' is only allowed in rules with the deny qualifier, everything else only without the deny qualifier. EXEC TARGET requires EXEC TRANSITION. LINK RULE is for linking. ALPHA and ALPHANUMERIC are just character sets. CHANGE_PROFILE RULE is for changing profiles. EXEC_MODE is safe or unsafe. EXEC COND is a FILEGLOB. and ALL RULE is just 'all'. iconic.

now, the tea on subprofiles: 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 aa_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 you're rolling with attachment conditionals, the conditionals for every profile in the namespace get evaluated, bestie. The profile with the set of attachments that results in the best match becomes the new profile after a transition operation. And attachments that don't match? That profile just isn't available for transition, sorry babe. 💅

If no conditionals are specified at all, then the profile only gets used if a transition explicitly specifies the profile name. That's the whole vibe.

Exec Attachment Conditional

The exec attachment conditional is the one that governs how closely your profile matches an executable program. It's only used during an exec operation when the matching exec rule specifies either a px or a cx transition type (or their derivatives). It'll also be used by tasks that are unconfined, because those roll with a pix transition rule. 🫶

And if there are no attachment matches, then it's up to the exec rule to decide what happens — fail, or a fallback option. No attachment match, no opinion, the exec rule runs the show.

Note: see profile Name for all the info 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 decide the winner when there are multiple matches at run time. The exact implementation of this resolution is kernel specific and has improved over time, all while retaining backwards compatibility. And if the heuristic can't determine a winner between multiple matches? Then the exec is denied. Periodt. 💀

Extended Attributes Attachment Conditional

AppArmor profiles have the ability to target files based on their xattr(7) values in addition to their path. Like, obsessed. For example, this 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 let you modify the behavior of the profile. And if a profile flag is specified, it takes priority over any conflicting flags that have been specified by rules in the profile body. Flags beat rules, no cap. ✨

Profile Mode

The profile mode lets you control 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 don't grant permission, the action is denied, with an EACCES or EPERM error code returned to userspace, and the violation gets logged with a tag of the access being DENIED.
kill — This is a variant of enforce mode where, on top of 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 don't grant permission, the action is allowed, but the violation still gets logged with a tag of the access being ALLOWED.
- It is important to understand that complain mode does not allow everything. It only allows policy violations that are not covered by a rule in the confining profile. This means that errors caused by non-policy violations, permissions being denied by interactions with other subsystems, or actions denied due to none policy based restrictions will not be allowed.
- The set of what can be allowed may change with the kernel version, either because new mediation hooks have been added, policy has been extended to cover cases that were hardcoded restrictions, ABI mismatch, or new failure possibilities have been introduced.
- A non-complete list of places where complain mode will not convert an error into an allowed operation follows. 👇
  - explicit denials — If the kernel is carrying explicit denial information (generated by deny rules), the access will not be allowed. complain mode will only convert implicit denials to ALLOWED.
    - It is important to note that a kernel may not have the ability to carry explicit denial information, and that even if the kernel does carry explicit denial information, the compiler may choose to strip explicit denial information (-O filter-deny).
  - stacked denials — Denials from other profiles that are not in complain but are in a mediation stack with a profile in complain mode can cause mediation to fail. These failures will be reported against those profiles and not the profile in complain mode.
  - Peer profiles interaction — In mediation that involves a peer profile (eg. ipc or ptrace), the peer profile can cause an operation to be denied even though the current task's profile is in complain mode.
    - This is because these interactions require both profiles to allow the action, and there is a cross check that gets done. If the peer profile does not allow the requested action, and it is not in complain mode, the cross check will fail and the requested action will be denied. Such a denial will be logged against the peer profile, but the requesting task will receive the denial error.
  - Memory allocations errors (ENOMEM) — If mediation requires allocation of memory and the allocation of memory fails, AppArmor will fail closed, returning an ENOMEM error. This prevents attackers from trying to use memory DOS attacks to by-pass policy. 🛡️
  - Interrupts — Interrupts that may cause a syscall restart, break locks, or otherwise result in interrupting mediation will result in the appropriate error being returned (eg. ERESTART).
  - disconnected objects — Objects (files, paths, sockets, mounts) that do not have sufficient mediation information may be denied. Examples include file objects opened in a different mount namespace that have not been delegated to the task being mediated, sockets in a different network namespace, users from a different user namespace.
    - It may also include mount objects without sufficient tracking information, file objects that have been deleted/removed, sockets that have been shutdown, controlling terminals that have been removed, etc.
  - Permissions denied by another subsystem — If AppArmor queries the capabilities subsystem, and it denies the access, depending on why the query was made the access may be denied, instead of converted to an ALLOWED operation. Similarly this may be done for unix DAC permissions.
  - No-new-privs — The no-new-privs restriction occurs when a task indicates to the kernel that no new privileges should be granted. It is a way for userspace to request an explicit security barrier. AppArmor respects the no-new-privs request and will not allow adding permissions or changing policy unless the change can be proven to be a subset of the existing confinement.
    - no-new-privs in particular affects profile transitions.
  - Restrictions not covered by policy — AppArmor has a few hardcoded restrictions that are not covered by policy, and thus can not be allowed by policy. Hence they are not covered by complain mode. When these restrictions are applied they will return EPERM instead of EACCES. An example of this is trying to disable AppArmor via the module enabled parameter, after AppArmor has been initialized during kernel initialization in early boot. This parameter is restricted to use as a kernel parameters set in the boot loader.
    - The full set of these restrictions can change based on kernel version.
  - ABI mismatch — If the ABI of policy does not match the ABI of the kernel, complain mode may be affected in non-intuitive ways. Generally the ABI mismatch will not result in failures that result in an error that could be converted to an ALLOWED message by complain mode. Instead, ABI mismatches usually result in rules not being enforced, resulting in no mediation or allowed messages even though a kernel may support a given feature.
    - eg. the kernel may support fine grained network ip mediation, but the policy was declared under an ABI that does not specify support for fine grained network mediation. In this scenario the profile will not deny based on fine grained network access and there may not be any complain mode ALLOWED messages or denied messages.
    - ABI mismatches can cause rule downgrades instead of rules not being mediated. Generally this means rules are broader, resulting in the same issue seen with rules not being enforced, ie. what is being allowed by the kernel is more generic than what the rule specified, but it is still not allowing everything that a full rule not enforced would.
    - An example of this would be a fine grained ip address rule being downgraded to a coarser, socket level rule. Eg.

allow network rw stream ip=127.0.0.1 port=5555,

being downgraded to

allow network inet stream,

The downgraded rule can result in denials. The above example will result in denials for inet dgram that can be converted into ALLOWED messages by complain mode. However it will allow inet stream access to ports that are not 5555, and to addresses that are not 127.0.0.1. Neither of these broader accesses will result in denial messages that can be converted to ALLOWED messages by complain mode.

There is a case where rule downgrades can result in ALLOWED messages for mediation covered by a rule in policy. When deny rules are downgraded, they get narrower (to avoid denying more than what was specified in policy) and rely on default deny to cover gaps between the explicit deny rule and the allow rules in policy. This however means that a downgrade of a deny rule may result in complain mode ALLOWED messages for accesses that are already explicitly denied by policy. 😭

null-XXX profiles — okay so these are the kernel's special null profiles, and their whole job is tracking the execution of child processes that a program in complain mode execs. Here's the tea tho: depending on which kernel you're on, these null profiles might have a different ABI than the parent profile in complain mode, which gives you weird behavior that looks exactly like an ABI mismatch. Not a vibe. 😭
default_allow — bestie, this mode flips AppArmor's whole default from default deny to default allow. So when default_allow is specified, the resulting profile will just allow operations that it doesn't even have a rule for. It's giving unconfined, but it still lets you do allow rules, deny rules, specify audit, and domain transitions. One little thing: profiles in this mode may be reported as being in enforce mode or allow mode when introspected from the kernel, so don't panic.

Note: default_allow is similar to — and for many profiles will be equivalent to — specifying an allow all, rule in the profile. But the default_allow flag does not provide all the same options that the allow all, rule provides. Close, but not the same, iykyk.

unconfined — this mode lets a task confined by the profile behave as though it is unconfined. You can flip that unconfined behavior back to confinement later using profile replacement. Do not use this under regular deployment, for real — it's for debugging and some system initialization scenarios only. 🎀

This mode is similar to default_allow, and on kernels that no longer support a true unconfined mode it may be emulated by default_allow. It does not generally allow for specifying deny rules, or allow rules that override the default behavior — except in a few custom kernels where unconfined restricts a few operations. It relies on special customized behavior of the unconfined profile in the kernel, so like… it should only be used for debugging.

Note: true unconfined is being phased out 😭, with unconfined becoming a replaceable profile. As such, unconfined mode will be emulated by a special profile compiled with the default_allow flag in newer kernels.

prompt — this mode lets task mediation send an up call to userspace to ask for a decision whenever there isn't a rule covering the permission request. And if userspace doesn't respond? The access will be denied. No response, no entry. 💅

🌈 Audit Mode 🌈

The audit mode is all about controlling how AppArmor messages get logged to the audit system.

audit — this flag causes all actions, whether allowed or denied, to be logged. Every. Single. One. 👑

🦋 Misc modes 🦋

mediate_deleted — forces AppArmor to mediate deleted files as if they still exist in the file system. Ghost files, but make it policy.
attach_disconnected — 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.
attach_disconnected.path=ABS PATH — like attach_disconnected, but it attaches disconnected objects to the supplied path instead of the root of the namespace.
attach_disconnected.ipc — a subset of attach_disconnected, but specific for IPC namespaces. It allows attaching disconnected IPC paths without having to allow attaching all types of files.
attach_disconnected.ipc=ABS PATH — like attach_disconnected.ipc, but attach disconnected posix mqueue to the supplied path instead of the root of the namespace.
chroot_relative — forces file names to be relative to a chroot and behave as if the chroot is a mount namespace.
debug — this flag turns on kernel debug messages on a per-profile basis. It works in conjunction with other kernel debug flags to control what messages will be output. Its effect is kernel dependent, and it should never appear in policy except when you're trying to debug kernel or policy problems.
interruptible — enables interrupts for prompt upcall to userspace.
kill.signal=SIGNAL — changes the signal that AppArmor will send when it's in kill mode or a kill rule has been violated.
error=ERROR CODE — changes the error code returned by AppArmor when a rule has been violated.

✨ Access Modes ✨

File permission access modes are made of combinations of these:

r — read
w — write — conflicts with append
a — append — conflicts with write
ux — unconfined execute
Ux — unconfined execute — use ld.so(8) secure-execution mode
px — discrete profile execute
Px — discrete profile execute — use ld.so(8) secure-execution mode
cx — transition to subprofile on execute
Cx — transition to subprofile on execute — use ld.so(8) secure-execution mode
ix — inherit execute
pix — discrete profile execute with inherit fallback
Pix — discrete profile execute with inherit fallback — use ld.so(8) secure-execution mode
cix — transition to subprofile on execute with inherit fallback
Cix — transition to subprofile on execute with inherit fallback — use ld.so(8) secure-execution mode
pux — discrete profile execute with fallback to unconfined
PUx — discrete profile execute with fallback to unconfined — use ld.so(8) secure-execution mode
cux — transition to subprofile on execute with fallback to unconfined
CUx — transition to subprofile on execute with fallback to unconfined — use ld.so(8) secure-execution mode
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. Yes bestie, your shell scripts need this one.

🍓 `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 use ld.so(8) secure-execution mode to clear 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. 💀