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

docs: rewrite the configuration section.

Browse Source
This commit is contained in:
Alexandre Pujol 2024-10-01 22:53:30 +01:00
parent 86719377a8
commit b51576139b
No known key found for this signature in database
GPG Key ID: C5469996F0DF68EC
6 changed files with 203 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/abbreviations.md Normal file
View File

@ -0,0 +1,3 @@
*[MAC]: Mandatory Access Control
*[AppArmor tunables]: AppArmor global variables

235
docs/configuration.md
View File

@ -2,107 +2,206 @@
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 -a /etc/apparmor/parser.conf
echo 'Optimize=compress-fast' | sudo tee -a /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 it to fit any system.
It is mostly done by setting personalized XDG like directories in AppArmor tunables. More advanced configuration can be done by adding your own rules in local profile addition.
!!! danger
You need to ensure that all personal directories you are using are well-defined XDG directory. You may need to edit these variables to your own settings.
You need to ensure that all personal directories you are using are well-defined XDG directory. You may need to edit these variables to your own settings.
This project is designed in such a way that it is easy to personalize the directories your programs have access by defining a few variables.
This part is vital to ensure that the profiles are correctly configured for your system. It will lead to breakage if not done correctly.
The profiles heavily use the (largely extended) XDG directory variables defined in the **[Variables Reference](variables.md)** page.
??? note "XDG variables overview"
## Personalize Apparmor
See **[Variables Reference](variables.md)** page for more.
### Tunables
| 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` |
The profiles heavily use the **largely extended** [XDG directory variables](#xdg-variables). All the variables are list you can append with your own values.
You can personalize these values.
1. First create the directory `/etc/apparmor.d/tunables/xdg-user-dirs.d/apparmor.d.d`:
```sh
sudo mkdir -p /etc/apparmor.d/tunables/xdg-user-dirs.d/apparmor.d.d
```
2. Then create a `local` addition file in it 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"
```
3. Then restart the AppArmor service to reload the profiles in the kernel:
```sh
sudo systemctl restart apparmor.service
```
First create the directory `/etc/apparmor.d/tunables/xdg-user-dirs.d/apparmor.d.d`:
```
sudo mkdir /etc/apparmor.d/tunables/xdg-user-dirs.d/apparmor.d.d
```
Then create a `local` addition file in it 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"
```
### Profile Additions
Then restart the AppArmor service to reload the profiles in the kernel:
```sh
sudo systemctl restart apparmor.service
```
You can extend any profile with your own rules by creating a file in the `/etc/apparmor.d/local/` directory with the name of the profile you want to personalize.
**Examples**
**Example**
By default, `nautilus` (and any file browser) only allows access to user files. Thus, your cannot browse system files such as `/etc/`, `/srv/`, `/var/`. You can change this behaviour by creating a local profile addition file for `nautilus`:
1. Create the file `/etc/apparmor.d/local/nautilus` and add the following rules in it:
```sh
/** r,
```
You call also restrict this to specific directories:
```sh
/etc/** r,
/srv/** r,
/var/** r,
```
2. Then restart the AppArmor service to reload the profiles in the kernel:
```sh
sudo systemctl restart apparmor.service
```
### XDG variables
Please ensure that all personal directories you are using are well-defined XDG directory defined below. If not, personalize the [variables](#tunables) to your own settings.
??? quote "**User directories**"
<figure markdown>
| Description | Name | Default Value(s) |
|-------------|------|---------------|
| Desktop | `@{XDG_DESKTOP_DIR}` | `Desktop` |
| Documents | `@{XDG_DOCUMENTS_DIR}` | `Documents` |
| Downloads | `@{XDG_DOWNLOAD_DIR}` | `Downloads` |
| Music | `@{XDG_MUSIC_DIR}` | `Music` |
| Pictures | `@{XDG_PICTURES_DIR}` | `Pictures` |
| Videos | `@{XDG_VIDEOS_DIR}` | `Videos` |
| Screenshots | `@{XDG_SCREENSHOTS_DIR}` | `@{XDG_PICTURES_DIR}/Screenshots` |
| Wallpapers | `@{XDG_WALLPAPERS_DIR}` | `@{XDG_PICTURES_DIR}/Wallpapers` |
| Books | `@{XDG_BOOKS_DIR}` | `Books` |
| Games | `@{XDG_GAMES_DIR}` | `.games` |
| Templates | `@{XDG_TEMPLATES_DIR}` | `Templates` |
| Public | `@{XDG_PUBLICSHARE_DIR}` | `Public` |
| Projects | `@{XDG_PROJECTS_DIR}` | `Projects` |
| Private | `@{XDG_PRIVATE_DIR}` | `.{p,P}rivate {p,P}rivate` |
| Work | `@{XDG_WORK_DIR}` | `Work` |
| Mail | `@{XDG_MAIL_DIR}` | `Mail .{m,M}ail` |
| Sync | `@{XDG_SYNC_DIR}` | `Sync` |
| Torrents | `@{XDG_TORRENTS_DIR}` | `Torrents` |
| Vm | `@{XDG_VM_DIR}` | `.vm` |
| Vm Shares | `@{XDG_VM_SHARES_DIR}` | `VM_Shares` |
| Disk images | `@{XDG_IMG_DIR}` | `images` |
| Games Studio | `@{XDG_GAMESSTUDIO_DIR}` | `.unity3d` |
</figure>
??? quote "**Dotfiles**"
<figure markdown>
| Description | Name | Default Value(s) |
|-------------|------|------------------|
| Cache | ` @{XDG_CACHE_DIR}` | `.cache` |
| Config | `@{XDG_CONFIG_DIR}` | `.config` |
| Data | `@{XDG_DATA_DIR}` | `.local/share` |
| State | `@{XDG_STATE_DIR}` | `.local/state` |
| Bin | `@{XDG_BIN_DIR}` | `.local/bin` |
| Lib | `@{XDG_LIB_DIR}` | `.local/lib` |
| GPG | `@{XDG_GPG_DIR}` | `.gnupg` |
| SSH | `@{XDG_SSH_DIR}` | `.ssh` |
| Private | `@{XDG_PRIVATE_DIR}` | `.{p,P}rivate {p,P}rivate` |
| Passwords | `@{XDG_PASSWORD_STORE_DIR}` | `.password-store` |
</figure>
??? quote "**Full configuration path**"
<figure markdown>
| Description | Name | Default Value(s) |
|-------------|:----:|---------------|
| Cache | `@{user_cache_dirs}` | `@{HOME}/@{XDG_CACHE_DIR}` |
| Config | `@{user_config_dirs}` | `@{HOME}/@{XDG_CONFIG_DIR}` |
| Bin | `@{user_bin_dirs}` | `@{HOME}/@{XDG_BIN_DIR}` |
| Lib | `@{user_lib_dirs}` | `@{HOME}/@{XDG_LIB_DIR}` |
| Share | `@{user_share_dirs}` | ` @{HOME}/@{XDG_DATA_DIR}` |
| State | `@{user_state_dirs}` | ` @{HOME}/@{XDG_STATE_DIR}` |
| Build | `@{user_build_dirs}` | `/tmp/build/` |
| Packages | `@{user_pkg_dirs}` | `/tmp/pkg/` |
</figure>
??? quote "**Full user path**"
<figure markdown>
| Description | Name | Default Value(s) |
|-------------|:----:|---------------|
| Documents | `@{user_documents_dirs}` | `@{HOME}/@{XDG_DOCUMENTS_DIR} @{MOUNTS}/@{XDG_DOCUMENTS_DIR}` |
| Downloads | `@{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}` |
| Videos | `@{user_videos_dirs}` | `@{HOME}/@{XDG_VIDEOS_DIR} @{MOUNTS}/@{XDG_VIDEOS_DIR}` |
| Books | `@{user_books_dirs}` | `@{HOME}/@{XDG_BOOKS_DIR} @{MOUNTS}/@{XDG_BOOKS_DIR}` |
| Games | `@{user_games_dirs}` | `@{HOME}/@{XDG_GAMES_DIR} @{MOUNTS}/@{XDG_GAMES_DIR}` |
| Private | `@{user_private_dirs}` | `@{HOME}/@{XDG_PRIVATE_DIR} @{MOUNTS}/@{XDG_PRIVATE_DIR}` |
| Passwords | `@{user_password_store_dirs}` | `@{HOME}/@{XDG_PASSWORD_STORE_DIR} @{MOUNTS}/@{XDG_PASSWORD_STORE_DIR}` |
| Work | `@{user_work_dirs}` | `@{HOME}/@{XDG_WORK_DIR} @{MOUNTS}/@{XDG_WORK_DIR}` |
| Mail | `@{user_mail_dirs}` | `@{HOME}/@{XDG_MAIL_DIR} @{MOUNTS}/@{XDG_MAIL_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}` |
| Templates | `@{user_templates_dirs}` | `@{HOME}/@{XDG_TEMPLATES_DIR} @{MOUNTS}/@{XDG_TEMPLATES_DIR}` |
| Torrents | `@{user_torrents_dirs}` | `@{HOME}/@{XDG_TORRENTS_DIR} @{MOUNTS}/@{XDG_TORRENTS_DIR}` |
| Sync | `@{user_sync_dirs}` | `@{HOME}/@{XDG_SYNC_DIR} @{MOUNTS}/*/@{XDG_SYNC_DIR}` |
| Vm | `@{user_vm_dirs}` | `@{HOME}/@{XDG_VM_DIR} @{MOUNTS}/@{XDG_VM_DIR}` |
| Vm Shares | `@{user_vm_shares}` | `@{HOME}/@{XDG_VM_SHARES_DIR} @{MOUNTS}/@{XDG_VM_SHARES_DIR}` |
| Disk images | `@{user_img_dirs}` | `@{HOME}/@{XDG_IMG_DIR} @{MOUNTS}/@{XDG_IMG_DIR}` |
</figure>
System variables can also be personalized, they are defined in the **[Variables Reference](variables.md)** page.
## Program Personalization
### Examples
All profiles use the variables defined above. Therefore, you can personalize them by setting your own values in `/etc/apparmor.d/tunables/xdg-user-dirs.d/apparmor.d.d/local`.
- 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
### Mountpoints
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.
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.
**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 URLs with Firefox, create the file `/etc/apparmor.d/local/child-open` with:
```sh
@{bin}/firefox rPx,
```
If you mount a disk on `/ssd/`, add the following to `/etc/apparmor.d/tunables/xdg-user-dirs.d/apparmor.d.d/local`:
```sh
@{MOUNT}+=/ssd/
```
!!! note
<!-- ### User data
This is an example, no need to add Firefox into `child-open`, it is already there.
!!! warning "TODO" -->
!!! info
### File browsers
`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.
All supported file browsers (`nautilus`, `dolphin`, `thunar`) are configured to only access user files. If you want to allow access to system files, you can create a local profile addition file for the file browser you are using.
### Games
Then, reload the AppArmor rules with `sudo systemctl restart AppArmor`.
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"`.
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.

