mirrors/apparmor.d
1
0
Fork 0
mirror of https://github.com/roddhjav/apparmor.d.git synced 2024-12-24 14:06:47 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: initial documentation website.

Browse source
This commit is contained in:
Alexandre Pujol 2023-01-29 21:18:22 +00:00
parent 3c3f164e91
commit ecf82c7176
Failed to generate hash of commit
17 changed files with 1143 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
.gitlab-ci.yml
View file

@ -12,6 +12,7 @@ stages:
- test - test
- build - build
- preprocess - preprocess
- deploy
# Code Linter # Code Linter
@ -128,3 +129,19 @@ preprocess-ubuntu:
- apt-get install -y apparmor apparmor-profiles - apt-get install -y apparmor apparmor-profiles
- dpkg --install $PKGDEST/* - dpkg --install $PKGDEST/*
- apparmor_parser --preprocess /etc/apparmor.d 1> /dev/null - 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

BIN
docs/assets/favicon.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 19 KiB

30
docs/concepts.md Normal file
View file

@ -0,0 +1,30 @@
---
title: Concepts
---
# Concepts
*One profile a day keeps the hacker away*
There are over 50000 Linux packages and even more applications. It is simply not
possible to write an AppArmor profile for all of them. Therefore, a question arises:
**What to confine and why?**
We take inspiration from the [Android/ChromeOS Security Model][android_model] and
we apply it to the Linux world. Modern [Linux security distribution][clipos] usually
consider an immutable core base image with a carefully set of selected applications.
Everything else should be sandboxed. Therefore, this project tries to confine all
the *core* applications you will usually find in a Linux system: all systemd services,
xwayland, network, bluetooth, your desktop environment... Non-core user applications
are out of scope as they should be sandboxed using a dedicated tool (minijail,
bubblewrap, toolbox...).
This is fundamentally different from how AppArmor is usually used on Linux server
as it is common to only confine the applications that face the internet and/or the users.
[android_model]: https://arxiv.org/pdf/1904.05572
[clipos]: https://clip-os.org/en/
[write xor execute]: https://en.wikipedia.org/wiki/W%5EX

106
docs/configuration.md Normal file
View file

@ -0,0 +1,106 @@
---
title: Configuration
---
## AppArmor
As there are a lot of rules, it is recommended to enable caching AppArmor profiles.
In `/etc/apparmor/parser.conf`, add `write-cache` and `Optimize=compress-fast`.
```sh
echo 'write-cache' | sudo tee /etc/apparmor/parser.conf
echo 'Optimize=compress-fast' | sudo tee /etc/apparmor/parser.conf
```
!!! info
See [Speed up AppArmor Start] on the Arch Wiki for more information:
[Speed up AppArmor Start]: https://wiki.archlinux.org/title/AppArmor#Speed-up_AppArmor_start_by_caching_profiles
## Personal directories
This project is designed in such a way that it is easy to personalize the
directory your program can access by defining a few variables.
The profiles heavily use the (largely extended) XDG directory variables defined
in the **[Variables Reference](/variables)** page.
??? note "XDG variables overview"
See **[Variables Reference](/variables)** page for more.
| 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` |
You can personalize these values with by creating a file such as:
`/etc/apparmor.d/tunables/xdg-user-dirs.d/local` where you define your own
personal directories. Example:
```sh
@{XDG_VIDEOS_DIR}+="Films"
@{XDG_MUSIC_DIR}+="Musique"
@{XDG_PICTURES_DIR}+="Images"
@{XDG_BOOKS_DIR}+="BD" "Comics"
@{XDG_PROJECTS_DIR}+="Git" "Papers"
```
Then restart the apparmor service to reload the profiles in the kernel:
```sh
sudo systemctl restart apparmor.service
```
**Examples**
- For git support, you may want to add your `GO_PATH` in the `XDG_PROJECTS_DIR`:
```sh
@{XDG_PROJECTS_DIR}+="go"
```
- If you use Keepass, personalize `XDG_PASSWORD_STORE_DIR` with your password directory. Eg:
```sh
@{XDG_PASSWORD_STORE_DIR}+="@{HOME}/.keepass/"
```
- Add pacman integration with your AUR helper. Eg for `yay`:
```sh
@{user_pkg_dirs}+=@{user_cache_dirs}/yay/
```
## Local profile extensions
You can extend any profile with your own rules by creating a file in the
`/etc/apparmor.d/local/` directory with the name of your profile. For example,
to extend the `foo` profile, create a file `/etc/apparmor.d/local/foo` and add
your rules in it.
**Example**
- `child-open`, a profile that allows other program to open resources (URL,
picture, books...) with some predefined GUI application. To allow it to open
URL with Firefox, create the file `/etc/apparmor.d/local/child-open` with:
```sh
/{usr/,}bin/firefox rPx,
```
**NB:** This is an example, no need to add Firefox into `child-open`, it is already there.
!!! note
`rPx` allows transition to the Firefox profile. Use `rPUx` to allow
transition to an unconfined state if you do not have the profile for a
given program.
Then, reload the apparmor rules with `sudo systemctl restart apparmor`.

128
docs/development/guidelines.md Normal file
View file

@ -0,0 +1,128 @@
---
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.
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:
* 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.
## Guidelines
!!! note
This profile guideline is still evolving, feel free to propose improvement
as long as it does 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.
The rules in the profile should be sorted in rule ***block*** as follow:
- `include`
- `set rlimit`
- `capability`
- `network`
- `mount`
- `remount`
- `umount`
- `pivot_root`
- `change_profile`
- `signal`
- `ptrace`
- `unix`
- `dbus`
- `file`
- local include
This rule order is taken from AppArmor with minor changes as we tend to:
- Divide the file block in multiple subcategories
- Put the block with the longer rules (`files`, `dbus`) after the other blocks
### The file blocks
The file block should be sorted as follow:
- `@{exec_path} mr`, the entry point of the profile
- The binaries and library required:
- `/{usr/,}bin/`, `/{usr/,}lib/`, `/opt/`...
- It is the only place where you can have `mr`, `rix`, `rPx`, `rUx`, `rPUX` rules.
- The shared resources: `/usr/share`...
- The system configuration: `/etc`...
- The system data: `/var`...
- The user data: `owner @{HOME}/`...
- The user configuration, cache and in general all dotfiles
- Temporary and runtime data: `/tmp/`, `@{run}/`, `/dev/shm/`...
- Sys files: `@{sys}/`...
- Proc files: `@{PROC}/`...
- Dev files: `/dev/`...
- Deny rules: `deny`...
### The dbus block
The dbus block should be sorted as follow:
- The system bus should be sorted *before* the session bus
- The bind rules should be sorted *after* the send & receive rules
For DBus, try to determine peer's label when possible. E.g.:
```
dbus send bus=session path=/org/freedesktop/DBus
interface=org.freedesktop.DBus
member={RequestName,ReleaseName}
peer=(name=org.freedesktop.DBus, label=dbus-daemon),
```
If there is no predictable label it can be omitted.
### Profiles rules
`bin, sbin & lib`
: - Do not use: `/usr/lib` or `/usr/bin` but `/{usr/,}bin/` or `/{usr/,}lib/`
- Do not use: `/usr/sbin` or `/sbin` but `/{usr/,}{s,}bin/`.
`Variables`
: Always use the apparmor variables.
`Sort`
: In a rule block, the rule shall be alphabetically sorted.
`Sub profile`
: Sub profile should comes at the end of a profile.
`Similar purpose`
: When some file access share similar purpose, they may be sorted together. Eg:
```
/etc/machine-id r,
/var/lib/dbus/machine-id r,
```
## Additional recommended documentation
* [The AppArmor Core Policy Reference](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference)
* [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

99
docs/development/index.md Normal file
View file

@ -0,0 +1,99 @@
---
title: Development
---
# Development
You want to contribute to `apparmor.d`, **thank 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"
1. If you don't have git on your machine, [install it][git].
2. Fork this repo by clicking on the fork button on the top of this page.
3. Clone the repository and go to the directory:
```sh
git clone https://github.com/this-is-you/apparmor.d.git
cd apparmor.d
```
4. Create a branch:
```
git checkout -b my_contribution
```
5. Make the changes and commit:
```
git add <files changed>
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 <your@email>
# SPDX-License-Identifier: GPL-2.0-only
abi <abi/3.0>,
include <tunables/global>
@{exec_path} = /{usr/,}bin/foo
profile foo @{exec_path} {
include <abstractions/base>
@{exec_path} mr,
include if exists <local/foo>
}
```
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

173
docs/development/structure.md Normal file
View file

@ -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 <abstractions/user-download-strict>
```
## 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

17
docs/enforce.md Normal file
View file

@ -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.

39
docs/index.md Normal file
View file

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

89
docs/install.md Normal file
View file

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

46
docs/issues.md Normal file
View file

@ -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.

27
docs/recovery.md Normal file
View file

@ -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/<your-disk-id> vg0`
1. Mount your root partition: `mount /dev/<your-plain-disk-id> /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/<profile-name>`
- 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`

14
docs/report.md Normal file
View file

@ -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/

121
docs/usage.md Normal file
View file

@ -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 <profile-name>` (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.
```

97
docs/variables.md Normal file
View file

@ -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` |

137
mkdocs.yml Normal file
View file

@ -0,0 +1,137 @@
# apparmor.d - Full set of apparmor profiles
# Copyright (c) 2021-2023 Alexandre Pujol <alexandre@pujol.io>
# 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 &copy; 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

3
requirements.txt Normal file
View file

@ -0,0 +1,3 @@
mkdocs
mkdocs-git-revision-date-localized-plugin
mkdocs-material