The profile language at a glance

every construct, one page for everyone

The shape of a policy file shown on one example profile. A preamble, a profile head, rules and nested blocks. The reference lists every syntax deck and maps each line of the example to its deck.

On the map: start here

▶ Watch this deck — 9 scenes, ~7 min

Worth seeing first

  • Why AppArmor — demo's nine-line profile, which this deck grows

Part of journeys

01 One profile, every kind of line

THE PROFILE LANGUAGE /etc/apparmor.d/demo 38 lines preamble settings for the whole file profile head name, program, flags rules one per line, each ends with a comma blocks conditions, child profiles, hats the full text is in the reference below
A miniature of a 38-line profile whose lines are grouped into four regions: preamble, profile head, rules and blocks

A policy file is a preamble followed by profiles. A profile is a head and a body of rules and nested blocks. The example shows syntax and is not a recommended policy; its full text is in the reference, with a line-by-line index.

In the first deck, demo's profile was nine lines long. Real profiles grow. This version has thirty-eight lines, and it uses every kind of line the language has, on purpose. You don't need to learn it. What helps is seeing that the page has only four regions. At the top, a preamble: settings for the whole file. Then one head line, with the profile's name, its program and its flags. Then a long run of rules. And near the end, a few nested blocks. This deck walks through the regions and tells you where on the map each kind of line is explained. The full text is in the reference below.

Details and sources

Details

  • The 38-line example is in the reference under this deck, with a line-by-line index. The program, the paths and the names are invented, and it is not a recommended policy.
  • It was checked with the parser built from the AppArmor tree at 836052d21: apparmor_parser -Q -K --skip-kernel-load --warn=all, with --base set to the tree's profiles/apparmor.d and --kernel-features to the tree's abi/5.0. Exit status 0, no warning. -N printed demo, demo//admin and demo//worker. Nothing was loaded into a kernel.
  • The four regions in the man page's grammar: PROFILE FILE = ( [ PREAMBLE ] [ PROFILE ] )* and PROFILE = ( PROFILE HEAD ) [ ATTACHMENT SPECIFICATION ] [ PROFILE IDENTITIES ] [ PROFILE FLAG CONDS ] '{' ( RULES )* '}' (apparmor.d.pod:105, apparmor.d.pod:131).
  • RULES are line rules (comments, includes), comma rules and block rules (apparmor.d.pod:170-176).
  • To check a file of your own without loading it: apparmor_parser -Q -K FILE; add -N to list the profile names in it.

Read more

for AppArmor developers for security researchers

In the code

  • The top rule of the grammar is list: preamble ... profilelist (parser_yacc.y:345); the head is profile_base: TOK_ID opt_id_or_var opt_cond_list identities flags TOK_OPEN (parser_yacc.y:391).

02 The grammar in three habits

