felipe/apparmor.d
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc: general update.

Browse source
This commit is contained in:
Alexandre Pujol 2024-08-30 20:38:30 +01:00
parent fe32720765
commit fb29e8ba74
No known key found for this signature in database
GPG key ID: C5469996F0DF68EC
14 changed files with 350 additions and 223 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/development/dbus.md
View file

@ -26,6 +26,14 @@ Access to common dbus interfaces is done using the abstractions under **[`abstra
For more access, simply use the [`aa:dbus talk`](#dbus-directive) directive.
There is a trade of between security and maintenance to make:
- `aa:dbus talk` will generate less issue as it give full talk access
- `abstractions/bus/*` will provide more restriction, and possibly more issue.
Ideally, these rules should be automatically generated from either the dbus interface documentation or the program call.
## Dbus Directive
We use a special [directive](directives.md) to generate more advanced dbus access. The directive format is on purpose very similar to the AppArmor dbus rule.

19
docs/development/guidelines.md
View file

@ -78,7 +78,7 @@ The file block should be sorted as follows:
The dbus block should be sorted as follows:
- The system bus should be sorted *before* the session bus
- The bind rules should be sorted *after* the send & receive rules
- The bind rules should be sorted *after* send & receive rules
For DBus, try to determine peer's label when possible. E.g.:
```
@ -115,6 +115,23 @@ If there is no predictable label it can be omitted.
/var/lib/dbus/machine-id r,
```
#### :material-numeric-5-circle: Limit the use of `deny`
: The use of `deny` should be limited to the minimum:
- In MAC policies, we only allow access ([Rule :material-numeric-1-circle:](index.md#rule-mandatory-access-control "Mandatory Access Control"))
- `deny` rules are enforced even in complain mode,
- If it works on your machine does not mean it will work on others ([Rule :material-numeric-4-circle:](index.md#rule-distribution-and-devices-agnostic "Distribution and devices agnostic")).
#### :material-numeric-6-circle: Comments
: Ensure you only have useful comments. E.g.:
```
# Config files for foo
owner @{user_config_dirs}/foo/{,**} r,
```
Does not help, and if generalized it would add a lot of complexity to any profiles.
## Additional recommended documentation

2
docs/development/index.md
View file

@ -70,7 +70,7 @@ If you're looking to contribute to `apparmor.d` you can get started by going to
Here is the bare minimum for the program `foo`:
``` sh
# apparmor.d - Full set of apparmor profiles
# Copyright (C) 2023 You <your@email>
# Copyright (C) 2024 You <your@email>
# SPDX-License-Identifier: GPL-2.0-only
abi <abi/3.0>,

47
docs/development/install.md
View file

@ -11,28 +11,39 @@ title: Installation
See `debian/`, `PKGBUILD` and `dists/apparmor.d.spec`.
**:material-docker: Docker**
=== ":material-arch: Archlinux"
For any system with docker installed you can simply build the package with:
```sh
make package dist=<distribution>
```
Then you can install the package with `dpkg`, `pacman` or `rpm`.
```sh
make pkg
```
**:material-arch: Arch Linux**
```sh
make pkg
```
=== ":material-ubuntu: Ubuntu"
**:material-ubuntu: Ubuntu & :material-debian: Debian**
```sh
make dpkg
```
```sh
make dpkg
```
**:simple-suse: openSUSE**
```sh
make rpm
```
=== ":material-debian: Debian"
```sh
make dpkg
```
=== ":simple-suse: openSUSE"
```sh
make rpm
```
=== ":material-docker: Docker"
For any system with docker installed you can simply build the package with:
```sh
make package dist=<distribution>
```
Then you can install the package with `dpkg`, `pacman` or `rpm`.
## Profile flags

41
docs/development/structure.md
View file

@ -9,7 +9,7 @@ Description of common structure found across various AppArmor profiles
Some programs should not be confined by themselves. For example, tools such as `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 profile would at best be minimal at worst be a security theater.
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 profile would at best be minimal at worst be a security theatre.
It gets even worse. Let's say, we write a profile for `cat`. Such a profile would need access to `/etc/`. We will add the following rule:
```sh
@ -76,20 +76,17 @@ You do not protect these programs. *Protect the usage you have of these programs
[Toolbox]: https://containertoolbx.org/
## Open Resources
## Abstractions
The standard way to allow opening resource in this project is to use one of the
child-open profile. Eg: `@{open_path} rPx -> child-open,`
This project and the apparmor-profiles official project provide a large selection of abstractions to be included in profiles. They should be used.
They are available in the [`children`][children] group.
For instance, to allow download directory access, instead of writing:
```sh
owner @{HOME}/@{XDG_DOWNLOAD_DIR}/{,**} rw,
```
You should write:
```sh
include <abstractions/user-download-strict>
```
* **`child-open`**: Instead of allowing the ability to run all software in `@{bin}/`, the purpose of this profile is to list all GUI 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.
* **`child-open-browsers`**: This version of child-open only allow to open browsers.
* **`child-open-help`**: This version of child-open only allow to open browsers and help programs.
* **`child-open-strict`**: This version of child-open only allow to open browsers & folders.
## Children profiles
@ -104,31 +101,11 @@ Usually, a child profile is in the [`children`][children] group. They have the f
Here is an overview of the current children profile:
1. **`child-open`**: To open resources. Instead of allowing the ability to run all software in `@{bin}/`, the purpose of this profile is to list all GUI 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.
2. **`child-pager`**: Simple access to pagers such as `pager`, `less` and `more`. This profile assumes the pager is reading its data from stdin, not from a file on disk.
3. **`child-systemctl`**: Common `systemctl` action. Do not use it too much as most of the time you will need more privilege than what this profile is giving you.
## Browsers
Chromium based browsers share a similar structure. Therefore, they share the same abstraction: [`abstractions/chromium`][chromium] that includes most of the profile content.
This abstraction requires the following variables defined in the profile header:
```sh
@{name} = chromium
@{domain} = org.chromium.Chromium
@{lib_dirs} = @{lib}/chromium
@{config_dirs} = @{user_config_dirs}/chromium
@{cache_dirs} = @{user_cache_dirs}/chromium
```
If your application requires chromium to run (like electron) use [`abstractions/chromium-common`][chromium-common] instead.
[chromium]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/abstractions/chromium
[chromium-common]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/abstractions/chromium-common
## Udev rules
See the **[kernel docs][kernel]** to check the major block and char numbers used in `/run/udev/data/`.