docs: add development workflow.
This commit is contained in:
Alexandre Pujol
parent
baad12a754
commit
9112c6466d
13 changed files with 514 additions and 275 deletions
195
docs/development/workflow.md
Normal file
195
docs/development/workflow.md
Normal file
|
|
@ -0,0 +1,195 @@
|
|||
---
|
||||
title: Workflow
|
||||
---
|
||||
|
||||
**Workflow to write profiles**
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-file-document: **[Write a blanck profile](#add-a-blank-profile)**
|
||||
|
||||
</div>
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-download: **[Install the profile](#individual-profile)**
|
||||
|
||||
</div>
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-test-tube: **[Profile the program](#program-profiling)**
|
||||
|
||||
</div>
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :octicons-law-16: **[Respect the profile guidelines](guidelines.md)**
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
## Add a blank profile
|
||||
|
||||
1. To add a new profile `foo`, add the file `foo` in [`apparmor.d/profile-a-f`](https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/profiles-a-f).
|
||||
If your profile is part of a large group of profiles, it can also go in
|
||||
[`apparmor.d/groups`](https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups).
|
||||
|
||||
2. Write the profile content, the rules depend on the confined program,
|
||||
Here is the bare minimum for the program `foo`:
|
||||
``` sh
|
||||
# apparmor.d - Full set of apparmor profiles
|
||||
# Copyright (C) 2024 You <your@email>
|
||||
# SPDX-License-Identifier: GPL-2.0-only
|
||||
|
||||
abi <abi/3.0>,
|
||||
|
||||
include <tunables/global>
|
||||
|
||||
@{exec_path} = @{bin}/foo
|
||||
profile foo @{exec_path} {
|
||||
include <abstractions/base>
|
||||
|
||||
@{exec_path} mr,
|
||||
|
||||
include if exists <local/foo>
|
||||
}
|
||||
|
||||
# vim:syntax=apparmor
|
||||
```
|
||||
|
||||
## Development Install
|
||||
|
||||
It is not recommended installing the full project *"manually"* (with `make`, `sudo make install`). The distribution specific packages are intended to be used in development as they include additional rule to ensure compatibility with upstream (see `debian/`, `PKGBUILD` and `dists/apparmor.d.spec`).
|
||||
|
||||
Instead, install an individual profile or the development package, the following way.
|
||||
|
||||
### Development package
|
||||
|
||||
=== ":material-arch: Archlinux"
|
||||
|
||||
```sh
|
||||
make pkg
|
||||
```
|
||||
|
||||
=== ":material-ubuntu: Ubuntu"
|
||||
|
||||
```sh
|
||||
make dpkg
|
||||
```
|
||||
|
||||
=== ":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`.
|
||||
|
||||
### Individual profile
|
||||
|
||||
**Format**
|
||||
|
||||
```sh
|
||||
make dev name=<profile-name>
|
||||
```
|
||||
|
||||
**Exampe**
|
||||
|
||||
: Testing the profile `pass`
|
||||
|
||||
```
|
||||
make dev name=pass
|
||||
```
|
||||
|
||||
This:
|
||||
|
||||
- Prebuild the `pass` profile in complain mode to `.build`,
|
||||
- Install the profile to `/etc/apparmor.d/`
|
||||
- Load the profile by restarting the AppArmor service.
|
||||
|
||||
|
||||
More advanced development, like editing the abstractions or working over multiple profiles at the same time requires installing the full development package.
|
||||
|
||||
For this individual profile installation to work, the full package needs to be installed, regardless of the installation method ([dev](#development-package) or [stable](../install.md)).
|
||||
|
||||
## Program Profiling
|
||||
|
||||
### Workflow
|
||||
|
||||
To discover the access needed by a program, you can use the following tools:
|
||||
|
||||
1. Star the program in *complain* mode, let it initialize itself, then close it.
|
||||
|
||||
1. Run **[`aa-log -r`](../usage.md#apparmor-log)**. It will:
|
||||
- Convert the logs to AppArmor rules.
|
||||
- Detect if flags such as `attach_disconnected` are needed.
|
||||
- Convert all common paths to **[variables](../variables.md)**.
|
||||
|
||||
1. From `aa-log` output, you can:
|
||||
- Copy the rules to the profile.
|
||||
- Replace some rules with **[abstractions](abstractions.md)** as 80% of the rules should already be covered by an abstraction.
|
||||
|
||||
1. Then, [update the profile](#individual-profile) and start the program again. Use the program as you would normally do, but also try to run all the features of the program, e.g.: open the help, settings, etc.
|
||||
|
||||
1. Run **[`aa-log`](../usage.md#apparmor-log)**. Stop the program as long as you get over 100 new rules. Add the rules to the profile.
|
||||
|
||||
After 2 or 3 iterations, you should have a working profile.
|
||||
|
||||
### Recommendations
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-function: **[Use the abstractions](abstractions.md)**
|
||||
- :simple-files: **[Learn how to open resources](internal.md#open-resources)**
|
||||
- :fontawesome-solid-bus-simple: **[Learn how Dbus rules are handled](dbus.md)**
|
||||
- :material-sign-direction: **[Learn about directives `#aa:`](directives.md)**
|
||||
- :octicons-law-16: **[Follow the profile guidelines](guidelines.md)**
|
||||
- :octicons-light-bulb-16: **[See other recommendations](recommendations.md)**
|
||||
|
||||
</div>
|
||||
|
||||
!!! danger "Warning"
|
||||
|
||||
Following the [profile guidelines](guidelines.md) is **mandatory** for all profiles. PRs that do not follow the guidelines will not get merged.
|
||||
|
||||
### Tools
|
||||
|
||||
* **[aa-notify](https://wiki.archlinux.org/title/AppArmor#Get_desktop_notification_on_DENIED_actions)** is a tool that will allow you to get notified on every apparmor log.
|
||||
|
||||
* **[aa-logprof](https://man.archlinux.org/man/aa-logprof.8)** is another tool that will help you to generate a profile from logs. However, the logs generated by `aa-logprof` need to be rewritten to comply with the profile [guidelines](guidelines.md).
|
||||
|
||||
* **[aa-complain](https://man.archlinux.org/man/aa-complain.8), aa-enforce** are tools to quickly change the mode of a profile.
|
||||
|
||||
|
||||
## Development Settings
|
||||
|
||||
### Profile flags
|
||||
|
||||
Flags for all profiles in this project are tracked under the [`dists/flags`](https://github.com/roddhjav/apparmor.d/tree/main/dists/flags) directory. It is used for profile that are not considered stable. Files in this directory should respect the following format: `<profile> <flags>`, flags should be comma separated.
|
||||
|
||||
For instance, to move `adb` in *complain* mode, edit **[`dists/flags/main.flags`](https://github.com/roddhjav/apparmor.d/blob/main/dists/flags/main.flags)** and add the following line:
|
||||
```sh
|
||||
adb complain
|
||||
```
|
||||
|
||||
Beware, flags defined in this file overwrite flags in the profile. So you may need to add other flags. Example for `gnome-shell`:
|
||||
```sh
|
||||
gnome-shell attach_disconnected,mediate_deleted,complain
|
||||
```
|
||||
|
||||
|
||||
### Ignore profiles
|
||||
|
||||
It can be handy to not install a profile for a given distribution. Profiles and directories to ignore are tracked under the [`dists/ignore`](https://github.com/roddhjav/apparmor.d/tree/main/dists/ignore) directory. Files in this directory should respect the following format: `<profile or path>`. One ignore by line. It can be a profile name or a directory to ignore (relative to the project root).
|
||||
Loading…
Add table
Add a link
Reference in a new issue