mirrors/apparmor.d
1
0
Fork 0
mirror of https://github.com/roddhjav/apparmor.d.git synced 2025-03-03 22:24:43 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

doc: update integration tests section.

Browse source
This commit is contained in:
Alexandre Pujol 2025-03-01 16:04:18 +01:00
parent 835b73f64e
commit fa6c37a7ab
Failed to generate hash of commit
5 changed files with 161 additions and 136 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

136
docs/development/integration.md
View file

@ -2,147 +2,33 @@
title: Integration Tests
---
!!! danger "Work in Progress"
The purpose of integration testing in apparmor.d is to ensure the profiles are not going to break programs found in Linux distributions and Desktop Environment that we support.
Although the integration test suite is intended to be run in a [Development VM](vm.md), it is also deployed the GitHub Action pipeline.
**Workflow**
1. Create a testing VM
2. Start the VM, do some dev
3. Run the integration tests against the testing VM
4. Ensure no new logs have been raised
2. Run the integration tests against the testing VM
3. Ensure no new logs have been raised
## Test Virtual Machines
The test VMs are built using [`cloud-init`][cloud-init] (when available), [`packer`][packer], and [`vagrant`][vagrant] 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.
[cloud-init]: https://cloud-init.io/
[packer]: https://www.packer.io/
[vagrant]: https://www.vagrantup.com/
### Requirements
* docker
* [packer]
* [vagrant]
* vagrant plugin install vagrant-libvirt
!!! note
You may need to edit some settings to fit your setup:
- The libvirt configuration in `tests/Vagrantfile`
- The default ssh key and ISO directory in `tests/packer/variables.pkr.hcl`
### Build
**Build an image**
To build a VM image for development purpose, run the following from the `tests` directory:
| Distribution | Flavor | Build command | VM name |
|:------------:|:------:|:-------------:|:-------:|
| Arch Linux | Gnome | `make archlinux flavor=gnome` | `arch-gnome` |
| Arch Linux | KDE | `make archlinux flavor=kde` | `arch-kde` |
| Debian | Server | `make debian flavor=server` | `debian-server` |
| openSUSE | KDE | `make opensuse flavor=kde` | `opensuse-kde` |
| Ubuntu | Server | `make ubuntu flavor=server` | `ubuntu-server` |
| Ubuntu | Desktop | `make ubuntu flavor=desktop` | `ubuntu-desktop` |
**VM management**
The development workflow is done through vagrant:
* Star a VM: `vagran up <name>`
* Shutdown a VM: `vagrant halt <name>`
* Reboot a VM: `vagrant reload <name>`
The available VM `name` is defined in the `tests/boxes.yml` file
### Develop
**Credentials**
The admin user is: `user`, its password is: `user`. It has passwordless sudo access. Automatic login is **not** enabled on DE. The root user is not locked.
**Directories**
All the images come pre-configured with the latest version of `apparmor.d` installed and running in the VM. apparmor.d is mounted as `/home/user/Projects/apparmor.d`
**Usage**
On all images, `aa-update` can be used to rebuild and install the latest version of the profiles. `p`, `pf`, and `pu` are two pre-configured aliases of `ps` that show the security status of processes. `htop` is also configured to show this status.
## Tests
!!! warning
The test suite is expected to be run in a [VM](#test-virtual-machines)
### Getting started
## Getting started
Prepare the test environment:
```sh
cd tests
make <dist> flavor=<flavor>
AA_INTEGRATION=true vagrant up <name>
just img <dist> <flavor>
just vm <dist> <flavor>
```
Run the integration tests on the test VM:
```sh
make integration box=<dist> IP=<ip>
just integration <dist> <flavor>
```
### Create integration tests
## Create integration tests
**Test suite usage**
All integration tests are written in [Bats](https://github.com/bats-core/bats-core) and are located in the `tests/integration` directory. The initial tests have been generated using [tldr page](https://tldr.sh/) with the following command:
Initialise the tests with:
```sh
./aa-test --bootstrap
```
List the tests scenarios to be run
```sh
./aa-test --list
```
Start the tests and collect the results
```sh
./aa-test --run
```
**Tests manifest**
A basic set of test is generated on initialization. More tests can be manually written in yaml file. They must have the following structure:
```yaml
- name: acpi
profiled: true
root: false
require: []
arguments: {}
tests:
- dsc: Show battery information
cmd: acpi
stdin: []
- dsc: Show thermal information
cmd: acpi -t
stdin: []
- dsc: Show cooling device information
cmd: acpi -c
stdin: []
- dsc: Show thermal information in Fahrenheit
cmd: acpi -tf
stdin: []
- dsc: Show all information
cmd: acpi -V
stdin: []
- dsc: Extract information from `/proc` instead of `/sys`
cmd: acpi -p
stdin: []
go run ./tests/cmd --bootstrap
```

8
docs/development/internal.md
View file

@ -159,10 +159,12 @@ All common programs are tracked and labelled in the [`apparmor.d/tunables/multia
## Re-attached path
**[<span class="pg-red">:material-tag-heart-outline: abi/4.0</span>]("Minimum version")**
The flag `attach_disconnect` control how disconnected paths are handled. It determines if pathnames resolved to be outside the namespace are attached to the root (ie. have the `/` character prepended).
It is a security issue as it allows disconnected paths to alias to other files that exist in the file name. Therefore, it is only provided to work around problems that can arise with sandboxed programs.
AppAmor 4.0 provides the `attach_disconnect.path` flag allowing to reattach this path to a prefix that is not `/`. When used it provide an important security improvement from AppArmor 3.0.
AppAmor 4.0 provides the `attach_disconnect.path` flag allowing to reattach this path to a prefix that is not `/`. When used it provides an important security improvement from AppArmor 3.0.
**`apparmor.d`** uses `attach_disconnect.path` by **default and automatically** on all profiles with the `attach_disconnect` flag. The attached path is set to `@{att}` a new dynamically generated variable set at build time in the preamble of all profile to be:
@ -170,7 +172,9 @@ AppAmor 4.0 provides the `attach_disconnect.path` flag allowing to reattach this
- `@{att}=/` for other profiles
## User Confinement [:material-police-badge-outline:{ .pg-red }](../full-system-policy.md "Only for Full System Policy (FSP)")
## User Confinement
[:material-police-badge-outline:{ .pg-red }](../full-system-policy.md "Full System Policy only (FSP)")
!!! warning "TODO"

38
docs/development/tests.md
View file

@ -1,15 +1,37 @@
---
title: Tests suite
title: Overview
---
A full test suite to ensure compatibility across supported distributions and that software is still considered a work in progress. Here is an overview of the current CI jobs:
Misconfigured AppArmor profiles is one of the most effective ways to break someone's system. This section present the various tests applied to the profiles as well as their current stage of deployment.
**On Gitlab CI**
**Current**
- Packages build for all supported distributions
- Profiles preprocessing verification for all supported distributions
- Go based command linting, coverage, and unit tests
- [x] **[Build:](https://gitlab.com/roddhjav/apparmor.d/-/pipelines)** `make`
- Build the profiles for all supported distributions.
- All CI jobs validate the profiles syntax and ensure they can be safely loaded into a kernel.
- Ensure the profile entry point (`@{exec_path}`) is defined.
**On Github Action**
- [x] **[Checks:](https://github.com/roddhjav/apparmor.d/blob/main/tests/check.sh)** `make check` checks basic style of profiles:
- Ensure apparmor.d header & licence
- Ensure 2 spaces indentation
- Ensure local include for profile and subprofiles
- Ensure abi 4 is used
- Ensure modern profile naming
- Ensure `vim:syntax=apparmor`
- 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 direct access to a VM with AppArmor included.
- [x] **[Integration Tests:](integration.md)** `make integration`
- Run simple CLI commands to ensure no logs are raised.
- Uses the [bats](https://github.com/bats-core/bats-core) test system.
- Run in the Github Action as well as in all local [test VM](vm.md).
**Plan**
For more complex software suite, more integration tests need to be done. The plan is to run existing integration suite from these very software in an environment with `apparmor.d` profiles.
- [ ] Systemd
- They use mkosi to generate a VM image to run their own integration tests.
- See https://www.codethink.co.uk/articles/2024/systemd-integration-testing-part-1/
- [ ] Gnome
- They use openQA to run their integration tests.
- See https://gitlab.gnome.org/GNOME/openqa-tests/

112
docs/development/vm.md Normal file
View file

@ -0,0 +1,112 @@
---
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`.
```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
up dist flavor # Start a machine
halt dist flavor # Stops 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
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
```
## Requirements
* [docker](https://www.docker.com/)
* [just](https://github.com/casey/just)
* [packer](https://www.packer.io/)
* [libvirt](https://libvirt.org/)
* [qemu](https://www.qemu.org/)
!!! note
You may need to edit some settings to fit your setup:
- The default ssh key and ISO directory in `tests/packer/variables.pkr.hcl`
## Build
One can see the available images by running:
```sh
$ just available
```
```
Distribution Flavor
archlinux gnome
archlinux kde
archlinux server
archlinux xfce
debian12 gnome
debian12 kde
debian12 server
ubuntu24 server
...
```
A VM image can be build with:
```sh
$ just img archlinux gnome
```
The image will then be showed in the list of images:
```sh
$ just images
```
```
Distribution Flavor Size Date
archlinux gnome 3.3G Mar 1 14:49
```
The VM can then be created with:
```sh
$ just vm archlinux gnome
```
And connected to with:
```sh
$ just ssh archlinux gnome
```
## Develop
**Credentials**
The admin user is: `user`, its password is: `user`. It has passwordless sudo access. Automatic login is **not** enabled on DE. The root user is not locked.
**Directories**
All the images come pre-configured with the latest version of `apparmor.d` installed and running in the VM. The apparmor.d project directory is mounted as `/home/user/Projects/apparmor.d`
**Usage**
On all images, `aa-update` can be used to rebuild and install the latest version of the profiles. `p`, `pf`, and `pu` are two pre-configured aliases of `ps` that show the security status of processes. `htop` is also configured to show this status.

1
mkdocs.yml
View file

@ -165,4 +165,5 @@ nav:
- development/build.md
- Tests:
- development/tests.md
- development/vm.md
- development/integration.md