diff --git a/README.md b/README.md index cd53afd6..b1dc82fe 100644 --- a/README.md +++ b/README.md @@ -7,28 +7,27 @@ **Full set of AppArmor profiles** > **Warning**: This project is still in its early development. Help is very -> welcome see the [documentation website](https://apparmor.pujol.io/) including +> welcome; see the [documentation website](https://apparmor.pujol.io/) including > its [development](https://apparmor.pujol.io/development) section. ## Description -**AppArmor.d** is a set of over 1400 AppArmor profiles which aims is to confine -most of Linux base applications and processes. +**AppArmor.d** is a set of over 1400 AppArmor profiles whose aim is to confine +most Linux based applications and processes. **Purpose** - Confine all root processes such as all `systemd` tools, `bluetooth`, `dbus`, - `polkit`, `NetworkManager`, `OpenVPN`, `GDM`, `rtkit`, `colord`. + `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) **Goals** -- Target both desktop and server +- Target both desktops and servers - Support all distributions that support AppArmor: * Currently: - Archlinux @@ -37,6 +36,7 @@ most of Linux base applications and processes. * Not (yet) tested on openSUSE - Support all major desktop environments: * Currently only Gnome +- Fully tested (Work in progress) > This project is originaly based on the work from [Morfikov][upstream] and aims @@ -52,15 +52,15 @@ possible to write an AppArmor profile for all of them. Therefore, a question ari **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. +we apply it to the Linux world. Modern [Linux security distributions][clipos] usually +consider an immutable core base image with a carefully selected set of 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 +This is fundamentally different from how AppArmor is usually used on Linux servers as it is common to only confine the applications that face the internet and/or the users. diff --git a/docs/concepts.md b/docs/concepts.md index 14e5417e..1a6320db 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -12,15 +12,15 @@ possible to write an AppArmor profile for all of them. Therefore, a question ari **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. +we apply it to the Linux world. Modern [Linux security distributions][clipos] usually +consider an immutable core base image with a carefully selected set of 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 +This is fundamentally different from how AppArmor is usually used on Linux servers as it is common to only confine the applications that face the internet and/or the users. diff --git a/docs/configuration.md b/docs/configuration.md index f8b91307..0f375f07 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -21,7 +21,7 @@ echo 'Optimize=compress-fast' | sudo tee /etc/apparmor/parser.conf ## 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. +directories your programs have access by defining a few variables. The profiles heavily use the (largely extended) XDG directory variables defined in the **[Variables Reference](/variables)** page. @@ -48,7 +48,7 @@ in the **[Variables Reference](/variables)** page. | 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: +You can personalize these values by creating a file such as: `/etc/apparmor.d/tunables/xdg-user-dirs.d/local` where you define your own personal directories. Example: ```sh @@ -90,14 +90,17 @@ your rules in it. - `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: + URLs 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 + This is an example, no need to add Firefox into `child-open`, it is already there. + +!!! info + `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. diff --git a/docs/development/guidelines.md b/docs/development/guidelines.md index 96aee3fe..2506fed6 100644 --- a/docs/development/guidelines.md +++ b/docs/development/guidelines.md @@ -25,13 +25,13 @@ use of more variables. !!! 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. + This profile guideline is still evolving, feel free to propose improvements + as long as they do 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: +The rules in the profile should be sorted in the rule ***block*** as follows: - `include` - `set rlimit` @@ -54,7 +54,7 @@ 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 The file block should be sorted as follow: @@ -90,7 +90,7 @@ dbus send bus=session path=/org/freedesktop/DBus ``` If there is no predictable label it can be omitted. -### Profiles rules +### Profile rules `bin, sbin & lib` @@ -103,7 +103,7 @@ If there is no predictable label it can be omitted. `Sort` -: In a rule block, the rule shall be alphabetically sorted. +: In a rule block, the rules must be alphabetically sorted. `Sub profile` @@ -111,7 +111,7 @@ If there is no predictable label it can be omitted. `Similar purpose` -: When some file access share similar purpose, they may be sorted together. Eg: +: When some rules share similar purpose, they may be sorted together. Eg: ``` /etc/machine-id r, /var/lib/dbus/machine-id r, diff --git a/docs/development/index.md b/docs/development/index.md index 61b05c88..a7b0f523 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -4,14 +4,14 @@ title: Development # Development -You want to contribute to `apparmor.d`, **thank a lot for this.** Feedbacks, +You want to contribute to `apparmor.d`, **thanks 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. + 2. Fork this repo by clicking on the fork button on the top of the [project Github][project] page. 3. Clone the repository and go to the directory: ```sh git clone https://github.com/this-is-you/apparmor.d.git @@ -38,7 +38,7 @@ the useful information needed to contribute. `Rule 1: Mandatory Access Control` -: As these are mandatory access control policies only what it explicitly required +: As these are mandatory access control policies only what is explicitly required should be authorized. Meaning, you should **not** allow everything (or a large area) and blacklist some sub areas. @@ -93,6 +93,7 @@ profile foo @{exec_path} { [git]: https://help.github.com/articles/set-up-git/ +[project]: https://github.com/roddhjav/apparmor.d [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 diff --git a/docs/development/structure.md b/docs/development/structure.md index 28ce2f68..f0b0991b 100644 --- a/docs/development/structure.md +++ b/docs/development/structure.md @@ -5,10 +5,10 @@ title: Structure Description of common structure found across various AppArmor profiles -## Program to not confine +## Programs 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. +`ls`, `rm`, `diff` or `cat` do not have profiles 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 @@ -45,7 +45,7 @@ our profile: profile diff { ``` -* In `pass`, as it is a dependency of pass. Here `diff` inherit pass profile +* In `pass`, as it is a dependency of pass. Here `diff` inherits 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: @@ -66,8 +66,8 @@ 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` + 1. Do not a create profile for programs such as: `rm`, `ls`, `diff`, `cd`, `cat` + 2. Do not a create profile for the shell: `bash`, `sh`, `dash`, `zsh` 3. Use [Toolbox]. [project-rules]: /development/#project-rules @@ -106,9 +106,9 @@ the following note: Here is an overview of the current children profile: -1. **`child-open`**: To opens resources. Instead of allowing the run of all +1. **`child-open`**: To open 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 + programs 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. @@ -124,7 +124,7 @@ Here is an overview of the current children profile: 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 +Special care must be given as sometimes udev numbers are allocated dynamically by the kernel. Therefore, the full range must be allowed: !!! note "" diff --git a/docs/development/tests.md b/docs/development/tests.md index 95c7cd63..33f4d92a 100644 --- a/docs/development/tests.md +++ b/docs/development/tests.md @@ -10,8 +10,8 @@ Here is an overview of the current CI jobs: **On Gitlab CI** -- Packages build for all supported distribution -- Profiles preprocessing verification for all supported distribution +- Packages build for all supported distributions +- Profiles preprocessing verification for all supported distributions - Go based command linting, coverage, and unit tests **On Github Action** diff --git a/docs/enforce.md b/docs/enforce.md index 79221fb6..76b31fa6 100644 --- a/docs/enforce.md +++ b/docs/enforce.md @@ -5,7 +5,7 @@ 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. +Once you tested have 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 diff --git a/docs/index.md b/docs/index.md index 1050dec7..c1fc4ae8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,27 +8,26 @@ title: AppArmor.d !!! danger "Help Wanted" - This project is still in its early development. Help is very welcome + 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. +**AppArmor.d** is a set of over 1400 AppArmor profiles whose aim is to confine +most Linux based applications and processes. **Purpose** - Confine all root processes such as all `systemd` tools, `bluetooth`, `dbus`, - `polkit`, `NetworkManager`, `OpenVPN`, `GDM`, `rtkit`, `colord`. + `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 +- Target both desktops and servers - Support all distributions that support AppArmor: * Currently: - :material-arch: Archlinux @@ -37,3 +36,4 @@ See the [Concepts](concepts) page for more detail on the architecture. * Not (yet) tested on openSUSE - Support all major desktop environments: * Currently only :material-gnome: Gnome +- Fully tested (Work in progress) diff --git a/docs/install.md b/docs/install.md index 207e704e..395e945d 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,7 +4,7 @@ title: Installation !!! danger - In order to not break your system, the default package configuration install + In order to not break your system, the default package configuration installs all profiles in complain mode. They can be enforced later. See the [Enforce Mode](/enforce) page. diff --git a/docs/issues.md b/docs/issues.md index 24905ed9..76143ca5 100644 --- a/docs/issues.md +++ b/docs/issues.md @@ -25,9 +25,9 @@ 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 +allow access of your home directory. -This provides a basic protection against some package (on the AUR) that may have +This provides a basic protection against some packages (on the AUR) that may have rogue install script. [pacman]: https://github.com/roddhjav/apparmor.d/blob/master/apparmor.d/groups/pacman/pacman @@ -36,7 +36,7 @@ rogue install script. ### 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. +This is a known bug, help is very welcome. The complexity is that: