From 601b62e93ad8241c2445b8aa229514865a20c22d Mon Sep 17 00:00:00 2001 From: Alexandre Pujol Date: Sat, 30 Mar 2024 11:50:34 +0000 Subject: [PATCH] doc: update abstraction structure to the last changes. --- docs/development/abstractions.md | 111 ++++++++++++++++++++----------- docs/development/directives.md | 2 +- 2 files changed, 75 insertions(+), 38 deletions(-) diff --git a/docs/development/abstractions.md b/docs/development/abstractions.md index 27438246..6657bb78 100644 --- a/docs/development/abstractions.md +++ b/docs/development/abstractions.md @@ -19,28 +19,13 @@ This project and the apparmor profile official project provide a large selection All of these abstractions can be extended by a system admin by adding rules in a file under `/etc/apparmor.d/.d` where `` is the name of one of these abstractions. - ## Application helper -### **`bwrap`** +Abstraction that aim at including a complete set of rule for a given program. The calling profile only need to add rules dependant of its use case/program. -Minimal set of rules for sandboxed program using `bwrap`. A profile using this abstraction still needs to set: +It is mostly useful for program often used in sub profile or for forks based on the same upstream. -- The flag: `attach_disconnected` -- Bwrap execution: `@{bin}/bwrap rix,` - -### **`bwrap-app`** - -Common rules for unknown userland UI applications sandboxed using `bwrap`. - -!!! warning - - This abstraction is wide on purpose. It is meant to be used by sandboxed applications that have no way to restrict access depending on the application being confined. - - **Do not use it for classic profile.** - - -### **`chromium`** +### **`app/chromium`** Full set of rules for all chromium based browsers. It works as a *function* and requires some variables to be provided as *arguments* and set in the header of the calling profile: @@ -55,13 +40,14 @@ Full set of rules for all chromium based browsers. It works as a *function* and @{cache_dirs} = @{user_cache_dirs}/@{name} ``` -If your application requires chromium to run (like electron) use [`chromium-common`](#chromium-common) instead. +If your application requires chromium to run use [`common/chromium`](#commonchromium) or [`common/electron`](#commonelectron) +instead. -### **`chromium-common`** -Minimal set of rules for chromium based application such as electron. Handle access for internal sandbox. +### **`app/pgrep`** -### **`sudo`** + +### **`app/sudo`** Minimal set of rules for profile including internal `sudo`. Interactive sudo need more rules. It is intended to be used in profile or sub profile that need to elevate their privileges using `sudo` or `su` for a very specific action: ```sh @@ -69,15 +55,13 @@ Minimal set of rules for profile including internal `sudo`. Interactive sudo nee profile root { include - include + include - @{bin}/sudo rm, - include if exists _root> } ``` -### **`systemctl`** +### **`app/systemctl`** Alternative solution for [child-systemctl](structure.md#children-profiles), when the child profile provide too much/not enough access. This abstraction should be used by a sub profile as follows: ```sh @@ -85,13 +69,68 @@ Alternative solution for [child-systemctl](structure.md#children-profiles), when profile systemctl { include - include + include include if exists _systemctl> } ``` +## Common Dependencies + +On the contrary of [`abstractions/app/`](#application-helper), abstractions in this directory are expected to provide a minimal set of rules to make a program using a dependency work. + +### **`common/app`** + +Common rules for unknown userland UI applications sandboxed using `bwrap`. + +!!! warning + + This abstraction is wide on purpose. It is meant to be used by sandboxed applications that have no way to restrict access depending on the application being confined. + + **Do not use it for classic profile.** + + +### **`common/apt`** + +Minimal access to apt sources, preferences and configuration. + +### **`common/bwrap`** + +Minimal set of rules for sandboxed program using `bwrap`. A profile using this abstraction still needs to set: + +- The flag: `attach_disconnected` +- Bwrap execution: `@{bin}/bwrap rix,` + + +### **`common/chromium`** + +Minimal set of rules for chromium based application. Handle access for internal sandbox. + + +### **`common/electron`** + +Minimal set of rules for all electron based UI application. It works as a *function* and requires some variables to be provided as *arguments* and set in the header of the calling profile: + +!!! note "" + + [apparmor.d/profile-s-z/spotify](https://github.com/roddhjav/apparmor.d/blob/e979fe05b06f525e5a65c767b4eabe5600147355/apparmor.d/profile-s-z/spotify#L10-L13) + ``` sh linenums="10" + @{name} = spotify + @{lib_dirs} = /opt/@{name} + @{config_dirs} = @{user_config_dirs}/@{name} + @{cache_dirs} = @{user_cache_dirs}/@{name} + ``` + +### **`common/systemd`** + +Common set of rules for internal systemd suite. + +!!! warning + + It should **only** be used by the systemd suite. + + ## Audio ### **`audio-client`** @@ -142,7 +181,14 @@ Permissions for querying dconf settings with write access. !!! warning - This abstractions are only required when an interactive shell is started. Classic shell scripts do not need them. + These abstractions are only required when an interactive shell is started. Classic shell scripts do not need them. + + +Only use [`shells`](#shells), other abstractions are software dependant and should not usually be used directly. + +### **`shells`** + +Common rules for interactive shells. ### **`bash-strict`** @@ -163,15 +209,6 @@ Many programs wish to perform nameservice like operations, such as looking up us Use this abstraction instead of upstream `abstractions/nameservice` as upstream abstraction also provide full network access which is not needed for a lot of programs. -### **`systemd-common`** - -Common set of rules for internal systemd suite. - -!!! warning - - It should **only** be used by the systemd suite. - - ### **`app-open`** Instead of allowing the run of all software under `@{bin}` or `@{lib}` the purpose of this abstraction is to list all GUI program that can open resources. Ultimately, only sandbox manager program such as `bwrap`, `snap`, `flatpak`, `firejail` should be present here. Until this day, this profile will be a controlled mess. diff --git a/docs/development/directives.md b/docs/development/directives.md index c9d0082e..fb8c79c4 100644 --- a/docs/development/directives.md +++ b/docs/development/directives.md @@ -133,7 +133,7 @@ The `exec` directive is useful to allow executing transition to a profile withou ```sh # Stacked profile: systemd-oomd include - include + include capability dac_override, capability kill, unix (bind) type=stream addr=@@{hex}/bus/systemd-oomd/bus-api-oom,