Add AppArmor profile for Debian and Ubuntu installations

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.

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.
-

example/apparmor/gotosocial

@@ -0,0 +1,50 @@
+#include <tunables/global>
+
+profile gotosocial flags=(attach_disconnected, mediate_deleted) {
+  #include <abstractions/base>
+  #include <abstractions/nameservice>
+
+  /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

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