From 1652633d93aa578e4d902a94c94a48f08ae78c3a Mon Sep 17 00:00:00 2001 From: kernelmethod <17100608+kernelmethod@users.noreply.github.com> Date: Wed, 30 Nov 2022 17:09:26 -0500 Subject: [PATCH] [docs] Add AppArmor profile for Debian and Ubuntu installations (#1183) * Enable the 'admonitions' Markdown extension for Mkdocs. The admonitions extension to Python-Markdown allows you to include rST-style "admonitions" to Markdown documents, for instance, !!! note Here's an important note to keep in mind! In general, the current documentation uses bold text to try to achieve the same effect, which is a bit harder to notice and makes it difficult to differentiate between "here's something useful to know" versus "here there be dragons". * Add AppArmor profile and documentation for LSM-related sandboxing This commit adds an AppArmor profile for gotosocial in examples/apparmor/gotosocial. This will (hopefully) serve as a helpful security mitigation for people are planning on deploying GTS on a Debian-family Linux distribution. I've also updates the documentation to include some information about deploying GTS with either AppArmor or SELinux (moving the documentation for the former out of the "binary installation guide" docs). --- docs/installation_guide/advanced.md | 92 +++++++++++++++++++++++++++++ docs/installation_guide/binary.md | 4 -- example/apparmor/gotosocial | 50 ++++++++++++++++ mkdocs.yml | 3 + 4 files changed, 145 insertions(+), 4 deletions(-) create mode 100644 example/apparmor/gotosocial diff --git a/docs/installation_guide/advanced.md b/docs/installation_guide/advanced.md index 29814bc90..aa752184f 100644 --- a/docs/installation_guide/advanced.md +++ b/docs/installation_guide/advanced.md @@ -164,3 +164,95 @@ Yes! GoToSocial supports canonical environment variables for doing this: `HTTP_P The http client that GoToSocial uses will be initialized with the appropriate proxy. The environment values may be either a complete URL or a `host[:port]`, in which case the "http" scheme is assumed. The schemes "http", "https", and "socks5" are supported. + +## Application sandboxing + +Although GoToSocial does not currently have any known vulnerabilities, it's +always a good idea to be proactive about security. One way you can help protect +your instance is to run it in a *sandbox* -- an environment that constrains the +actions a program can perform in order to limit the impact of a future exploit. + +[Using Docker](../../installation_guide/docker) to run GoToSocial can work as a +(limited) sandboxing mechanism. For Linux installations, [Linux Security +Modules](https://en.wikipedia.org/wiki/Linux_Security_Modules) such as +[AppArmor](https://www.apparmor.net/) and +[SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux) work as a +complementary mechanism that typically provide stronger protections. You should +use + +- **AppArmor** if you're running GoToSocial on Debian, Ubuntu, or OpenSUSE, and +- **SELinux** if you're using CentOS, RHEL, or Rocky Linux. + +For other Linux distributions, you will need to look up what Linux Security +Modules are supported by your kernel. + +!!! note + GoToSocial is currently alpha software, and as more features are implemented + these security policies may quickly become outdated. You may find that using + AppArmor or SELinux causes GoToSocial to fail in unexpected ways until GTS + becomes stable. + +!!! caution + Sandboxing is an _additional_ security mechanism to help defend against + certain kinds of attacks; it _is not_ a replacement for good security + practices. + +### AppArmor + +For Linux distributions supporting AppArmor, there is an AppArmor profile +available in `example/apparmor/gotosocial` that you can use to confine your +GoToSocial instance. If you're using a server (such as a VPS) to deploy +GoToSocial, you can install the AppArmor profile by downloading it and copying +it into the `/etc/apparmor.d/` directory: + +```bash +wget https://raw.githubusercontent.com/superseriousbusiness/gotosocial/main/example/apparmor/gotosocial +sudo install -o root -g root gotosocial /etc/apparmor.d/gotosocial +sudo apparmor_parser -Kr /etc/apparmor.d/gotosocial +``` + +If you're using Docker Compose, you should add the following `security_opt` +section to your Compose configuration file: + +```yaml +services: + gotosocial: + ... + security_opt: + - apparmor=gotosocial +``` + +If you're running GoToSocial as a Systemd service, you should instead add this +line under `[Service]`: + +```ini +[Service] +... +AppArmorProfile=gotosocial +``` + +For other deployment methods (e.g. a managed Kubernetes cluster), you should +review your platform's documentation for how to deploy an application with an +AppArmor profile. + +#### Disabling the AppArmor profile + +If enabling the AppArmor profile causes your instance to experience issues, you +can uninstall it from the system as follows: + +``` +sudo apparmor_parser -R /etc/apparmor.d/gotosocial +sudo rm -vi /etc/apparmor.d/gotosocial +``` + +You will also want to remove any changes you made to your Compose configuration +or Systemd service file to enable the profile. + +### SELinux + +!!! note + Currently, this SELinux policy only works for the [binary installation + method](../../installation_guide/binary). + +If SELinux is available on your system, you can optionally install [SELinux +policy](https://github.com/lzap/gotosocial-selinux) to further improve security. diff --git a/docs/installation_guide/binary.md b/docs/installation_guide/binary.md index 269f0d01b..d570a3974 100644 --- a/docs/installation_guide/binary.md +++ b/docs/installation_guide/binary.md @@ -141,7 +141,3 @@ sudo systemctl enable --now gotosocial.service If you want to run other webservers on port 443 or want to add an additional layer of security you might want to use [nginx](./nginx.md), [Caddy](./caddy.md) or [Apache httpd](./apache-httpd.md) as reverse proxy -## 8. SELinux (optional) - -If SELinux is available on your system, you can optionally install [SELinux policy](https://github.com/lzap/gotosocial-selinux) to further improve security. - diff --git a/example/apparmor/gotosocial b/example/apparmor/gotosocial new file mode 100644 index 000000000..341bfd205 --- /dev/null +++ b/example/apparmor/gotosocial @@ -0,0 +1,50 @@ +#include + +profile gotosocial flags=(attach_disconnected, mediate_deleted) { + #include + #include + + /gotosocial/gotosocial mrix, + /usr/bin/gotosocial mrix, + /usr/local/bin/gotosocial mrix, + + owner /gotosocial/{,**} r, + owner /gotosocial/storage/** wk, + + # Allow GoToSocial to write logs + # + # NOTE: you only need to allow write permissions to /var/log/syslog if you've + # enabled logging to syslog. Otherwise, you can comment out that line. + /var/log/gotosocial/* w, + owner /var/log/syslog w, + + # These directories are not currently used by any of the recommended + # GoToSocial installation methods, but they may be used in the future and/or + # for custom installations. + owner /etc/gotosocial/{,**} r, + owner /usr/lib/gotosocial/{,**} r, + owner /usr/share/gotosocial/{,**} r, + owner /usr/local/etc/gotosocial/{,**} r, + owner /usr/local/lib/gotosocial/{,**} r, + owner /usr/local/share/gotosocial/{,**} r, + owner /var/lib/gotosocial/{,**} r, + owner /opt/gotosocial/{,**} r, + owner /run/gotosocial/{,**} r, + + /proc/sys/net/core/somaxconn r, + /sys/kernel/mm/transparent_hugepage/hpage_pmd_size r, + owner @{PROC}/@{pid}/cpuset r, + + # TCP / UDP network access + network inet stream, + network inet6 stream, + network inet dgram, + network inet6 dgram, + + # Allow GoToSocial to send signals to/receive signals from worker processes + # Allow GoToSocial to receive signals from unconfined processes + signal (receive) peer=unconfined, + signal (send,receive) peer=gotosocial, +} + +# vim:syntax=apparmor diff --git a/mkdocs.yml b/mkdocs.yml index 0c3d6da00..3ed70661e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,6 +5,9 @@ copyright: GoToSocial is licensed under the GNU AGPL v3 LICENSE. Copyright (C) 2 plugins: - render_swagger +markdown_extensions: + - markdown.extensions.admonition + extra_javascript: - assets/js/swagger-ui-bundle.js