From 4d9430b6bed4244b571450bf91693bdfabece8ef Mon Sep 17 00:00:00 2001 From: Alexandre Pujol Date: Tue, 19 Sep 2023 19:18:15 +0100 Subject: [PATCH] doc: cosmetic. --- docs/development/guidelines.md | 14 +++------ docs/development/index.md | 4 +-- docs/development/structure.md | 54 ++++++++++++---------------------- docs/development/tests.md | 4 +-- docs/install.md | 10 ++----- docs/issues.md | 14 +++------ docs/recovery.md | 4 +-- docs/report.md | 9 ++---- docs/usage.md | 10 ++----- docs/variables.md | 3 ++ 10 files changed, 42 insertions(+), 84 deletions(-) diff --git a/docs/development/guidelines.md b/docs/development/guidelines.md index b3ca2709..4ba8d31e 100644 --- a/docs/development/guidelines.md +++ b/docs/development/guidelines.md @@ -4,22 +4,17 @@ title: Guidelines ## Common structure -AppArmor profiles can be written without any specific guidelines. However, -when you work with over 1400 profiles, you need a common structure among all the -profiles. +AppArmor profiles can be written without any specific guidelines. However, when you work with over 1400 profiles, you need a common structure among all the profiles. The logic behind it is that if a rule is present in a profile, it should only be in one place, making profile review easier. -For example, if a program needs to run executables binary. The rules allowing it -can only be in a specific rule block (just after the `@{exec_path} mr,` rule). It -is therefore easy to ensure some profile features such as: +For example, if a program needs to run executables binary. The rules allowing it can only be in a specific rule block (just after the `@{exec_path} mr,` rule). It is therefore easy to ensure some profile features such as: * A profile has access to a given resource * A profile enforces a strict [write xor execute] (W^X) policy. -It also improves compatibilities and makes personalization easier thanks to the -use of more variables. +It also improves compatibilities and makes personalization easier thanks to the use of more variables. ## Guidelines @@ -28,8 +23,7 @@ use of more variables. This profile guideline is still evolving, feel free to propose improvements as long as they do not vary too much from the existing rules. -In order to ensure a common structure across the profiles, all new profile **must** -follow the guidelines presented here. +In order to ensure a common structure across the profiles, all new profile **must** follow the guidelines presented here. The rules in the profile should be sorted in the rule ***block*** as follows: diff --git a/docs/development/index.md b/docs/development/index.md index 4d2b8f43..d0c34eff 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -4,9 +4,7 @@ title: Development # Development -You want to contribute to `apparmor.d`, **thanks a lot for this.** Feedbacks, -contributors, pull requests are all very welcome. You will find in this page all -the useful information needed to contribute. +You want to contribute to `apparmor.d`, **thanks a lot for this.** Feedbacks, contributors, pull requests are all very welcome. You will find in this page all the useful information needed to contribute. ??? info "How to contribute" diff --git a/docs/development/structure.md b/docs/development/structure.md index a7658fbd..eed8b012 100644 --- a/docs/development/structure.md +++ b/docs/development/structure.md @@ -7,21 +7,16 @@ Description of common structure found across various AppArmor profiles ## Programs to not confine -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. +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 theater. -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: +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 /etc/{,**} rw, ``` -However, as `/etc` can contain sensitive files, we now want to explicitly -prevent access to these sensitive files. Problems: +However, as `/etc` can contain sensitive files, we now want to explicitly prevent access to these sensitive files. Problems: 1. How do we know the exhaustive list of *sensitive files* in `/etc`? 2. How do we ensure access to these sensitive files are not required? @@ -29,11 +24,7 @@ prevent access to these sensitive files. Problems: See the [first rule of this project][project-rules] that is to only allow what is required. Here we allow everything and blacklist some paths. -It creates even more issues when we want to use this profile in other profiles. -Let's take the example of `diff`. Using this rule: `@{bin}/diff rPx,` will -restrict access to the very generic and not very confined `diff` profile. -Whereas most of the time, we want to restrict `diff` to some specific file in -our profile: +It creates even more issues when we want to use this profile in other profiles. Let's take the example of `diff`. Using this rule: `@{bin}/diff rPx,` will restrict access to the very generic and not very confined `diff` profile. Whereas most of the time, we want to restrict `diff` to some specific file in our profile: * In `dpkg`, an internal child profile (`rCx -> diff`), allows `diff` to only access etc config files: @@ -95,8 +86,7 @@ sandbox managed with [Toolbox] ## Abstractions -This project and the apparmor profile official project provide a large selection -of abstractions to be included in profiles. They should be used. +This project and the apparmor profile official project provide a large selection of abstractions to be included in profiles. They should be used. For instance, to allow download directory access, instead of writing: ```sh @@ -111,8 +101,7 @@ include ## Children profiles -Usually, a child profile is in the [`children`][children] group. They have -the following note: +Usually, a child profile is in the [`children`][children] group. They have the following note: !!! quote @@ -140,20 +129,18 @@ Here is an overview of the current children profile: ## Browsers -Chromium based browsers share a similar structure. Therefore, they share the same -abstraction: [`abstractions/chromium`][chromium] that includes most of the profile content. +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 definied in the profile header: ```sh -@{chromium_name} = chromium -@{chromium_domain} = org.chromium.Chromium -@{chromium_lib_dirs} = @{lib}/chromium -@{chromium_config_dirs} = @{user_config_dirs}/chromium -@{chromium_cache_dirs} = @{user_cache_dirs}/chromium +@{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. +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 @@ -162,8 +149,7 @@ If your application requires chromium to run (like electron) use See the **[kernel docs][kernel]** to check the major block and char numbers used in `/run/udev/data/`. -Special care must be given as sometimes udev numbers are allocated -dynamically by the kernel. Therefore, the full range must be allowed: +Special care must be given as sometimes udev numbers are allocated dynamically by the kernel. Therefore, the full range must be allowed: !!! note "" @@ -191,13 +177,12 @@ dynamically by the kernel. Therefore, the full range must be allowed: *Source: [AppArmor Wiki][apparmor-wiki]* -This feature is only enabled when the profiles are built with `make full`. The profiles for full system policies are maintained in the **[`_full`][_full]** group. It consists of two extra main profiles: +This feature is only enabled when the profiles are built with `make full`. The profiles for full system policies are maintained in the **[`_full`][full]** group. It consists of two extra main profiles: 1. **`init`**: For systemd as PID 1 2. **`systemd`**: For systemd as user -All core required applications that need to be started by systemd (both as user -or root) need to be present in these profiles. +All core required applications that need to be started by systemd (both as user or root) need to be present in these profiles. Early policy load should also be enabled. In `/etc/apparmor/parser.conf` ``` @@ -206,9 +191,8 @@ cache-loc /etc/apparmor/earlypolicy/ !!! danger - Full system policy is still under early development, do not run it outside a - development VM! **You have been warned!!!** + Full system policy is still under early development, do not run it outside a development VM! **You have been warned!!!** [apparmor-wiki]: https://gitlab.com/apparmor/apparmor/-/wikis/FullSystemPolicy -[_full]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/_full +[full]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/_full diff --git a/docs/development/tests.md b/docs/development/tests.md index 33f4d92a..1bd4b81a 100644 --- a/docs/development/tests.md +++ b/docs/development/tests.md @@ -4,9 +4,7 @@ title: Tests suite # Tests suite -A full test suite to ensure compatibility across distributions and software is -still a work in progress. -Here is an overview of the current CI jobs: +A full test suite to ensure compatibility across distributions and software is still a work in progress. Here is an overview of the current CI jobs: **On Gitlab CI** diff --git a/docs/install.md b/docs/install.md index daa38863..22e13692 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,16 +4,13 @@ title: Installation !!! danger - In order to not break your system, the default package configuration installs - all profiles in complain mode. They can be enforced later. - See the [Enforce Mode](/enforce) page. + In order to not break your system, the default package configuration installs all profiles in complain mode. They can be enforced later. See the [Enforce Mode](/enforce) page. ## Requirements **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 basic profiles and abstractions shipped with AppArmor must be installed. **Desktop environment** @@ -74,8 +71,7 @@ zypper install apparmor.d ## Partial install -For test purposes, you can install specific profiles with the following commands. -Abstractions, tunables, and most of the OS dependent post-processing is managed. +For test purposes, you can install specific profiles with the following commands. Abstractions, tunables, and most of the OS dependent post-processing is managed. ```sh make diff --git a/docs/issues.md b/docs/issues.md index b2d90e80..c21e0d34 100644 --- a/docs/issues.md +++ b/docs/issues.md @@ -25,24 +25,18 @@ error: could not get current working directory ... ``` -This is **a feature, not a bug!** It can safely be ignored. Pacman tries to get -your current directory. You will only get this error when you run pacman in your -home directory. +This is **a feature, not a bug!** It can safely be ignored. Pacman tries to get your current directory. You will only get this error when you run pacman in your home directory. -According the Archlinux guideline, on Archlinux, packages cannot install files -under `/home/`. Therefore the [`pacman`][pacman] profile purposely does not -allow access of your home directory. +According the Archlinux guideline, on Archlinux, packages cannot install files under `/home/`. Therefore the [`pacman`][pacman] profile purposely does not allow access of your home directory. -This provides a basic protection against some packages (on the AUR) that may have -rogue install script. +This provides a basic protection against some packages (on the AUR) that may have rogue install script. [pacman]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/pacman/pacman ### Gnome can be very slow to start. -[Gnome](https://github.com/roddhjav/apparmor.d/issues/80) can be slow to start. -This is a known bug, help is very welcome. +[Gnome](https://github.com/roddhjav/apparmor.d/issues/80) can be slow to start. This is a known bug, help is very welcome. The complexity is that: diff --git a/docs/recovery.md b/docs/recovery.md index 48ec71e5..96bf26c9 100644 --- a/docs/recovery.md +++ b/docs/recovery.md @@ -4,9 +4,7 @@ title: System Recovery # System Recovery -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 process to recover your system on Archlinux: +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 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` diff --git a/docs/report.md b/docs/report.md index e4ac5f6b..529cefc2 100644 --- a/docs/report.md +++ b/docs/report.md @@ -4,14 +4,11 @@ title: Report AppArmor logs # Report AppArmor logs -The **[aa-log](/usage/#apparmor-log)** tool reports all AppArmor `DENIED` and -`ALLOWED`. It should be used to fix AppArmor related issues. +The **[aa-log](/usage/#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`. +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`. [newissue]: https://github.com/roddhjav/apparmor.d/issues/new [paste]: https://pastebin.com/ diff --git a/docs/usage.md b/docs/usage.md index 34cb04a2..a9b52b86 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -4,8 +4,7 @@ title: Usage ## Enabled profiles -Once installed and with the rules enabled, you can ensure the rules are loaded -with: +Once installed and with the rules enabled, you can ensure the rules are loaded with: ```sh sudo aa-status ``` @@ -75,13 +74,10 @@ 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 +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. -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. ### Basic use diff --git a/docs/variables.md b/docs/variables.md index 54d32c6a..8faa4676 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -94,6 +94,9 @@ title: Variables References | Thread id | `@{tid}` | `[0-9]*` | | Single hexadecimal character | `@{h}` | `[0-9a-fA-F]` | | Single alphanumeric character | `@{c}` | `[0-9a-zA-Z]` | +| PCI Devices | `@{pci}` | `@{pci_bus}/**/` | +| PCI Bus | `@{pci_bus}` | `pci@{h}@{h}@{h}@{h}:@{h}@{h}` | +| PCI Id | `@{pci_id}` | `@{h}@{h}@{h}@{h}:@{h}@{h}:@{h}@{h}.@{h}` | **System Paths**