LINE STRUCTURE 7 profile demo /usr/bin/demo ... { 38 } braces hold a body 25 /etc/demo/** r, every rule ends with a comma 8 include <abstractions/base> include: no comma 1 # Example policy for the AppArmor map. ... # starts a comment /etc/demo/** r no comma /usr/bin/[a-z]* ix, missing an end of line character? (entry: /etc/demo/**) the parser reports it where the next rule starts
Five lines of the example profile showing braces around the body, a comma ending a rule, an include line without a comma and a comment, then the error printed when a comma is missing

Rules end with ,. Bodies sit in { }. include takes no comma and # starts a comment. A rule without its comma, followed by another rule, is reported as missing an end of line character? (entry: ...).

Three habits cover most of the language. First, braces. A profile's body sits between an opening brace on the head line and a closing brace at the end. Second, the comma. Every rule ends with one, and it's the comma, not the line break, that ends the rule, so two rules can share a line. Third, the exceptions. An include line takes no comma. And a hash starts a comment, except in the old spelling, #include. Forget a comma, and the parser tells you in its own way: at the next rule, it asks whether you are missing an end of line character.

Details and sources

Details

  • Man page: RULES = [ ( LINE RULES | COMMA RULES ',' | BLOCK RULES ); line rules are comments and includes (apparmor.d.pod:170-172).
  • Comment: # to the end of the line (parser_lex.l:815). The exception is #include, the old spelling of include, which still includes and warns deprecated use of '#include' (parser_lex.l:796-800). The warning class is include.
  • A variable assignment takes no comma either: @{X} = a, is the error Variable declarations do not accept trailing commas (parser_lex.l:573).
  • The missing comma, verbatim: missing an end of line character? (entry: PATH). It is reported at the line of the following rule and names the path of the rule that lacks the comma.
  • The last rule of a body without its comma gives another message: syntax error, unexpected TOK_CLOSE, expecting TOK_END_OF_RULE (observed with the parser built from the AppArmor tree at 836052d21).
  • Every message is prefixed AppArmor parser error for FILE in profile FILE at line N:.

for AppArmor developers for security researchers

In the code

  • The message comes from an error production: a file rule followed by another id where the comma should be, file_rule_tail: opt_exec_mode id_or_var file_perms id_or_var (parser_yacc.y:1132-1138).
  • The closing brace is the scanner pattern CLOSE_BRACE (parser_lex.l:250).

03 The preamble: settings before the first profile

PREAMBLE abi <abi/5.0>, which kernel features the policy was written for syn-abi include <tunables/global> pull in shared definitions syn-include syn-abstractions-tunables @{APP_DATA} = /var/lib/demo /srv/demo a variable with two values syn-variables ${DEMO_DEBUG} = false a boolean, for if blocks syn-boolean-variables alias /usr/ -> /opt/demo/usr/, the same rules for a second location syn-alias owner @{APP_DATA}/{cache,state}/** rwk, line 26 uses the variable: both directories
The five preamble lines of the example, each with what it does and the deck that explains it, and a rule from the body that uses the variable

The preamble holds abi, include, variable assignments and alias. Variables and aliases cannot be defined after the first profile starts; abi and include can also appear inside a profile.

Everything above the first profile is the preamble. The abi line says which kernel feature set the policy was written against. Include pulls in another file; here it's the standard tunables, which is where the @{HOME} variable used further down comes from. Next comes a variable of your own. It can hold several values, and a rule that uses it stands for each of them. The line with the dollar sign is a boolean, and it exists to be tested by an if. Alias tells the parser that one path prefix also lives somewhere else. Variables and aliases are set here, and only here. Line twenty-six uses the variable, so it covers both directories.

Details and sources

Details

  • Man page: PREAMBLE = ( COMMENT | VARIABLE ASSIGNMENT | ALIAS RULE | INCLUDE | ABI )*, with the note "Variable assignment and alias rules must come before the profile." (apparmor.d.pod:107-108).
  • abi <abi/5.0>, ends with a comma. Besides a file it accepts <kernel> and <default> (apparmor.d.pod:120). The file is /etc/apparmor.d/abi/5.0.
  • include <tunables/global>: the path in angle brackets is relative to /etc/apparmor.d/ (apparmor.d.pod:124-125). tunables/global includes tunables/home, which defines @{HOME} (home:21).
  • Variables: @{NAME} = value value, with the operators =, +=, ?= and := (apparmor.d.pod:110). A second = for the same name is the error variable @{NAME} was previously declared.
  • Boolean: ${NAME} = true or false.
  • Alias: alias /usr/ -> /opt/demo/usr/,; rewrite is another spelling of alias (parser_misc.c:105-106).
  • apparmor_parser -p FILE prints the file with the includes resolved, which shows what the preamble pulls in.

for AppArmor developers for security researchers

In the code

04 The head: one line, six parts

PROFILE HEAD line 7, split for reading profile demo the keyword and the name syn-profile-name /usr/bin/demo the program it attaches to attachment xattrs=(user.demo=trusted) only if the file carries this attribute syn-xattrs + identities=(demo-role) identities of the profile syn-identities flags=(complain, attach_disconnected) the mode, and other switches syn-flags-modes syn-flags-other { then the body profile demo /usr/bin/demo { most profiles stop here
The head line of the example profile split into six parts: keyword and name, attachment, xattrs, identities, flags and the opening brace, each with the deck that explains it

profile NAME ATTACHMENT xattrs=( ) + identities=( ) flags=( ) {. Only the name is required. The mode is one of the flags.

The head is one line, and on this profile it carries everything a head can. First the word profile and a name. The name is what you see in logs and on process labels. Then a path, the attachment: it tells the kernel which program gets this profile. An xattrs condition narrows that to files carrying an extended attribute. Identities come next, after a plus sign. Then the flags, where complain is the mode and attach_disconnected is one of more than a dozen other switches. An opening brace starts the body. Most profiles you meet have just the first two parts and the brace.

Details and sources

Details

  • Man page: PROFILE = ( PROFILE HEAD ) [ ATTACHMENT SPECIFICATION ] [ PROFILE IDENTITIES ] [ PROFILE FLAG CONDS ] '{' ( RULES )* '}' (apparmor.d.pod:131).
  • Name: profile NAME. A head that is only a path, /usr/bin/demo {, still works and warns The use of file paths as profile names is deprecated.; the path is then both the name and the attachment.
  • Attachment: a path pattern after the name. Anything else is the error Profile attachment must begin with a '/' or variable.
  • xattrs: xattrs=(user.demo=trusted); the list is separated by commas or white space (apparmor.d.pod:145-147).
  • Identities: + identities=(demo-role) (apparmor.d.pod:151). They are not sent to the kernel; see identities.
  • Flags: flags=(complain, attach_disconnected); the word flags= is optional (apparmor.d.pod:157). The six mode names are enforce, complain, kill, default_allow, unconfined, prompt (apparmor.d.pod:166); the other flag names are checked at profile.h:216-257. An unknown one is the error Invalid profile flag: NAME. (profile.h:261).
  • The name is what apparmor_parser -N prints, what the profile= field of a log record holds and what /proc/PID/attr/current shows.

for AppArmor developers for security researchers

In the code

05 File rules: a path and what may be done with it

FILE ACCESS qualifiers path pattern permissions -> target , grey parts are optional /etc/demo/** r, two stars: any depth, r: read syn-globbing syn-access-modes /usr/bin/[a-z]* ix, run it, keep this profile syn-exec-modes /usr/bin/demo-helper Px -> demo-helper, run under the profile after the arrow syn-named-transitions link /var/lib/demo/current -> /var/lib/demo/releases/*, hard links have their own rule syn-link-rules letters: r w a l k m and the exec modes ending in x
A file rule is optional qualifiers, a path pattern, permissions and an optional target; four example rules show a glob with read, an ix exec, a Px exec with a named target and a link rule

PATH PERMISSIONS, with globs in the path. Access letters r w a l k m; exec modes such as ix, Px, Cx choose the profile of the program being started, and -> name names it.

Most of any profile is file rules, and they read left to right: a path pattern, then letters. The pattern can use globs; two stars cross directory levels. The letter r is read, and there are letters for write, append, link, lock and memory map. The letter x is different. It doesn't come alone in an allow rule: the letter in front says which profile the new program runs under. ix keeps the current profile. Px switches to the profile of the program being started, and an arrow names the target outright. Hard links can also be written as a rule of their own, starting with the word link.

Details and sources

Details

  • Forms: PATH PERMS, or PERMS PATH,, optionally after the word file (parser_misc.c:108).
  • Access letters: r read, w write, a append (not together with w), l link, k lock, m memory map with PROT_EXEC.
  • Exec modes: ix inherit, px and Px the profile of the program, cx and Cx a child profile, ux and Ux unconfined; the capital letter scrubs the environment. Fallbacks such as pix and cix exist.
  • A bare x in an allow rule is the error Invalid perms, 'x' must be preceded by exec qualifier 'i', 'p', or 'u' (parser_misc.c:1099). deny PATH x, is the one place where x stands alone.
  • Named transition: /usr/bin/demo-helper Px -> demo-helper,. With Cx -> worker the kernel looks the name up among the children of the current profile (domain.c:603-606).
  • Globs: * within one directory level, ** across levels, ?, [a-z], {a,b}.
  • Link rule: link [subset] PATH -> TARGET, (parser_misc.c:94-98).

for AppArmor developers for security researchers

In the code

06 Qualifiers go in front, in a fixed order

QUALIFIERS priority=N audit allow | deny | prompt owner | other the rule all optional, always in this order audit deny @{HOME}/.ssh/** rw, refuse, and log it syn-audit syn-allow-deny owner @{APP_DATA}/{cache,state}/** rwk, only files the process owns syn-owner priority=10 allow /etc/demo/override.conf r, settles which rule wins syn-priority prompt @{HOME}/Documents/** r, ask first not acted on by the kernel syn-prompt deny { /proc/sys/** w, /sys/** w, } one qualifier, a block of rules syn-qualifier-blocks
The fixed order of qualifiers, priority, audit, allow or deny or prompt, owner or other, then the rule, with five example rules from the profile

Order: priority=N audit allow|deny|prompt owner|other. A qualifier can be put before a { } block of rules. prompt is loaded but not acted on by the kernel.

A rule on its own allows. Words in front change that, and they come in a fixed order: priority, audit, allow or deny, then owner. Deny refuses, even where another rule allows. Audit asks for a log line. So audit deny on your SSH directory means: refuse, and tell me. Owner limits a rule to files the process owns. Priority is a number that decides which rule wins when rules overlap. Prompt is meant to ask a person first, and the kernel doesn't act on it. And to qualify several rules at once, put the qualifier in front of a block in braces.

Details and sources

Details

  • Order: [priority=N] [audit] [allow|deny|prompt] [owner|other] RULE,. Another order is a syntax error; deny audit /foo r, gives syntax error, unexpected TOK_AUDIT, expecting TOK_ID or TOK_MODE or TOK_SET_VAR (observed with the parser built from the AppArmor tree at 836052d21).
  • Keywords: audit, deny, allow, prompt, owner, other; user is another spelling of owner (parser_misc.c:95-102).
  • priority=N takes an integer from -1000 to 1000 (immunix.h:198-199); the default is 0.
  • deny without audit refuses without a log record; audit deny refuses and logs apparmor="DENIED".
  • The man page's QUALIFIERS line lists only priority, audit and allow or deny (apparmor.d.pod:200); the parser also accepts prompt, owner and other in front of every rule class.
  • prompt: in mainline Linux the permission is unpacked and no kernel code acts on it. See prompt and upstream and Ubuntu kernels.
  • Block form: deny { /proc/sys/** w, /sys/** w, }. set rlimit rules take no qualifier.

for AppArmor developers for security researchers

In the code

07 Everything else starts with a keyword

RULE CLASSES capability net_bind_service, privileges also: set rlimit network inet stream, sockets also: unix, dbus mount fstype=tmpfs options=(rw, nosuid) tmpfs -> /run/demo/, mounts also: remount, umount, pivot_root signal (send) set=(term, hup) peer=demo//worker, other processes also: ptrace userns create, kernel facilities also: io_uring, mqueue change_profile -> demo//worker, switching profile name=value name=(a b) peer=( ... ) the same condition syntax in every class dbus: enforced by the bus daemon mqueue: not enforced by the kernel
Six rules from the example, each starting with its keyword, grouped as privileges, sockets, mounts, other processes, kernel facilities and switching profile, and the condition syntax they share

Fifteen keyword rule classes, plus all, which allows everything. They share one condition syntax: name=value, name=(a b) and peer=( ). dbus is enforced by the bus daemon; mqueue is not enforced by the kernel.

Everything that isn't a file rule starts with a keyword naming what it controls. Capability is for privileges, with rlimit beside it. Network is for sockets, with finer rules for unix sockets and for D-Bus. Mount has its relatives: remount, umount and pivot_root. Signal and ptrace cover what demo may do to other processes. Userns, io_uring and mqueue are kernel facilities, and change_profile switches confinement. After the keyword they look alike: optional permissions, often in parentheses, then conditions written name= value, and peer for the other end. And remember the earlier caution: a rule here is a request. Whether it is enforced depends on the kernel.

Details and sources

Details

  • The fifteen keywords: capability, set rlimit, network, unix, dbus, mount, remount, umount, pivot_root, signal, ptrace, userns, io_uring, mqueue, change_profile. Most are plain words in the parser's keyword table (parser_misc.c:81-138); unmount is another spelling of umount.
  • Shared condition syntax: name=value, name=(a b), name in (a b) and peer=( ... ). Examples from the example profile: unix (send, receive) type=stream peer=(label=demo-helper), and signal (send) set=(term, hup) peer=demo//worker,.
  • all, allows everything: the parser expands it to one bare rule of each class (all_rule.cc:33-40).
  • Enforcement in mainline Linux, read from the source: dbus is enforced by the bus daemon, not the kernel; mqueue has no kernel check point. See D-Bus mediation and upstream and Ubuntu kernels.
  • A class missing from the kernel feature set is dropped at compile time and the profile still loads. apparmor_parser --warn=rule-not-enforced prints, for example, Warning from profile demo (demo.sd): mqueue type=posix rules not enforced (observed with the parser built from the AppArmor tree at 836052d21 and --kernel-features /dev/null).
  • What the running kernel supports: ls /sys/kernel/security/apparmor/features.
  • The man page's COMMA RULES line omits ptrace and signal rules (apparmor.d.pod:174); the parser accepts both.

for AppArmor developers for security researchers

In the code

08 Blocks inside a profile

PROFILE STRUCTURE if ${DEMO_DEBUG} { /tmp/demo-debug.log w, } kept or dropped at compile time syn-boolean-conditionals profile worker { all, } a child profile syn-child-profiles line 32: /usr/lib/demo/worker Cx -> worker, ^admin { /etc/demo/admin.conf rw, } a hat: demo switches into it itself syn-hats $ apparmor_parser -N /etc/apparmor.d/demo demo demo//admin demo//worker demo demo//admin demo//worker three profiles in the kernel
The three blocks at the end of the example, an if block, a child profile and a hat, and the three profile names the parser prints for them

if blocks are decided at compile time. Child profiles and hats are written inside their parent and loaded as separate profiles named parent//child.

The last region is blocks. An if block tests a boolean from the preamble when the profile is compiled. Debug is set to false, so that rule is simply not there. A profile inside a profile is a child, and line thirty-two sends the worker program into it with Cx. The line with the caret is a hat: a sub-profile that the program switches into and out of by itself. Children and hats look nested in the text. But ask the parser for the names and you get three: demo, demo//admin and demo//worker. That is how they appear in logs.

Details and sources

Details

  • Man page: BLOCK RULES = ( SUBPROFILE | HAT | QUALIFIER BLOCK | IF_BLOCK ) (apparmor.d.pod:176).
  • Conditional: if EXPR { } else if EXPR { } else { }, with not, and, or and defined (apparmor.d.pod:188-192). It is decided by the parser; the kernel never sees the block or the variable.
  • Child profile: profile worker { ... } inside a body, reached by /usr/lib/demo/worker Cx -> worker,.
  • Hat: ^admin { ... } or hat admin { ... } (apparmor.d.pod:180). The program enters and leaves it with int aa_change_hat(const char *subprofile, unsigned long magic_token); (apparmor.h:79).
  • Names: apparmor_parser -N on the example printed demo, demo//admin and demo//worker (observed with the parser built from the AppArmor tree at 836052d21). The separator // is added at profile.h:454-459.
  • Loaded policy shows the same names: /sys/kernel/security/apparmor/profiles, the profile= field of a log record and /proc/PID/attr/current.
  • -N prints the hat and the child in the same form; the parser does not mark which is which in the name.

for AppArmor developers for security researchers

In the code

09 Six districts and three long decks

ROADS demo The preamble PREAMBLE AND REUSE · 9 decks Profile name PROFILE HEAD · 5 decks Attachment the long deck File rules FILE ACCESS · 7 decks allow and deny QUALIFIERS · 7 decks capability RULE CLASSES · 18 decks Hats PROFILE STRUCTURE · 4 decks Namespaces names like :ns:demo Stacking targets like demo//&other all 50 syntax decks are listed in the reference below
The four regions of the example profile lead to nine destinations: six district entry decks and the three long decks on attachment, namespaces and stacking

Each district has an entry deck: the preamble, the profile name, file rules, allow and deny, capability, hats. The reference below lists every syntax deck and maps each line of the example to its deck.

There are fifty decks on syntax, and one slide can't hold them. So here is how to find yours: each region of the page is a district of the map. For the lines above the profile, start at the preamble. For the head, start at the profile name; attachment has a long deck of its own. Rules split three ways: file rules, qualifiers, and the keyword classes, starting with capability. Hats and child profiles are under profile structure. Namespaces and stacking explain the names with colons and ampersands. And under this deck, the reference lists all fifty with one line each, next to the full example.

Details and sources

Details

  • The reference under this deck lists all 50 syntax decks with one line each and maps the 38 lines of the example to their decks; 45 of the 50 appear in that table.
  • Five decks have no line in the example: network conditionals, other, safe and unsafe, quoting, built-in variables. One line for each is in the reference; all five were accepted together by the parser built from the AppArmor tree at 836052d21.
  • Names with colons, :ns:name, belong to namespaces; targets with an ampersand, a//&b, belong to stacking.
  • Spellings that mean the same: rewrite and alias, unmount and umount, user and owner (parser_misc.c:96-112).
  • Commit read for this deck: AppArmor 836052d21 (6.0.0~alpha2).

Read more

The example profile

# Example policy for the AppArmor map. Lines 2-6 are the preamble.
abi <abi/5.0>,
include <tunables/global>
@{APP_DATA} = /var/lib/demo /srv/demo
${DEMO_DEBUG} = false
alias /usr/ -> /opt/demo/usr/,
profile demo /usr/bin/demo xattrs=(user.demo=trusted) + identities=(demo-role) flags=(complain, attach_disconnected) {
  include <abstractions/base>
  include if exists <local/demo>
  capability net_bind_service,
  network inet stream,
  unix (send, receive) type=stream peer=(label=demo-helper),
  dbus send bus=session path=/org/demo interface=org.demo.Api peer=(name=org.demo),
  mount fstype=tmpfs options=(rw, nosuid) tmpfs -> /run/demo/,
  remount options=(ro) /run/demo/,
  umount /run/demo/,
  pivot_root oldroot=/run/demo/old/ /run/demo/,
  signal (send) set=(term, hup) peer=demo//worker,
  ptrace (read) peer=demo//worker,
  mqueue (create, open) type=posix /demo-queue,
  userns create,
  io_uring sqpoll,
  change_profile -> demo//worker,
  set rlimit nofile <= 1024,
  /etc/demo/** r,
  owner @{APP_DATA}/{cache,state}/** rwk,
  audit deny @{HOME}/.ssh/** rw,
  priority=10 allow /etc/demo/override.conf r,
  prompt @{HOME}/Documents/** r,
  link /var/lib/demo/current -> /var/lib/demo/releases/*,
  /usr/bin/demo-helper Px -> demo-helper,
  /usr/lib/demo/worker Cx -> worker,
  /usr/bin/[a-z]* ix,
  deny { /proc/sys/** w, /sys/** w, }
  if ${DEMO_DEBUG} { /tmp/demo-debug.log w, }
  profile worker { all, }
  ^admin { /etc/demo/admin.conf rw, }
}

The program, the paths and the names are invented. The profile shows syntax and is not a recommended policy. It was checked with the tree's parser (6.0.0~alpha2) through tools/head-parser, with -Q -K --skip-kernel-load --warn=all, --base set to the tree's profiles/apparmor.d and the tree's abi/5.0 features: exit status 0 and no warning. With -N the parser printed demo, demo//admin and demo//worker. The profile is in complain mode to show the flag; the descriptions of deny and audit deny in the deck are for enforce mode.

Lines 13 (dbus), 20 (mqueue), 29 (prompt) and the identities on line 7 compile, but mainline Linux 7.4 does not enforce them itself. For dbus see dbus-mediation; for mqueue and prompt see upstream-and-ubuntu; for identities see syn-identities. When the kernel feature set given to the parser lacks a rule class, the line is dropped and the profile still loads; the warning for it is off by default (--warn=rule-not-enforced).

Line by line

Line numbers count from the comment on line 1 of the example.

LineConstructDeck
1commentComments
2-6the preamble as a wholeThe preamble
2feature ABIabi
3include of a tunables file (it defines @{HOME}, used on lines 27 and 29)include, Abstractions and tunables
4variable with two valuesVariables
5boolean variableBoolean variables
6aliasalias
7profile keyword and nameProfile name
7attachment /usr/bin/demoAttachment
7xattrs=( )xattrs
7+ identities=( )Identities
7flags=(complain, …)Mode flags
7attach_disconnectedOther flags
8include of an abstractioninclude, Abstractions and tunables
9include if existsinclude
10capabilitycapability
11networknetwork
12unix; the conditions type= and peer=( )unix, Rule conditionals
13dbus; conditionsdbus, Rule conditionals
14mount; fstype=, options=( )mount, Rule conditionals
15remountremount
16umountumount
17pivot_rootpivot_root
18signal; set=( ), peer=signal, Rule conditionals
19ptraceptrace
20mqueuemqueue
21usernsuserns
22io_uringio_uring
23change_profilechange_profile
24rlimitrlimit
25file rule, r, **File rules, Access modes, Globbing
26owner, use of a variable, {a,b}, rwkowner, Variables, Globbing, Access modes
27audit denyaudit, allow and deny
28priority=10 allowpriority, allow and deny
29promptprompt
30link ruleLink rules
31Px with -> profileExec modes, Named transitions
32Cx to the child on line 36Exec modes, Named transitions, Child profiles
33ix, [a-z]*Exec modes, Globbing
34qualifier blockQualifier blocks, allow and deny
35conditional testing the boolean of line 5Conditionals, Boolean variables
36child profile containing all,Child profiles, all
37hatHats
38closing braceComments (line structure)

45 of the 50 syntax decks appear in this table.

Not in the example

Five decks have no line in the example. One line for each; all five were accepted together in one scratch profile by the tree's parser (6.0.0~alpha2), exit status 0, no warning.

DeckA line that uses it
network conditionalsnetwork inet stream ip=127.0.0.1 port=8080,
otherother /srv/shared/** r,
safe and unsafesafe Px /usr/bin/extra-tool,
Quoting"/srv/my files/**" r,
Built-in variables/run/@{profile_name}.pid w,

safe and unsafe go first, with the permissions before the path. PATH safe Px, was rejected with "syntax error, unexpected TOK_SAFE, expecting TOK_MODE".

Also not shown, each belonging to a deck listed below: subset on link rules, else, the assignment operators += ?= :=, hat NAME, the PERMS PATH order and the bare file, rule, names in a namespace (Namespaces) and stacked targets (Stacking).

Every syntax deck

Profile head (5)

  • Profile name: the profile keyword and the name; path names without the keyword are deprecated.
  • Identities: + identities=( … ) after the attachment and xattrs, before the flags.
  • Mode flags: flags=( … ) with a mode: enforce, complain, kill, unconfined, prompt, default_allow.
  • Other flags: the other flag values, such as attach_disconnected, mediate_deleted, kill.signal=, error=, audit.
  • xattrs: xattrs=( name=value … ), attach only to files whose extended attributes match.

Profile structure (4)

  • Hats: ^name { } or hat name { }, a sub-profile the program switches into itself.
  • Child profiles: profile name { } inside a body, reached with cx transitions.
  • Comments: # comments, commas, and how a file is split into rules.
  • Quoting: "…" around names, paths and values, and the backslash escapes.

File access (7)

  • File rules: PATH PERMS, or PERMS PATH,, the optional file keyword and bare file,.
  • Access modes: the permission letters r w a l k m.
  • Exec modes: ix px Px cx Cx ux Ux and the fallback forms such as pix.
  • Named transitions: -> target after an exec permission.
  • safe and unsafe: safe and unsafe before exec rules and change_profile.
  • Link rules: link [subset] PATH -> TARGET,.
  • Globbing: * ** ? [abc] [^a] {a,b} in any path or pattern.

Qualifiers (7)

  • allow and deny: allow and deny before a rule or block, and how a deny overrides an allow.
  • audit: audit, log what a rule matches.
  • prompt: prompt in the place of allow or deny; not acted on by mainline Linux 7.4.
  • owner: owner (also spelled user), only files the task owns.
  • other: other, only files the task does not own.
  • priority: priority=N, N from -1000 to 1000, written first.
  • Qualifier blocks: qualifiers before { rules }, applied to every rule inside.

Rule classes (18)

  • capability: capability [name …], with names written without CAP_.
  • network: network [perms] [family] [type or protocol],.
  • network conditionals: the ip=, port=, interface= and label= conditions on network rules.
  • unix: unix [perms] [conds] [peer=( … )], for unix domain sockets.
  • dbus: dbus [perms] [conds] [peer=( … )],; enforced by the bus daemon, see dbus-mediation.
  • mount: mount [conds] [source] [-> mountpoint],.
  • umount: umount [conds] [mountpoint], (also spelled unmount).
  • remount: remount [conds] [mountpoint],.
  • pivot_root: pivot_root [oldroot=PATH] [newroot] [-> profile],.
  • signal: signal [perms] [set=( … )] [peer=LABEL],.
  • ptrace: ptrace [perms] [peer=LABEL], with trace, tracedby, read, readby.
  • mqueue: mqueue [perms] [type=posix|sysv] [label=…] [name],; not enforced by mainline Linux 7.4, see upstream-and-ubuntu.
  • userns: userns [create],.
  • io_uring: io_uring [sqpoll|override_creds] [label=…],.
  • change_profile: change_profile [[safe|unsafe] EXEC] [-> TARGET],.
  • rlimit: set rlimit NAME <= VALUE,.
  • all: all,, one rule that allows every class.
  • Rule conditionals: the shared condition syntax name=value, name=(a b), name in (a b), peer=( … ).

Preamble and reuse (9)

  • include: include <path>, include "path", include if exists, and the deprecated #include.
  • The preamble: what may come before the first profile.
  • Abstractions and tunables: the shared files under abstractions/ and tunables/.
  • Variables: @{NAME} and the operators = += ?= :=.
  • Built-in variables: @{profile_name}, @{attach_path}, @{exec_path}.
  • Boolean variables: ${NAME} = true|false.
  • Conditionals: if, else if, else blocks with not, and, or, defined.
  • alias: alias /from/ -> /to/, (also spelled rewrite).
  • abi: abi <abi/5.0>,, the feature ABI the policy was written for.

The three long decks

Spellings that mean the same

SpellingSame asDeck
rewritealiasalias
unmountumountumount
userownerowner
#includeinclude (deprecated spelling, warns)include
vfstypefstypemount
optionoptionsmount
hat NAME^NAMEHats
bare ( … ) in the headflags=( … )Mode flags

Errors you meet first

MessageWhen
"missing an end of line character? (entry: %s)"a rule without its comma followed by another rule; reported at the following line, with the path of the rule that lacks the comma
"syntax error, unexpected TOK_CLOSE, expecting TOK_END_OF_RULE"the last rule of a body without its comma
"Profile names must begin with a '/', namespace or keyword 'profile' or 'hat'."a name without profile in front
"The use of file paths as profile names is deprecated." (warning)/path { as a head
"Profile attachment must begin with a '/' or variable."a bad attachment
"Invalid profile flag: %s."an unknown flag
"Variable declarations do not accept trailing commas"@{X} = a,
"variable %s was previously declared"a second = for the same variable
"deprecated use of '#include'" (warning)the old spelling of include

The parser prints these translated when a translation is installed; the English text is the one in the source. Every other error belongs to the deck of its construct.

for AppArmor developers

Where each construct is lexed and parsed

Read at AppArmor 836052d21 (6.0.0~alpha2). "Scanner" is parser/parser_lex.l and "Grammar" is parser/parser_yacc.y unless another file is named. The process is in The lexer and The grammar.

A policy file is list: preamble ... profilelist (parser_yacc.y:345-371; preamble 506-509). Each rule ends with TOK_END_OF_RULE (parser_lex.l:250, 911-917).

How keywords are recognised: profile, hat, include, #include, all, flags, xattrs, peer, identities and priority are scanner patterns (parser_lex.l:409-436, 781-813, 848-850). Every other keyword is a plain word looked up in keyword_table (parser/parser_misc.c:81-138) by the {VARIABLE_NAME} rule (parser_lex.l:856-909). Permission words inside a rule, such as send, create and trace, are recognised only in that rule's scanner state (parser_lex.l:627-688).

Profile head

DeckScannerGrammar
syn-profile-name850 (PROFILE, defined 278); names in state SUB_ID 464-470profile 460-478, profile_base 391, opt_profile_flag 381-383
syn-identities409-416, + at 826631-670
syn-flags-modes433-436593-629; names parser/profile.cc:30-39; values parser/profile.h:212-258
syn-flags-other433-436parser/profile.h:216-257; error at parser/profile.h:261
syn-xattrs420-427opt_cond_list 1274-1275, cond_list 1268, used at 433-438
attachmentpart of idsopt_id_or_var 388-389, check at 431-433

Profile structure

DeckScannerGrammar
syn-hats^ 820, hat 848 (HAT, defined 277)hat 490-504, hat_start 1637-1638; in a body 827-834
syn-child-profiles850local_profile 480-488; stored with add_hat 836-843
syn-comments815-818; #include exception 796-803not a grammar construct
syn-quoting259-263, 295-296, processidnot a grammar construct

File access

DeckScannerGrammar
syn-file-rulesfile via keyword_table (parser/parser_misc.c:108); paths 838-841rule 1049-1050, file_rule 1103-1115, frule 1072-1101, file_rule_tail 1131-1139
syn-access-modesMODE_CHARS 257, token at 843-846file_perms 1640-1646, then parse_perms parser/parser_misc.c:736 and parse_sub_perms parser/parser_misc.c:560
syn-exec-modes257parser/parser_misc.c:606-700
syn-named-transitions-> 822 (state SUB_ID_WS)opt_named_transition 1043-1047, used 1072-1101
syn-safe-unsafekeyword_table parser/parser_misc.c:92-93opt_exec_mode 1065-1067; file rules 1117-1130; change_profile 1648
syn-link-ruleslink, subset via keyword_table (parser/parser_misc.c:94, 98)link_rule 1141-1152; opt_subset_flag 672-675
syn-globbingpart of idsconvert_aaregex_to_pcre parser/parser_regex.c:118-445

Qualifiers

The fixed order is opt_prefix (parser_yacc.y:705-711).

DeckScannerGrammar
syn-allow-denykeyword_table parser/parser_misc.c:100-101opt_rule_mode 700-703
syn-auditparser/parser_misc.c:99opt_audit_flag 693-694
syn-promptparser/parser_misc.c:102703
syn-owner, syn-otherparser/parser_misc.c:95-97opt_owner_flag 696-698
syn-priority428-432; integer in INTEGER_MODE 697-705opt_priority 677-691; bounds parser/immunix.h:198-199
syn-qualifier-blocks{ 834block 738-741; rules opt_prefix block 743-759

Rule classes

DeckGrammarPermission and condition words
syn-capability1694-1716; added at 821-825names without CAP_; "Invalid capability %s." (1708)
syn-network, syn-network-inet1154-1194; rules action 761-783perms 1356-1408; conditions ip port interface label (parser/network.cc:450-468)
syn-unix1418-1432conditions type protocol label (parser/af_rule.cc:30-33), addr (parser/af_unix.cc:49)
syn-dbus1340-1354perms 1302-1330; conditions parser/dbus.cc:51-61
syn-mount1277-1285conditions parser/mount.cc:418-442; flag names parser/mount.cc:247-266
syn-umount1292-1295as mount
syn-remount1287-1290as mount
syn-pivot-root1297-1300condition oldroot (1824)
syn-signal1466-1470perms 1434-1456; conditions set, peer (parser/signal.cc:170-177)
syn-ptrace1509-1513perms 1472-1499; condition peer (parser/ptrace.cc:45)
syn-mqueue1586-1595perms 1541-1576; conditions label, type (parser/mqueue.cc:78-85)
syn-userns1535-1539create (1515-1525)
syn-io-uring1620-1627override_creds, sqpoll (1597-1610); condition label (parser/io_uring.cc:44)
syn-change-profile1648-1692; added at 804-819default target ** (1681)
syn-rlimit852-859names parser/parser_misc.c:146-168
syn-all1629-1635; scanner 811-813expands to one bare rule of each class (parser/all_rule.cc:33)
syn-rule-conditionals1196-1275scanner 420-452, 490-560

Preamble and reuse

DeckScannerGrammar
syn-include781-809; file name 376-398; include_filename 162scanner only
syn-preamblenone of its ownpreamble 506-509
syn-abstractions-tunablesas includenot grammar; the files are under profiles/apparmor.d/abstractions/ and tunables/
syn-variables714-717; values in ASSIGN_MODE 564-592; operators 303-307, 824-832varassign 524-548, assign_op 519-522
syn-builtin-variablesas variablesnot grammar; parser/parser.h:335-337, parser/parser_variable.c:137-177
syn-boolean-variables707-722varassign 550-570
syn-boolean-conditionalsEXPR_MODE 725-767cond_rule 862-900; expr, term, notfactor, factor 902-1035
syn-aliasparser/parser_misc.c:105-106511-517
syn-abistate ABI_MODE, 376-398abi_rule 1052-1063; in the preamble 509 and in a body 722; abi_features 1884

Tokens with no construct

  • TOK_PEER (keyword_table, parser/parser_misc.c:123), TOK_COLON (parser_lex.l:852), TOK_SOFT_RLIMIT and the TOK_RLIMIT_* tokens (parser_yacc.y:168-184) are declared and not used in any grammar rule.
  • The scanner state IOURING_MODE is declared (parser_lex.l:355) and has rules (685-688), but the keyword switch has no case TOK_IO_URING (parser_lex.l:860-906), so the state is not entered. override_creds and sqpoll are recognised through keyword_table instead (parser/parser_misc.c:133-134).
  • opt_subset_flag accepts TOK_LE (parser_yacc.y:674), but the scanner returns it only in RLIMIT_MODE and EXPR_MODE (parser_lex.l:624, 763), so link <= A -> B, is a lexer error.

Where apparmor.d.pod and the code disagree

  • COMMA RULES omits PTRACE RULE and SIGNAL RULE (parser/apparmor.d.pod:174); both are prefix_rule alternatives (parser_yacc.y:785-793).
  • QUALIFIERS lists priority, audit and an access type of allow or deny (parser/apparmor.d.pod:198-200); the grammar also accepts prompt, owner and other for every rule class (parser_yacc.y:696-711).
  • The pod lists the unix conditionals attr and opt (parser/apparmor.d.pod:375-377); neither string occurs in the parser sources. The supported ones are type, protocol, label (parser/af_rule.cc:30-33) and addr (parser/af_unix.cc:49).
  • PROFILE FLAGS (parser/apparmor.d.pod:159-164) omits namespace_relative, delegate_deleted, no_attach_disconnected, chroot_attach and chroot_no_attach, which flagvals::init accepts (parser/profile.h:226-237).
  • SUBPROFILE and HAT (parser/apparmor.d.pod:178-180) show no identities and HAT no attachment; the grammar uses the same profile_base for all three (parser_yacc.y:480, 490).
  • RLIMIT RULE (parser/apparmor.d.pod:379) marks the limit as optional; the grammar requires it (parser_yacc.y:852).
  • PREAMBLE does not mention that abi is also accepted inside a profile body (parser_yacc.y:722).

Roads from here

ATTACHMENT, NAMESPACES, STACKING

FILE ACCESS

PREAMBLE AND REUSE

PROFILE HEAD

QUALIFIERS

RULE CLASSES

PROFILE STRUCTURE

  • Hats — hats and child profiles and the lines between them