11
docs/index.md
View File

@ -8,12 +8,11 @@ title: AppArmor.d
!!! danger "Help Wanted"
This project is still in its early development. Help is very welcome;
see [Development](development/index.md)
This project is still in its early development. Help is very welcome; see [Development](development/index.md)
**AppArmor.d** is a set of over 1500 AppArmor profiles whose aim is to confine most Linux based applications and processes.
**Purpose**
### Purpose
- Confine all root processes such as all `systemd` tools, `bluetooth`, `dbus`, `polkit`, `NetworkManager`, `OpenVPN`, `GDM`, `rtkit`, `colord`
- Confine all Desktop environments
@ -23,7 +22,7 @@ title: AppArmor.d
See the [Concepts](concepts.md)' page for more detail on the architecture.
**Goals**
### Goals
- Target both desktops and servers
- Support for all distributions that support AppArmor:
@ -37,13 +36,13 @@ See the [Concepts](concepts.md)' page for more detail on the architecture.
- [ ] :simple-xfce: XFCE (Lightdm) *(work in progress)*
- Fully tested *(work in progress)*
**Presentations**
### Presentations
Building the largest set of AppArmor profiles:
- [Linux Security Summit North America (LSS-NA 2023)](https://events.linuxfoundation.org/linux-security-summit-north-america/) *([Slide](https://lssna2023.sched.com/event/1K7bI/building-the-largest-working-set-of-apparmor-profiles-alexandre-pujol-the-collaboratory-tudublin), [Video](https://www.youtube.com/watch?v=OzyalrOzxE8))*
- [Ubuntu Summit 2023](https://events.canonical.com/event/31/) *([Slide](https://events.canonical.com/event/31/contributions/209/), [Video](https://www.youtube.com/watch?v=GK1J0TlxnFI))*
**Chat**
### Chat
A development chat is available on https://matrix.to/#/#apparmor.d:matrix.org

31
docs/install.md
View File

@ -10,13 +10,13 @@ title: Installation
Due to the development stage of this project, the default package configuration installs all profiles in **complain** mode. The recommended installation workflow is as-follow:
1. [Install](#installation) *apparmor.d* in the (default) complain mode.
1. Configure [apparmor settings](configuration.md#apparmor) as well as your [personal directories](configuration.md#personal-directories).
1. Ensure you have reloaded the profiles in the kernel: `sudo systemctl restart apparmor.service`.
1. **[Configure AppArmor](#configure-apparmor)** AppArmor for *apparmor.d*.
1. **[Install](#installation)** *apparmor.d* in the (default) complain mode.
1. **[Configure your personal directories](configuration.md)**.
1. Reboot your system.
1. You **must** check for any AppArmor logs with [`aa-log`](usage.md#apparmor-log).
1. [Report](https://apparmor.pujol.io/report/) any raised logs.
1. Use the profiles in complain mode for a while (a week), regularly check for new AppArmor logs.
1. **[Report](https://apparmor.pujol.io/report/)** any raised logs.
1. Use the profiles in *complain* mode for a while (a week), regularly check for new AppArmor logs.
1. Only if there are no logs raised for your daily usage, install it in [enforce mode](enforce.md).
@ -30,15 +30,25 @@ An `AppArmor` supported Linux distribution is required. The default profiles and
The following desktop environments are supported:
- [x] :material-gnome: Gnome (GDM)
- [x] :simple-kde: KDE (SDDM)
- [ ] :simple-xfce: XFCE (Lightdm) *(work in progress)*
- [x] :material-gnome: Gnome (GDM)
- [x] :simple-kde: KDE (SDDM)
- [ ] :simple-xfce: XFCE (Lightdm) *(work in progress)*
**Build dependency**
* Go >= 1.21
## Configure AppArmor
As there are a lot of rules (~80k lines), it is recommended to enable fast caching compression of AppArmor profiles. In `/etc/apparmor/parser.conf`, add `write-cache` and `Optimize=compress-fast`:
```sh
echo 'write-cache' | sudo tee -a /etc/apparmor/parser.conf
echo 'Optimize=compress-fast' | sudo tee -a /etc/apparmor/parser.conf
```
## Installation
=== ":material-arch: Archlinux"
@ -115,7 +125,7 @@ The following desktop environments are supported:
!!! warning
**Beware**: do not install a `.deb` made for Debian on Ubuntu, the packages are different.
**Beware**: do not install a `.deb` made for Ubuntu on Debian, the packages are different.
If your distribution is based on Debian, you may want to manually set the target distribution by exporting `DISTRIBUTION=debian`.
@ -154,6 +164,9 @@ The following desktop environments are supported:
So, you can install the additional profiles `wl-copy`, `xclip`, `pass-import`, and `child-pager` if desired.
[Next: Configure your personal directories](configuration.md){ .md-button .md-button--primary }
## Uninstallation
=== ":material-arch: Archlinux"

3
docs/usage.md
View File

@ -24,9 +24,10 @@ apparmor module is loaded.
...
30 processes are in complain mode.
...
0 processes are in prompt mode.
0 processes are in kill 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:

5
mkdocs.yml
View File

@ -70,6 +70,7 @@ plugins:
- minify:
minify_html: true
- git-committers:
enabled: !ENV [ENABLED_GIT_REVISION_DATE, true]
token: !ENV [MKDOCS_GIT_COMMITTERS_APIKEY]
repository: roddhjav/apparmor.d
branch: main
@ -116,7 +117,9 @@ markdown_extensions:
user: squidfunk
repo: mkdocs-material
- pymdownx.smartsymbols
- pymdownx.snippets
- pymdownx.snippets:
auto_append:
- docs/abbreviations.md
- pymdownx.superfences:
custom_fences:
- name: mermaid