mirrors/apparmor.d
1
0
Fork 0
mirror of https://github.com/roddhjav/apparmor.d.git synced 2024-11-14 23:43:56 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

doc: cosmetic.

Browse Source
This commit is contained in:
Alexandre Pujol 2023-09-19 19:18:15 +01:00
parent dd576f71af
commit 4d9430b6be
No known key found for this signature in database
GPG Key ID: C5469996F0DF68EC
10 changed files with 42 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/development/guidelines.md
View File

@ -4,22 +4,17 @@ title: Guidelines
## Common structure
AppArmor profiles can be written without any specific guidelines. However,
when you work with over 1400 profiles, you need a common structure among all the
profiles.
AppArmor profiles can be written without any specific guidelines. However, when you work with over 1400 profiles, you need a common structure among all the profiles.
The logic behind it is that if a rule is present in a profile, it should only be
in one place, making profile review easier.
For example, if a program needs to run executables binary. The rules allowing it
can only be in a specific rule block (just after the `@{exec_path} mr,` rule). It
is therefore easy to ensure some profile features such as:
For example, if a program needs to run executables binary. The rules allowing it can only be in a specific rule block (just after the `@{exec_path} mr,` rule). It is therefore easy to ensure some profile features such as:
* A profile has access to a given resource
* A profile enforces a strict [write xor execute] (W^X) policy.
It also improves compatibilities and makes personalization easier thanks to the
use of more variables.
It also improves compatibilities and makes personalization easier thanks to the use of more variables.
## Guidelines
@ -28,8 +23,7 @@ use of more variables.
This profile guideline is still evolving, feel free to propose improvements
as long as they do not vary too much from the existing rules.
In order to ensure a common structure across the profiles, all new profile **must**
follow the guidelines presented here.
In order to ensure a common structure across the profiles, all new profile **must** follow the guidelines presented here.
The rules in the profile should be sorted in the rule ***block*** as follows:

4
docs/development/index.md
View File

@ -4,9 +4,7 @@ title: Development
# Development
You want to contribute to `apparmor.d`, **thanks a lot for this.** Feedbacks,
contributors, pull requests are all very welcome. You will find in this page all
the useful information needed to contribute.
You want to contribute to `apparmor.d`, **thanks a lot for this.** Feedbacks, contributors, pull requests are all very welcome. You will find in this page all the useful information needed to contribute.
??? info "How to contribute"

54
docs/development/structure.md
View File

