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
- New to AppArmor, step 2 of 10 · previous: Why AppArmor · next: The profile name
01 One profile, every kind of line
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--baseset to the tree'sprofiles/apparmor.dand--kernel-featuresto the tree'sabi/5.0. Exit status 0, no warning.-Nprinteddemo,demo//adminanddemo//worker. Nothing was loaded into a kernel. - The four regions in the man page's grammar:
PROFILE FILE = ( [ PREAMBLE ] [ PROFILE ] )*andPROFILE = ( PROFILE HEAD ) [ ATTACHMENT SPECIFICATION ] [ PROFILE IDENTITIES ] [ PROFILE FLAG CONDS ] '{' ( RULES )* '}'(apparmor.d.pod:105, apparmor.d.pod:131). RULESare 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-Nto list the profile names in it.
Read more
- apparmor.d(5) FORMAT: the whole grammar in BNF style.
- Profiles quick reference on apparmor.net.
- wiki: AppArmor_Core_Policy_Reference (marked DRAFT by its authors) and wiki: QuickProfileLanguage.
- Why AppArmor for the nine-line version, the pipeline for what happens to the text.
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 isprofile_base: TOK_ID opt_id_or_var opt_cond_list identities flags TOK_OPEN(parser_yacc.y:391).
02 The grammar in three habits
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 ofinclude, which still includes and warnsdeprecated use of '#include'(parser_lex.l:796-800). The warning class isinclude. - A variable assignment takes no comma either:
@{X} = a,is the errorVariable 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:.
Read more
- apparmor.d(5) FORMAT and Comments.
- Profiles quick reference: comments on apparmor.net.
- Comments, include, quoting.
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
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/globalincludestunables/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 errorvariable @{NAME} was previously declared. - Boolean:
${NAME} = trueorfalse. - Alias:
alias /usr/ -> /opt/demo/usr/,;rewriteis another spelling ofalias(parser_misc.c:105-106). apparmor_parser -p FILEprints the file with the includes resolved, which shows what the preamble pulls in.
Read more
for AppArmor developers for security researchers
In the code
preambleis the grammar rule at parser_yacc.y:506-509;abiinside a profile body isrules: rules abi_rule(parser_yacc.y:722). The redeclaration error is at parser_yacc.y:542.
04 The head: one line, six parts
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 warnsThe 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 wordflags=is optional (apparmor.d.pod:157). The six mode names areenforce,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 errorInvalid profile flag: NAME.(profile.h:261). - The name is what
apparmor_parser -Nprints, what theprofile=field of a log record holds and what/proc/PID/attr/currentshows.
Read more
for AppArmor developers for security researchers
In the code
- The head is
profile_base(parser_yacc.y:391); the attachment check is at parser_yacc.y:431-433;flagsat parser_yacc.y:593 andidentitiesat parser_yacc.y:631. The deprecation warning is at parser_yacc.y:470.
05 File rules: a path and what may be done with it
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,orPERMS PATH,, optionally after the wordfile(parser_misc.c:108). - Access letters:
rread,wwrite,aappend (not together withw),llink,klock,mmemory map withPROT_EXEC. - Exec modes:
ixinherit,pxandPxthe profile of the program,cxandCxa child profile,uxandUxunconfined; the capital letter scrubs the environment. Fallbacks such aspixandcixexist. - A bare
xin an allow rule is the errorInvalid perms, 'x' must be preceded by exec qualifier 'i', 'p', or 'u'(parser_misc.c:1099).deny PATH x,is the one place wherexstands alone. - Named transition:
/usr/bin/demo-helper Px -> demo-helper,. WithCx -> workerthe 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).
Read more
for AppArmor developers for security researchers
In the code
- File rule:
frule: id_or_var file_perms opt_named_transition TOK_END_OF_RULE(parser_yacc.y:1072); the arrow isopt_named_transition(parser_yacc.y:1043); link rule:link_rule: TOK_LINK opt_subset_flag id_or_var TOK_ARROW id_or_var TOK_END_OF_RULE(parser_yacc.y:1141).
06 Qualifiers go in front, in a fixed order
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,givessyntax 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;useris another spelling ofowner(parser_misc.c:95-102). priority=Ntakes an integer from -1000 to 1000 (immunix.h:198-199); the default is 0.denywithoutauditrefuses without a log record;audit denyrefuses and logsapparmor="DENIED".- The man page's
QUALIFIERSline lists onlypriority,auditandallowordeny(apparmor.d.pod:200); the parser also acceptsprompt,ownerandotherin 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 rlimitrules take no qualifier.
Read more
for AppArmor developers for security researchers
In the code
- The order is one production:
opt_prefix: opt_priority opt_audit_flag opt_rule_mode opt_owner_flag(parser_yacc.y:705); priority isopt_priority(parser_yacc.y:677) and the block isblock: TOK_OPEN rules TOK_CLOSE(parser_yacc.y:738).
07 Everything else starts with a keyword
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);unmountis another spelling ofumount. - Shared condition syntax:
name=value,name=(a b),name in (a b)andpeer=( ... ). Examples from the example profile:unix (send, receive) type=stream peer=(label=demo-helper),andsignal (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:
dbusis enforced by the bus daemon, not the kernel;mqueuehas 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-enforcedprints, 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 RULESline omits ptrace and signal rules (apparmor.d.pod:174); the parser accepts both.
Read more
- apparmor.d(5): Capabilities, Network Rules, Mount Rules, Signal rules, all rule.
- Profiles quick reference on apparmor.net.
- capability, network, unix, dbus, mount, signal, ptrace, all, rule conditionals.
- The other classes: remount, umount, pivot_root, userns, io_uring, mqueue, change_profile, rlimit.
for AppArmor developers for security researchers
In the code
- The condition syntax is the
condrule (parser_yacc.y:1196), shared by every keyword class. Class numbers and the rule classes behind them are in rule classes in the parser.
08 Blocks inside a profile
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 { }, withnot,and,oranddefined(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 { ... }orhat admin { ... }(apparmor.d.pod:180). The program enters and leaves it withint aa_change_hat(const char *subprofile, unsigned long magic_token);(apparmor.h:79). - Names:
apparmor_parser -Non the example printeddemo,demo//adminanddemo//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, theprofile=field of a log record and/proc/PID/attr/current. -Nprints the hat and the child in the same form; the parser does not mark which is which in the name.
Read more
for AppArmor developers for security researchers
In the code
- Grammar:
cond_rule: TOK_IF expr block(parser_yacc.y:862),rules: rules hat(parser_yacc.y:827),rules: rules local_profile(parser_yacc.y:836). - Hats and children are serialized after their parent as separate profiles by
load_flattened_hats(parser_interface.c:783-786).
09 Six districts and three long decks
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:
rewriteandalias,unmountandumount,userandowner(parser_misc.c:96-112). - Commit read for this deck: AppArmor 836052d21 (6.0.0~alpha2).
Read more
- apparmor.d(5) and the Profiles quick reference.
- Entry decks: the preamble, profile name, file rules, allow and deny, capability, hats.
- The long decks: attachment, namespaces, stacking.
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.
| Line | Construct | Deck |
|---|---|---|
| 1 | comment | Comments |
| 2-6 | the preamble as a whole | The preamble |
| 2 | feature ABI | abi |
| 3 | include of a tunables file (it defines @{HOME}, used on lines 27 and 29) | include, Abstractions and tunables |
| 4 | variable with two values | Variables |
| 5 | boolean variable | Boolean variables |
| 6 | alias | alias |
| 7 | profile keyword and name | Profile name |
| 7 | attachment /usr/bin/demo | Attachment |
| 7 | xattrs=( ) | xattrs |
| 7 | + identities=( ) | Identities |
| 7 | flags=(complain, …) | Mode flags |
| 7 | attach_disconnected | Other flags |
| 8 | include of an abstraction | include, Abstractions and tunables |
| 9 | include if exists | include |
| 10 | capability | capability |
| 11 | network | network |
| 12 | unix; the conditions type= and peer=( ) | unix, Rule conditionals |
| 13 | dbus; conditions | dbus, Rule conditionals |
| 14 | mount; fstype=, options=( ) | mount, Rule conditionals |
| 15 | remount | remount |
| 16 | umount | umount |
| 17 | pivot_root | pivot_root |
| 18 | signal; set=( ), peer= | signal, Rule conditionals |
| 19 | ptrace | ptrace |
| 20 | mqueue | mqueue |
| 21 | userns | userns |
| 22 | io_uring | io_uring |
| 23 | change_profile | change_profile |
| 24 | rlimit | rlimit |
| 25 | file rule, r, ** | File rules, Access modes, Globbing |
| 26 | owner, use of a variable, {a,b}, rwk | owner, Variables, Globbing, Access modes |
| 27 | audit deny | audit, allow and deny |
| 28 | priority=10 allow | priority, allow and deny |
| 29 | prompt | prompt |
| 30 | link rule | Link rules |
| 31 | Px with -> profile | Exec modes, Named transitions |
| 32 | Cx to the child on line 36 | Exec modes, Named transitions, Child profiles |
| 33 | ix, [a-z]* | Exec modes, Globbing |
| 34 | qualifier block | Qualifier blocks, allow and deny |
| 35 | conditional testing the boolean of line 5 | Conditionals, Boolean variables |
| 36 | child profile containing all, | Child profiles, all |
| 37 | hat | Hats |
| 38 | closing brace | Comments (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.
| Deck | A line that uses it |
|---|---|
| network conditionals | network inet stream ip=127.0.0.1 port=8080, |
| other | other /srv/shared/** r, |
| safe and unsafe | safe 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
profilekeyword 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 { }orhat name { }, a sub-profile the program switches into itself. - Child profiles:
profile name { }inside a body, reached withcxtransitions. - 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,orPERMS PATH,, the optionalfilekeyword and barefile,. - Access modes: the permission letters
rwalkm. - Exec modes:
ixpxPxcxCxuxUxand the fallback forms such aspix. - Named transitions:
-> targetafter an exec permission. - safe and unsafe:
safeandunsafebefore exec rules andchange_profile. - Link rules:
link [subset] PATH -> TARGET,. - Globbing:
***?[abc][^a]{a,b}in any path or pattern.
Qualifiers (7)
- allow and deny:
allowanddenybefore a rule or block, and how a deny overrides an allow. - audit:
audit, log what a rule matches. - prompt:
promptin the place ofallowordeny; not acted on by mainline Linux 7.4. - owner:
owner(also spelleduser), 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 withoutCAP_. - network:
network [perms] [family] [type or protocol],. - network conditionals: the
ip=,port=,interface=andlabel=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 spelledunmount). - remount:
remount [conds] [mountpoint],. - pivot_root:
pivot_root [oldroot=PATH] [newroot] [-> profile],. - signal:
signal [perms] [set=( … )] [peer=LABEL],. - ptrace:
ptrace [perms] [peer=LABEL],withtrace,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/andtunables/. - Variables:
@{NAME}and the operators=+=?=:=. - Built-in variables:
@{profile_name},@{attach_path},@{exec_path}. - Boolean variables:
${NAME} = true|false. - Conditionals:
if,else if,elseblocks withnot,and,or,defined. - alias:
alias /from/ -> /to/,(also spelledrewrite). - abi:
abi <abi/5.0>,, the feature ABI the policy was written for.
The three long decks
- Attachment: the path in the head and how it picks the program.
- Namespaces: names of the form
:ns:name. - Stacking: targets of the form
a//&b.
Spellings that mean the same
Errors you meet first
| Message | When |
|---|---|
| "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
| Deck | Scanner | Grammar |
|---|---|---|
| syn-profile-name | 850 (PROFILE, defined 278); names in state SUB_ID 464-470 | profile 460-478, profile_base 391, opt_profile_flag 381-383 |
| syn-identities | 409-416, + at 826 | 631-670 |
| syn-flags-modes | 433-436 | 593-629; names parser/profile.cc:30-39; values parser/profile.h:212-258 |
| syn-flags-other | 433-436 | parser/profile.h:216-257; error at parser/profile.h:261 |
| syn-xattrs | 420-427 | opt_cond_list 1274-1275, cond_list 1268, used at 433-438 |
| attachment | part of ids | opt_id_or_var 388-389, check at 431-433 |
Profile structure
| Deck | Scanner | Grammar |
|---|---|---|
| syn-hats | ^ 820, hat 848 (HAT, defined 277) | hat 490-504, hat_start 1637-1638; in a body 827-834 |
| syn-child-profiles | 850 | local_profile 480-488; stored with add_hat 836-843 |
| syn-comments | 815-818; #include exception 796-803 | not a grammar construct |
| syn-quoting | 259-263, 295-296, processid | not a grammar construct |
File access
| Deck | Scanner | Grammar |
|---|---|---|
| syn-file-rules | file via keyword_table (parser/parser_misc.c:108); paths 838-841 | rule 1049-1050, file_rule 1103-1115, frule 1072-1101, file_rule_tail 1131-1139 |
| syn-access-modes | MODE_CHARS 257, token at 843-846 | file_perms 1640-1646, then parse_perms parser/parser_misc.c:736 and parse_sub_perms parser/parser_misc.c:560 |
| syn-exec-modes | 257 | parser/parser_misc.c:606-700 |
| syn-named-transitions | -> 822 (state SUB_ID_WS) | opt_named_transition 1043-1047, used 1072-1101 |
| syn-safe-unsafe | keyword_table parser/parser_misc.c:92-93 | opt_exec_mode 1065-1067; file rules 1117-1130; change_profile 1648 |
| syn-link-rules | link, subset via keyword_table (parser/parser_misc.c:94, 98) | link_rule 1141-1152; opt_subset_flag 672-675 |
| syn-globbing | part of ids | convert_aaregex_to_pcre parser/parser_regex.c:118-445 |
Qualifiers
The fixed order is opt_prefix (parser_yacc.y:705-711).
| Deck | Scanner | Grammar |
|---|---|---|
| syn-allow-deny | keyword_table parser/parser_misc.c:100-101 | opt_rule_mode 700-703 |
| syn-audit | parser/parser_misc.c:99 | opt_audit_flag 693-694 |
| syn-prompt | parser/parser_misc.c:102 | 703 |
| syn-owner, syn-other | parser/parser_misc.c:95-97 | opt_owner_flag 696-698 |
| syn-priority | 428-432; integer in INTEGER_MODE 697-705 | opt_priority 677-691; bounds parser/immunix.h:198-199 |
| syn-qualifier-blocks | { 834 | block 738-741; rules opt_prefix block 743-759 |
Rule classes
| Deck | Grammar | Permission and condition words |
|---|---|---|
| syn-capability | 1694-1716; added at 821-825 | names without CAP_; "Invalid capability %s." (1708) |
| syn-network, syn-network-inet | 1154-1194; rules action 761-783 | perms 1356-1408; conditions ip port interface label (parser/network.cc:450-468) |
| syn-unix | 1418-1432 | conditions type protocol label (parser/af_rule.cc:30-33), addr (parser/af_unix.cc:49) |
| syn-dbus | 1340-1354 | perms 1302-1330; conditions parser/dbus.cc:51-61 |
| syn-mount | 1277-1285 | conditions parser/mount.cc:418-442; flag names parser/mount.cc:247-266 |
| syn-umount | 1292-1295 | as mount |
| syn-remount | 1287-1290 | as mount |
| syn-pivot-root | 1297-1300 | condition oldroot (1824) |
| syn-signal | 1466-1470 | perms 1434-1456; conditions set, peer (parser/signal.cc:170-177) |
| syn-ptrace | 1509-1513 | perms 1472-1499; condition peer (parser/ptrace.cc:45) |
| syn-mqueue | 1586-1595 | perms 1541-1576; conditions label, type (parser/mqueue.cc:78-85) |
| syn-userns | 1535-1539 | create (1515-1525) |
| syn-io-uring | 1620-1627 | override_creds, sqpoll (1597-1610); condition label (parser/io_uring.cc:44) |
| syn-change-profile | 1648-1692; added at 804-819 | default target ** (1681) |
| syn-rlimit | 852-859 | names parser/parser_misc.c:146-168 |
| syn-all | 1629-1635; scanner 811-813 | expands to one bare rule of each class (parser/all_rule.cc:33) |
| syn-rule-conditionals | 1196-1275 | scanner 420-452, 490-560 |
Preamble and reuse
| Deck | Scanner | Grammar |
|---|---|---|
| syn-include | 781-809; file name 376-398; include_filename 162 | scanner only |
| syn-preamble | none of its own | preamble 506-509 |
| syn-abstractions-tunables | as include | not grammar; the files are under profiles/apparmor.d/abstractions/ and tunables/ |
| syn-variables | 714-717; values in ASSIGN_MODE 564-592; operators 303-307, 824-832 | varassign 524-548, assign_op 519-522 |
| syn-builtin-variables | as variables | not grammar; parser/parser.h:335-337, parser/parser_variable.c:137-177 |
| syn-boolean-variables | 707-722 | varassign 550-570 |
| syn-boolean-conditionals | EXPR_MODE 725-767 | cond_rule 862-900; expr, term, notfactor, factor 902-1035 |
| syn-alias | parser/parser_misc.c:105-106 | 511-517 |
| syn-abi | state ABI_MODE, 376-398 | abi_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_RLIMITand theTOK_RLIMIT_*tokens (parser_yacc.y:168-184) are declared and not used in any grammar rule.- The scanner state
IOURING_MODEis declared (parser_lex.l:355) and has rules (685-688), but the keyword switch has nocase TOK_IO_URING(parser_lex.l:860-906), so the state is not entered.override_credsandsqpollare recognised throughkeyword_tableinstead (parser/parser_misc.c:133-134). opt_subset_flagacceptsTOK_LE(parser_yacc.y:674), but the scanner returns it only inRLIMIT_MODEandEXPR_MODE(parser_lex.l:624, 763), solink <= A -> B,is a lexer error.
Where apparmor.d.pod and the code disagree
COMMA RULESomitsPTRACE RULEandSIGNAL RULE(parser/apparmor.d.pod:174); both areprefix_rulealternatives (parser_yacc.y:785-793).QUALIFIERSlistspriority,auditand an access type ofallowordeny(parser/apparmor.d.pod:198-200); the grammar also acceptsprompt,ownerandotherfor every rule class (parser_yacc.y:696-711).- The pod lists the unix conditionals
attrandopt(parser/apparmor.d.pod:375-377); neither string occurs in the parser sources. The supported ones aretype,protocol,label(parser/af_rule.cc:30-33) andaddr(parser/af_unix.cc:49). PROFILE FLAGS(parser/apparmor.d.pod:159-164) omitsnamespace_relative,delegate_deleted,no_attach_disconnected,chroot_attachandchroot_no_attach, whichflagvals::initaccepts (parser/profile.h:226-237).SUBPROFILEandHAT(parser/apparmor.d.pod:178-180) show no identities andHATno attachment; the grammar uses the sameprofile_basefor 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).PREAMBLEdoes not mention thatabiis also accepted inside a profile body (parser_yacc.y:722).
Roads from here
ATTACHMENT, NAMESPACES, STACKING
- Profile attachment — how the path in the head picks the program
- Policy namespaces — names that start with a colon
- Profile stacking — targets that contain an ampersand
FILE ACCESS
- File rules — path rules and their permissions
PREAMBLE AND REUSE
- The preamble — what comes before the first profile
PROFILE HEAD
- The profile name — the head of a profile starting with its name
QUALIFIERS
- allow and deny — the qualifiers in front of a rule
RULE CLASSES
- Capability rules — the first of the keyword rule classes
PROFILE STRUCTURE
- Hats — hats and child profiles and the lines between them