From 475d8dc082cdc6bc6048ce3d0838249071d1f8d3 Mon Sep 17 00:00:00 2001 From: Alexandre Pujol Date: Sun, 27 Apr 2025 14:28:18 +0200 Subject: [PATCH] doc: small update & improvements. --- docs/configuration.md | 4 ++-- docs/development/dbus.md | 2 ++ docs/development/roadmap.md | 9 ++++++++- docs/development/vm.md | 40 ++++++++++++++++++++++++++----------- docs/full-system-policy.md | 2 ++ 5 files changed, 42 insertions(+), 15 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index dda450a85..fd8a5d38c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -32,7 +32,7 @@ The profiles heavily use the **largely extended** [XDG directory variables](#xdg ``` 3. Then restart the AppArmor service to reload the profiles in the kernel: ```sh - sudo systemctl restart apparmor.service + sudo systemctl reload apparmor.service ``` ### Profile Additions @@ -55,7 +55,7 @@ By default, `nautilus` (and any file browser) only allows access to user files. ``` 2. Then restart the AppArmor service to reload the profiles in the kernel: ```sh - sudo systemctl restart apparmor.service + sudo systemctl reload apparmor.service ``` ### XDG variables diff --git a/docs/development/dbus.md b/docs/development/dbus.md index e4133e5d1..165626f24 100644 --- a/docs/development/dbus.md +++ b/docs/development/dbus.md @@ -20,6 +20,8 @@ Default **system**, **session**, and **accessibility** bus access are provided w - `abstractions/bus-session` - `abstractions/bus-accessibility` +Do not use the dbus abstractions from apparmor in this project, they won't work as expected as the dbus daemon is confined. Furthermore, in `apparmor.d` there is no such thing as a strict dbus abstraction (`abstractions/dbus-strict`) as they are strict by default: bus access needs to be explicitly allowed using an interface abstraction or a directive. + ### Interfaces Access to common dbus interfaces is done using the abstractions under **[`abstractions/bus/`](https://github.com/roddhjav/apparmor.d/tree/main/apparmor.d/abstractions/bus)**. They are kept minimal on purpose. The goal is not to give full talk access an interface but to provide a *read-only* like view of it. It may be required to have a look at the dbus interface documentation to check what method can be safely allowed. diff --git a/docs/development/roadmap.md b/docs/development/roadmap.md index 52d7201ea..75cbcdd10 100644 --- a/docs/development/roadmap.md +++ b/docs/development/roadmap.md @@ -6,7 +6,7 @@ title: Roadmap This is the current list of features that must be implemented to get to a stable release -- [ ] **Play machine** +- [x] **Play machine** - [ ] **[Sub packages](https://github.com/roddhjav/apparmor.d/issues/464)** - [x] Move most profiles into groups such that @@ -24,6 +24,13 @@ This is the current list of features that must be implemented to get to a stable - [ ] Provide a proper fix for [#74](https://github.com/roddhjav/apparmor.d/issues/74), [#80](https://github.com/roddhjav/apparmor.d/issues/80) & [#235](https://github.com/roddhjav/apparmor.d/issues/235) - [ ] The apt/dpkg profiles needs to be reworked +- [ ] Build system + - [ ] Continuous release on the main branch, ~2 releases per week + - [ ] Provide packages repo for ubuntu/debian + - [ ] Provide complain/enforced packages version + - [ ] Add a `just` target to install the profiles in the right place + - [ ] Fully drop the Makefile in favor of `just` + ## Next features - [ ] **Conditions** diff --git a/docs/development/vm.md b/docs/development/vm.md index ead82ed0f..66630022e 100644 --- a/docs/development/vm.md +++ b/docs/development/vm.md @@ -5,32 +5,48 @@ title: Development VM To ensure compatibility across distribution, this project ships a wide range of development and tests VM images. The test VMs can be built locally using [cloud-init](https://cloud-init.io/), [packer](https://www.packer.io/) on Qemu/KVM using Libvirt. No other hypervisor will be targeted for these tests. The files that generate these images can be found in the **[tests/packer](https://github.com/roddhjav/apparmor.d/tree/main/tests/packer)** directory. -The VMs are fully managed using a [justfile](https://github.com/casey/just) that provide an integration environment helper for `apparmor.d`. +The VMs are fully managed using a [justfile](https://github.com/casey/just) that provides an integration environment helper for `apparmor.d`. ```sh $ just ``` ``` -Integration environment helper for apparmor.d - Available recipes: - default # Show this help message - package dist # Build the apparmor.d package - img dist flavor # Build the image - vm dist flavor # Create the machine + help # Show this help message + build # Build the go programs + enforce # Prebuild the profiles in enforced mode + complain # Prebuild the profiles in complain mode + fsp # Prebuild the profiles in FSP mode + install # Install the profiles + pkg # Build & install apparmor.d on Arch based systems + dpkg # Build & install apparmor.d on Debian based systems + rpm # Build & install apparmor.d on OpenSUSE based systems + tests # Run the unit tests + lint # Run the linters + check # Run style checks on the profiles + man # Generate the man pages + docs # Build the documentation + serve # Serve the documentation + clean # Remove all build artifacts + package dist # Build the package in a clean OCI container + img dist flavor # Build the VM image + create dist flavor # Create the machine up dist flavor # Start a machine halt dist flavor # Stops the machine + reboot dist flavor # Reboot the machine destroy dist flavor # Destroy the machine ssh dist flavor # Connect to the machine list # List the machines - images # List the machine images - available # List the machine that can be created + images # List the VM images + available # List the VM images that can be created + init dist flavor # Install dependencies for the bats integration tests integration dist flavor # Run the integration tests on the machine - lint # Run the linters - clean # Remove the machine images get_ip dist flavor get_osinfo dist + +See https://apparmor.pujol.io/development/ for more information. + ``` ## Requirements @@ -88,7 +104,7 @@ archlinux gnome 3.3G Mar 1 14:49 The VM can then be created with: ```sh -$ just vm archlinux gnome +$ just create archlinux gnome ``` And connected to with: diff --git a/docs/full-system-policy.md b/docs/full-system-policy.md index 80da55c2a..c747cb739 100644 --- a/docs/full-system-policy.md +++ b/docs/full-system-policy.md @@ -29,6 +29,8 @@ Particularly: - Desktop environment must be explicitly supported, your UI will not start otherwise. Again, it is a **feature**. - FSP mode will run unknown user application into the `default` profile. It might be enough for your application. If not you have to make a profile for it. - In FSP mode, all sandbox managers **must** have a profile. Then user sandboxed applications (flatpak, snap, etc) will work as expected. +- PID 1 is the last program that should be confined. It does not make sense to confine only PID. All other programs must be confined first. + ## Installation