From 9b84ded0c29d08b4edcd26de4006d352c9ac7c85 Mon Sep 17 00:00:00 2001 From: Alexandre Pujol Date: Sun, 3 Jul 2022 18:55:21 +0100 Subject: [PATCH] doc: improve current doc. --- CONTRIBUTING.md | 63 ++++++++++++++++++++++++++++++++++++++++--------- README.md | 12 ++++++---- 2 files changed, 59 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9fe8cd57..c65cda9f 100644 --- a/CONTRIBUTING.md +++ b/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 +``` ## 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"` diff --git a/README.md b/README.md index d20438db..1b082b24 100644 --- a/README.md +++ b/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/ vg0` 1. Mount your root partition: `mount /dev/ /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