apparmor.d/docs/development/guidelines.md

title
Guidelines

Common structure

AppArmor profiles can be written without any specific guidelines. However, when you work with over 1400 profiles, you need a common structure among all the profiles.

The logic behind it is that if a rule is present in a profile, it should only be in one place, making profile review easier.

For example, if a program needs to run executables binary. The rules allowing it can only be in a specific rule block (just after the @{exec_path} mr, rule). It is therefore easy to ensure some profile features such as:

• A profile has access to a given resource
• A profile enforces a strict write xor execute (W^X) policy.

It also improves compatibilities and makes personalization easier thanks to the use of more variables.

Guidelines

!!! note

This profile guideline is still evolving, feel free to propose improvements
as long as they do not vary too much from the existing rules.

In order to ensure a common structure across the profiles, all new profile must follow the guidelines presented here.

The rules in the profile should be sorted in the rule block as follows:

Order	Name	Example
1	include	:octicons-link-external-24:
2	set rlimit	:octicons-link-external-24:
3	capability	:octicons-link-external-24:
4	network	:octicons-link-external-24:
5	mount	:octicons-link-external-24:
6	remount	:octicons-link-external-24:
7	umount	:octicons-link-external-24:
8	pivot_root	:octicons-link-external-24:
9	change_profile	:octicons-link-external-24:
10	mqueue	:octicons-link-external-24:
11	signal	:octicons-link-external-24:
12	ptrace	:octicons-link-external-24:
13	unix	:octicons-link-external-24:
14	userns	:octicons-link-external-24:
15	io_uring	:octicons-link-external-24:
16	dbus	:octicons-link-external-24:
17	file	:octicons-link-external-24:
18	local include	:octicons-link-external-24:

This rule order is taken from AppArmor with minor changes as we tend to:

• Divide the file block in multiple subcategories
• Put the block with the longer rules (files, dbus) after the other blocks

The file block

The file block should be sorted as follow:

Order	Description	Example	Link
1	The entry point of the profile	@{exec_path} mr,	:octicons-link-external-24:
2	The binaries and library required	@{bin}/, @{lib}/, /opt/. It is the only place where you can have mr, rix, rPx, rUx, rPUX rules.	:octicons-link-external-24:
3	The shared resources	/usr/share	:octicons-link-external-24:
4	The system configuration	/etc	:octicons-link-external-24:
5	The system data	/, /var, /boot	:octicons-link-external-24:
6	The user data	owner @{HOME}/	:octicons-link-external-24:
7	The user configuration, cache and dotfiles	@{user_cache_dirs}, @{user_config_dirs}, @{user_share_dirs}	:octicons-link-external-24:
8	Temporary and runtime data	/tmp/, @{run}/, /dev/shm/	:octicons-link-external-24:
9	Sys files	@{sys}/	:octicons-link-external-24:
10	Proc files	@{PROC}/	:octicons-link-external-24:
11	Dev files	/dev/	:octicons-link-external-24:
12	Deny rules	deny	:octicons-link-external-24:

The dbus block

The dbus block should be sorted as follow:

• The system bus should be sorted before the session bus
• The bind rules should be sorted after the send & receive rules

For DBus, try to determine peer's label when possible. E.g.:

dbus send bus=session path=/org/freedesktop/DBus
     interface=org.freedesktop.DBus
     member={RequestName,ReleaseName}
     peer=(name=org.freedesktop.DBus, label=dbus-daemon),

If there is no predictable label it can be omitted.

Profile rules

bin, sbin & lib

• Do not use: /usr/lib or /usr/bin but @{bin}/ or @{lib}/
• Do not use: /usr/sbin or /sbin but @{bin}/.

Variables

Always use the apparmor variables.

Sort

In a rule block, the rules must be alphabetically sorted.

Sub profile

Sub profile should comes at the end of a profile.

Similar purpose

When some rules share similar purpose, they may be sorted together. Eg:

/etc/machine-id r,
/var/lib/dbus/machine-id r,

Additional recommended documentation

• The AppArmor Core Policy Reference
• The AppArmor.d man page
• F**k AppArmor
• A Brief Tour of Linux Security Modules