From 683e9e15c50ad7cee27367bda0a63207ab1d3d53 Mon Sep 17 00:00:00 2001 From: Alexandre Pujol Date: Sat, 27 Jan 2024 19:54:13 +0000 Subject: [PATCH] doc: general update. --- docs/configuration.md | 30 +++++++++++------------------- docs/development/guidelines.md | 25 +++++++++++++------------ docs/index.md | 2 +- docs/install.md | 2 +- docs/report.md | 2 +- docs/variables.md | 11 +++++++++++ 6 files changed, 38 insertions(+), 34 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 2a94bcdb..05d4fa1f 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,8 +4,7 @@ title: Configuration ## AppArmor -As there are a lot of rules, it is recommended to enable caching AppArmor profiles. -In `/etc/apparmor/parser.conf`, add `write-cache` and `Optimize=compress-fast`. +As there are a lot of rules, it is recommended to enable caching AppArmor profiles. In `/etc/apparmor/parser.conf`, add `write-cache` and `Optimize=compress-fast`. ```sh echo 'write-cache' | sudo tee -a /etc/apparmor/parser.conf @@ -20,11 +19,13 @@ echo 'Optimize=compress-fast' | sudo tee -a /etc/apparmor/parser.conf ## Personal directories -This project is designed in such a way that it is easy to personalize the -directories your programs have access by defining a few variables. +!!! danger -The profiles heavily use the (largely extended) XDG directory variables defined -in the **[Variables Reference](variables.md)** page. + You need to ensure that all personal directories you are using are well-defined XDG directory. You may need to edit these variables to your own settings. + +This project is designed in such a way that it is easy to personalize the directories your programs have access by defining a few variables. + +The profiles heavily use the (largely extended) XDG directory variables defined in the **[Variables Reference](variables.md)** page. ??? note "XDG variables overview" @@ -48,9 +49,7 @@ in the **[Variables Reference](variables.md)** page. | 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 by creating a file such as: `/etc/apparmor.d/tunables/xdg-user-dirs.d/local` where you define your own personal directories. Example: ```sh @{XDG_VIDEOS_DIR}+="Films" @{XDG_MUSIC_DIR}+="Musique" @@ -81,16 +80,11 @@ sudo systemctl restart apparmor.service ## Local profile extensions -You can extend any profile with your own rules by creating a file in the -`/etc/apparmor.d/local/` directory with the name of your profile. For example, -to extend the `foo` profile, create a file `/etc/apparmor.d/local/foo` and add -your rules in it. +You can extend any profile with your own rules by creating a file in the `/etc/apparmor.d/local/` directory with the name of your profile. For example, to extend the `foo` profile, create a file `/etc/apparmor.d/local/foo` and add your rules in it. **Example** -- `child-open`, a profile that allows other program to open resources (URL, - picture, books...) with some predefined GUI application. To allow it to open - URLs with Firefox, create the file `/etc/apparmor.d/local/child-open` with: +- `child-open`, a profile that allows other program to open resources (URL, picture, books...) with some predefined GUI application. To allow it to open URLs with Firefox, create the file `/etc/apparmor.d/local/child-open` with: ```sh @{bin}/firefox rPx, ``` @@ -101,9 +95,7 @@ your rules in it. !!! info - `rPx` allows transition to the Firefox profile. Use `rPUx` to allow - transition to an unconfined state if you do not have the profile for a - given program. + `rPx` allows transition to the Firefox profile. Use `rPUx` to allow transition to an unconfined state if you do not have the profile for a given program. Then, reload the apparmor rules with `sudo systemctl restart apparmor`. diff --git a/docs/development/guidelines.md b/docs/development/guidelines.md index e6fa080f..21bfebdc 100644 --- a/docs/development/guidelines.md +++ b/docs/development/guidelines.md @@ -30,18 +30,18 @@ The rules in the profile should be sorted in the rule ***block*** as follows: |:-----:|:----:|:-------:| | **1** | [`include`](https://man.archlinux.org/man/apparmor.d.5##include_mechanism) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+include+%3Cabstractions%2F&type=code) | | **2** | [`set rlimit`](https://man.archlinux.org/man/apparmor.d.5#rlimit_rules) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+set+rlimit&type=code) | -| **3** | [`capability`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#capability-rules) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+capability&type=code) | -| **4** | [`network`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#network-rules) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22+network+%22&type=code) | -| **5** | [`mount`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#mount-rules-apparmor-28-and-later) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22++mount+%22&type=code) | -| **6** | [`remount`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#remount) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+remount&type=code) | -| **7** | [`umount`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#umount)| [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22umount+%22&type=code) | -| **8** | [`pivot_root`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#pivot_root)| [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+pivot_root&type=code) | -| **9** | [`change_profile`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#change_profile)| [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+change_profile+&type=code) | -| **10** | `mqueue` | [:octicons-link-external-24:]() | -| **11** | [`signal`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#signals)| [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22signal+%22&type=code) | -| **12** | [`ptrace`](https://man.archlinux.org/man/apparmor.d.5#PTrace_rules) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22ptrace+%22&type=code) | -| **13** | [`unix`](https://man.archlinux.org/man/apparmor.d.5#Unix_socket_rules) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22unix+%22&type=code) | -| **14** | `userns` | [:octicons-link-external-24:]() | +| **3** | [`userns`](https://gitlab.com/apparmor/apparmor/-/wikis/unprivileged_userns_restriction) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+userns&type=code) | +| **4** | [`capability`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#capability-rules) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+capability&type=code) | +| **5** | [`network`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#network-rules) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22+network+%22&type=code) | +| **6** | [`mount`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#mount-rules-apparmor-28-and-later) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22++mount+%22&type=code) | +| **7** | [`remount`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#remount) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+remount&type=code) | +| **8** | [`umount`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#umount)| [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22umount+%22&type=code) | +| **9** | [`pivot_root`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#pivot_root)| [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+pivot_root&type=code) | +| **10** | [`change_profile`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#change_profile)| [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+change_profile+&type=code) | +| **11** | `mqueue` | [:octicons-link-external-24:]() | +| **12** | [`signal`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#signals)| [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22signal+%22&type=code) | +| **13** | [`ptrace`](https://man.archlinux.org/man/apparmor.d.5#PTrace_rules) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22ptrace+%22&type=code) | +| **14** | [`unix`](https://man.archlinux.org/man/apparmor.d.5#Unix_socket_rules) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md+%22unix+%22&type=code) | | **15** | `io_uring` | [:octicons-link-external-24:]() | | **16** | [`dbus`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#dbus-rules) | [:octicons-link-external-24:](https://github.com/search?q=repo%3Aroddhjav%2Fapparmor.d+NOT+path%3A*.md++NOT+path%3A*.go+%22+dbus+%22&type=code) | | **17** | [`file`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#file-access-rules) | [:octicons-link-external-24:](https://github.com/roddhjav/apparmor.d/blob/2e4788c51ef73798c0ac94993af3cd769723e8e4/apparmor.d/groups/gnome/gnome-shell#L481-L663) | @@ -120,6 +120,7 @@ If there is no predictable label it can be omitted. ## Additional recommended documentation * [The AppArmor Core Policy Reference](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference) +* [The OpenSUSE Documentation](https://doc.opensuse.org/documentation/leap/security/html/book-security/part-apparmor.html) * [The AppArmor.d man page](https://man.archlinux.org/man/apparmor.d.5) * [F**k AppArmor](https://presentations.nordisch.org/apparmor/#/) * [A Brief Tour of Linux Security Modules](https://www.starlab.io/blog/a-brief-tour-of-linux-security-modules) diff --git a/docs/index.md b/docs/index.md index 136f4178..40ed5a9f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@ title: AppArmor.d This project is still in its early development. Help is very welcome; see [Development](development/index.md) -**AppArmor.d** is a set of over 1400 AppArmor profiles whose aim is to confine +**AppArmor.d** is a set of over 1500 AppArmor profiles whose aim is to confine most Linux based applications and processes. **Purpose** diff --git a/docs/install.md b/docs/install.md index 7d038629..1b42ebab 100644 --- a/docs/install.md +++ b/docs/install.md @@ -19,7 +19,7 @@ The following desktop environments are supported: - [x] :material-gnome: Gnome - [ ] :simple-kde: KDE *(work in progress)* -**Build dependencies** +**Build dependency** * Go >= 1.18 diff --git a/docs/report.md b/docs/report.md index 06b14c50..a84a6a38 100644 --- a/docs/report.md +++ b/docs/report.md @@ -6,7 +6,7 @@ title: Report AppArmor logs The **[aa-log](usage.md#apparmor-log)** tool reports all AppArmor `DENIED` and `ALLOWED`. It should be used to fix AppArmor related issues. -While testing, if something get wrong, you need to put the profile in complain mode, to that you can investigate and it does not block your program. +While testing, if something get wrong, you need to put the profile in complain mode, to that you can investigate, and it does not block your program. When creating [an issue on Github][newissue]. Please ensure you post a link to the [paste] of the AppArmor audit log: `/var/log/audit/audit.log`. diff --git a/docs/variables.md b/docs/variables.md index 8faa4676..f1113be1 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -114,3 +114,14 @@ title: Variables References | Sys | `@{sys}` | `/sys/` | | Flatpack export | `@{flatpak_exports_root}` | `{flatpak/exports,flatpak/{app,runtime}/*/*/*/*/export}` | | System wide share | `@{system_share_dirs}` | `/{usr,usr/local,var/lib/@{flatpak_exports_root}}/share` | + +**Program paths** + +| Description | Name | Default Value | +|-------------|:----:|---------------| +| All the shells | `@{shells}` | `sh zsh bash dash fish rbash ksh tcsh csh` | +| Shells path | `@{shells_path}` | `@{bin}/@{shells}` | +| Coreutils programs that should not have dedicated profile | `@{coreutils}` | See [tunables/multiarch.d/paths](https://github.com/roddhjav/apparmor.d/blob/c2d88c9bffc626fcf7d9b15b42b50706afb29562/apparmor.d/tunables/multiarch.d/paths#L46) | +| Coreutils paths | `@{coreutils_path}` | `@{bin}/@{coreutils}` | +| Launcher paths | `@{open_path}` | `@{bin}/exo-open @{bin}/xdg-open @{lib}/@{multiarch}/glib-[0-9]*/gio-launch-desktop @{lib}/gio-launch-desktop` +| All browser paths | `@{*_path}` | See [tunables/multiarch.d/paths](https://github.com/roddhjav/apparmor.d/blob/c2d88c9bffc626fcf7d9b15b42b50706afb29562/apparmor.d/tunables/multiarch.d/paths#L11)