Differences between revisions 30 and 81 (spanning 51 versions)
Revision 30 as of 2015-01-29 17:31:39
Size: 2694
Editor: UlrikeUhlig
Comment: Simplification: people are not required to manually copy profiles to /etc/apparmor.d/. and do not need to manually parse them.
Revision 81 as of 2022-08-24 19:54:43
Size: 7070
Editor: TheAnarcat
Comment: more debugging
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: none-~<<Navigation(siblings,1)>>
----
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: English - [[zh_CN/AppArmor/HowToUse|简体中文]]-~

This page describes how to use and troubleshoot '''AppArmor''' on Debian.
Line 7: Line 9:
== Requirements == ----
Line 9: Line 11:
A Debian 7 "Wheezy" or newer GNU/Linux system is required. == Install AppArmor ==
Line 11: Line 13:
If you are using wheezy, upgrading to systemd 204-14 from wheezy-backports is recommended, but not mandatory. !AppArmor is available in Debian since Debian 7 "Wheezy".
Line 13: Line 15:
== Install software == [[PackageManagement#Installing.2C_removing.2C_upgrading_software|Install]] !AppArmor userspace tools:
Line 15: Line 17:
Install !AppArmor userspace tools and some contributed profiles:

{{{
$ sudo apt-get install apparmor apparmor-profiles apparmor-utils
}}}
 * [[DebianPkg:apparmor]]
 * [[DebianPkg:apparmor-utils]]
 * [[DebianPkg:auditd]] (If you intend to use automatic profile generation tools)
Line 23: Line 23:
Enable the !AppArmor LSM: If you are using Debian 10 "Buster" or newer, AppArmor is enabled by default so you can skip this step.

The !AppArmor Linux Security Modules (LSM) must be enabled from the linux kernel command line in the bootloader:
Line 26: Line 28:
$ sudo perl -pi -e 's,GRUB_CMDLINE_LINUX="(.*)"$,GRUB_CMDLINE_LINUX="$1 apparmor=1 security=apparmor",' /etc/default/grub $ sudo mkdir -p /etc/default/grub.d
$ echo
'GRUB_CMDLINE_LINUX_DEFAULT="$GRUB_CMDLINE_LINUX_DEFAULT apparmor=1 security=apparmor"' \
  | sudo tee
/etc/default/grub.d/apparmor.cfg
Line 31: Line 35:
In the future, this should be automated, see [[http://bugs.debian.org/702030|#702030]]
Line 34: Line 37:

!AppArmor profiles can be set to different modes:

 * `complain` mode: violations to the policy will only be logged
 * `enforce` mode: operations that violate the policy will be blocked.

Note that `deny` rules in profiles are enforced/blocked even in `complain` mode.

Find out if !AppArmor is enabled (returns Y if true):

{{{
$ cat /sys/module/apparmor/parameters/enabled
}}}

List all loaded !AppArmor profiles for applications and processes and detail their status (enforced, complain, unconfined):
Line 38: Line 56:
will list all loaded !AppArmor profiles for applications and processes and detail their status (enforced, complain, unconfined).
List running executables which are currently confined by an !AppArmor profile:
Line 42: Line 62:
will list running executables which are currently confined by an !AppArmor profile.
Line 44: Line 63:
== Enable / install more profiles ==

Find more profiles:

 * in the DebianPkg:apparmor-profiles package;
 * in the DebianPkg:apparmor-profiles-extra package (available in wheezy-backports and jessie);
 * in [[https://udd.debian.org/cgi-bin/bts-usertags.cgi?user=pkg-apparmor-team@lists.alioth.debian.org|the patches, with new profiles included]], that were submitted to Debian;
 * in Ubuntu.

!AppArmor profiles live in `/etc/apparmor.d/`. One can use [[DebianMan:8/apparmor_parser|apparmor_parser(8)]] to insert them into the kernel. This is done automatically when installing the DebianPkg:apparmor-profiles or the DebianPkg:apparmor-profiles-extra package.

For example, to set all "extra" profiles (provided in the apparmor-profiles package) to complain mode (security policy is not enforced, but corresponding access violations are logged), do the following:

## cd /usr/share/doc/apparmor-profiles/extras
## cp -i *.* /etc/apparmor.d/
List of processes with tcp or udp ports that do not have !AppArmor profiles loaded:
Line 61: Line 66:
for f in *.* ; do aa-complain /etc/apparmor.d/$f; done $ sudo aa-unconfined
$ sudo aa-unconfined --paranoid
Line 64: Line 70:
To set these profiles to enforce mode, use `aa-enforce` instead of `aa-complain`. Note that many of these profiles are not up-to-date and might break functionality in enforce mode.
== Find / install more profiles ==

!AppArmor profiles live in `/etc/apparmor.d/`. Some packages automatically install their own profiles in this directory. To find more profiles:

 * [[DebianPkg:apparmor-profiles-extra]] provides and enables Debian-specific (not upstreamed) profiles.
 * [[DebianPkg:apparmor-profiles]] provides various experimental profiles, and enables some by default.
 * Check the equivalent [[https://packages.ubuntu.com/search?keywords=apparmor-profiles|Ubuntu packages]]
 * Check newly [[https://udd.debian.org/cgi-bin/bts-usertags.cgi?user=pkg-apparmor-team@lists.alioth.debian.org|submitted patches/profiles]] for !AppArmor in Debian


== Enabling profiles ==

Debian packages that install profiles to `/etc/apparmor.d/` automatically enable them (`complain` mode). Other profiles need to be copied to this directory and manually set to `complain` or `enforce` mode.


For example to install an "extra" profile from the `/usr/share/apparmor/extra-profiles/` directory provided by [[DebianPkg:apparmor-profiles]] and set it to `complain` mode:


{{{
# list available profiles
$ ls /usr/share/apparmor/extra-profiles/

# install the profile
$ sudo cp /usr/share/apparmor/extra-profiles/usr.bin.example /etc/apparmor.d/

# set the profile to complain mode
sudo aa-complain /etc/apparmor.d/usr.bin.example
}}}



To set a profile to enforce mode, use `aa-enforce` instead of `aa-complain`. '''Beware''' though: many profiles are not up-to-date and will break functionality in enforce mode, be ready to [[#Debug|debug]]!
Line 68: Line 107:
!AppArmor audit logs can be found in `/var/log/syslog`. !AppArmor '''logs''' can be found in the [[systemd]] journal, in `/var/log/syslog` and `/var/log/kern.log` (and `/var/log/audit.log` when auditd is installed).
Line 70: Line 109:
For more detailed instructions, please read the dedicated documentation for [[AppArmor/Debug|debugging AppArmor]].
Line 72: Line 110:
== Learn more == === Diagnose if a bug might have been caused by AppArmor ===
Line 74: Line 112:
[[AppArmor#External_links|Learn more]] or [[AppArmor/Contribute| start contributing]]. Look in these logs for:

 * `ALLOWED` (logged when a profile in `complain` mode violates the policy)
 * `DENIED` (logged when a profile in `enforce` mode actually blocks an operation)

The full log message should provide more information on what exact access has been denied. You can use this to [[#Edit_AppArmor_profiles|edit profiles]] before turning them on in enforce mode.

Sometimes, it's useful to disable a profile and to test again if the bug persists:

{{{
# disable a profile temporarily
$ sudo aa-disable /etc/apparmor.d/usr.bin.example
# after testing, re-enable it in complain mode
$ sudo aa-complain /etc/apparmor.d/usr.bin.example
# or in enforce mode
$ sudo aa-enforce /etc/apparmor.d/usr.bin.example
}}}

Note that systemd '''might still load the profile''' if you have `AppArmorProfile` setup in the unit file. Then the proper way to disable the profile then is to comment out that line in the unit file, or through a systemd override.

=== Desktop notifications ===

The [[DebianPkg:apparmor-notify]] package provides desktop notifications (through [[DebianMan:aa-notify]]) when a policy violation occurs. The program should start automatically when you login.

 * If [[DebianPkg:auditd]] is not installed, your user should be a member of the `adm` [[SystemGroups|Group]]
 * If auditd is installed, `/etc/xdg/autostart/apparmor-notify.desktop` should be modified as `Exec=sudo aa-notify -p -f /var/log/audit/audit.log`

=== Dumping profiles ===

In [[https://gitlab.com/apparmor/apparmor/-/wikis/AppArmorMonitoring|AppArmorMonitoring]], the upstream wiki has information on how to debug the parsing of actual profiles. The DebianMan:apparmor_parser command has many different tools for this. For example, this will dump the preprocessed profile, flattening all the `#include` parameters in a single stream:

{{{
apparmor_parser --preprocess /etc/apparmor.d/usr.bin/man
}}}

And this will do everything but loading the kernel, dumping the exact paths and settings passed into the kernel:

{{{
apparmor_parser --skip-kernel-load --debug /etc/apparmor.d/usr.bin/man
}}}

=== Report bugs ===

If you've found a bug in an !AppArmor profile provided by a debian package, please [[AppArmor/Reportbug|report it]]

=== Disable AppArmor ===

!AppArmor is a security mechanism and disabling it is not recommended. If you really need to disable !AppArmor on your system:

{{{
$ sudo mkdir -p /etc/default/grub.d
$ echo 'GRUB_CMDLINE_LINUX_DEFAULT="$GRUB_CMDLINE_LINUX_DEFAULT apparmor=0"' \
  | sudo tee /etc/default/grub.d/apparmor.cfg
$ sudo update-grub
$ sudo reboot
}}}



== Edit AppArmor profiles ==

You can find documentation on building your own profiles at '''[[AppArmor#External_links]]'''

Once a profile has been edited, reload the profile in the kernel with [[DebianMan:8/apparmor_parser|apparmor_parser(8)]]:

{{{
$ sudo apparmor_parser -r /etc/apparmor.d/usr.bin.example
}}}

Restart the application and reverify logs.

Note: the parser silently ignores rules that are not supported by the running kernel. To check which rules are actually enforced, pass the `--warn=rules-not-enforced --warn=rule-downgraded` options to `apparmor_parser`.







----

CategorySystemSecurity

Translation(s): English - 简体中文

This page describes how to use and troubleshoot AppArmor on Debian.


Install AppArmor

AppArmor is available in Debian since Debian 7 "Wheezy".

Install AppArmor userspace tools:

Enable AppArmor

If you are using Debian 10 "Buster" or newer, AppArmor is enabled by default so you can skip this step.

The AppArmor Linux Security Modules (LSM) must be enabled from the linux kernel command line in the bootloader:

$ sudo mkdir -p /etc/default/grub.d
$ echo 'GRUB_CMDLINE_LINUX_DEFAULT="$GRUB_CMDLINE_LINUX_DEFAULT apparmor=1 security=apparmor"' \
  | sudo tee /etc/default/grub.d/apparmor.cfg
$ sudo update-grub
$ sudo reboot

Inspect the current state

AppArmor profiles can be set to different modes:

  • complain mode: violations to the policy will only be logged

  • enforce mode: operations that violate the policy will be blocked.

Note that deny rules in profiles are enforced/blocked even in complain mode.

Find out if AppArmor is enabled (returns Y if true):

$ cat /sys/module/apparmor/parameters/enabled

List all loaded AppArmor profiles for applications and processes and detail their status (enforced, complain, unconfined):

$ sudo aa-status

List running executables which are currently confined by an AppArmor profile:

$ ps auxZ | grep -v '^unconfined'

List of processes with tcp or udp ports that do not have AppArmor profiles loaded:

$ sudo aa-unconfined
$ sudo aa-unconfined --paranoid

Find / install more profiles

AppArmor profiles live in /etc/apparmor.d/. Some packages automatically install their own profiles in this directory. To find more profiles:

Enabling profiles

Debian packages that install profiles to /etc/apparmor.d/ automatically enable them (complain mode). Other profiles need to be copied to this directory and manually set to complain or enforce mode.

For example to install an "extra" profile from the /usr/share/apparmor/extra-profiles/ directory provided by apparmor-profiles and set it to complain mode:

# list available profiles
$ ls /usr/share/apparmor/extra-profiles/

# install the profile
$ sudo cp /usr/share/apparmor/extra-profiles/usr.bin.example /etc/apparmor.d/

# set the profile to complain mode
sudo aa-complain /etc/apparmor.d/usr.bin.example

To set a profile to enforce mode, use aa-enforce instead of aa-complain. Beware though: many profiles are not up-to-date and will break functionality in enforce mode, be ready to debug!

Debug

AppArmor logs can be found in the systemd journal, in /var/log/syslog and /var/log/kern.log (and /var/log/audit.log when auditd is installed).

Diagnose if a bug might have been caused by AppArmor

Look in these logs for:

  • ALLOWED (logged when a profile in complain mode violates the policy)

  • DENIED (logged when a profile in enforce mode actually blocks an operation)

The full log message should provide more information on what exact access has been denied. You can use this to edit profiles before turning them on in enforce mode.

Sometimes, it's useful to disable a profile and to test again if the bug persists:

# disable a profile temporarily
$ sudo aa-disable /etc/apparmor.d/usr.bin.example
# after testing, re-enable it in complain mode
$ sudo aa-complain /etc/apparmor.d/usr.bin.example
# or in enforce mode
$ sudo aa-enforce /etc/apparmor.d/usr.bin.example

Note that systemd might still load the profile if you have AppArmorProfile setup in the unit file. Then the proper way to disable the profile then is to comment out that line in the unit file, or through a systemd override.

Desktop notifications

The apparmor-notify package provides desktop notifications (through aa-notify) when a policy violation occurs. The program should start automatically when you login.

  • If auditd is not installed, your user should be a member of the adm Group

  • If auditd is installed, /etc/xdg/autostart/apparmor-notify.desktop should be modified as Exec=sudo aa-notify -p -f /var/log/audit/audit.log

Dumping profiles

In AppArmorMonitoring, the upstream wiki has information on how to debug the parsing of actual profiles. The apparmor_parser command has many different tools for this. For example, this will dump the preprocessed profile, flattening all the #include parameters in a single stream:

apparmor_parser --preprocess /etc/apparmor.d/usr.bin/man

And this will do everything but loading the kernel, dumping the exact paths and settings passed into the kernel:

apparmor_parser --skip-kernel-load --debug /etc/apparmor.d/usr.bin/man

Report bugs

If you've found a bug in an AppArmor profile provided by a debian package, please report it

Disable AppArmor

AppArmor is a security mechanism and disabling it is not recommended. If you really need to disable AppArmor on your system:

$ sudo mkdir -p /etc/default/grub.d
$ echo 'GRUB_CMDLINE_LINUX_DEFAULT="$GRUB_CMDLINE_LINUX_DEFAULT apparmor=0"' \
  | sudo tee /etc/default/grub.d/apparmor.cfg
$ sudo update-grub
$ sudo reboot

Edit AppArmor profiles

You can find documentation on building your own profiles at AppArmor#External_links

Once a profile has been edited, reload the profile in the kernel with apparmor_parser(8):

$ sudo apparmor_parser -r /etc/apparmor.d/usr.bin.example

Restart the application and reverify logs.

Note: the parser silently ignores rules that are not supported by the running kernel. To check which rules are actually enforced, pass the --warn=rules-not-enforced --warn=rule-downgraded options to apparmor_parser.


CategorySystemSecurity