diff --git a/docs/abbreviations.md b/docs/abbreviations.md new file mode 100644 index 000000000..f99a4f70c --- /dev/null +++ b/docs/abbreviations.md @@ -0,0 +1,3 @@ + +*[MAC]: Mandatory Access Control +*[AppArmor tunables]: AppArmor global variables diff --git a/docs/configuration.md b/docs/configuration.md index e784dcb82..f2f1d3722 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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**" + +
+ + | 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` | + +
+ +??? quote "**Dotfiles**" + +
+ + | 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` | + +
+ +??? quote "**Full configuration path**" + +
+ + | 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/` | + +
+ +??? quote "**Full user path**" + +
+ + | 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}` | + +
+ +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 + -!!! 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. diff --git a/docs/index.md b/docs/index.md index b57bae7a3..8f5696074 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 diff --git a/docs/install.md b/docs/install.md index 5d84331ce..91b0b4ae6 100644 --- a/docs/install.md +++ b/docs/install.md @@ -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" diff --git a/docs/usage.md b/docs/usage.md index 9690733b1..e73439efc 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -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: diff --git a/mkdocs.yml b/mkdocs.yml index 404905913..689785a31 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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