@ -7,21 +7,16 @@ Description of common structure found across various AppArmor profiles
## Programs to not confine
Some programs should not be confined by themselves. For example, tools such as
`ls`, `rm`, `diff` or `cat` do not have profiles in this project. Let's see why.
Some programs should not be confined by themselves. For example, tools such as `ls`, `rm`, `diff` or `cat` do not have profiles in this project. Let's see why.
These are general tools that in a general context can legitimately access any
file in the system. Therefore, the confinement of such tools by a global
profile would at best be minimal at worst be a security theater.
These are general tools that in a general context can legitimately access any file in the system. Therefore, the confinement of such tools by a global profile would at best be minimal at worst be a security theater.
It gets even worse. Let's say, we write a profile for `cat`. Such a profile
would need access to `/etc/`. We will add the following rule:
It gets even worse. Let's say, we write a profile for `cat`. Such a profile would need access to `/etc/`. We will add the following rule:
```sh
/etc/{,**} rw,
```
However, as `/etc` can contain sensitive files, we now want to explicitly
prevent access to these sensitive files. Problems:
However, as `/etc` can contain sensitive files, we now want to explicitly prevent access to these sensitive files. Problems:
1. How do we know the exhaustive list of *sensitive files* in `/etc`?
2. How do we ensure access to these sensitive files are not required?
@ -29,11 +24,7 @@ prevent access to these sensitive files. Problems:
See the [first rule of this project][project-rules] that is to only allow
what is required. Here we allow everything and blacklist some paths.
It creates even more issues when we want to use this profile in other profiles.
Let's take the example of `diff`. Using this rule: `@{bin}/diff rPx,` will
restrict access to the very generic and not very confined `diff` profile.
Whereas most of the time, we want to restrict `diff` to some specific file in
our profile:
It creates even more issues when we want to use this profile in other profiles. Let's take the example of `diff`. Using this rule: `@{bin}/diff rPx,` will restrict access to the very generic and not very confined `diff` profile. Whereas most of the time, we want to restrict `diff` to some specific file in our profile:
* In `dpkg`, an internal child profile (`rCx -> diff`), allows `diff` to only
access etc config files:
@ -95,8 +86,7 @@ sandbox managed with [Toolbox]
## Abstractions
This project and the apparmor profile official project provide a large selection
of abstractions to be included in profiles. They should be used.
This project and the apparmor profile official project provide a large selection of abstractions to be included in profiles. They should be used.
For instance, to allow download directory access, instead of writing:
```sh
@ -111,8 +101,7 @@ include <abstractions/user-download-strict>
## Children profiles
Usually, a child profile is in the [`children`][children] group. They have
the following note:
Usually, a child profile is in the [`children`][children] group. They have the following note:
!!! quote
@ -140,20 +129,18 @@ Here is an overview of the current children profile:
## Browsers
Chromium based browsers share a similar structure. Therefore, they share the same
abstraction: [`abstractions/chromium`][chromium] that includes most of the profile content.
Chromium based browsers share a similar structure. Therefore, they share the same abstraction: [`abstractions/chromium`][chromium] that includes most of the profile content.
This abstraction requires the following variables definied in the profile header:
```sh
@{chromium_name} = chromium
@{chromium_domain} = org.chromium.Chromium
@{chromium_lib_dirs} = @{lib}/chromium
@{chromium_config_dirs} = @{user_config_dirs}/chromium
@{chromium_cache_dirs} = @{user_cache_dirs}/chromium
@{name} = chromium
@{domain} = org.chromium.Chromium
@{lib_dirs} = @{lib}/chromium
@{config_dirs} = @{user_config_dirs}/chromium
@{cache_dirs} = @{user_cache_dirs}/chromium
```
If your application requires chromium to run (like electron) use
[`abstractions/chromium-common`][chromium-common] instead.
If your application requires chromium to run (like electron) use [`abstractions/chromium-common`][chromium-common] instead.
[chromium]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/abstractions/chromium
[chromium-common]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/abstractions/chromium-common
@ -162,8 +149,7 @@ If your application requires chromium to run (like electron) use
See the **[kernel docs][kernel]** to check the major block and char numbers used in `/run/udev/data/`.
Special care must be given as sometimes udev numbers are allocated
dynamically by the kernel. Therefore, the full range must be allowed:
Special care must be given as sometimes udev numbers are allocated dynamically by the kernel. Therefore, the full range must be allowed:
!!! note ""
@ -191,13 +177,12 @@ dynamically by the kernel. Therefore, the full range must be allowed:
*Source: [AppArmor Wiki][apparmor-wiki]*
This feature is only enabled when the profiles are built with `make full`. The profiles for full system policies are maintained in the **[`_full`][_full]** group. It consists of two extra main profiles:
This feature is only enabled when the profiles are built with `make full`. The profiles for full system policies are maintained in the **[`_full`][full]** group. It consists of two extra main profiles:
1. **`init`**: For systemd as PID 1
2. **`systemd`**: For systemd as user
All core required applications that need to be started by systemd (both as user
or root) need to be present in these profiles.
All core required applications that need to be started by systemd (both as user or root) need to be present in these profiles.
Early policy load should also be enabled. In `/etc/apparmor/parser.conf`
```
@ -206,9 +191,8 @@ cache-loc /etc/apparmor/earlypolicy/
!!! danger
Full system policy is still under early development, do not run it outside a
development VM! **You have been warned!!!**
Full system policy is still under early development, do not run it outside a development VM! **You have been warned!!!**
[apparmor-wiki]: https://gitlab.com/apparmor/apparmor/-/wikis/FullSystemPolicy
[_full]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/_full
[full]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/_full

4
docs/development/tests.md
View File

@ -4,9 +4,7 @@ title: Tests suite
# Tests suite
A full test suite to ensure compatibility across distributions and software is
still a work in progress.
Here is an overview of the current CI jobs:
A full test suite to ensure compatibility across distributions and software is still a work in progress. Here is an overview of the current CI jobs:
**On Gitlab CI**

10
docs/install.md
View File

