doc: improve documentation.

docs/configuration.md

@@ -49,7 +49,14 @@ The profiles heavily use the (largely extended) XDG directory variables defined
     | Vm | `@{XDG_VM_DIR}` | `.vm`
     | Wallpapers | `@{XDG_WALLPAPERS_DIR}` | `@{XDG_PICTURES_DIR}/Wallpapers` |
 
-You can personalize these values by creating a file such as: `/etc/apparmor.d/tunables/xdg-user-dirs.d/local` where you define your own personal directories. Example:
+You can personalize these values.
+
+First create the directory `/etc/apparmor.d/tunables/xdg-user-dirs.d/apparmor.d.d`:
+```
+sudo mkdir /etc/apparmor.d/tunables/xdg-user-dirs.d/apparmor.d.d
+```
+Then create a `local` addition file in it where you define your own personal
+directories. Example:
 ```sh
 @{XDG_VIDEOS_DIR}+="Films"
 @{XDG_MUSIC_DIR}+="Musique"

docs/development/abstractions.md

@@ -114,7 +114,7 @@ Minimal set of rules for all electron based UI application. It works as a *funct
 
 !!! note ""
 
-    [apparmor.d/profile-s-z/spotify](https://github.com/roddhjav/apparmor.d/blob/e979fe05b06f525e5a65c767b4eabe5600147355/apparmor.d/profile-s-z/spotify#L10-L13)
+    [apparmor.d/profile-s-z/spotify](https://github.com/roddhjav/apparmor.d/blob/7d1380530aa56f31589ccc6a360a8144f3601731/apparmor.d/profiles-s-z/spotify#L10-L13)
     ``` sh linenums="10"
     @{name} = spotify
     @{lib_dirs} = /opt/@{name}

docs/development/dbus.md

@@ -2,7 +2,13 @@
 title: Dbus
 ---
 
