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

Part of journeys

01 Every profile needs a name

THE PROFILE NAME profile demo /usr/bin/demo { on a process demo $ cat /proc/1234/attr/current demo (enforce) in a denial apparmor="DENIED" ... profile="demo" in a rule another profile /usr/bin/demo Px -> demo, one name, used everywhere what it looks like; not a captured session the example in this deck: demo, the small service from the start of the map
The head of the demo profile with the name demo highlighted, and the three places the name shows up: the label of a process, a denial in the log and a rule in another profile.

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 in profile demo /usr/bin/demo {.
  • Where the name shows up:
  • the label of a confined task, demo (enforce), read from /proc/PID/attr/current or with aa_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/profiles and the output of aa-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 demo and 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

GRAMMAR profile NAME ATTACHMENT xattrs=( ) + identities=( ) flags=( ) { profile: may be left out if NAME starts with / NAME: one word, or one "quoted string"; the only part you must write profile demo /usr/bin/demo flags=(complain) { NAME ATTACHMENT flags profile demo flags=(complain) /usr/bin/demo { syntax error, unexpected TOK_ID, expecting TOK_OPEN the parser knows one order attachment syn-xattrs syn-identities syn-flags-modes each optional part has a deck of its own, named under its box
Syntax diagram of the profile head: the keyword profile, the name, four optional parts and the opening brace, then a head in the right order and one in the wrong order with its syntax error.

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=( ... ) ] {. Only NAME is required; at most one ATTACHMENT.
  • 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).

for AppArmor developers for security researchers

In the code

03 Two spellings: a word or a path

TWO SPELLINGS profile demo /usr/bin/demo { namedemo attaches to/usr/bin/demo /usr/bin/demo { name/usr/bin/demo attaches to/usr/bin/demo copied from the name $ apparmor_parser -N FILE demo /usr/bin/demo in every log line and rule $ apparmor_parser --warn=deprecated FILE The use of file paths as profile names is deprecated. See man apparmor.d ... profile /usr/bin/demo { gets the same warning: it looks at the name, not at the keyword
Two profile heads side by side: with the keyword the name is demo, without it the name is the path; the parser's name listing for each and the deprecation warning for a path used as the name.

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 {: name demo, 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 with apparmor_parser --warn=deprecated or --warn=all.
  • Both spellings in the parser's tests: /does/not/exist flags=(complain) { (flags_ok.sd:7) and profile exist /does/not/exist { (profile_basic_named_ok1.sd:8).
  • Known discrepancy: a nested profile named with a path does not get the warning.

for AppArmor developers for security researchers

In the code

04 One word, or one quoted string

CHARACTERS IN A NAME profile demo-service_2 /usr/bin/demo { demo-service_2 no spaces, no " ! , profile "demo service" /usr/bin/demo { demo service the quotes are not part of the name profile :ops:demo /usr/bin/demo { :ops://demo a leading :name: is a namespace profile demo{v2 { no attachment on this line Invalid profile name 'demo{v2' - bad regular expression without an attachment the name is also the pattern, so { [ * ? keep their meaning
Four profile heads and the name each one gives: a plain word, a quoted name with a space, a name in a namespace, and a name with an unclosed curly brace that the parser rejects.

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 by apparmor_parser -N as demo service.
  • :ns:name puts the profile in namespace ns.
  • 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 with Regex grouping error: Unclosed grouping or character class, expecting close } and Invalid 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.

for AppArmor developers for security researchers

In the code

05 From the name to the label

THE FULL NAME what you write profile demo /usr/bin/demo { profile worker { ... } ^admin { ... } } what the parser loads $ apparmor_parser -N demo demo demo//admin demo//worker parent // child the kernel's code demo admin worker rebuilt from the names demo//worker (enforce) the label of a process in the child
A demo profile with a child profile worker and a hat admin, the parser's listing of three full names joined with two slashes, and the kernel rebuilding the parent and its two children from those names.

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 -N on the parser built from the AppArmor tree at 836052d21 lists:
  • profile worker { } inside demo as demo//worker;
  • ^admin { } inside demo as demo//admin;
  • profile /usr/lib/demo/helper { } inside demo as demo///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) and fqname() (: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

PARSER AND KERNEL profile :ops:demo /usr/bin/demo { scanner profile{WS}* -> SUB_ID next {IDS}|{QUOTED_ID} = TOK_ID parser_lex.l:850, 456-461 grammar profile: opt_profile_flag profile_base parser_yacc.y:460, 391 parse_label() ns = ops name = demo parser_misc.c:843-958 Profile::hname() parent//child :ns://name profile.h:454-469 sd_serialize_profile() first string of struct "profile" parser_interface.c:487-493 unpack_profile() splits :ns: off, allocates under the rest of the name policy_unpack.c:1138-1165 policy.c:523-539 finds the parent at //
A profile head travelling through the scanner, the grammar, parse_label, Profile hname, the serializer and the kernel's unpack_profile, with what each stage does to the name.

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: PROFILE is profile{WS}* (parser_lex.l:294); it returns TOK_PROFILE and pushes the state SUB_ID (parser_lex.l:850).
  • In SUB_ID the next ({IDS}|{QUOTED_ID}) is returned as TOK_ID after processid(), and the state is popped (parser_lex.l:456-461). Nothing looks at what the word is, which is why profile flags=(complain) { yields a name.
  • Grammar: profile_base takes the TOK_ID and calls parse_label(&self_stack, &prof->ns, &prof->name, $1, true); the profile production 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:name and :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() and get_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 gets get_name(false) (parser_interface.c:487-493).
  • The kernel: unpack_profile() reads the string, calls aa_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

COMMON MISTAKES demo { Profile names must begin with a '/', namespace or keyword 'profile' or 'hat'. profile demo /usr/bin/demo /usr/sbin/demo { syntax error, unexpected TOK_ID, expecting TOK_OPEN one attachment only profile demo usr { Profile attachment must begin with a '/' or variable. profile flags=(complain) { no error, no warning $ apparmor_parser -N FILE flags=(complain) after the keyword the next word is the name, whatever it is: the profile loads in enforce mode under that name
Four mistaken profile heads and the parser's answer to each: a missing keyword, two attachments, an attachment that is not a path, and a missing name, which is accepted and names the profile after the flags.

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 named flags=(complain) in enforce mode, with no message (tree). So is profile profile { }. Whether this is intended is not settled; it is a known discrepancy.
  • apparmor_parser -N FILE lists the names that were read.
  • Two more from the same family: a new line between profile and the name gives Lexer found unexpected character: '\n' (0xa) in state: SUB_ID (tree), and a { } gives syntax 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

08 Where to go from the name

ROADS profile demo /usr/bin/demo xattrs=( ) + identities=( ) flags=( ) { attachment how the path picks the program syn-xattrs syn-identities syn-flags-modes syn-child-profiles syn-hats demo//worker demo//admin namespaces :ops://demo syn-quoting names with spaces fe-lexer how the scanner finds the name syntax-map the whole profile
The full head of the demo profile with roads from each part: the attachment, xattrs, identities and flags decks, the decks on nested names and namespaces, and quoting, the scanner and the syntax map.

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//child for nested profiles, :ns:name in a namespace. apparmor_parser -N shows 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

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. NAME is the only required part. At most one ATTACHMENT is accepted.
  • The keyword profile may be left out only when NAME starts with / or carries a namespace: :ns:a { } is accepted without the keyword (5.0.2).
  • After the keyword profile the next word or quoted string is always the name.
  • hat NAME and ^NAME at 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

SpellingWhereMeaning
profilestart of a head, top level or nestedthe next word is the name; the name may be any word
hat, ^start of a heada hat; same head, see syn-hats
:ns:prefix of the namethe profile belongs to namespace ns; see namespaces
//inside a loaded nameseparates parent and child; written by the parser for nested profiles
&first character of the namerejected in a profile head

Characters in a name

FormAllowed
unquoted wordany byte except blank, tab, carriage return, new line, ", ! and ,; a , is allowed when a word character follows it
escapes in an unquoted wordbackslash blank, backslash tab, \", \!, \,
quoted stringany 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.

HeadName 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 demodemo//worker
^admin { } inside demodemo//admin
profile /usr/lib/demo/helper { } inside demodemo///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).

MessageWhenBasis
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 bracetree
Profile names must begin with a '/' or a namespacethe 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_OPENa second attachment, head parts out of order, or profile demo usr/bin/demo {tree
Invalid profile name 'NAME' - bad regular expressiona 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 coloncode
Empty namespace: NAMEnothing between the two colonscode
Empty named transition profile name: NAMEnothing after the namespace; also printed for profile "" { }code; tree for the empty name
Failed to find declaration for: @{x}an undeclared variable in the name5.0.2
Lexer found unexpected character: '\n' (0xa) in state: SUB_IDa new line between profile and the nametree
syntax error, unexpected TOK_MODEno keyword and a single-letter name such as a { }, read as a file permission5.0.2
WarningWhenClass
The use of file paths as profile names is deprecated. See man apparmor.d for more informationa top-level name starts with /, with or without the keyworddeprecated (--warn=deprecated), off by default
FILE: -n NS overriding policy specified namespace :NS:--namespace-string replaces the namespace written in the filecode

Known discrepancies

  • profile flags=(complain) { } and profile profile { } are accepted and name the profile flags=(complain) and profile. 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 with apparmor_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

WhatWhere
profile{WS}* pattern, push to state SUB_IDparser/parser_lex.l:294, parser/parser_lex.l:850
name token in SUB_IDparser/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, profileparser/parser_yacc.y:381-383, parser/parser_yacc.y:391-478
local_profile, hatparser/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 nameparser/parser_variable.c:58-78
name compiled as a patternparser/parser_regex.c:478-624
Profile::hname(), fqname(), get_name()parser/profile.h:454-476
name written as the first string of the profile structparser/parser_interface.c:487-493
kernel: namespace split and allocationlinux: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

ATTACHMENT, NAMESPACES, STACKING

PROFILE HEAD

PROFILE STRUCTURE

INSIDE THE PARSER