@ -4,16 +4,13 @@ title: Installation
!!! danger
In order to not break your system, the default package configuration installs
all profiles in complain mode. They can be enforced later.
See the [Enforce Mode](/enforce) page.
In order to not break your system, the default package configuration installs all profiles in complain mode. They can be enforced later. See the [Enforce Mode](/enforce) page.
## Requirements
**AppArmor**
An `apparmor` based Linux distribution is required. The basic profiles and
abstractions shipped with AppArmor must be installed.
An `apparmor` based Linux distribution is required. The basic profiles and abstractions shipped with AppArmor must be installed.
**Desktop environment**
@ -74,8 +71,7 @@ zypper install apparmor.d
## Partial install
For test purposes, you can install specific profiles with the following commands.
Abstractions, tunables, and most of the OS dependent post-processing is managed.
For test purposes, you can install specific profiles with the following commands. Abstractions, tunables, and most of the OS dependent post-processing is managed.
```sh
make

14
docs/issues.md
View File

@ -25,24 +25,18 @@ error: could not get current working directory
...
```
This is **a feature, not a bug!** It can safely be ignored. Pacman tries to get
your current directory. You will only get this error when you run pacman in your
home directory.
This is **a feature, not a bug!** It can safely be ignored. Pacman tries to get your current directory. You will only get this error when you run pacman in your home directory.
According the Archlinux guideline, on Archlinux, packages cannot install files
under `/home/`. Therefore the [`pacman`][pacman] profile purposely does not
allow access of your home directory.
According the Archlinux guideline, on Archlinux, packages cannot install files under `/home/`. Therefore the [`pacman`][pacman] profile purposely does not allow access of your home directory.
This provides a basic protection against some packages (on the AUR) that may have
rogue install script.
This provides a basic protection against some packages (on the AUR) that may have rogue install script.
[pacman]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/pacman/pacman
### Gnome can be very slow to start.
[Gnome](https://github.com/roddhjav/apparmor.d/issues/80) can be slow to start.
This is a known bug, help is very welcome.
[Gnome](https://github.com/roddhjav/apparmor.d/issues/80) can be slow to start. This is a known bug, help is very welcome.
The complexity is that:

4
docs/recovery.md
View File

@ -4,9 +4,7 @@ title: System Recovery
# System Recovery
Issue in some core profiles like the systemd suite, or the desktop environment
can fully break your system. This should not happen a lot, but if it does here
is the process to recover your system on Archlinux:
Issue in some core profiles like the systemd suite, or the desktop environment can fully break your system. This should not happen a lot, but if it does here is the process to recover your system on Archlinux:
1. Boot from a Archlinux live USB
1. If you root partition is encryped, decrypt it: `cryptsetup open /dev/<your-disk-id> vg0`

9
docs/report.md
View File

@ -4,14 +4,11 @@ title: Report AppArmor logs
# Report AppArmor logs
The **[aa-log](/usage/#apparmor-log)** tool reports all AppArmor `DENIED` and
`ALLOWED`. It should be used to fix AppArmor related issues.
The **[aa-log](/usage/#apparmor-log)** tool reports all AppArmor `DENIED` and `ALLOWED`. It should be used to fix AppArmor related issues.
While testing, if something get wrong, you need to put the profile in complain mode,
to that you can investigate and it does not block your program.
While testing, if something get wrong, you need to put the profile in complain mode, to that you can investigate and it does not block your program.
When creating [an issue on Github][newissue]. Please ensure you post a link to
the [paste] of the AppArmor audit log: `/var/log/audit/audit.log`.
When creating [an issue on Github][newissue]. Please ensure you post a link to the [paste] of the AppArmor audit log: `/var/log/audit/audit.log`.
[newissue]: https://github.com/roddhjav/apparmor.d/issues/new
[paste]: https://pastebin.com/

10
docs/usage.md
View File

@ -4,8 +4,7 @@ title: Usage
## Enabled profiles
Once installed and with the rules enabled, you can ensure the rules are loaded
with:
Once installed and with the rules enabled, you can ensure the rules are loaded with:
```sh
sudo aa-status
```
@ -75,13 +74,10 @@ ps (complain) user ps auxZ
## AppArmor Log
Ensure that `auditd` is installed and running on your system in order to read
AppArmor log from `/var/log/audit/audit.log`. Then you can see the log with the
provided command `aa-log` allowing you to review AppArmor generated messages in
Ensure that `auditd` is installed and running on your system in order to read AppArmor log from `/var/log/audit/audit.log`. Then you can see the log with the provided command `aa-log` allowing you to review AppArmor generated messages in
a colorful way.
Other AppArmor userspace tools such as `aa-enforce`, `aa-complain`, and `aa-logprof`
should work as expected.
Other AppArmor userspace tools such as `aa-enforce`, `aa-complain`, and `aa-logprof` should work as expected.
### Basic use

3
docs/variables.md
View File

@ -94,6 +94,9 @@ title: Variables References
| Thread id | `@{tid}` | `[0-9]*` |
| Single hexadecimal character | `@{h}` | `[0-9a-fA-F]` |
| Single alphanumeric character | `@{c}` | `[0-9a-zA-Z]` |
| PCI Devices | `@{pci}` | `@{pci_bus}/**/` |
| PCI Bus | `@{pci_bus}` | `pci@{h}@{h}@{h}@{h}:@{h}@{h}` |
| PCI Id | `@{pci_id}` | `@{h}@{h}@{h}@{h}:@{h}@{h}:@{h}@{h}.@{h}` |
**System Paths**