From ecf82c71766f23a83dda6951d68f8bd684b2432e Mon Sep 17 00:00:00 2001 From: Alexandre Pujol Date: Sun, 29 Jan 2023 21:18:22 +0000 Subject: [PATCH] docs: initial documentation website. --- .gitlab-ci.yml | 17 ++++ docs/assets/favicon.png | Bin 0 -> 19010 bytes docs/concepts.md | 30 ++++++ docs/configuration.md | 106 ++++++++++++++++++++ docs/development/guidelines.md | 128 ++++++++++++++++++++++++ docs/development/index.md | 99 +++++++++++++++++++ docs/development/structure.md | 173 +++++++++++++++++++++++++++++++++ docs/enforce.md | 17 ++++ docs/index.md | 39 ++++++++ docs/install.md | 89 +++++++++++++++++ docs/issues.md | 46 +++++++++ docs/recovery.md | 27 +++++ docs/report.md | 14 +++ docs/usage.md | 121 +++++++++++++++++++++++ docs/variables.md | 97 ++++++++++++++++++ mkdocs.yml | 137 ++++++++++++++++++++++++++ requirements.txt | 3 + 17 files changed, 1143 insertions(+) create mode 100644 docs/assets/favicon.png create mode 100644 docs/concepts.md create mode 100644 docs/configuration.md create mode 100644 docs/development/guidelines.md create mode 100644 docs/development/index.md create mode 100644 docs/development/structure.md create mode 100644 docs/enforce.md create mode 100644 docs/index.md create mode 100644 docs/install.md create mode 100644 docs/issues.md create mode 100644 docs/recovery.md create mode 100644 docs/report.md create mode 100644 docs/usage.md create mode 100644 docs/variables.md create mode 100644 mkdocs.yml create mode 100644 requirements.txt diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 080a248b8..499ac9e3e 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -12,6 +12,7 @@ stages: - test - build - preprocess + - deploy # Code Linter @@ -128,3 +129,19 @@ preprocess-ubuntu: - apt-get install -y apparmor apparmor-profiles - dpkg --install $PKGDEST/* - apparmor_parser --preprocess /etc/apparmor.d 1> /dev/null + + +# Deploy the documentation +# ------------------------ + +pages: + stage: deploy + image: python + script: + - pip install -r requirements.txt + - mkdocs build --verbose --site-dir public + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..11ee3307f0fd4efff4f035ea4217c28f49197998 GIT binary patch literal 19010 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 + git commit -m "A message for sum up my contribution" + ``` + 6. Push changes to GitHub: + ``` + git push origin my_contribution + ``` + 7. 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. + + +## Project rules + +`Rule 1: Mandatory Access Control` + +: As these are mandatory access control policies only what it explicitly required + should be authorized. Meaning, you should **not** allow everything (or a large area) + and blacklist some sub areas. + +`Rule 2: Do not break a program` + +: A profile **should not break a normal usage of the confined software**. It can + be complex as simply running the program for your own use case is not always + exhaustive of the program features and required permissions. + +`Rule 3: Do not confine everything` + +: Some programs should not be confined by a MAC policy. + + + +## Add a profile + +!!! danger "Warning" + + Following the [profile guidelines](guidelines) 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 of the confined program, + Here is the bare minimum for the program `foo`: +``` sh +# apparmor.d - Full set of apparmor profiles +# Copyright (C) 2023 You +# SPDX-License-Identifier: GPL-2.0-only + +abi , + +include + +@{exec_path} = /{usr/,}bin/foo +profile foo @{exec_path} { + include + + @{exec_path} mr, + + include if exists +} +``` + + +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. + + +[git]: https://help.github.com/articles/set-up-git/ + +[flags]: https://github.com/roddhjav/apparmor.d/blob/master/dists/flags/main.flags +[profiles-a-f]: https://github.com/roddhjav/apparmor.d/blob/master/apparmor.d/profiles-a-f +[groups]: https://github.com/roddhjav/apparmor.d/blob/master/apparmor.d/groups diff --git a/docs/development/structure.md b/docs/development/structure.md new file mode 100644 index 000000000..28ce2f687 --- /dev/null +++ b/docs/development/structure.md @@ -0,0 +1,173 @@ +--- +title: Structure +--- + +Description of common structure found across various AppArmor profiles + + +## Program to not confine + +Some programs should not be confined by themselves. For example, tools such as +`ls`, `rm`, `diff` or `cat` do not have profile 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. + +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: + +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? +3. This breaks the principle of mandatory access control. + 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: `/{,usr/}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: + +!!! note "" + + [apparmor.d/apparmor.d/groups/apt/dpkg](https://github.com/roddhjav/apparmor.d/blob/accf5538bdfc1598f1cc1588a7118252884df50c/apparmor.d/groups/apt/dpkg#L123) + ``` aa linenums="123" + profile diff { + ``` + +* In `pass`, as it is a dependency of pass. Here `diff` inherit pass profile + and has the same access than the pass profile, so it will be allowed to diff + password files because more than a generic `diff` it is a `diff` for the pass + password manager: + +!!! note "" + + [apparmor.d/apparmor.d/profiles-m-r/pass](https://github.com/roddhjav/apparmor.d/blob/accf5538bdfc1598f1cc1588a7118252884df50c/apparmor.d/profiles-m-r/pass#L20 + ) + ``` aa linenums="20" + /{usr/,}bin/diff rix, + ``` + +**What if I still want to protect these programs?** + +You do not protect this program. *Protect the usage you have of these tools*. +In practice, it means that you should put your development's terminal in a +sandbox managed with [Toolbox] + +!!! example "To sum up" + + 1. Do not create profile for programs such as: `rm`, `ls`, `diff`, `cd`, `cat` + 2. Do not create profile for the shell: `bash`, `sh`, `dash`, `zsh` + 3. Use [Toolbox]. + +[project-rules]: /development/#project-rules +[Toolbox]: https://containertoolbx.org/ + + + +## Abstractions + +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 +owner @{HOME}/@{XDG_DOWNLOAD_DIR}/{,**} rw, +``` + +You should write: +```sh +include +``` + + +## Children profiles + +Usually, a child profile is in the [`children`][children] group. They have +the following note: + +!!! quote + + Note: This profile does not specify an attachment path because it is + intended to be used only via `"Px -> child-open"` exec transitions + from other profiles. + +[children]: https://github.com/roddhjav/apparmor.d/blob/master/apparmor.d/groups/children + +Here is an overview of the current children profile: + +1. **`child-open`**: To opens resources. Instead of allowing the run of all + software in `/{usr/,}bin/`, the purpose of this profile is to list all GUI + program 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 pager such as `pager`, `less` and `more`. + This profile supposes 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. + + +## Udev rules + +See the **[kernel docs][kernel]** to check the major block and char numbers used in `/run/udev/data/`. + +Special care must be given as some as sometime udev numbers are allocated +dynamically by the kernel. Therefore, the full range must be allowed: + +!!! note "" + + [apparmor.d/groups/virt/libvirtd](https://github.com/roddhjav/apparmor.d/blob/15e33a1fe6654f67a187cd5157c9968061b9511e/apparmor.d/groups/virt/libvirtd#L179-L184) + ``` aa linenums="179" + @{run}/udev/data/c23[4-9]:[0-9]* r, # For dynamic assignment range 234 to 254 + @{run}/udev/data/c24[0-9]:[0-9]* r, + @{run}/udev/data/c25[0-4]:[0-9]* r, + @{run}/udev/data/c3[0-9]*:[0-9]* r, # For dynamic assignment range 384 to 511 + @{run}/udev/data/c4[0-9]*:[0-9]* r, + @{run}/udev/data/c5[0-9]*:[0-9]* r, + ``` + +[kernel]: https://raw.githubusercontent.com/torvalds/linux/master/Documentation/admin-guide/devices.txt + + +## Full system policy + +!!! quote + + AppArmor is also capable of being used for full system policy + where processes are by default not running under the `unconfined` + profile. This might be useful for high security environments or + embedded systems. + + *Source: [AppArmor Wiki][apparmor-wiki]* + +This feature is only enabled when the `--full` option is passed to +the `configure` script. 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. + +!!! danger + + 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/master/apparmor.d/groups/_full diff --git a/docs/enforce.md b/docs/enforce.md new file mode 100644 index 000000000..79221fb6f --- /dev/null +++ b/docs/enforce.md @@ -0,0 +1,17 @@ +--- +title: Enforce Mode +--- + +# Enforce Mode + +The default package configuration installs all profiles in *complain* mode. +Once you tested them and it works fine, you can easily switch to *enforce* mode. +To do this, edit `PKGBUILD` on Archlinux or `debian/rules` on Debian and remove +the `--complain` option to the configure script. Then build the package as usual: +```diff +- ./configure --complain ++ ./configure +``` + +Do not worry, 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/master/dists/flags) directory. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..1050dec76 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,39 @@ +--- +title: AppArmor.d +--- + +# AppArmor.d + +**Full set of AppArmor profiles** + +!!! danger "Help Wanted" + + This project is still in its early development. Help is very welcome + see [Development](development/) + +**AppArmor.d** is a set of over 1400 AppArmor profiles which aims is to confine +most of Linux base applications and processes. + +**Purpose** + +- Confine all root processes such as all `systemd` tools, `bluetooth`, `dbus`, + `polkit`, `NetworkManager`, `OpenVPN`, `GDM`, `rtkit`, `colord`. +- Confine all Desktop environments +- Confine all user services such as `Pipewire`, `Gvfsd`, `dbus`, `xdg`, `xwayland` +- Confine some *"special"* user applications: web browser, file browser... +- Should not break a normal usage of the confined software +- Fully tested (Work in progress) + +See the [Concepts](concepts) page for more detail on the architecture. + +**Goals** + +- Target both desktop and server +- Support all distributions that support AppArmor: + * Currently: + - :material-arch: Archlinux + - :material-ubuntu: Ubuntu 22.04 + - :material-debian: Debian 11 + * Not (yet) tested on openSUSE +- Support all major desktop environments: + * Currently only :material-gnome: Gnome diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 000000000..207e704e7 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,89 @@ +--- +title: Installation +--- + +!!! danger + + In order to not break your system, the default package configuration install + 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. + +**Desktop environment** + +The following desktop environments are supported: + + - [x] :material-gnome: Gnome + +Also, please note wayland has better support than xorg. + +**Build dependencies** + +* Go +* Rsync + +## :material-arch: Archlinux + +`apparmor.d-git` is available in the [Arch User Repository][aur]: +```sh +git clone https://aur.archlinux.org/apparmor.d-git.git +cd apparmor.d-git +makepkg -s +sudo pacman -U apparmor.d-*.pkg.tar.zst \ + --overwrite etc/apparmor.d/tunables/global \ + --overwrite etc/apparmor.d/tunables/xdg-user-dirs \ + --overwrite etc/apparmor.d/abstractions/trash +``` + +The overwrite options are only required on the first install. You can use `yay` +or your preferred AUR install method to update it. + +!!! note + + The following Archlinux based distributions are supported: + + - [x] CachyOS + - [x] EndeavourOS + - [x] :material-manjaro: Manjaro Linux + + +## :material-ubuntu: 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_*_all.deb +``` + + +## Partial install + +!!! warning + + Partial installation is discouraged because profile dependencies are + not fetched. You may need to either switch desired `rPx` rules to `rPUx` + (fallback to unconfined) or install these related profiles. + (PR is welcome see [#77](https://github.com/roddhjav/apparmor.d/issues/77)) + +For test purposes, you can install a specific profile with the following commands. +Abstractions, tunables, and most of the OS dependent post-processing is managed. + +```sh +./configure --complain +make +sudo make profile-names... +``` + +[aur]: https://aur.archlinux.org/packages/apparmor.d-git +[repo]: https://repo.pujol.io/ +[keys]: https://repo.pujol.io/gpgkey diff --git a/docs/issues.md b/docs/issues.md new file mode 100644 index 000000000..24905ed9f --- /dev/null +++ b/docs/issues.md @@ -0,0 +1,46 @@ +--- +title: Known issues +--- + +# Known issues + +!!! info + + Known bugs are tracked on the meta issue **[#75](https://github.com/roddhjav/apparmor.d/issues/74)**. + + +### Pacman "could not get current working directory" + +```sh +$ sudo pacman -Syu +... +error: could not get current working directory +:: Processing package changes... +... +``` + +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. This is + +This provides a basic protection against some package (on the AUR) that may have +rogue install script. + +[pacman]: https://github.com/roddhjav/apparmor.d/blob/master/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 bugs help is very welcome. + +The complexity is that: + +- It works fine without AppArmor +- It works fine on most system (including test VM) +- It seems to be dbus related +- On archlinux, the dbus mediation is not enabled. So, there is nothing special to allow. diff --git a/docs/recovery.md b/docs/recovery.md new file mode 100644 index 000000000..48ec71e50 --- /dev/null +++ b/docs/recovery.md @@ -0,0 +1,27 @@ +--- +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: + +1. Boot from a Archlinux live USB +1. If you root partition is encryped, decrypt it: `cryptsetup open /dev/ vg0` +1. Mount your root partition: `mount /dev/ /mnt` +1. Chroot into your system: `arch-chroot /mnt` +1. Check the AppArmor messages to see what profile is faulty: `aa-log` +1. Temporarily fix the issue with either: + - When only one profile is faultily, remove it: `rm /etc/apparmor.d/` + - Otherwise, you can also remove the package: `pacman -R apparmor.d` + - Alternatively, you may temporarily disable apparmor as it will allow you to + boot and study the log: `systemctl disable apparmor` +1. Exit, unmount, and reboot: + ```sh + exit + umount -R /mnt + reboot + ``` +1. Create an issue and report the output of `aa-log` diff --git a/docs/report.md b/docs/report.md new file mode 100644 index 000000000..0507abc7b --- /dev/null +++ b/docs/report.md @@ -0,0 +1,14 @@ +--- +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. + +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 new file mode 100644 index 000000000..c0ae423aa --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,121 @@ +--- +title: Usage +--- + +## Enabled profiles + +Once installed and with the rules enabled, you can ensure the rules are loaded +with: +```sh +sudo aa-status +``` + +It should give something like: +``` +apparmor module is loaded. +1441 profiles are loaded. +112 profiles are in enforce mode. + ... +0 profiles are in kill mode. +0 profiles are in unconfined mode. +155 processes have profiles defined. +14 processes are in enforce mode. + ... +141 processes are in complain mode. + ... +0 processes are unconfined but have a profile defined. +0 processes are in mixed mode. +0 processes are in kill mode. +``` + +You can also list the current processes alongside with their security profile with: +```sh +ps auxZ +``` + +Most of the processes should then be confined: +``` +unconfined root /usr/lib/systemd/systemd --switched-root --system --deserialize 33 +systemd-udevd (complain) root /usr/lib/systemd/systemd-udevd +systemd-journald (complain) root /usr/lib/systemd/systemd-journald +rngd (complain) root /usr/bin/rngd -f +systemd-timesyncd (complain) systemd+ /usr/lib/systemd/systemd-timesyncd +auditd (complain) root /sbin/auditd +acpid (complain) root /usr/bin/acpid --foreground --netlink +dbus-daemon (complain) dbus /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only +power-profiles-daemon (complain) root /usr/lib/power-profiles-daemon +systemd-logind (complain) root /usr/lib/systemd/systemd-logind +systemd-machined (complain) root /usr/lib/systemd/systemd-machined +NetworkManager (complain) root /usr/bin/NetworkManager --no-daemon +polkitd (complain) polkitd /usr/lib/polkit-1/polkitd --no-debug +gdm (complain) root /usr/bin/gdm +accounts-daemon (complain) root /usr/lib/accounts-daemon +rtkit-daemon (complain) rtkit /usr/lib/rtkit-daemon +packagekitd (complain) root /usr/lib/packagekitd +colord (complain) colord /usr/lib/colord +unconfined user /usr/lib/systemd/systemd --user +unconfined user (sd-pam) +gdm-wayland-session (complain) user /usr/lib/gdm-wayland-session /usr/bin/gnome-session +gnome-session-binary (complain) user /usr/lib/gnome-session-binary +gnome-session-ctl (complain) user /usr/lib/gnome-session-ctl --monitor +gnome-session-binary (complain) user /usr/lib/gnome-session-binary --systemd-service --session=gnome +gnome-shell (complain) user /usr/bin/gnome-shell +... +ps (complain) user ps auxZ +``` + +??? info "Hide the kernel thread in `ps`" + + To hide the kernel thread in `ps` use `ps auxZ | grep -v '\[.*\]'`. You can + add an alias in your shell: + ```sh + alias p="ps auxZ | grep -v '\[.*\]'" + ``` + + +## 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. + +Other AppArmor userspace tools such as `aa-enforce`, `aa-complain`, and `aa-logprof` +should work as expected. + + +### Basic use + +To read the AppArmor log from `/var/log/audit/audit.log`: +```sh +aa-log +``` + +To optionally filter a given profile name: `aa-log ` (zsh will +autocomplete the profile name): +``` +aa-log dnsmasq +DENIED dnsmasq open /proc/sys/kernel/osrelease comm=dnsmasq requested_mask=r denied_mask=r +DENIED dnsmasq open /proc/1/environ comm=dnsmasq requested_mask=r denied_mask=r +DENIED dnsmasq open /proc/cmdline comm=dnsmasq requested_mask=r denied_mask=r +``` + +!!! info + + Other logs file in `/var/log/audit/` can easily be checked: `aa-log -f 1` + parses `/var/log/audit/audit.log.1`. + + +### Help + +``` +aa-log [-h] [-s] [-f file] [profile] + + Review AppArmor generated messages in a colorful way. + It can be given an optional profile name to filter the output with. + + -f file + Set a logfile or a suffix to the default log file. (default "/var/log/audit/audit.log") + -h Show this help message and exit. + -s Parse systemd dbus logs. +``` diff --git a/docs/variables.md b/docs/variables.md new file mode 100644 index 000000000..5b37ea19f --- /dev/null +++ b/docs/variables.md @@ -0,0 +1,97 @@ +--- +title: Variables References +--- + +## XDG directories + +### User directories + +| Description | Name | Value | +|-------------|:----:|---------| +| Desktop | `@{XDG_DESKTOP_DIR}` | `Desktop` | +| Download | `@{XDG_DOWNLOAD_DIR}` | `Downloads` | +| Templates | `@{XDG_TEMPLATES_DIR}` | `Templates` | +| Public | `@{XDG_PUBLICSHARE_DIR}` | `Public` | +| Documents | `@{XDG_DOCUMENTS_DIR}` | `Documents` | +| Music | `@{XDG_MUSIC_DIR}` | `Music` | +| Pictures | `@{XDG_PICTURES_DIR}` | `Pictures` | +| Videos | `@{XDG_VIDEOS_DIR}` | `Videos` | +| Books | `@{XDG_BOOKS_DIR}` | `Books` | +| Projects | `@{XDG_PROJECTS_DIR}` | `Projects` | +| Screenshots | `@{XDG_SCREENSHOTS_DIR}` | `@{XDG_PICTURES_DIR}/Screenshots` | +| Sync | `@{XDG_SYNC_DIR}` | `Sync` | +| Torrents | `@{XDG_TORRENTS_DIR}` | `Torrents` | +| Vm | `@{XDG_VM_DIR}` | `.vm` +| Wallpapers | `@{XDG_WALLPAPERS_DIR}` | `@{XDG_PICTURES_DIR}/Wallpapers` | + +### Dotfiles + +| Description | Name | Value | +|-------------|:----:|---------| +| SSH | `@{XDG_SSH_DIR}` | `.ssh` | +| GPG | `@{XDG_GPG_DIR}` | `.gnupg` | +| Passwords | `@{XDG_PASSWORD_STORE_DIR}` | `.password-store` | +| Cache | ` @{XDG_CACHE_HOME}` | `.cache` | +| Config | `@{XDG_CONFIG_HOME}` | `.config` | +| Data | `@{XDG_DATA_HOME}` | `.local/share` | +| Bin | `@{XDG_BIN_HOME}` | `.local/bin` | +| Lib | `@{XDG_LIB_HOME}` | `.local/lib` | + +### Full configuration path + +| Description | Name | Value | +|-------------|:----:|---------| +| Cache | `@{user_cache_dirs}` | `@{HOME}/@{XDG_CACHE_HOME}` | +| Config | `@{user_config_dirs}` | `@{HOME}/@{XDG_CONFIG_HOME}` | +| Share | `@{user_share_dirs}` | ` @{HOME}/.local/share/` | +| Bin | `@{user_bin_dirs}` | `@{HOME}/@{XDG_BIN_HOME}` | +| Lib | `@{user_lib_dirs}` | `@{HOME}/@{XDG_LIB_HOME}` | +| Build | `@{user_build_dirs}` | `/tmp/` | +| Tmp | `@{user_tmp_dirs}` | `@{run}/user/@{uid} /tmp/` | +| Packages | `@{user_pkg_dirs}` | `/tmp/pkg/` | + +### Full user path + +| Description | Name | Value | +|-------------|:----:|---------| +| Books | `@{user_books_dirs}` | `@{HOME}/@{XDG_BOOKS_DIR} @{MOUNTS}/@{XDG_BOOKS_DIR}` | +| Documents | `@{user_documents_dirs}` | `@{HOME}/@{XDG_DOCUMENTS_DIR} @{MOUNTS}/@{XDG_DOCUMENTS_DIR}` | +| Download | `@{user_download_dirs}` | `@{HOME}/@{XDG_DOWNLOAD_DIR} @{MOUNTS}/@{XDG_DOWNLOAD_DIR}` | +| Music | `@{user_music_dirs}` | `@{HOME}/@{XDG_MUSIC_DIR} @{MOUNTS}/@{XDG_MUSIC_DIR}` | +| Pictures | `@{user_pictures_dirs}` | `@{HOME}/@{XDG_PICTURES_DIR} @{MOUNTS}/@{XDG_PICTURES_DIR}` | +| Projects | `@{user_projects_dirs}` | `@{HOME}/@{XDG_PROJECTS_DIR} @{MOUNTS}/@{XDG_PROJECTS_DIR}` | +| Public | `@{user_publicshare_dirs}` | `@{HOME}/@{XDG_PUBLICSHARE_DIR} @{MOUNTS}/@{XDG_PUBLICSHARE_DIR}` | +| Sync | `@{user_sync_dirs}` | `@{HOME}/@{XDG_SYNC_DIR} @{MOUNTS}/*/@{XDG_SYNC_DIR}` | +| Templates | `@{user_templates_dirs}` | `@{HOME}/@{XDG_TEMPLATES_DIR} @{MOUNTS}/@{XDG_TEMPLATES_DIR}` | +| Torrents | `@{user_torrents_dirs}` | `@{HOME}/@{XDG_TORRENTS_DIR} @{MOUNTS}/@{XDG_TORRENTS_DIR}` | +| Videos | `@{user_videos_dirs}` | `@{HOME}/@{XDG_VIDEOS_DIR} @{MOUNTS}/@{XDG_VIDEOS_DIR}` | +| Vm | `@{user_vm_dirs}` | `@{HOME}/@{XDG_VM_DIR} @{MOUNTS}/@{XDG_VM_DIR}` +| Password | `@{user_password_store_dirs}` | `@{HOME}/@{XDG_PASSWORD_STORE_DIR} @{MOUNTS}/@{XDG_PASSWORD_STORE_DIR}` | + + +## System variables + +!!! warning + + Do not modify these variables unless you know what you are doing + +| Description | Name | Value | +|-------------|:----:|---------| +| Root Home | `@{HOMEDIRS}` | `/home/` | +| Home directories | `@{HOME}` | `@{HOMEDIRS}/*/ /root/` | +| Current Process id | `@{pid}` | `[0-9]*` | +| Processes ids | `@{pids}` | `[0-9]*` | +| User id | `@{uid}` | `[0-9]*` | +| Thread id | `@{tid}` | `[0-9]*` | +| Root Mountpoints | `@{MOUNTDIRS}` | `/media/ @{run}/media/ /mnt/` | +| Mountpoints directories | `@{MOUNTS}` | `@{MOUNTDIRS}/*/` | +| Universally unique identifier | `@{uuid}` | `[0-9a-fA-F]*-[0-9a-fA-F]*-[0-9a-fA-F]*-[0-9a-fA-F]*-[0-9a-fA-F]*` | +| Hexadecimal | `@{hex}` | `[0-9a-fA-F]*` | +| Libexec *(Archlinux)* | `@{libexec}` | `/{usr/,}lib` | +| Libexec *(Debian/Ubuntu)* | `@{libexec}` | `/{usr/,}libexec` | +| multi-arch library | `@{multiarch}` | `*-linux-gnu*` | +| Proc | `@{PROC}` | `/proc/` | +| Run | `@{run}` | `/run/ /var/run/` | +| 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` | diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..3b8f3fc74 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,137 @@ +# apparmor.d - Full set of apparmor profiles +# Copyright (c) 2021-2023 Alexandre Pujol +# SPDX-License-Identifier: GPL-2.0-only + +# Project information +site_name: AppArmor.d +site_url: https://apparmord.pujol.io +site_author: Alexandre Pujol +site_description: >- + Full set of AppArmor profiles + +# Repository +repo_name: roddhjav/apparmor.d +repo_url: https://github.com/roddhjav/apparmor.d +edit_uri: edit/main/docs/ + +# Copyright +copyright: Copyright © 2021-2023 Alexandre Pujol + +# Configuration +theme: + name: material + logo: assets/favicon.png + favicon: assets/favicon.png + palette: + - scheme: default + primary: white + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + - scheme: slate + primary: brown + accent: deep orange + toggle: + icon: material/brightness-4 + name: Switch to light mode + icon: + repo: fontawesome/brands/github + edit: material/file-edit-outline + view: material/file-eye-outline + features: + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + - navigation.expand + - navigation.footer + - navigation.indexes + - navigation.sections + - navigation.tabs + - navigation.top + - search.highlight + - search.share + - search.suggest + +# Plugins +plugins: + - search + - git-revision-date-localized: + enable_creation_date: true + fallback_to_build_date: true + +# Customization +extra: + social: + - icon: fontawesome/brands/twitter + link: https://twitter.com/roddhjav + - icon: fontawesome/brands/github + link: https://github.com/roddhjav/apparmor.d + - icon: fontawesome/brands/gitlab + link: https://gitlab.com/roddhjav/apparmor.d + - icon: fontawesome/solid/up-right-from-square + link: https://pujol.io + +# Extensions +markdown_extensions: + - abbr + - admonition + - attr_list + - def_list + - footnotes + - md_in_html + - toc: + permalink: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.mark + - pymdownx.tilde + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.keys + - pymdownx.magiclink: + repo_url_shorthand: true + user: squidfunk + repo: mkdocs-material + - pymdownx.smartsymbols + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + +# Page tree +nav: + - Home: + - index.md + - Getting Started: + - concepts.md + - install.md + - configuration.md + - usage.md + - Advanced: + - variables.md + - enforce.md + - Troubleshooting: + - issues.md + - report.md + - recovery.md + - Development: + - development/index.md + - Architecture: + - development/guidelines.md + - development/structure.md + - Tests: + - development/tests.md diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 000000000..80b68e38b --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +mkdocs +mkdocs-git-revision-date-localized-plugin +mkdocs-material