mirror of
https://github.com/roddhjav/apparmor.d.git
synced 2024-11-15 07:54:17 +01:00
643a84997e
* Unbreaking Debian 11 and partially Ubuntu 22.04 * pre-cleanup * pre-cleanup2 * Update im-launch * Update gnome-extension-ding * polishing * not yet * Update ubuntu.flags Allow GDM to boot. `No new privs` fix. * Update debian.flags Allow GDM to boot. `No new privs` fix. * Update CONTRIBUTING.md * fixes * reverting w * move setpriv to main.flags
236 lines
8.5 KiB
Markdown
236 lines
8.5 KiB
Markdown
# Contributing
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
|
|
## Projects rules
|
|
|
|
A few rules:
|
|
1. 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 area.
|
|
2. 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 alway
|
|
exhaustive of the program features and required permissions.
|
|
|
|
|
|
## Add a profile
|
|
|
|
1. To add a new profile `foo`, add the file `foo` in `apparmor.d/profile-a-f`.
|
|
If your profile is part of a large group of profiles, it can also go in
|
|
`apparmor.d/groups`.
|
|
|
|
2. Write the profile content, the rules depend of the confined program,
|
|
Here is the bare minimum for the program `foo`:
|
|
```
|
|
# apparmor.d - Full set of apparmor profiles
|
|
# Copyright (C) 2022 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` and adding a new line with: `foo complain`
|
|
|
|
4. Build & install for your distribution.
|
|
|
|
|
|
## Profile Guidelines
|
|
|
|
**A common structure**
|
|
|
|
AppArmor profiles can be written without any specific guidelines. However, when
|
|
you work with over 1200 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 improvment
|
|
> 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 should
|
|
try to follow the guideline presented here.
|
|
|
|
The rules in the profile should be sorted as follow:
|
|
- include
|
|
- capability
|
|
- network
|
|
- mount
|
|
- remount
|
|
- umount
|
|
- pivot_root
|
|
- ptrace
|
|
- signal
|
|
- unix
|
|
- dbus (send, receive) send receice
|
|
- @{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`...
|
|
- Local include
|
|
|
|
|
|
**Other rules**
|
|
* 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/`.
|
|
* Always use the apparmor variables.
|
|
* In a rule block, the rule shall be alphabetically sorted.
|
|
* Subprofile should comes at the end of a profile.
|
|
* When some file access share similar purpose, they may be sorted together. Eg:
|
|
```
|
|
/etc/machine-id r,
|
|
/var/lib/dbus/machine-id r,
|
|
```
|
|
* For DBus, try to determine peer's label when possible. If there's no predictable label - it can be omited. 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),
|
|
```
|
|
|
|
The included tool `aa-log` can be useful to explore the apparmor log
|
|
|
|
## 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, instead of writting:
|
|
```sh
|
|
owner @{HOME}/@{XDG_DOWNLOAD_DIR}/{,**} rw,
|
|
```
|
|
to allow download directory access, you should write
|
|
|
|
```sh
|
|
include <abstractions/user-download-strict>
|
|
```
|
|
|
|
## AppArmor variables
|
|
|
|
**Included variables:**
|
|
|
|
* `@{PROC}=/proc/`
|
|
* `@{run}=/run/ /var/run/`
|
|
* `@{sys}=/sys/`
|
|
* The home root: `@{HOMEDIRS}=/home/`
|
|
* The home directories: `@{HOME}=@{HOMEDIRS}/*/ /root/`
|
|
* Process id(s): `@{pid}`, `@{pids}`
|
|
* User id: `@{uid}`
|
|
* Thread id: `@{tid}`
|
|
* Classic XDG user directories:
|
|
- 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"`
|
|
|
|
**Additional variables available with this project:**
|
|
|
|
* Mountpoints root: `@{MOUNTDIRS}=/media/ @{run}/media/ /mnt/`
|
|
* Common mountpoints: `@{MOUNTS}=@{MOUNTDIRS}/*/`
|
|
* Universally unique identifier: `@{uuid}=[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*`
|
|
* Hexadecimal: `@{hex}=[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]`
|
|
* Extended XDG user directories:
|
|
- 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"`
|
|
* Extended XDG dotfiles:
|
|
- SSH: `@{XDG_SSH_DIR}=".ssh"`
|
|
- GPG: `@{XDG_GPG_DIR}=".gnupg"`
|
|
- 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 path of the user configuration directories
|
|
- Cache: `@{user_cache_dirs}=@{HOME}/@{XDG_CACHE_HOME}`
|
|
- Config: `@{user_config_dirs}=@{HOME}/@{XDG_CONFIG_HOME}`
|
|
- Bin: `@{user_bin_dirs}=@{HOME}/@{XDG_BIN_HOME}`
|
|
- Lib: `@{user_lib_dirs}=@{HOME}/@{XDG_LIB_HOME}`
|
|
* Full path user directories
|
|
- 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}`
|
|
|
|
## Additional documentation
|
|
|
|
* https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference
|
|
* https://presentations.nordisch.org/apparmor/#/
|
|
|
|
[git]: https://help.github.com/articles/set-up-git/
|
|
[write xor execute]: https://en.wikipedia.org/wiki/W%5EX
|