The profile name
profile keyword, paths for application developers for security researchers
The first words of a profile. The profile keyword and a name or a path used as the name. Which characters a name may hold and how the name becomes the label you see in logs and on processes.
On the map: profile head
▶ Watch this deck — 8 scenes, ~6 min
Worth seeing first
- The profile language at a glance — where the head sits in a whole profile
Part of journeys
- New to AppArmor, step 3 of 10 · previous: The profile language at a glance · next: Profile mode flags
01 Every profile needs a name
The name in the profile head is the profile's identifier. The kernel's code prints it with the mode, as in demo (enforce); a denial carries it as profile="demo"; rules such as Px -> demo use it as their target.
You open a log and it says profile="demo". Where does that word come from? From the first line of the profile. On the kernel, the name is what the kernel puts on a confined process, what a denial is filed under, and what another profile writes when it wants to send a program here. This deck is about that one word: how to write it, what it may contain, and what the kernel ends up calling the profile. The example is demo, the small service from the start of the map.
Details and sources
Details
- Syntax: the word after
profile, as inprofile demo /usr/bin/demo {. - Where the name shows up:
- the label of a confined task,
demo (enforce), read from/proc/PID/attr/currentor withaa_getcon(). The kernel prints the name followed by the mode (label.c:1563-1570); - the
profile="demo"field of an audit record (audit.c:128-129); - the listing in
/sys/kernel/security/apparmor/profilesand the output ofaa-status; - the target of rules in other profiles:
/usr/bin/demo Px -> demo,,change_profile -> demo,,signal peer=demo,. apparmor_parser -N FILE(--names) prints the names a file defines without loading anything.- The profile
demoand its program are invented for the map. The kernel statements are read from the kernel source, not observed on a running kernel.
02 The name comes first
profile NAME [ATTACHMENT] [xattrs=( )] [+ identities=( )] [flags=( )] {. The order is fixed and only one attachment is accepted. Out of order, the tree's parser answers syntax error, unexpected TOK_ID, expecting TOK_OPEN.
A profile head is one sequence, always in the same order. The keyword profile, then the name, then up to four optional parts: the attachment path, an xattrs condition, identities and flags. Then the brace. Only the name has to be there. Here is demo with a name, a path and flags, each in its place. Put the parts in another order, flags before the path, and you get a plain syntax error, because the parser knows exactly one order. The rest of this district takes the optional parts one deck at a time.
Details and sources
Details
- Grammar of the head:
[ profile | hat | ^ ] NAME [ ATTACHMENT ] [ xattrs=( ... ) ] { + identities=( ... ) } [ flags=( ... ) ] {. OnlyNAMEis required; at most oneATTACHMENT. - Out of order, for example flags before the path, the parser built from the AppArmor tree at 836052d21 answers
syntax error, unexpected TOK_ID, expecting TOK_OPEN(-Q -K --skip-kernel-load, nothing loaded into a kernel). - The full form of a parser error is
AppArmor parser error for FILE in profile FILE at line N: MESSAGE. - The same head is used for top-level profiles, child profiles and hats.
- A head with a name, a path and flags in the parser's tests:
profile exist /does/not/exist {(profile_basic_named_ok1.sd),/does/not/exist flags=(complain) {(flags_ok.sd).
Read more
for AppArmor developers for security researchers
In the code
- The head is one production,
profile_base: TOK_ID opt_id_or_var opt_cond_list identities flags TOK_OPEN(parser_yacc.y:391-399); the keyword slot isopt_profile_flag(parser_yacc.y:381-383) and the two meet inprofile(parser_yacc.y:460).
03 Two spellings: a word or a path
profile demo /usr/bin/demo { is named demo. /usr/bin/demo { is named /usr/bin/demo and attaches to the same path. --warn=deprecated prints "The use of file paths as profile names is deprecated. See man apparmor.d for more information" for any top-level name that starts with /.
Two ways to write the start. With the keyword, the name is a word of your choice, and the path after it says which program the profile is for. Without the keyword, the first thing on the line has to be a path, and that path is both the name and the attachment. Older profiles are written that way. It still works, but the long path then shows up in every log line and every rule that mentions the profile, and the parser calls it deprecated. You only see that warning if you ask for it. And you get it just the same with the keyword and a path as the name.
Details and sources
Details
profile demo /usr/bin/demo {: namedemo, attachment/usr/bin/demo./usr/bin/demo {: name/usr/bin/demo, and the same string is the attachment.- When no attachment is written and the name starts with
/, the parser copies the name into the attachment (parser_variable.c:67-77). - Without the keyword the name must start with
/or carry a namespace (:ns:name { }). - Warning, verbatim:
The use of file paths as profile names is deprecated. See man apparmor.d for more information. It is raised for any top-level name that starts with/, with or without the keyword. - The warning belongs to the class
deprecated(parser_main.c:284), which is not among the default warnings (parser.h:77-78). Turn it on withapparmor_parser --warn=deprecatedor--warn=all. - Both spellings in the parser's tests:
/does/not/exist flags=(complain) {(flags_ok.sd:7) andprofile exist /does/not/exist {(profile_basic_named_ok1.sd:8). - Known discrepancy: a nested profile named with a path does not get the warning.
Read more
- apparmor.d(5): Name.
- apparmor.net: Profiles basics, attached profiles.
- Attachment: how the path picks the program.
for AppArmor developers for security researchers
In the code
- The warning and the test for a missing keyword are in the
profileaction (parser_yacc.y:469-473).
04 One word, or one quoted string
A name is one unquoted word (no blank, tab, ", ! or ,) or one double-quoted string. :ns:name selects a namespace. Without an attachment the name is compiled as a pattern, so {, [, * and ? act as in a path.
What can the name be? One word. Letters, digits, dashes, dots, slashes, nearly anything except a space, a double quote, an exclamation mark or a comma. If you want a space, put the whole name in double quotes; the quotes themselves are dropped. A name that starts with a colon, a word and another colon puts the profile in a namespace, which has its own deck. And one trap: when there is no attachment, the parser also reads the name as a pattern, so a lone curly brace in it is an error.
Details and sources
Details
- Unquoted word: any byte except blank, tab, carriage return, new line,
",!and,; a,is allowed when a word character follows it. Escapes: backslash blank, backslash tab,\",\!,\,. - Quoted string: any byte except NUL and
", with\"for a quote. The quotes are stripped and are not part of the name (parser_misc.c:509-535).profile "demo service" /usr/bin/demo { }is listed byapparmor_parser -Nasdemo service. :ns:nameputs the profile in namespacens.- A name that starts with
&is rejected:Profile names must begin with a '/' or a namespace. - With no attachment the name is also compiled as the attachment pattern (parser_regex.c:478-506).
profile demo{v2 { }fails withRegex grouping error: Unclosed grouping or character class, expecting close }andInvalid profile name 'NAME' - bad regular expression;profile demo{v2 /usr/bin/demo { }is accepted. Seen with the parser built from the AppArmor tree at 836052d21. - Variables in a name are expanded; an undeclared one gives
Failed to find declaration for: @{x}(seen with the installed parser 5.0.2). - Which characters the kernel refuses in a name was not determined.
Read more
for AppArmor developers for security researchers
In the code
- Character classes:
ID_CHARS,ID,IDS(parser_lex.l:262-267) andQUOTED_ID(parser_lex.l:287-288); the name token after the keyword is({IDS}|{QUOTED_ID})in stateSUB_ID(parser_lex.l:456-461). parse_label()separates the namespace and reports a leading&(parser_misc.c:843-958).
05 From the name to the label
A nested profile is loaded as parent//name: demo//worker, demo//admin. apparmor_parser -N prints the full names in alphabetical order. A namespace is printed in front as :ns://name. The kernel side is read from the kernel code, not run.
The name you write is not always the whole name. Put a profile inside demo, call it worker, and the parser loads it as demo//worker. A hat called admin becomes demo//admin in the same way. You can ask the parser for the list with -N. The kernel is handed three separate profiles, and its code rebuilds the family from those names, cutting each one at the double slash to find the parent. The long form is the label a process in the child carries. The two kinds of nested profile, hats and children, have their own decks.
Details and sources
Details
- A nested profile is loaded under its full name, parent and child joined by
//.apparmor_parser -Non the parser built from the AppArmor tree at 836052d21 lists: profile worker { }insidedemoasdemo//worker;^admin { }insidedemoasdemo//admin;profile /usr/lib/demo/helper { }insidedemoasdemo///usr/lib/demo/helper;profile :ops:demo /usr/bin/demo { }as:ops://demo.- The listing is in alphabetical order, not source order.
- The parser builds the name in
hname()(parent's name,//, own name) andfqname()(:ns://in front) (profile.h:454-476), and writes it as the first string of each profile in the binary policy (parser_interface.c:487-493). - The kernel, read from the code and not run: the unpacker reads that string and splits a leading namespace off it (policy_unpack.c:1138-1165); the parent of a nested profile is found by cutting the name at each
//(policy.c:523-539). - A task in the child reads
demo//worker (enforce)from/proc/PID/attr/current; the name and mode are printed at label.c:1563-1570.
06 How the parser reads the name for AppArmor developers for security researchers
profile → state SUB_ID → TOK_ID → profile_base → parse_label() → Profile::hname() → first string of the profile struct → unpack_profile() in the kernel.
For the people who work on the parser. The keyword profile, with any white space after it, pushes the scanner into a state called SUB_ID. In that state the very next word or quoted string becomes the name token, whatever it looks like. The grammar's profile_base rule takes that token and hands it to parse_label, which separates a namespace from the name. Nested profiles get their full name from hname. The serializer writes the name as the first string of the profile structure, and the unpack code of the kernel splits the namespace off again and looks up the parent at the double slash.
Details and sources
for AppArmor developers for security researchers
Details
- Lexer:
PROFILEisprofile{WS}*(parser_lex.l:294); it returnsTOK_PROFILEand pushes the stateSUB_ID(parser_lex.l:850). - In
SUB_IDthe next({IDS}|{QUOTED_ID})is returned asTOK_IDafterprocessid(), and the state is popped (parser_lex.l:456-461). Nothing looks at what the word is, which is whyprofile flags=(complain) {yields a name. - Grammar:
profile_basetakes theTOK_IDand callsparse_label(&self_stack, &prof->ns, &prof->name, $1, true); theprofileproduction adds the keyword checks (parser_yacc.y:391-478). bool parse_label(bool *_stack, char **_ns, char **_name, const char *label, bool yyerr)and its helper split:ns:nameand:ns://name(parser_misc.c:843-958).- Variables in the name are expanded, and a path name is copied into the attachment, in
process_variables_in_name()(parser_variable.c:58-78). Profile::hname(),fqname()andget_name()build the full name (profile.h:454-476).- Serialization:
sd_write_struct(buf, "profile"), then the name as an unnamed string; a nested profile getsget_name(false)(parser_interface.c:487-493). - The kernel:
unpack_profile()reads the string, callsaa_splitn_fqname()and allocates the profile (policy_unpack.c:1138-1165);__lookup_parent()walks the//separators (policy.c:523-539).
07 Four ways to get the first words wrong
demo { fails with "Profile names must begin with a '/', namespace or keyword 'profile' or 'hat'." A second path is a syntax error. profile flags=(complain) { is accepted by the parser as it is today and defines a profile named flags=(complain), a known discrepancy: check names with apparmor_parser -N.
Four slips you will make sooner or later. Forget the keyword on a name that is not a path, and the parser tells you names must begin with a slash, a namespace, or the keyword. Give two paths and you get a syntax error, because a head takes one attachment. Start an attachment without a slash and it says so. The fourth is the quiet one: write profile, forget the name, and go straight to flags. The parser takes the next word as the name. Today that gives you a profile called flags=(complain), in enforce mode, and no message at all. -N shows the names it read.
Details and sources
Details
Messages are verbatim; "tree" means seen with the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load).
demo { }:Profile names must begin with a '/', namespace or keyword 'profile' or 'hat'.It is reported at the line of the closing brace (tree).- A second path, as in
profile demo /usr/bin/demo /usr/bin/demo2 {:syntax error, unexpected TOK_ID, expecting TOK_OPEN(tree). profile demo usr {:Profile attachment must begin with a '/' or variable.(tree).profile flags=(complain) { }is accepted and defines a profile namedflags=(complain)in enforce mode, with no message (tree). So isprofile profile { }. Whether this is intended is not settled; it is a known discrepancy.apparmor_parser -N FILElists the names that were read.- Two more from the same family: a new line between
profileand the name givesLexer found unexpected character: '\n' (0xa) in state: SUB_ID(tree), anda { }givessyntax error, unexpected TOK_MODE, because a single letter is read as a file permission (seen with the installed parser 5.0.2).
for AppArmor developers for security researchers
In the code
- The three messages: parser_yacc.y:472-473 (missing keyword), parser_yacc.y:431-433 (attachment), parser_yacc.y:410-412 (leading
&). - After the keyword the scanner returns the next word as the name without looking at it (parser_lex.l:456-461).
08 Where to go from the name
Next in the head: attachment, syn-xattrs, syn-identities, syn-flags-modes. Nested names: syn-child-profiles, syn-hats. Names with a colon: namespaces.
That is the name. From here the head continues: the attachment deck explains how the path picks the program, and the next decks in this district cover xattrs, identities and the flags. If you want to know more about names with two slashes, go to child profiles or hats; names with a colon are namespaces. Quoting has its own deck, the scanner deck shows the machinery behind the name token, and the syntax map puts the whole profile back on one page.
Details and sources
Details
- The name is the one required part of the head:
profile NAME [ATTACHMENT] [xattrs=( )] [+ identities=( )] [flags=( )] {. - A word of your choice with the keyword, or a path without it; one unquoted word or one quoted string.
- Loaded names:
parent//childfor nested profiles,:ns:namein a namespace.apparmor_parser -Nshows them. - Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825). Parser results come from running the parser without loading; kernel statements are read from the source.
Read more
Read more
Rows marked "tree" were run with the parser built from the AppArmor tree at the commit above (-Q -K --skip-kernel-load, the tree's abi/5.0 features). Rows marked "5.0.2" were run with the installed parser 5.0.2. Kernel behaviour was read from the kernel's code and not run on a kernel.
Grammar
[ profile | hat | ^ ] NAME [ ATTACHMENT ] [ xattrs=( ... ) ] { + identities=( ... ) } [ flags=( ... ) ] { rules }
- The order is fixed.
NAMEis the only required part. At most oneATTACHMENTis accepted. - The keyword
profilemay be left out only whenNAMEstarts with/or carries a namespace::ns:a { }is accepted without the keyword (5.0.2). - After the keyword
profilethe next word or quoted string is always the name. hat NAMEand^NAMEat top level use the same head; see syn-hats.- The parts after the name have their own decks: attachment, syn-xattrs, syn-identities, syn-flags-modes.
Keywords and tokens
| Spelling | Where | Meaning |
|---|---|---|
profile | start of a head, top level or nested | the next word is the name; the name may be any word |
hat, ^ | start of a head | a hat; same head, see syn-hats |
:ns: | prefix of the name | the profile belongs to namespace ns; see namespaces |
// | inside a loaded name | separates parent and child; written by the parser for nested profiles |
& | first character of the name | rejected in a profile head |
Characters in a name
| Form | Allowed |
|---|---|
| unquoted word | any byte except blank, tab, carriage return, new line, ", ! and ,; a , is allowed when a word character follows it |
| escapes in an unquoted word | backslash blank, backslash tab, \", \!, \, |
| quoted string | any byte except NUL and "; \" for a quote. The quotes are not part of the name |
| first character without the keyword | /, @ (a variable), : or &; of these & is then rejected |
- Pattern characters
{,[,*and?are compiled as a pattern when the name is used as the attachment, which is the case when no attachment is written.profile demo{v2 { }fails;profile demo{v2 /usr/bin/demo { }is accepted (tree). - Variables in a name are expanded. An undeclared one gives
Failed to find declaration for: @{x}(5.0.2). - Which characters the kernel refuses in a name was not determined.
Name, attachment, full name
Output of apparmor_parser -N (tree). The listing is in alphabetical order, not source order.
| Head | Name listed |
|---|---|
profile demo /usr/bin/demo { } | demo |
/usr/bin/demo { } | /usr/bin/demo (also the attachment) |
profile /usr/bin/demo { } | /usr/bin/demo (also the attachment) |
profile "demo service" /usr/bin/demo { } | demo service |
profile :ops:demo /usr/bin/demo { } | :ops://demo |
profile worker { } inside demo | demo//worker |
^admin { } inside demo | demo//admin |
profile /usr/lib/demo/helper { } inside demo | demo///usr/lib/demo/helper |
- Mainline Linux 7.4's code prints a label as the name followed by the mode, as in
demo (enforce), splits a leading:ns:off the loaded name and finds the parent of a nested profile at the//.
Errors and warnings
Errors are printed as AppArmor parser error for FILE in profile FILE at line N: MESSAGE (tree).
| Message | When | Basis |
|---|---|---|
Profile names must begin with a '/', namespace or keyword 'profile' or 'hat'. | no keyword, the name is not a path and has no namespace; reported at the line of the closing brace | tree |
Profile names must begin with a '/' or a namespace | the name starts with & | code |
Profile attachment must begin with a '/' or variable. | the attachment is another kind of word, as in profile demo usr { | tree |
syntax error, unexpected TOK_ID, expecting TOK_OPEN | a second attachment, head parts out of order, or profile demo usr/bin/demo { | tree |
Invalid profile name 'NAME' - bad regular expression | a pattern error in a name used as the attachment; preceded by Regex grouping error: Unclosed grouping or character class, expecting close } | tree |
Namespace not terminated: NAME | :ns without the closing colon | code |
Empty namespace: NAME | nothing between the two colons | code |
Empty named transition profile name: NAME | nothing after the namespace; also printed for profile "" { } | code; tree for the empty name |
Failed to find declaration for: @{x} | an undeclared variable in the name | 5.0.2 |
Lexer found unexpected character: '\n' (0xa) in state: SUB_ID | a new line between profile and the name | tree |
syntax error, unexpected TOK_MODE | no keyword and a single-letter name such as a { }, read as a file permission | 5.0.2 |
| Warning | When | Class |
|---|---|---|
The use of file paths as profile names is deprecated. See man apparmor.d for more information | a top-level name starts with /, with or without the keyword | deprecated (--warn=deprecated), off by default |
FILE: -n NS overriding policy specified namespace :NS: | --namespace-string replaces the namespace written in the file | code |
Known discrepancies
profile flags=(complain) { }andprofile profile { }are accepted and name the profileflags=(complain)andprofile. After the keyword the next word is taken as the name without looking at it. The first loads in enforce mode. Whether this is intended is not settled. Check names withapparmor_parser -N.- The deprecation warning for path names is raised for top-level profiles only. A nested profile named with a path does not get it.
for AppArmor developers for security researchers
Code map
| What | Where |
|---|---|
profile{WS}* pattern, push to state SUB_ID | parser/parser_lex.l:294, parser/parser_lex.l:850 |
name token in SUB_ID | parser/parser_lex.l:456-461 |
names without the keyword (LABEL, QUOTED_LABEL) | parser/parser_lex.l:301-302, parser/parser_lex.l:838-841 |
opt_profile_flag, profile_base, profile | parser/parser_yacc.y:381-383, parser/parser_yacc.y:391-478 |
local_profile, hat | parser/parser_yacc.y:480-504 |
processid() (quotes and escapes), parse_label() | parser/parser_misc.c:509-535, parser/parser_misc.c:843-958 |
| name copied into the attachment, variables in the name | parser/parser_variable.c:58-78 |
| name compiled as a pattern | parser/parser_regex.c:478-624 |
Profile::hname(), fqname(), get_name() | parser/profile.h:454-476 |
name written as the first string of the profile struct | parser/parser_interface.c:487-493 |
| kernel: namespace split and allocation | linux:security/apparmor/policy_unpack.c:1138-1165 |
kernel: parent lookup at // | linux:security/apparmor/policy.c:523-539 |
kernel: name (mode) | linux:security/apparmor/label.c:1564 |
Roads from here
START HERE
- The profile language at a glance — back to the whole profile on one page
ATTACHMENT, NAMESPACES, STACKING
- Profile attachment — how the path after the name picks the program
- Policy namespaces — names that start with a colon
PROFILE HEAD
- Extended attribute conditions — the next part of the head
- Profile mode flags — the flags at the end of the head
PROFILE STRUCTURE
- Child profiles — names with two slashes in them
- Hats — the caret and hat spellings of a nested name
- Quoting and escaping — names with spaces and the escapes a name may use
INSIDE THE PARSER
- The lexer — how the scanner finds the name