doc: cosmetic.

docs/development/guidelines.md

@@ -4,22 +4,17 @@ title: Guidelines
 
 ## Common structure
 
-AppArmor profiles can be written without any specific guidelines. However,
+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. 
-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
+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:
-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
+It also improves compatibilities and makes personalization easier thanks to the use of more variables.
-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**
+In order to ensure a common structure across the profiles, all new profile **must** follow the guidelines presented here.
-follow the guidelines presented here.
 
 The rules in the profile should be sorted in the rule ***block*** as follows:
 

docs/development/index.md

@@ -4,9 +4,7 @@ title: Development
 
 # Development
 
-You want to contribute to `apparmor.d`, **thanks a lot for this.** Feedbacks, 
+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.
-contributors, pull requests are all very welcome. You will find in this page all
-the useful information needed to contribute.
 
 ??? info "How to contribute"
 

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
+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.
-`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
+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.
-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
+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:
-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
+However, as `/etc` can contain sensitive files, we now want to explicitly prevent access to these sensitive files. Problems:
-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.
+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:
-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
+This project and the apparmor profile official project provide a large selection of abstractions to be included in profiles. They should be used.
-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 <abstractions/user-download-strict>
 
 ## Children profiles
 
-Usually, a child profile is in the [`children`][children] group. They have 
+Usually, a child profile is in the [`children`][children] group. They have  the following note:
-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
+Chromium based browsers share a similar structure. Therefore, they share the same abstraction: [`abstractions/chromium`][chromium] that includes most of the profile content.
-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
+@{name} = chromium
-@{chromium_domain} = org.chromium.Chromium
+@{domain} = org.chromium.Chromium
-@{chromium_lib_dirs} = @{lib}/chromium
+@{lib_dirs} = @{lib}/chromium
-@{chromium_config_dirs} = @{user_config_dirs}/chromium
+@{config_dirs} = @{user_config_dirs}/chromium
-@{chromium_cache_dirs} = @{user_cache_dirs}/chromium
+@{cache_dirs} = @{user_cache_dirs}/chromium
 ```
 
-If your application requires chromium to run (like electron) use
+If your application requires chromium to run (like electron) use [`abstractions/chromium-common`][chromium-common] instead.
-[`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
+Special care must be given as sometimes udev numbers are allocated dynamically by the kernel. Therefore, the full range must be allowed:
-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
+All core required applications that need to be started by systemd (both as user or root) need to be present in these profiles.
-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
+    Full system policy is still under early development, do not run it outside a development VM! **You have been warned!!!**
-    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

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
+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:
-still a work in progress.
-Here is an overview of the current CI jobs:
 
 **On Gitlab CI**
 

docs/install.md

@@ -4,16 +4,13 @@ title: Installation
 
 !!! danger
 
-    In order to not break your system, the default package configuration installs
+    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.
-    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
+An `apparmor` based Linux distribution is required. The basic profiles and abstractions shipped with AppArmor must be installed.
-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.
+For test purposes, you can install specific profiles with the following commands. Abstractions, tunables, and most of the OS dependent post-processing is managed.
-Abstractions, tunables, and most of the OS dependent post-processing is managed.
 
 ```sh
 make

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
+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.
-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
+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.
-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
+This provides a basic protection against some packages (on the AUR) that may have rogue install script.
-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.
+[Gnome](https://github.com/roddhjav/apparmor.d/issues/80) can be slow to start. This is a known bug, help is very welcome.
-This is a known bug, help is very welcome.
 
 The complexity is that:
 

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
+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:
-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/<your-disk-id> vg0`

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
+The **[aa-log](/usage/#apparmor-log)** tool reports all AppArmor `DENIED` and `ALLOWED`. It should be used to fix AppArmor related issues.
-`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,
+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.
-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
+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`.
-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/

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
+Once installed and with the rules enabled, you can ensure the rules are loaded with:
-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
+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
-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`
+Other AppArmor userspace tools such as `aa-enforce`, `aa-complain`, and `aa-logprof` should work as expected.
-should work as expected.
 
 
 ### Basic use

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**