diff options
| -rw-r--r-- | docs/installation_guide/advanced.md | 92 | ||||
| -rw-r--r-- | docs/installation_guide/binary.md | 4 | ||||
| -rw-r--r-- | example/apparmor/gotosocial | 50 | ||||
| -rw-r--r-- | mkdocs.yml | 3 |
4 files changed, 145 insertions, 4 deletions
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 <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 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 |