-All dbus rules are labelled under the name of the given profiles that provide dbus data. If the profiles were going to change (a renaming, an architectural change), the dbus rules need to be updated accordingly.
+All dbus rules are labelled under the name of the given profiles that provide dbus data. It is one of the value added by this project, as we have profile for *everything*, we can restrict the bus further by limitint connection to a given peer label (the profile name). In case of a renaming of a profile, all dbus rules related it this profile need to be updated accordingly.
+
+## Profiles
+
+Regardless of the Dbus implementation used (`dbus-daemon` or `dbus-broker`), all dbus daemons are handled under the same set of profiles: [`dbus-system`](https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/bus/dbus-system), [`dbus-session`](https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/bus/dbus-session), and [`dbus-accessibility`](https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/bus/dbus-accessibility). This structure largely improves the confinement of each profile.
+
+To ensure system and session bus are handled by a different profile, a [systemd drop-in](https://github.com/roddhjav/apparmor.d/blob/main/systemd/default/system/dbus.service) configuration file is used to set the specific dbus profile a dbus service must use.
 
 ## Abstractions
 

docs/development/directives.md

@@ -136,7 +136,7 @@ The `exec` directive is useful to allow executing transition to a profile withou
     include <abstractions/common/systemd>
     capability dac_override,
     capability kill,
-    unix (bind) type=stream addr=@@{hex}/bus/systemd-oomd/bus-api-oom,
+    unix (bind) type=stream addr=@@{hex16}/bus/systemd-oomd/bus-api-oom,
     #aa:dbus own bus=system name=org.freedesktop.oom1
     /etc/systemd/oomd.conf r,
     /etc/systemd/oomd.conf.d/{,**} r,

docs/development/guidelines.md

@@ -91,24 +91,23 @@ If there is no predictable label it can be omitted.
 
 ### Profile rules
 
-`bin, sbin & lib`
+#### :material-numeric-1-circle: Variables
 
-:   - Do not use: `/usr/lib` or `/usr/bin` but `@{bin}/` or `@{lib}/`
-    - Do not use: `/usr/sbin` or `/sbin` but `@{bin}/`.
+:   Always use the apparmor [variables](../variables.md).
+    Example:
 
-`Variables`
+    - `/usr/lib` or `/usr/bin` become `@{bin}` or `@{lib}`
+    - `/usr/sbin` or `/sbin` become `@{bin}`.
 
-:   Always use the apparmor variables.
-
-`Sort`
+#### :material-numeric-2-circle: Sort
 
 :   In a rule block, the rules must be alphabetically sorted.
 
-`Sub profile`
+#### :material-numeric-3-circle: Sub profile
 
 :   Sub profile should come at the end of a profile.
 
-`Similar purpose`
+#### :material-numeric-4-circle: Similar purpose
 
 :   When some rules share similar purpose, they may be sorted together. Eg:
     ```

docs/development/index.md

@@ -36,7 +36,7 @@ You want to contribute to `apparmor.d`, **thanks a lot for this.** Feedbacks, co
 
 :   As these are mandatory access control policies only what is explicitly required
     should be authorized. Meaning, you should **not** allow everything (or a large area)
-    and blacklist some sub areas.
+    and deny some sub areas.
 
 #### Rule :material-numeric-2-circle: - Do not break a program
 

docs/full-system-policy.md

@@ -1,5 +1,5 @@
 ---
-title: Full system policy
+title: Full system policy (FSP)
 ---
 
 !!! danger
@@ -18,6 +18,19 @@ title: Full system policy
     *Source: [AppArmor Wiki][apparmor-wiki]*
 
 
+## Overview
+
+The default mode of `apparmor.d` is the more advanced confinement configuration we can achieve while being as simple as installing a package and doing some minor configuration on your system. By design, a full system confinement does not work this way. Before enabling you need to consider your use case and security objective.
+
+Particularly:
+
+- Every system application will be **blocked** if they do not have a profile.
+- Any non-standard system app need to be explicitly profiled and allowed to run. For instance, if you want to use your own proxy or VPN software, you need to ensure it is correctly profiled and allowed to run in the `systemd` profile.
+- Desktop environment must be explicitly supported, your UI will not start otherwise. Again, it is a **feature**.
+- FSP mode will run unknown user application into the `default` profile. It might be enough for your application. If not you have to make a profile for it.
+- In FSP mode, all sandbox manager **must** have a profile. Then user sandboxed application (flatpak, snap...) will work as expected.
+
+
 ## Install
 
 

docs/install.md

@@ -14,7 +14,7 @@ title: Installation
 
 **AppArmor**
 
-An `apparmor` based Linux distribution is required. The basic profiles and abstractions shipped with AppArmor must be installed.
+An `apparmor` based Linux distribution is required. The default profiles and abstractions shipped with AppArmor must be installed.
 
 **Desktop environment**
 

docs/report.md

@@ -16,5 +16,10 @@ If this command produce nothing, try:
 aa-log -s -R
 ```
 
+You can get more logs with:
+
+1. `aa-log -R -s` that will provide all apparmor logs since boot time (if journalctl collect them)
+2. `aa-log -R -f <nb>` where `<nb>` is `1`, `2`, `3` and `4` (the rotated audit log file)
+
 [newissue]: https://github.com/roddhjav/apparmor.d/issues/new
 [paste]: https://pastebin.com/

docs/usage.md

@@ -86,17 +86,27 @@ Other AppArmor userspace tools such as `aa-enforce`, `aa-complain`, and `aa-logp
 
 To read the AppArmor log from `/var/log/audit/audit.log`:
 ```sh
-aa-log
+$ aa-log
 ```
 
 To optionally filter a given profile name: `aa-log <profile-name>` (your shell will autocomplete the profile name):
 ```
-aa-log dnsmasq
+$ aa-log dnsmasq
 DENIED  dnsmasq open /proc/sys/kernel/osrelease comm=dnsmasq requested_mask=r denied_mask=r
 DENIED  dnsmasq open /proc/1/environ comm=dnsmasq requested_mask=r denied_mask=r
 DENIED  dnsmasq open /proc/cmdline comm=dnsmasq requested_mask=r denied_mask=r
 ```
 
+To generate AppArmor rule:
+```sh
+$ aa-log -r dnsmasq
+profile dnsmasq {
+  @{PROC}/@{pid}/environ r,
+  @{PROC}/cmdline r,
+  @{PROC}/sys/kernel/osrelease r,
+}
+```
+
 !!! info
 
     Other logs file in `/var/log/audit/` can easily be checked: `aa-log -f 1`

docs/variables.md

@@ -86,7 +86,6 @@ title: Variables References
 | Integer (up to 10 digits) | `@{int}` | `[0-9]{[0-9],}{[0-9],}{[0-9],}{[0-9],}{[0-9],}{[0-9],}{[0-9],}{[0-9],}{[0-9],}` |
 | Any 6, 8 or 10 characters | `@{rand6}`, `@{rand8}`, `@{rand10}` | |
 | Hexadecimal | `@{h}*@{h}` |  |
-| MD5 hash | `@{md5}` |  |
 | Universally unique identifier | `@{uuid}` |  |
 | Current Process id | `@{pid}` | `[0-9]*` |
 | Processes ids | `@{pids}` | `[0-9]*` |