[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).
This commit is contained in:
kernelmethod 2022-11-30 17:09:26 -05:00 committed by GitHub
parent 3a11861ac6
commit 1652633d93
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 145 additions and 4 deletions

View file

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

View file

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

View file

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

View file

@ -5,6 +5,9 @@ copyright: GoToSocial is licensed under the GNU AGPL v3 LICENSE. Copyright (C) 2
plugins: plugins:
- render_swagger - render_swagger
markdown_extensions:
- markdown.extensions.admonition
extra_javascript: extra_javascript:
- assets/js/swagger-ui-bundle.js - assets/js/swagger-ui-bundle.js