From fb29e8ba74aa9712b5b06c20e935a7f4cd208b8c Mon Sep 17 00:00:00 2001 From: Alexandre Pujol Date: Fri, 30 Aug 2024 20:38:30 +0100 Subject: [PATCH] doc: general update. --- README.md | 16 +-- docs/development/dbus.md | 8 ++ docs/development/guidelines.md | 19 ++- docs/development/index.md | 2 +- docs/development/install.md | 47 ++++--- docs/development/structure.md | 41 ++---- docs/enforce.md | 68 ++++++---- docs/full-system-policy.md | 62 +++++---- docs/index.md | 19 +-- docs/install.md | 227 +++++++++++++++++++++------------ docs/report.md | 40 ++++-- docs/usage.md | 4 +- docs/variables.md | 13 +- mkdocs.yml | 7 +- 14 files changed, 350 insertions(+), 223 deletions(-) diff --git a/README.md b/README.md index ae9899b7..7aed183d 100644 --- a/README.md +++ b/README.md @@ -27,15 +27,15 @@ - Target both desktops and servers - Support all distributions that support AppArmor: - * Arch Linux - * Ubuntu 22.04 - * Debian 12 - * OpenSUSE Tumbleweed + * [Arch Linux](https://apparmor.pujol.io/install#archlinux) + * [Ubuntu 24.04/22.04](https://apparmor.pujol.io/install#ubuntu) + * [Debian 12](https://apparmor.pujol.io/install#debian) + * [OpenSUSE Tumbleweed](https://apparmor.pujol.io/install#opensuse) - Support for all major desktop environments: - * Gnome - * KDE - * XFCE *(work in progress)* -- Fully tested (Work in progress) + * Gnome (GDM) + * KDE (SDDM) + * XFCE (Lightdm) *(work in progress)* +- Fully tested *(work in progress)* > This project is originally based on the work from [Morfikov][upstream] and aims to extend it to more Linux distributions and desktop environments. diff --git a/docs/development/dbus.md b/docs/development/dbus.md index 98b46501..c8efda0c 100644 --- a/docs/development/dbus.md +++ b/docs/development/dbus.md @@ -26,6 +26,14 @@ Access to common dbus interfaces is done using the abstractions under **[`abstra For more access, simply use the [`aa:dbus talk`](#dbus-directive) directive. +There is a trade of between security and maintenance to make: + +- `aa:dbus talk` will generate less issue as it give full talk access +- `abstractions/bus/*` will provide more restriction, and possibly more issue. + +Ideally, these rules should be automatically generated from either the dbus interface documentation or the program call. + + ## Dbus Directive We use a special [directive](directives.md) to generate more advanced dbus access. The directive format is on purpose very similar to the AppArmor dbus rule. diff --git a/docs/development/guidelines.md b/docs/development/guidelines.md index b359576a..3d83fea5 100644 --- a/docs/development/guidelines.md +++ b/docs/development/guidelines.md @@ -78,7 +78,7 @@ The file block should be sorted as follows: The dbus block should be sorted as follows: - The system bus should be sorted *before* the session bus -- The bind rules should be sorted *after* the send & receive rules +- The bind rules should be sorted *after* send & receive rules For DBus, try to determine peer's label when possible. E.g.: ``` @@ -115,6 +115,23 @@ If there is no predictable label it can be omitted. /var/lib/dbus/machine-id r, ``` +#### :material-numeric-5-circle: Limit the use of `deny` + +: The use of `deny` should be limited to the minimum: + + - In MAC policies, we only allow access ([Rule :material-numeric-1-circle:](index.md#rule-mandatory-access-control "Mandatory Access Control")) + - `deny` rules are enforced even in complain mode, + - If it works on your machine does not mean it will work on others ([Rule :material-numeric-4-circle:](index.md#rule-distribution-and-devices-agnostic "Distribution and devices agnostic")). + +#### :material-numeric-6-circle: Comments + +: Ensure you only have useful comments. E.g.: + ``` + # Config files for foo + owner @{user_config_dirs}/foo/{,**} r, + ``` + Does not help, and if generalized it would add a lot of complexity to any profiles. + ## Additional recommended documentation diff --git a/docs/development/index.md b/docs/development/index.md index c12226a7..c68745e2 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -70,7 +70,7 @@ If you're looking to contribute to `apparmor.d` you can get started by going to Here is the bare minimum for the program `foo`: ``` sh # apparmor.d - Full set of apparmor profiles -# Copyright (C) 2023 You +# Copyright (C) 2024 You # SPDX-License-Identifier: GPL-2.0-only abi , diff --git a/docs/development/install.md b/docs/development/install.md index 74271c13..6b1f4758 100644 --- a/docs/development/install.md +++ b/docs/development/install.md @@ -11,28 +11,39 @@ title: Installation See `debian/`, `PKGBUILD` and `dists/apparmor.d.spec`. -**:material-docker: Docker** +=== ":material-arch: Archlinux" -For any system with docker installed you can simply build the package with: -```sh -make package dist= -``` -Then you can install the package with `dpkg`, `pacman` or `rpm`. + ```sh + make pkg + ``` -**:material-arch: Arch Linux** -```sh -make pkg -``` +=== ":material-ubuntu: Ubuntu" -**:material-ubuntu: Ubuntu & :material-debian: Debian** -```sh -make dpkg -``` + ```sh + make dpkg + ``` -**:simple-suse: openSUSE** -```sh -make rpm -``` +=== ":material-debian: Debian" + + ```sh + make dpkg + ``` + +=== ":simple-suse: openSUSE" + + ```sh + make rpm + ``` + +=== ":material-docker: Docker" + + For any system with docker installed you can simply build the package with: + + ```sh + make package dist= + ``` + + Then you can install the package with `dpkg`, `pacman` or `rpm`. ## Profile flags diff --git a/docs/development/structure.md b/docs/development/structure.md index 0035b6c9..c6b82e29 100644 --- a/docs/development/structure.md +++ b/docs/development/structure.md @@ -9,7 +9,7 @@ Description of common structure found across various AppArmor profiles Some programs should not be confined by themselves. For example, tools such as `ls`, `rm`, `diff` or `cat` do not have profiles in this project. Let's see why. -These are general tools that in a general context can legitimately access any file in the system. Therefore, the confinement of such tools by a global profile would at best be minimal at worst be a security theater. +These are general tools that in a general context can legitimately access any file in the system. Therefore, the confinement of such tools by a global profile would at best be minimal at worst be a security theatre. It gets even worse. Let's say, we write a profile for `cat`. Such a profile would need access to `/etc/`. We will add the following rule: ```sh @@ -76,20 +76,17 @@ You do not protect these programs. *Protect the usage you have of these programs [Toolbox]: https://containertoolbx.org/ +## Open Resources -## Abstractions +The standard way to allow opening resource in this project is to use one of the +child-open profile. Eg: `@{open_path} rPx -> child-open,` -This project and the apparmor-profiles official project provide a large selection of abstractions to be included in profiles. They should be used. +They are available in the [`children`][children] group. -For instance, to allow download directory access, instead of writing: -```sh -owner @{HOME}/@{XDG_DOWNLOAD_DIR}/{,**} rw, -``` - -You should write: -```sh -include -``` +* **`child-open`**: Instead of allowing the ability to run all software in `@{bin}/`, the purpose of this profile is to list all GUI programs that can open resources. Ultimately, only sandbox manager programs such as `bwrap`, `snap`, `flatpak`, `firejail` should be present here. Until this day, this profile will be a controlled mess. +* **`child-open-browsers`**: This version of child-open only allow to open browsers. +* **`child-open-help`**: This version of child-open only allow to open browsers and help programs. +* **`child-open-strict`**: This version of child-open only allow to open browsers & folders. ## Children profiles @@ -104,31 +101,11 @@ Usually, a child profile is in the [`children`][children] group. They have the f Here is an overview of the current children profile: -1. **`child-open`**: To open resources. Instead of allowing the ability to run all software in `@{bin}/`, the purpose of this profile is to list all GUI programs that can open resources. Ultimately, only sandbox manager programs such as `bwrap`, `snap`, `flatpak`, `firejail` should be present here. Until this day, this profile will be a controlled mess. - 2. **`child-pager`**: Simple access to pagers such as `pager`, `less` and `more`. This profile assumes the pager is reading its data from stdin, not from a file on disk. 3. **`child-systemctl`**: Common `systemctl` action. Do not use it too much as most of the time you will need more privilege than what this profile is giving you. -## Browsers - -Chromium based browsers share a similar structure. Therefore, they share the same abstraction: [`abstractions/chromium`][chromium] that includes most of the profile content. - -This abstraction requires the following variables defined in the profile header: -```sh -@{name} = chromium -@{domain} = org.chromium.Chromium -@{lib_dirs} = @{lib}/chromium -@{config_dirs} = @{user_config_dirs}/chromium -@{cache_dirs} = @{user_cache_dirs}/chromium -``` - -If your application requires chromium to run (like electron) use [`abstractions/chromium-common`][chromium-common] instead. - -[chromium]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/abstractions/chromium -[chromium-common]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/abstractions/chromium-common - ## Udev rules See the **[kernel docs][kernel]** to check the major block and char numbers used in `/run/udev/data/`. diff --git a/docs/enforce.md b/docs/enforce.md index 52241859..692cbd1e 100644 --- a/docs/enforce.md +++ b/docs/enforce.md @@ -4,37 +4,59 @@ title: Enforce Mode The default package configuration installs all profiles in *complain* mode. This is a safety measure to ensure you are not going to break your system on initial installation. Once you have tested it, and it works fine, you can easily switch to *enforce* mode. The profiles that are not considered stable are kept in complain mode, they can be tracked in the [`dists/flags`](https://github.com/roddhjav/apparmor.d/tree/main/dists/flags) directory. -!!! warning +!!! danger - - Please test in complain mode first and ensure your system boots! - - When reporting an issue, please ensure the affected profiles are in complain mode. + - You **must** test in complain mode first and ensure your system works as expected. + - You **must** regularly check AppArmor log with [`aa-log`](usage.md#apparmor-log) and [report](report.md) issues first. + - When reporting an issue, you **must** ensure the affected profiles are in complain mode. -#### :material-arch: Arch Linux +=== ":material-arch: Archlinux" -In `PKGBUILD`, replace `make` by `make enforce`: -```diff -- make DISTRIBUTION=arch -+ make enforce DISTRIBUTION=arch -``` + In the `PKGBUILD`, replace `make` by `make enforce`: -#### :material-ubuntu: Ubuntu & :material-debian: Debian + ```diff + - make DISTRIBUTION=arch + + make enforce DISTRIBUTION=arch + ``` -In `debian/rules`, add the following lines: + Then, build the package with: `make pkg` -```make -override_dh_auto_build: - make enforce -``` +=== ":material-ubuntu: Ubuntu" -#### :simple-suse: openSUSE + In `debian/rules`, add the following lines: -In `dists/apparmor.d.spec`, replace `%make_build` by `make enforce` -```diff -- %make_build -+ %make_build enforce -``` + ```make + override_dh_auto_build: + make enforce + ``` -#### Partial install + Then, build the package with: `make dpkg` -Use the `make enforce` command to build instead of `make` +=== ":material-debian: Debian" + + In `debian/rules`, add the following lines: + + ```make + override_dh_auto_build: + make enforce + ``` + + Then, build the package with: `make dpkg` + +=== ":simple-suse: openSUSE" + + In `dists/apparmor.d.spec`, replace `%make_build` by `%make_build enforce` + + ```diff + - %make_build + + %make_build enforce + ``` + + Then, build the package with: `make rpm` + +=== ":material-home: Partial Install" + + Use the `make enforce` command to build instead of `make` + +[aur]: https://aur.archlinux.org/packages/apparmor.d-git diff --git a/docs/full-system-policy.md b/docs/full-system-policy.md index 2b9f5745..d37cf307 100644 --- a/docs/full-system-policy.md +++ b/docs/full-system-policy.md @@ -31,7 +31,7 @@ Particularly: - In FSP mode, all sandbox managers **must** have a profile. Then user sandboxed applications (flatpak, snap, etc) will work as expected. -## Install +## Installation This feature is only enabled when the project is built with `make full`. [Early policy](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmorInSystemd#early-policy-loads) load **must** also be enabled. Once `apparmor.d` has been installed in FSP mode, it is required to reboot to apply the changes. @@ -43,35 +43,53 @@ cache-loc /etc/apparmor/earlypolicy/ Optimize=compress-fast ``` -**:material-arch: Arch Linux** +=== ":material-arch: Archlinux" -In `PKGBUILD`, replace `make` by `make full`: -```diff -- make -+ make full -``` + In `PKGBUILD`, replace `make` by `make full`: -**:material-ubuntu: Ubuntu & :material-debian: Debian** + ```diff + - make + + make full + ``` -In `debian/rules`, add the following lines: + Then, build the package with: `make pkg` -```make -override_dh_auto_build: - make full -``` +=== ":material-ubuntu: Ubuntu" -**:simple-suse: openSUSE** + In `debian/rules`, add the following lines: -In `dists/apparmor.d.spec`, replace `%make_build` by `make full` -```diff -- %make_build -+ %make_build full -``` + ```make + override_dh_auto_build: + make full + ``` -**Partial install** + Then, build the package with: `make dpkg` -Use the `make full` command to build instead of `make` +=== ":material-debian: Debian" + + In `debian/rules`, add the following lines: + ```make + override_dh_auto_build: + make full + ``` + + Then, build the package with: `make dpkg` + +=== ":simple-suse: openSUSE" + + In `dists/apparmor.d.spec`, replace `%make_build` by `%make_build full` + + ```diff + - %make_build + + %make_build full + ``` + + Then, build the package with: `make rpm` + +=== ":material-home: Partial Install" + + Use the `make full` command to build instead of `make` ## Structure @@ -113,7 +131,7 @@ To work as intended, userland services started by `systemd --user` **should** ha !!! info - To be allowed to run, additional root or user services may need to add extra rules inside the `usr/systemd.d` or `usr/systemd-user.d` directory. For example, when installing a new privileged service `foo` with [stacking](#no-new-privileges) you may need to add the following to `/etc/apparmor.d/usr/systemd.d/foo`: + To be allowed to run, additional root or user services may need to add extra rules inside the `usr/systemd.d` or `usr/systemd-user.d` directory. For example, when installing a new privileged service `foo` with [stacking](development/structure.md#no-new-privileges) you may need to add the following to `/etc/apparmor.d/usr/systemd.d/foo`: ``` @{lib}/foo rPx -> systemd//&foo, ``` diff --git a/docs/index.md b/docs/index.md index 3a9381cc..b57bae7a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,13 +2,7 @@ title: AppArmor.d --- - + **Full set of AppArmor profiles** @@ -34,13 +28,14 @@ See the [Concepts](concepts.md)' page for more detail on the architecture. - Target both desktops and servers - Support for all distributions that support AppArmor: * [:material-arch: Arch Linux](install.md#archlinux) - * [:material-ubuntu: Ubuntu 22.04](install.md#ubuntu-debian) - * [:material-debian: Debian 12](install.md#ubuntu-debian) + * [:material-ubuntu: Ubuntu 24.04/22.04](install.md#ubuntu) + * [:material-debian: Debian 12](install.md#debian) * [:simple-suse: openSUSE Tumbleweed](install.md#opensuse) - Support for all major desktop environments: - - [x] :material-gnome: Gnome - - [ ] :simple-kde: KDE *(work in progress)* -- Fully tested (Work in progress) + - [x] :material-gnome: Gnome (GDM) + - [x] :simple-kde: KDE (SDDM) + - [ ] :simple-xfce: XFCE (Lightdm) *(work in progress)* +- Fully tested *(work in progress)* **Presentations** diff --git a/docs/install.md b/docs/install.md index c0807234..5afac9c7 100644 --- a/docs/install.md +++ b/docs/install.md @@ -2,15 +2,23 @@ title: Installation --- -!!! warning - - To prevent the risk of breaking your system, the default package configuration installs all profiles in complain mode. They can be enforced later. See the [Enforce Mode](enforce.md) page. - - After installation, you **must** regularly check AppArmor log with [`aa-log`](usage.md#apparmor-log). You can also configure [a desktop notification on denied actions](https://wiki.archlinux.org/title/AppArmor#Get_desktop_notification_on_DENIED_actions). +## Setup !!! danger - Do **not** expect this project to work correctly if your Desktop Environment and Display Manager are not supported. Your Desktop Environment or Display Manager might not load, and that would be a feature. + Do **not** expect this project to work correctly on your desktop if your Desktop Environment (DE) and Display Manager (DM) are not supported. Your DE/DM might not load, and that would be a **feature**. + +Due to the development stage of this project, the default package configuration installs all profiles in **complain** mode. The recommended installation workflow is as-follow: + +1. [Install](#installation) *apparmor.d* in the (default) complain mode. +1. Configure [apparmor settings](configuration.md#apparmor) as well as your [personal directories](configuration.md#personal-directories). +1. Ensure you have reloaded the profiles in the kernel: `sudo systemctl restart apparmor.service`. +1. Reboot your system. +1. You **must** check for any AppArmor logs with [`aa-log`](usage.md#apparmor-log). +1. [Report](https://apparmor.pujol.io/report/) any raised logs. +1. Use the profiles in complain mode for a while (a week), regularly check for new AppArmor logs. +1. Only if there are no logs raised for your daily usage, install it in [enforce mode](enforce.md). + ## Requirements @@ -22,105 +30,156 @@ An `AppArmor` supported Linux distribution is required. The default profiles and The following desktop environments are supported: - - [x] :material-gnome: Gnome - - [x] :simple-kde: KDE - - [ ] :simple-xfce: XFCE *(work in progress)* + - [x] :material-gnome: Gnome (GDM) + - [x] :simple-kde: KDE (SDDM) + - [ ] :simple-xfce: XFCE (Lightdm) *(work in progress)* **Build dependency** -* Go >= 1.18 - -## :material-arch: Arch Linux - -`apparmor.d-git` is available in the [Arch User Repository][aur]: -``` -yay -S apparmor.d-git # or your preferred AUR install method -``` - -Or without an AUR helper: -```sh -git clone https://aur.archlinux.org/apparmor.d-git.git -cd apparmor.d-git -makepkg -si -``` +* Go >= 1.21 -## :material-ubuntu: Ubuntu & :material-debian: Debian +## Installation -Build the package from sources: -```sh -sudo apt install apparmor-profiles build-essential config-package-dev debhelper golang-go rsync git -git clone https://github.com/roddhjav/apparmor.d.git -cd apparmor.d -dpkg-buildpackage -b -d --no-sign -sudo dpkg -i ../apparmor.d_*.deb -``` +=== ":material-arch: Archlinux" -!!! tip + `apparmor.d-git` is available in the [Arch User Repository][aur]: - If you have `devscripts` installed, you can use the one liner: ```sh - make dpkg + yay -S apparmor.d-git # or your preferred AUR install method ``` -!!! note + Or without an AUR helper: - Debian user may need golang from the backports repository to build: ```sh - echo 'deb http://deb.debian.org/debian bookworm-backports main contrib non-free' | sudo tee -a /etc/apt/sources.list - sudo apt update - sudo apt install -t bookworm-backports golang-go + git clone https://aur.archlinux.org/apparmor.d-git.git + cd apparmor.d-git + makepkg -si ``` -!!! warning +=== ":material-ubuntu: Ubuntu" - **Beware**: do not install a `.deb` made for Debian on Ubuntu, the packages are different. + Build the package from sources: - If your distribution is based on Ubuntu or Debian, you may want to manually set the target distribution by exporting `DISTRIBUTION=debian` if is Debian based, or `DISTRIBUTION=ubuntu` if it is Ubuntu based. - -## :simple-suse: openSUSE - -openSUSE users need to add [cboltz](https://en.opensuse.org/User:Cboltz) repo on OBS -```sh -zypper addrepo https://download.opensuse.org/repositories/home:cboltz/openSUSE_Factory/home:cboltz.repo -zypper refresh -zypper install apparmor.d -``` - - -## Partial install - -For test purposes, you can install specific profiles with the following commands. Abstractions, tunable, and most of the OS dependent post-processing is managed. - -```sh -make -sudo make profile-names... -``` - -!!! warning - - Partial installation is discouraged because profile dependencies are not fetched. To prevent some AppArmor issues, the dependencies are automatically switched to unconfined (`rPx` -> `rPUx`). The installation process warns on the missing profiles so that you can easily install them if desired. (PR is welcome see [#77](https://github.com/roddhjav/apparmor.d/issues/77)) - - For instance, `sudo make pass` gives: ```sh - Warning: profile dependencies fallback to unconfined. - @{bin}/wl-{copy,paste} rPx, - @{bin}/xclip rPx, - @{bin}/python3.@{int} rPx -> pass-import, # pass-import - @{bin}/pager rPx -> child-pager, - @{bin}/less rPx -> child-pager, - @{bin}/more rPx -> child-pager, - '.build/apparmor.d/pass' -> '/etc/apparmor.d/pass' + sudo apt install apparmor-profiles build-essential config-package-dev debhelper golang-go rsync git + git clone https://github.com/roddhjav/apparmor.d.git + cd apparmor.d + dpkg-buildpackage -b -d --no-sign + sudo dpkg -i ../apparmor.d_*.deb ``` - So, you can install the additional profiles `wl-copy`, `xclip`, `pass-import`, and `child-pager` if desired. + + !!! tip + + If you have `devscripts` installed, you can use the one liner: + + ```sh + make dpkg + ``` + + !!! warning + + **Beware**: do not install a `.deb` made for Debian on Ubuntu, the packages are different. + + If your distribution is based on Ubuntu, you may want to manually set the target distribution by exporting `DISTRIBUTION=ubuntu`. + +=== ":material-debian: Debian" + + Build the package from sources: + + ```sh + sudo apt install apparmor-profiles build-essential config-package-dev debhelper golang-go rsync git + git clone https://github.com/roddhjav/apparmor.d.git + cd apparmor.d + dpkg-buildpackage -b -d --no-sign + sudo dpkg -i ../apparmor.d_*.deb + ``` + + !!! tip + + If you have `devscripts` installed, you can use the one liner: + + ```sh + make dpkg + ``` + + !!! note + + You may need golang from the backports repository to build: + + ```sh + echo 'deb http://deb.debian.org/debian bookworm-backports main contrib non-free' | sudo tee -a /etc/apt/sources.list + sudo apt update + sudo apt install -t bookworm-backports golang-go + ``` + + !!! warning + + **Beware**: do not install a `.deb` made for Debian on Ubuntu, the packages are different. + + If your distribution is based on Debian, you may want to manually set the target distribution by exporting `DISTRIBUTION=debian`. + +=== ":simple-suse: openSUSE" + + openSUSE users need to add [cboltz](https://en.opensuse.org/User:Cboltz) repo on OBS: + + ```sh + zypper addrepo https://download.opensuse.org/repositories/home:cboltz/openSUSE_Factory/home:cboltz.repo + zypper refresh + zypper install apparmor.d + ``` + +=== ":material-home: Partial" + + For test purposes, you can install specific profiles with the following commands. Abstractions, tunable, and most of the OS dependent post-processing is managed. + + ```sh + make + sudo make profile-names... + ``` + + !!! warning + + Partial installation is discouraged because profile dependencies are not fetched. To prevent some AppArmor issues, the dependencies are automatically switched to unconfined (`rPx` -> `rPUx`). The installation process warns on the missing profiles so that you can easily install them if desired. (PR is welcome see [#77](https://github.com/roddhjav/apparmor.d/issues/77)) + + For instance, `sudo make pass` gives: + ```sh + Warning: profile dependencies fallback to unconfined. + @{bin}/wl-{copy,paste} rPx, + @{bin}/xclip rPx, + @{bin}/python3.@{int} rPx -> pass-import, # pass-import + @{bin}/pager rPx -> child-pager, + @{bin}/less rPx -> child-pager, + @{bin}/more rPx -> child-pager, + '.build/apparmor.d/pass' -> '/etc/apparmor.d/pass' + ``` + So, you can install the additional profiles `wl-copy`, `xclip`, `pass-import`, and `child-pager` if desired. -## Uninstall +## Uninstallation -- :material-arch: Arch Linux `sudo pacman -R apparmor.d` -- :material-ubuntu: Ubuntu & :material-debian: Debian `sudo apt purge apparmor.d` -- :simple-suse: openSUSE `sudo zypper remove apparmor.d` +=== ":material-arch: Archlinux" + + ```sh + sudo pacman -R apparmor.d + ``` + +=== ":material-ubuntu: Ubuntu" + + ```sh + sudo apt purge apparmor.d + ``` + +=== ":material-debian: Debian" + + ```sh + sudo apt purge apparmor.d + ``` + +=== ":simple-suse: openSUSE" + + ```sh + sudo zypper remove apparmor.d + ``` [aur]: https://aur.archlinux.org/packages/apparmor.d-git -[repo]: https://repo.pujol.io/ -[keys]: https://repo.pujol.io/gpgkey diff --git a/docs/report.md b/docs/report.md index e13ac9e9..e82d4e9e 100644 --- a/docs/report.md +++ b/docs/report.md @@ -11,25 +11,39 @@ When creating [an issue on Github][newissue], please post a link to the [paste] aa-log -R ``` -If this command produce nothing, try: +??? question "No logs with `aa-log`?" + + If the log file is empty, check that Auditd is running: + + ```sh + sudo systemctl status auditd.service + ``` + + If Auditd is disabled aa-log will not have new results, you can enable Auditd with: + + ```sh + sudo systemctl enable auditd.service --now + ``` + +If this command produces nothing, use `-s` to provide all logs since boot time (provided that `journalctl` collected them): ```sh aa-log -s -R ``` -If the log file is empty, check that Auditd is running: +??? question "No logs with `aa-log -s`?" + + On certain distributions/configurations, AppArmor logs in journal could be taken over by *auditd* when it is installed. To overcome this, `systemd-journald-audit.socket` could be enabled: + + ```sh + sudo systemctl enable systemd-journald-audit.socket + ``` + +You can get older logs with: + ```sh -sudo systemctl status auditd.service +aa-log -R -f ``` - -If Auditd is disabled aa-log will not have new results, you can enable Auditd by doing the following command: -```sh -sudo systemctl enable auditd.service --now -``` - -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 ` where `` is `1`, `2`, `3` and `4` (the rotated audit log file) +Where `` is `1`, `2`, `3` and `4` (the rotated audit log file). [newissue]: https://github.com/roddhjav/apparmor.d/issues/new [paste]: https://pastebin.com/ diff --git a/docs/usage.md b/docs/usage.md index 70eaaa29..9690733b 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -76,9 +76,9 @@ ps (complain) user ps auxZ ## AppArmor Log -Ensure that `Auditd` is installed and running on your system in order to read AppArmor log from `/var/log/audit/audit.log`. Then you can see the log with the provided command `aa-log` allowing you to review AppArmor generated messages in a colorful way. +Ensure that `Auditd` is installed and running on your system in order to read AppArmor log from `/var/log/audit/audit.log`. Then you can see the log with the provided command `aa-log` allowing you to review AppArmor generated messages in a colourful way. -Other AppArmor userspace tools such as `aa-enforce`, `aa-complain`, and `aa-logprof` should work as expected. +Other AppArmor userspace tools such as `aa-enforce`, `aa-complain`, and `aa-logprof` should work as expected. You can also configure [a desktop notification on denied actions](https://wiki.archlinux.org/title/AppArmor#Get_desktop_notification_on_DENIED_actions). ### Basic use diff --git a/docs/variables.md b/docs/variables.md index a7035826..b45df411 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -26,9 +26,10 @@ title: Variables References | Mail | `@{XDG_MAIL_DIR}` | `Mail .{m,M}ail` | | Sync | `@{XDG_SYNC_DIR}` | `Sync` | | Torrents | `@{XDG_TORRENTS_DIR}` | `Torrents` | -| Vm | `@{XDG_VM_DIR}` | `.vm` -| Vm Shares | `@{XDG_VM_SHARES_DIR}` | `VM_Shares` +| Vm | `@{XDG_VM_DIR}` | `.vm` | +| Vm Shares | `@{XDG_VM_SHARES_DIR}` | `VM_Shares` | | Disk images | `@{XDG_IMG_DIR}` | `images` | +| Games Studio | `@{XDG_GAMESSTUDIO_DIR}` | `.unity3d` | ### Dotfiles @@ -56,7 +57,7 @@ title: Variables References | Lib | `@{user_lib_dirs}` | `@{HOME}/@{XDG_LIB_DIR}` | | Share | `@{user_share_dirs}` | ` @{HOME}/@{XDG_DATA_DIR}` | | State | `@{user_state_dirs}` | ` @{HOME}/@{XDG_STATE_DIR}` | -| Build | `@{user_build_dirs}` | `/tmp/` | +| Build | `@{user_build_dirs}` | `/tmp//build/` | | Packages | `@{user_pkg_dirs}` | `/tmp/pkg/` | | Tmp | `@{user_tmp_dirs}` | `@{run}/user/@{uid} /tmp/` | @@ -80,9 +81,9 @@ title: Variables References | Templates | `@{user_templates_dirs}` | `@{HOME}/@{XDG_TEMPLATES_DIR} @{MOUNTS}/@{XDG_TEMPLATES_DIR}` | | Torrents | `@{user_torrents_dirs}` | `@{HOME}/@{XDG_TORRENTS_DIR} @{MOUNTS}/@{XDG_TORRENTS_DIR}` | | Sync | `@{user_sync_dirs}` | `@{HOME}/@{XDG_SYNC_DIR} @{MOUNTS}/*/@{XDG_SYNC_DIR}` | -| Vm | `@{user_vm_dirs}` | `@{HOME}/@{XDG_VM_DIR} @{MOUNTS}/@{XDG_VM_DIR}` -| Vm Shares | `@{user_vm_shares}` | `@{HOME}/@{XDG_VM_DIR} @{MOUNTS}/@{XDG_VM_DIR}` -| Disk images | `@{user_img_dirs}` | `@{HOME}/@{XDG_VM_SHARES_DIR} @{MOUNTS}/@{XDG_VM_SHARES_DIR}` | +| Vm | `@{user_vm_dirs}` | `@{HOME}/@{XDG_VM_DIR} @{MOUNTS}/@{XDG_VM_DIR}` | +| Vm Shares | `@{user_vm_shares}` | `@{HOME}/@{XDG_VM_SHARES_DIR} @{MOUNTS}/@{XDG_VM_SHARES_DIR}` | +| Disk images | `@{user_img_dirs}` | `@{HOME}/@{XDG_IMG_DIR} @{MOUNTS}/@{XDG_IMG_DIR}` | ## System variables diff --git a/mkdocs.yml b/mkdocs.yml index d72fd86b..67d8cc5a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,8 +43,10 @@ theme: - content.action.edit - content.code.annotate - content.code.copy + - content.tabs.link - content.tooltips - navigation.indexes + - navigation.instant - navigation.sections - navigation.tabs - navigation.top @@ -118,6 +120,9 @@ markdown_extensions: format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true + slugify: !!python/object/apply:pymdownx.slugs.slugify + kwds: + case: lower - pymdownx.tasklist: custom_checkbox: true @@ -130,13 +135,13 @@ nav: - install.md - configuration.md - usage.md + - report.md - Advanced: - variables.md - enforce.md - full-system-policy.md - Troubleshooting: - issues.md - - report.md - recovery.md - Development: - development/index.md