From b10f2df5ecc4229368427732bdb5ae975af4aa35 Mon Sep 17 00:00:00 2001 From: Alexandre Pujol Date: Sun, 23 Feb 2025 20:10:21 +0100 Subject: [PATCH] doc: add roadmap and prebuilt pages. --- docs/development/build.md | 152 ++++++++++++++++++++++++++++++++++++ docs/development/roadmap.md | 60 ++++++++++++++ mkdocs.yml | 3 + 3 files changed, 215 insertions(+) create mode 100644 docs/development/build.md create mode 100644 docs/development/roadmap.md diff --git a/docs/development/build.md b/docs/development/build.md new file mode 100644 index 00000000..89bf8e89 --- /dev/null +++ b/docs/development/build.md @@ -0,0 +1,152 @@ +--- +title: Building the profiles +--- + +The profiles in `apparmor.d` must not be used directly. They need to be prebuilt (by running `make`). This page documents all possibles prebuild tasks. It is not intended to be read by end user, and it is only targeted at developers and maintainers. + +The build system is fully configurable, general usage can be seen with: +```sh +go run ./cmd/prebuild -h +``` + +``` +aa-prebuild [-h] [--complain | --enforce] [--full] [--abi 3|4] + + Prebuild apparmor.d profiles for a given distribution and apply + internal built-in directives. + +Options: + -h, --help Show this help message and exit. + -c, --complain Set complain flag on all profiles. + -e, --enforce Set enforce flag on all profiles. + -a, --abi ABI Target apparmor ABI. + -f, --full Set AppArmor for full system policy. + -F, --file Only prebuild a given file. + +Prepare tasks: + configure - Set distribution specificities + setflags - Set flags on some profiles + fsp - Configure AppArmor for full system policy + merge - Merge profiles (from group/, profiles-*-*/) to a unified apparmor.d directory + overwrite - Overwrite dummy upstream profiles + synchronise - Initialize a new clean apparmor.d build directory + ignore - Ignore profiles and files from: + systemd-default - Configure systemd unit drop in files to a profile for some units + systemd-early - Configure systemd unit drop in files to ensure some service start after apparmor + +Build tasks: + abi3 - Convert all profiles from abi 4.0 to abi 3.0 + attach - Re-attach disconnected path + complain - Set complain flag on all profiles + enforce - All profiles have been enforced + fsp - Prevent unconfined transitions in profile rules + hotfix - Temporary fix for #74, #80 & #235 + userspace - Resolve variable in profile attachments + +Directive: + #aa:dbus own bus= name= [interface=AARE] [path=AARE] + #aa:dbus talk bus= name= label= [interface=AARE] [path=AARE] + #aa:exec [P|U|p|u|PU|pu|] profiles... + #aa:only filters... + #aa:exclude filters... + #aa:stack [X] profiles... +``` + +## Prepare Tasks + +### **`synchronise`** + +Initialize a new clean `apparmor.d` build directory in `.build/`. + +*Enabled by default. Can be disabled in `cmd/prebuild/main.go`* + +### **`ignore`** + +Ignore profiles and files as defined in the `dist/ignore` directory. See [workflow](workflow.md#ignore-profiles). + +*Enabled by default. Can be disabled in `cmd/prebuild/main.go`* + +### **`merge`** + +Merge profiles from `apparmor.d/group/`, `apparmor.d/profiles-*-*/` to a unified directory in `.build/apparmor.d` that AppArmor can parse. + +*Enabled by default. Can be disabled in `cmd/prebuild/main.go`* + +### **`configure`** + +Set distribution specificities as defined in [`pkg/prebuild/prepare/configure.go`](https://github.com/roddhjav/apparmor.d/blob/main/pkg/prebuild/prepare/configure.go) + +*Enabled by default. Can be disabled in `cmd/prebuild/main.go`* + +### **`setflags`** + +Set flags on profiles as defined in the [flags manifest](workflow.md#profile-flags). + +*Enabled by default. Can be disabled in `cmd/prebuild/main.go`* + +### **`overwrite`** + +Overwrite (dummy) upstream profiles as defined in `dist/overwrite`. + +*Enabled by default. Can be disabled in `cmd/prebuild/main.go`* + +### **`systemd-default`** + +Install systemd unit drop in files from `systemd/default`. They configure the various dbus daemon to use specific profiles. + +*Enabled by default. Can be disabled in `cmd/prebuild/main.go`* + +### **`systemd-early`** + +Install systemd unit drop in files from `systemd/early` to ensure some services start after AppArmor. THis task will be removed in the future, as it will not be needed any more. + +*Enabled by default. Can be disabled in `pkg/prebuild/cli/cli.go`* + +### **`fsp`** + +Configure AppArmor for full system policy. + +*Enable with the `--full` option in the prebuild command.* + + +## Build Tasks + +### **`abi3`** + +This task will convert all profiles from `abi/4.0` to `abi/3.0`. The rules not supported by `abi/3.0` are commented in the build profiles. + +*Enable with the `--abi 3` option in the prebuild command.* + +### **`complain | enforce`** + +Set or remove the complain flag on all profiles. The `complain` task is enabled by default. When building in enforce mode, it is disabled. Enabling the `enforce` task will enforce **all** profiles including the one set in the [flags manifest](workflow.md#profile-flags). It is intended to be used in specialized system such as CTF or (very) high security VM. + +*Enable with the `--complain` or `--enforce` option in the prebuild command.* + +### **`userspace`** + +Resolve variables in profile attachments. It fixes issues with the userland AppArmor tools (aa-enforce, aa-logprof...) that does not support identical variable in the profiles attachments. + +*Enabled by default. Can be disabled in `cmd/prebuild/main.go`* + +### **`attach`** + +This task reattaches disconnected paths. See [#559](https://github.com/roddhjav/apparmor.d/issues/559): + +- Add the `attach_disconnected.path` flag on all profiles with the `attach_disconnected` flag +- Add the attached/base abstraction in the profile +- For compatibility, non-disconnected profile will have the `@{att}` variable set to `/` + +*Enabled when abi >= 4.0* + +### **`hotfix`** + +Temporary fix for #74, #80 & #235. Only an issue on Gnome, can be disabled on server. + +*Enabled by default. Can be disabled in `cmd/prebuild/main.go`* + +### **`fsp`** + +Prevent unconfined transitions in profile rules. + +*Enable with the `--full` option in the prebuild command.* diff --git a/docs/development/roadmap.md b/docs/development/roadmap.md new file mode 100644 index 00000000..e8a047a0 --- /dev/null +++ b/docs/development/roadmap.md @@ -0,0 +1,60 @@ +--- +title: Roadmap +--- + +## Toward a stable release + +This is the current list of features that must be implemented to get to a stable release + +- [ ] **Play machine** + +- [ ] **[Sub packages](https://github.com/roddhjav/apparmor.d/issues/464)** + - [x] Move most profiles into groups such that + - [ ] New simplified build system to generate the packages with profile dependencies check + +- [ ] **Tests** + - [x] Tests VM for all supported targets (see [tests/vm](vm.md)) + - [ ] Small integration tests for all core profiles (see [tests/integration](integration.md)) + +- [ ] **Documentation** + - [ ] Initial draft of the security model and goal + - [ ] General documentation improvements + +- [ ] **General improvements** + - [ ] Provide a proper fix for #74, #80 & #235 + - [ ] The apt/dpkg profiles needs to be reworked + +## Next features + +- [ ] **Conditions** + - [ ] Integrate the new condition feature in the profiles and restrict them a lot according to the application actually in use. Eg: `Gnome | KDE`, `X11 | Wayland`, etc. + - [ ] Create a new `aa-config` tool, similar to seboolean, to manage various settings, based on conditions. + +- [ ] **User Data** + - [ ] Fully rewrite the way user data is allowed / denied. The current implementation requires too much configuration to be usable by everyone. + - [ ] Add a prompt listener to handle the user data access. + +- [ ] **[Full System Policy](https://github.com/roddhjav/apparmor.d/issues/252)** + - [ ] Debug tool to show the profiles transition tree, and ensure no profile is missing + - [ ] Remove the `default` profile + +## Done + +**Abstractions** + +- [x] New `audio-client` and `audio-server` abstractions +- [x] New desktop agnostic `desktop` abstraction for all common access for any GUI app. +- [x] New `graphics` abstraction, hardware-agnostic. Fully replace and restrict the old `opencl` abstractions +- [x] All new abstractions are documented in the [abstractions](abstractions.md) page + +**Dbus** + +- [x] New `dbus-{system,session,accessibility}` profiles. Works regardless of the dbus implementation in use. +- [x] New talk directive: Allow the application to talk to session services. (send to) +- [x] New own directive: Allow the application to own session services under the given name. (receive, send, bind) +- [x] New `bus-{system,session,accessibility}` abstraction to be used in the profiles + +**Directives** + +- [x] Add directive. See the [directive](directives.md) page + diff --git a/mkdocs.yml b/mkdocs.yml index 9390b3dd..ed14108a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -152,6 +152,7 @@ nav: - recovery.md - Development: - development/index.md + - development/roadmap.md - Profiles: - development/workflow.md - development/guidelines.md @@ -160,6 +161,8 @@ nav: - development/directives.md - development/dbus.md - development/recommendations.md + - Packages: + - development/build.md - Tests: - development/tests.md - development/integration.md