diff --git a/Makefile b/Makefile index f22d56e650..055700336e 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ BUILDDIR=builddir CODESPELL_PARAMS=\ -S Makefile,imgtype,copy,AUTHORS,bin,.git,CHANGELOG.md,changelog.txt,.cirrus.yml,"*.xz,*.gz,*.tar,*.tgz,*ico,*.png,*.1,*.5,*.orig,*.rej,*.xml,*xsl",build.ninja,intro-targets.json,./tests/tests/tier0/proxy-service-fails-on-typo-in-file/systemd/simple.service,tags,./builddir,./subprojects,\ - -L keypair,flate,uint,iff,od,ERRO,crate\ + -L keypair,flate,uint,iff,od,ERRO,crate,te \ --ignore-regex=".*codespell-ignore$$" build: diff --git a/doc/docs/security/selinux.md b/doc/docs/security/selinux.md index 13aa45532e..5666548da9 100644 --- a/doc/docs/security/selinux.md +++ b/doc/docs/security/selinux.md @@ -1,4 +1,5 @@ + # BlueChi's SELinux policy BlueChi provides a custom SELinux policy, limiting access of the `bluechi-controller` and `bluechi-agent`. It can be installed via @@ -42,3 +43,94 @@ semanage permissive -a bluechi_t # add the permissive property to bluechi-agent semanage permissive -a bluechi_agent_t ``` + +## Allowing access to restricted units + +The SELinux policy of BlueChi allows it to manage all systemd units. + +However, when installing some applications and their respective systemd units, e.g. via `dnf`, there might also be additional SELinux Policies installed which prevent BlueChi from managing these. For example, when installing `httpd` on Fedora, it installs also the systemd unit `httpd.service` and the [policy module for apache](https://github.com/fedora-selinux/selinux-policy/blob/rawhide/policy/modules/contrib/apache.te). When trying to start the service via `bluechictl`, the policy will prevent certain operations: + +```bash +# The apache policy prevents BlueChi from managing the httpd service +$ bluechictl stop httpd.service +Failed to issue method call: SELinux policy denies access: Permission denied + +# However, using systemctl works as this is enabled by default in the apache policy +$ systemctl stop httpd.service +``` + +In order to allow BlueChi to manage the `httpd.service`, the necessary allow rule(s) need to be added. + +### Allowing access using audit2allow + +The [audit2allow](https://man7.org/linux/man-pages/man1/audit2allow.1.html) tool can be used to generate these rules based on AVCs. + +First, run all operations with BlueChi that should be allowed. These will fail and create the AVCs used by `audit2allow`. Then use `audit2allow` to generate the allow rules and create the policy package (.pp) which can be installed via `semodule`. The following snippet shows an example for the httpd.service: + +```bash +# generate AVC for the status operation +$ bluechictl status httpd.service +Failed to issue method call: SELinux policy denies access: Permission denied + +# generate AVC for the stop operation +$ bluechictl stop httpd.service +Failed to issue method call: SELinux policy denies access: Permission denied + +# view the type enforcement rule that allows the denied operations +$ audit2allow -a +#============= bluechi_agent_t ============== + +allow bluechi_agent_t httpd_unit_file_t:service { status stop }; + +# create the policy package (.pp) and type enforcement file (.te) +$ audit2allow -a -M httpd-allow +******************** IMPORTANT *********************** +To make this policy package active, execute: + +semodule -i httpd-allow.pp + +$ ls +httpd-allow.pp httpd-allow.te + +# install policy package and run the previously prevented operation +$ semodule -i httpd-allow.pp +$ bluechictl status httpd.service +UNIT | LOADED | ACTIVE | SUBSTATE | FREEZERSTATE | ENABLED | +--------------------------------------------------------------------------------- +httpd.service | loaded | inactive | dead | running | disabled | +``` + +### Allowing access by custom policy + +If you want to grant BlueChi full access, then writing your custom policy is faster. For `httpd` it might look like this: + +```bash +$ cat httpd-allow.te + +module my 1.0; + +require { + type httpd_unit_file_t; + type bluechi_agent_t; + class service { reload start status stop kill load }; +} + +#============= bluechi_agent_t ============== +allow bluechi_agent_t httpd_unit_file_t:service { start stop status reload kill load } ; +``` + +Then install the `selinux-policy-devel` package, compile the `.te` file and install the generated package policy: + +```bash +# install required packages +$ dnf install selinux-policy-devel -y + +# compile .te file +$ make -f /usr/share/selinux/devel/Makefile httpd-allow.pp +Compiling targeted httpd-allow module +Creating targeted httpd-allow.pp policy package +rm tmp/httpd-allow.mod.fc tmp/httpd-allow.mod + +# install compiled policy package +semodule -i httpd-allow.pp +```