mirror of
https://github.com/roddhjav/apparmor.d.git
synced 2024-11-14 23:43:56 +01:00
doc: most of the readme content have moved.
This commit is contained in:
Alexandre Pujol
parent
ecf82c7176
commit
14ff96a88a
282
README.md
282
README.md
@ -6,277 +6,95 @@
|
|||||||
|
|
||||||
**Full set of AppArmor profiles**
|
**Full set of AppArmor profiles**
|
||||||
|
|
||||||
> **Warning**: This project is still in early development. Help is very welcome
|
> **Warning**: This project is still in its early development. Help is very
|
||||||
> see [`CONTRIBUTING.md`](CONTRIBUTING.md)
|
> welcome see the [documentation website](https://apparmor.pujol.io/) including
|
||||||
|
> its [development](https://apparmor.pujol.io/development) section.
|
||||||
|
|
||||||
|
|
||||||
## Description
|
## Description
|
||||||
|
|
||||||
A set of over 1400 AppArmor profiles which aims is to confine most of Linux base
|
**AppArmor.d** is a set of over 1400 AppArmor profiles which aims is to confine
|
||||||
applications and processes.
|
most of Linux base applications and processes.
|
||||||
|
|
||||||
**Goals & Purpose**
|
**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)
|
||||||
|
|
||||||
|
**Goals**
|
||||||
|
|
||||||
|
- Target both desktop and server
|
||||||
- Support all distributions that support AppArmor:
|
- Support all distributions that support AppArmor:
|
||||||
* *Currently*: Archlinux, Debian 11 and the last Ubuntu LTS.
|
* Currently:
|
||||||
|
- Archlinux
|
||||||
|
- Ubuntu 22.04
|
||||||
|
- Debian 11
|
||||||
* Not (yet) tested on openSUSE
|
* Not (yet) tested on openSUSE
|
||||||
- Target both desktop and server,
|
- Support all major desktop environments:
|
||||||
- Confine all root processes. Eg: all systemd tools, bluetooth, dbus, polkit,
|
* Currently only Gnome
|
||||||
NetworkManager, OpenVPN, GDM, rtkit, colord...
|
|
||||||
- Confine all Desktop environments:
|
|
||||||
* *Currently only Gnome*, see `apparmor.d/groups/gnome`
|
|
||||||
- Confine all user services: Eg: 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),
|
|
||||||
|
|
||||||
> This project is based on the excellent work from [Morfikov][upstream] and aims
|
|
||||||
to extend it to more Linux distributions and desktop environements.
|
|
||||||
|
|
||||||
|
> This project is originaly based on the work from [Morfikov][upstream] and aims
|
||||||
|
> to extend it to more Linux distributions and desktop environements.
|
||||||
|
|
||||||
## Concepts
|
## Concepts
|
||||||
|
|
||||||
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?*
|
*One profile a day keeps the hacker away*
|
||||||
|
|
||||||
We take inspiration from the [Android/ChromeOS Security Model][android_model] and we apply it to the Linux world. Modern [linux security implementation][clipos] usually consider a 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...).
|
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:
|
||||||
|
|
||||||
This is fundamentally different from how AppArmor is used on Linux server as it is common to only confine the applications that face the internet and/or the users.
|
**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.
|
||||||
|
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
> **Warning**: In order to not break your system, the default package configuration install all profiles in complain mode. They can be enforced later. See [Enforce Mode](#enfore-mode)
|
Please see [apparmor.pujol.io/install](https://apparmor.pujol.io/install)
|
||||||
|
|
||||||
**Requirements**
|
## Configuration
|
||||||
* An `apparmor` based linux distribution.
|
|
||||||
* Base profiles and abstractions shipped with AppArmor are supposed to be
|
|
||||||
installed.
|
|
||||||
* Go (build dependency only)
|
|
||||||
* rsync (build dependency only)
|
|
||||||
|
|
||||||
**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
|
|
||||||
```
|
|
||||||
|
|
||||||
> **Note**: The overwrite options are only required on the first install. You can use `yay` or your preferred AUR install method to update it.
|
|
||||||
|
|
||||||
The `PKGBUILD` included in this repository is intended for development only.
|
|
||||||
|
|
||||||
**Debian / Ubuntu**
|
|
||||||
|
|
||||||
Build using standard Debian package build tools:
|
|
||||||
```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**
|
|
||||||
|
|
||||||
For test purpose, 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...
|
|
||||||
```
|
|
||||||
|
|
||||||
> **Note** 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 [#77](https://github.com/roddhjav/apparmor.d/issues/77))
|
|
||||||
|
|
||||||
|
Please see [apparmor.pujol.io/configuration](https://apparmor.pujol.io/configuration)
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
**Enabled profiles**
|
Please see [apparmor.pujol.io/usage](https://apparmor.pujol.io/usage)
|
||||||
|
|
||||||
Once installed and with the rules enabled, you can ensure the rules are loaded
|
|
||||||
with `sudo aa-satus`, it should give something like:
|
|
||||||
```
|
|
||||||
apparmor module is loaded.
|
|
||||||
1137 profiles are loaded.
|
|
||||||
794 profiles are in enforce mode.
|
|
||||||
...
|
|
||||||
343 profiles are in complain mode.
|
|
||||||
...
|
|
||||||
0 profiles are in kill mode.
|
|
||||||
0 profiles are in unconfined mode.
|
|
||||||
130 processes have profiles defined.
|
|
||||||
108 processes are in enforce mode.
|
|
||||||
...
|
|
||||||
22 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
|
|
||||||
`ps auxZ`. Most of the process should then be confined.
|
|
||||||
|
|
||||||
**AppArmor Log**
|
|
||||||
|
|
||||||
The provided command `aa-log` allow you review AppArmor generated messages in a
|
|
||||||
colorful way:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ aa-log
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
`aa-log` can optionally be given a profile name as argument to
|
|
||||||
only show the log for a given profile:
|
|
||||||
```
|
|
||||||
$ 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
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
## Personalisation
|
|
||||||
|
|
||||||
**AppArmor configuration**
|
|
||||||
|
|
||||||
As they are a lot of rules, it is recommended to enable caching AppArmor profiles.
|
|
||||||
In `/etc/apparmor/parser.conf`, uncomment `write-cache` and `Optimize=compress-fast`.
|
|
||||||
See [Speed up AppArmor Start] on the Arch Wiki for more information.
|
|
||||||
|
|
||||||
|
|
||||||
**Personal directories**
|
|
||||||
|
|
||||||
The profiles heavily use the XDG directory variables defined in `/etc/apparmor.d/tunables/xdg-user-dirs`. You can personalise these values with by creating a
|
|
||||||
file such as `/etc/apparmor.d/tunables/xdg-user-dirs.d/perso` with (for example)
|
|
||||||
the following content:
|
|
||||||
```sh
|
|
||||||
@{XDG_VIDEOS_DIR}+="Films"
|
|
||||||
@{XDG_MUSIC_DIR}+="Musique"
|
|
||||||
@{XDG_PICTURES_DIR}+="Images"
|
|
||||||
@{XDG_BOOKS_DIR}+="BD" "Comics"
|
|
||||||
@{XDG_PROJECTS_DIR}+="Git" "Papers"
|
|
||||||
```
|
|
||||||
|
|
||||||
**Local profiles**
|
|
||||||
|
|
||||||
You can extend a profile with your own rules by creating a file in the
|
|
||||||
`/etc/apparmor.d/local/` directory. For example, to extend the `gnome-shell`
|
|
||||||
profile, create a file `/etc/apparmor.d/local/gnome-shell` and add your rules.
|
|
||||||
Then, reload the apparmor rules with `sudo systemctl restart apparmor`.
|
|
||||||
|
|
||||||
|
|
||||||
## Enfore Mode
|
|
||||||
|
|
||||||
The default package configuration installs all profile 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` directory.
|
|
||||||
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
**AppArmor messages**
|
|
||||||
|
|
||||||
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 `aa-log`
|
|
||||||
|
|
||||||
|
|
||||||
**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 faultly, remove it: `rm /etc/apparmor.d/<profile-name>`
|
|
||||||
- Otherwise, you can also remove the package: `pacman -R apparmor.d`
|
|
||||||
- Alternativelly, you may temporarily disable apparmor as it will allow you to
|
|
||||||
boot and studdy the log: `systemctl disable apparmor`
|
|
||||||
1. Exit, umount, and reboot:
|
|
||||||
```sh
|
|
||||||
exit
|
|
||||||
umount -R /mnt
|
|
||||||
reboot
|
|
||||||
```
|
|
||||||
1. Create an issue and report the output of `aa-log`
|
|
||||||
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
A full test suite to ensure compatibility across distributions and softwares is still a work in progress.
|
|
||||||
|
|
||||||
Here is an overview of the current CI jobs:
|
|
||||||
|
|
||||||
**On Gitlab CI**
|
|
||||||
- Package build for all supported distribution
|
|
||||||
- Profiles preprocessing verification for all supported distribution
|
|
||||||
- Go based command linting and unit tests
|
|
||||||
|
|
||||||
**On Github Action**
|
|
||||||
- Integration test on the ubuntu-latest VM: run a simple list of tasks with
|
|
||||||
all the rules enabled and ensure no new issue has been raised. Github Action
|
|
||||||
is used as it offers a direct access to a VM with AppArmor included.
|
|
||||||
|
|
||||||
|
|
||||||
## Contribution
|
## Contribution
|
||||||
|
|
||||||
Feedbacks, contributors, pull requests are all very welcome. Please read the
|
Feedbacks, contributors, pull requests are all very welcome. Please read the
|
||||||
[`CONTRIBUTING.md`](CONTRIBUTING.md) file for more details on the contribution process.
|
https://apparmor.pujol.io/development for more details on the contribution process.
|
||||||
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
This program is based on Mikhail Morfikov's [apparmor profiles project][upstream] and thus has the same license (GPL2).
|
This Project was initially based on Mikhail Morfikov's [apparmor profiles project][upstream]
|
||||||
|
and thus has the same license (GPL2).
|
||||||
```
|
|
||||||
Copyright (C) Alexandre PUJOL & Mikhail Morfikov
|
|
||||||
|
|
||||||
This program is free software; you can redistribute it and/or modify
|
|
||||||
it under the terms of the GNU General Public License as published by
|
|
||||||
the Free Software Foundation; version 2 of the License.
|
|
||||||
|
|
||||||
This program is distributed in the hope that it will be useful,
|
|
||||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
||||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
||||||
GNU General Public License for more details.
|
|
||||||
|
|
||||||
You should have received a copy of the GNU General Public License along
|
|
||||||
with this program; if not, write to the Free Software Foundation, Inc.,
|
|
||||||
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
||||||
```
|
|
||||||
|
|
||||||
[upstream]: https://gitlab.com/morfikov/apparmemall
|
[upstream]: https://gitlab.com/morfikov/apparmemall
|
||||||
[project]: https://gitlab.com/roddhjav/apparmor.d
|
[project]: https://gitlab.com/roddhjav/apparmor.d
|
||||||
[build]: https://gitlab.com/roddhjav/apparmor.d/badges/master/pipeline.svg?style=flat-square
|
[build]: https://gitlab.com/roddhjav/apparmor.d/badges/main/pipeline.svg?style=flat-square
|
||||||
[workflow]: https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Froddhjav%2Fapparmor.d%2Fbadge&style=flat-square
|
[workflow]: https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Froddhjav%2Fapparmor.d%2Fbadge&style=flat-square
|
||||||
[action]: https://actions-badge.atrox.dev/roddhjav/apparmor.d/goto
|
[action]: https://actions-badge.atrox.dev/roddhjav/apparmor.d/goto
|
||||||
[quality]: https://img.shields.io/badge/go%20report-A+-brightgreen.svg?style=flat-square
|
[quality]: https://img.shields.io/badge/go%20report-A+-brightgreen.svg?style=flat-square
|
||||||
[goreportcard]: https://goreportcard.com/report/github.com/roddhjav/apparmor.d
|
[goreportcard]: https://goreportcard.com/report/github.com/roddhjav/apparmor.d
|
||||||
|
|
||||||
[aur]: https://aur.archlinux.org/packages/apparmor.d-git
|
|
||||||
[android_model]: https://arxiv.org/pdf/1904.05572
|
[android_model]: https://arxiv.org/pdf/1904.05572
|
||||||
[clipos]: https://clip-os.org/en/
|
[clipos]: https://clip-os.org/en/
|
||||||
[Speed up AppArmor Start]: https://wiki.archlinux.org/title/AppArmor#Speed-up_AppArmor_start_by_caching_profiles
|
|
||||||
[write xor execute]: https://en.wikipedia.org/wiki/W%5EX
|
[write xor execute]: https://en.wikipedia.org/wiki/W%5EX
|
||||||
|
|||||||
@ -4,7 +4,7 @@
|
|||||||
|
|
||||||
# Project information
|
# Project information
|
||||||
site_name: AppArmor.d
|
site_name: AppArmor.d
|
||||||
site_url: https://apparmord.pujol.io
|
site_url: https://apparmor.pujol.io
|
||||||
site_author: Alexandre Pujol
|
site_author: Alexandre Pujol
|
||||||
site_description: >-
|
site_description: >-
|
||||||
Full set of AppArmor profiles
|
Full set of AppArmor profiles
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user