docs: add development workflow.

roddhjav · Oct 2, 2024 · 9112c64 · 9112c64
1 parent baad12a
commit 9112c64
Show file tree

Hide file tree

Showing 13 changed files with 514 additions and 275 deletions.
diff --git a/docs/abbreviations.md b/docs/abbreviations.md
@@ -1,3 +1,5 @@
 
 *[MAC]: Mandatory Access Control
+*[W^X]: Write XOR Execute
+*[FSP]: Full System Policy
 *[AppArmor tunables]: AppArmor global variables
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -181,9 +181,9 @@ All profiles use the variables defined above. Therefore, you can personalize the
     @{user_pkg_dirs}+=@{user_cache_dirs}/yay/
     ```
 
-### Mountpoints
+### Mount points
 
-Common mountpoints are defined in the `@{MOUNTS}` variable. If you mount a disk on a different location, you can add it to the `@{MOUNTS}` variable.
+Common mount points are defined in the `@{MOUNTS}` variable. If you mount a disk on a different location, you can add it to the `@{MOUNTS}` variable.
 
 **Example**
 
@@ -202,6 +202,6 @@ All supported file browsers (`nautilus`, `dolphin`, `thunar`) are configured to
 
 ### Games
 
-In order to not allow access to user data, game profiles use the `@{XDG_GAMESSTUDIO_DIR}` variable. It may needs to be expanded with other game studio directory. The default is `@{XDG_GAMESSTUDIO_DIR}="unity3d"`.
+In order to not allow access to user data, game profiles use the `@{XDG_GAMESSTUDIO_DIR}` variable. It may need to be expanded with other game studio directory. The default is `@{XDG_GAMESSTUDIO_DIR}="unity3d"`.
 
-The `@{XDG_GAMES_DIR}` variable is used to define the game directory such as steam storage directory. If your steam storage is on another drive/mountpoint, you should personalize `@{user_games_dirs}` instead.
+The `@{XDG_GAMES_DIR}` variable is used to define the game directory such as steam storage directory. If your steam storage is on another drive, you should personalize `@{user_games_dirs}` instead.
diff --git a/docs/development/abstractions.md b/docs/development/abstractions.md
@@ -137,7 +137,8 @@ A minimal set of rules for profiles including internal `pkexec`. Like `app/sudo`
 
 ### **`app/systemctl`**
 
-An alternative solution for [child-systemctl](structure.md#children-profiles), when the child profile provides too much/not enough access. This abstraction should be used by a sub profile as follows:
+An alternative solution for [child-systemctl](internal.md#children-profiles), when the child profile provides too much/not enough access. This abstraction should be used by a sub profile as follows:
+
 ```sh
   @{bin}/systemctl  rCx ->  systemctl,
 

diff --git a/docs/development/guidelines.md b/docs/development/guidelines.md
@@ -11,7 +11,7 @@ The logic behind it is that if a rule is present in a profile, it should only be
 For example, if a program needs to run executable binaries then 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. 
+* A profile enforces a strict [write xor execute](https://en.wikipedia.org/wiki/W%5EX) (W^X) policy. 
 
 It also improves compatibilities and makes personalization easier thanks to the use of more variables.
 
@@ -132,14 +132,3 @@ If there is no predictable label it can be omitted.
     ```
     Does not help, and if generalized it would add a lot of complexity to any profiles.
 
-
-## 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)
-* https://documentation.suse.com/sles/12-SP5/html/SLES-all/cha-apparmor-intro.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)
-
-[write xor execute]: https://en.wikipedia.org/wiki/W%5EX
diff --git a/docs/development/index.md b/docs/development/index.md
@@ -4,31 +4,38 @@ title: Development
 
 If you're looking to contribute to `apparmor.d` you can get started by going to the project [GitHub repository](https://github.com/roddhjav/apparmor.d/)! All contributions are welcome no matter how small. In this page you will find all the useful information needed to contribute to the apparmor.d project.
 
-??? info "How to contribute pull requests"
+??? info "How to contribute pull requests?"
 
     1. If you don't have git on your machine, [install it](https://help.github.com/articles/set-up-git/).
-    2. Fork this repo by clicking on the fork button on the top of the [project GitHub][project] page.
-    3. Clone the forked repository and go to the directory:
+    1. Fork this repo by clicking on the fork button on the top of the [project GitHub](https://github.com/roddhjav/apparmor.d) page.
+    1. [Generate a new SSH key](    https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) and add it to your GitHub account.
+    1. Clone the forked repository and go to the directory:
     ```sh
-    git clone https://github.com/your-github-username/apparmor.d.git
+    git clone git@github.com:your-github-username/apparmor.d.git 
     cd apparmor.d
     ```
-    4. Create a branch:
+    1. Create a branch:
     ```
     git checkout -b my_contribution
     ```
-    5. Make the changes and commit:
+    1. Make the changes and commit:
     ```
     git add <files changed>
     git commit -m "A message to sum up my contribution"
     ```
-    6. Push changes to GitHub:
+    1. Push changes to GitHub:
     ```
     git push origin my_contribution
     ```
-    7. Submit your changes for review: If you go to your repository on GitHub,
+    1. Submit your changes for review: If you go to your repository on GitHub,
     you'll see a Compare & pull request button, fill and submit the pull request.
 
+<div class="grid cards" markdown>
+
+-   :material-arrow-right: &nbsp; **[See the workflow to write profiles](workflow.md)**
+
+</div>
+
 
 ## Project rules
 
@@ -55,48 +62,11 @@ If you're looking to contribute to `apparmor.d` you can get started by going to
     your devices or for your use case.
 
 
-## Add a profile
-
-!!! danger "Warning"
-
-    Following the [profile guidelines](guidelines.md) is **mandatory** for all new profiles.
-
-
-1. To add a new profile `foo`, add the file `foo` in [`apparmor.d/profile-a-f`][profiles-a-f]. 
-   If your profile is part of a large group of profiles, it can also go in
-   [`apparmor.d/groups`][groups].
-
-2. Write the profile content, the rules depend on the confined program,
-   Here is the bare minimum for the program `foo`:
-``` sh
-# apparmor.d - Full set of apparmor profiles
-# Copyright (C) 2024 You <your@email>
-# SPDX-License-Identifier: GPL-2.0-only
-
-abi <abi/3.0>,
-
-include <tunables/global>
-
-@{exec_path} = @{bin}/foo
-profile foo @{exec_path} {
-  include <abstractions/base>
-
-  @{exec_path} mr,
-
-  include if exists <local/foo>
-}
-
-# vim:syntax=apparmor
-```
-
-
-3. You can automatically set the `complain` flag on your profile by editing the file [`dists/flags/main.flags`][flags] and add a new line with: `foo complain`
-
-4. Build & install for your distribution.
-
-
-[project]: https://github.com/roddhjav/apparmor.d
+## Additional recommended documentation
 
-[flags]: https://github.com/roddhjav/apparmor.d/blob/main/dists/flags/main.flags
-[profiles-a-f]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/profiles-a-f
-[groups]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups
+* [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)
+* https://documentation.suse.com/sles/12-SP5/html/SLES-all/cha-apparmor-intro.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/development/install.md b/docs/development/install.md
diff --git a/docs/development/integration.md b/docs/development/integration.md
@@ -74,7 +74,7 @@ All the images come pre-configured with the latest version of `apparmor.d` insta
 
 **Usage**
 
-On all images, `aa-update` can be used to rebuild and install the latest version of the profiles. `p`, `pf`, and `pu` are two preconfigured aliases of `ps` that show the security status of processes. `htop` is also configured to show this status.
+On all images, `aa-update` can be used to rebuild and install the latest version of the profiles. `p`, `pf`, and `pu` are two pre-configured aliases of `ps` that show the security status of processes. `htop` is also configured to show this status.
 
 
 ## Tests
@@ -118,7 +118,7 @@ Start the tests and collect the results
 
 **Tests manifest**
 
-A basic set of test is generated on initialisation. More tests can be manually written in yaml file. They must have the following structure:
+A basic set of test is generated on initialization. More tests can be manually written in yaml file. They must have the following structure:
 
 ```yaml
 - name: acpi