doc: improve current doc.

CONTRIBUTING.md

@@ -30,6 +30,17 @@ in this page all the useful information needed to contribute.
 you'll see a Compare & pull request button, fill and submit the pull request.
 
 
+## Projects rules
+ 
+A few rules:
+1. As these are mandatory access control policies only what it explicitly required
+   should be authorized. Meaning, you should not allow everything (or a large area)
+   and blacklist some sub area.
+2. A profile **should not break a normal usage of the confined software**. It can
+   be complex as simply running the program for your own use case is not alway
+   exhaustive of the program features and required permissions.
+
+
 ## Add a profile
 
 1. To add a new profile `foo`, add the file `foo` in `apparmor.d/profile-a-f`. 
@@ -64,36 +75,65 @@ profile foo @{exec_path} {
 
 ## Profile Guidelines
 
-In order to ensure a common structure across the profiles, all new profile should try to follow the guideline presented here.
+> This profile guideline is still evloving, feel free to propose improvment
 
-The rules in the profile should be sorted as follow: 
+In order to ensure a common structure across the profiles, all new profile should
+try to follow the guideline presented here.
+
+The rules in the profile should be sorted as follow:
 - include
 - capability
+- network
+- mount
+- remount
+- umount
 - ptrace
 - signal
-- network 
-- mount
+- unix
+- dbus (send, receive) send receice 
 - @{exec_path} mr,
 - The binaries and library required: `/{usr/,}bin/`, `/{usr/,}lib/`, `/opt/`...
 - The shared resources: `/usr/share`...
 - The system configuration: `/etc`...
+- The system data: `/var`...
 - The user data: `owner @{HOME}/`...
-- The user configuration (all dotfiles)
+- The user configuration, cache and in general all dotfiles
 - Temporary data: `/tmp/`, `@{run}/`...
 - Sys files: `@{sys}/`...
 - Proc files: `@{PROC}/`... 
 - Dev files: `/dev/`...
+- Deny rules: `deny`...
+- Local include
 
 
 **Other rules**
 * Do not use: `/usr/lib` or `/usr/bin` but `/{usr/,}bin/` or `/{usr/,}lib/`.
+* Do not use: `/usr/sbin` or `/sbin` but `/{usr/,}{s,}bin/`.
 * Always use the apparmor variables.
 * In a rule block, the rule shall be alphabetically sorted.
-* When some file access share similar purpose, they shall be sorted together. Eg:
-    ```
-    /etc/machine-id r,
-    /var/lib/dbus/machine-id r,
-    ```
+* Subprofile should comes at the end of a profile.
+* When some file access share similar purpose, they may be sorted together. Eg:
+  ```
+  /etc/machine-id r,
+  /var/lib/dbus/machine-id r,
+  ```
+
+The included tool `aa-log` can be useful to explore the apparmor log 
+
+## Abstraction
+
+This project and the apparmor profile official project provide a large selection
+of abstraction to be included in profiles. They should be used.
+
+For instance, instead of writting:
+```sh
+owner @{HOME}/@{XDG_DOWNLOAD_DIR}/{,**} rw,
+```
+to allow download directory access, you should write
+
+```sh
+include <abstractions/user-download-strict>
+```
 
 ## AppArmor variables
 
@@ -119,10 +159,11 @@ The rules in the profile should be sorted as follow:
 **Additional variables available with this project:**
 
 * Common mountpoints: `@{MOUNTS}=/media/ @{run}/media /mnt`
+* Universally unique identifier: `@{uuid}=[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*`
 * Extended XDG user directories: 
     - Projects: `@{XDG_PROJECTS_DIR}="Projects"`
     - Books: `@{XDG_BOOKS_DIR}="Books"`
-    - Wallpapers: `@{XDG_WALLPAPERS_DIR}="Pictures/Wallpapers"`
+    - Wallpapers: `@{XDG_WALLPAPERS_DIR}="@{XDG_PICTURES_DIR}/Wallpapers"`
     - Sync: `@{XDG_SYNC_DIR}="Sync"`
     - Vm: `@{XDG_VM_DIR}=".vm"`
     - SSH: `@{XDG_SSH_DIR}=".ssh"`

README.md

@@ -11,7 +11,8 @@
 
 ## Description 
 
-A set of over 1000 AppArmor profiles which aims is to confine most of Linux base applications and processes.
+A set of over 1200 AppArmor profiles which aims is to confine most of Linux base
+applications and processes.
 
 **Goals & Purpose**
 - Support all distributions that support AppArmor:
@@ -65,7 +66,7 @@ sudo pacman -U apparmor.d-*.pkg.tar.zst \
 Build using standard Debian package build tools:
 ```sh
 dpkg-buildpackage -b -d --no-sign
-sudo dpkg --install ../apparmor.d_*_all.deb
+sudo dpkg -i ../apparmor.d_*_all.deb
 ```
 
 > Note: for a first install, it is recommanded to install all profiles in complain mode. See [Complain mode](#troubleshooting)
@@ -131,7 +132,7 @@ DENIED  dnsmasq open /proc/cmdline comm=dnsmasq requested_mask=r denied_mask=r
 **AppArmor configuration**
 
 As they are a lot of rules, it is recommended to enable caching AppArmor profiles.
-In `/etc/apparmor/parser.conf`, uncomment `write-cache`.
+In `/etc/apparmor/parser.conf`, uncomment `write-cache` and `Optimize=compress-fast`.
 See [Speed up AppArmor Start] on the Arch Wiki for more information.
 
 
@@ -176,9 +177,9 @@ AppArmor log from `/var/log/audit/audit.log`. Then you can see the log with `aa-
 
 **System Recovery**
 
-Issue in some core profiles like the systemd tools, or the desktop environment
+Issue in some core profiles like the systemd suite, or the desktop environment
 can fully break your system. This should not happen a lot, but if it does here
-is the procces to recover your system on Archlinux:
+is the process to recover your system on Archlinux:
 1. Boot from a Archlinux live USB
 1. If you root partition is encryped, decrypt it: `cryptsetup open /dev/<your-disk-id> vg0`
 1. Mount your root partition: `mount /dev/<your-plain-disk-id> /mnt`
@@ -253,3 +254,4 @@ with this program; if not, write to the Free Software Foundation, Inc.,
 [android_model]: https://arxiv.org/pdf/1904.05572
 [clipos]: https://clip-os.org/en/
 [Speed up AppArmor Start]: https://wiki.archlinux.org/title/AppArmor#Speed-up_AppArmor_start_by_caching_profiles
+[write xor execute]: https://en.wikipedia.org/wiki/W%5EX