aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorGravatar Joe Banks <[email protected]>2024-08-13 22:44:40 +0100
committerGravatar Joe Banks <[email protected]>2024-08-14 20:02:36 +0100
commit70866889526b7b05453285aac36a6f225b03864c (patch)
tree156c235dde41ce6b4018bd4209eba57880afe848 /docs
parentInstall cowsay (diff)
Add documentation on available mail-based services
Diffstat (limited to 'docs')
-rw-r--r--docs/docs/services/email/mail-services.md64
1 files changed, 64 insertions, 0 deletions
diff --git a/docs/docs/services/email/mail-services.md b/docs/docs/services/email/mail-services.md
new file mode 100644
index 0000000..134ab39
--- /dev/null
+++ b/docs/docs/services/email/mail-services.md
@@ -0,0 +1,64 @@
+---
+description: Automated services available over the Python Discord mailserver
+---
+# Automated Mail Services
+
+We host a selection of services that are made accessible via email to
+`@int.pydis.wtf` addresses.
+
+Unlike service accounts, their mail is not delivered to typical UNIX mailboxes
+(for example, like DMARC reports are), but is instead processed by a local
+script which is spawned by the `master.cf` Postfix config file, and run as the
+`servicemailer` user.
+
+These scripts are flexible on what they can do, they can respond to an email,
+forward something, trigger an action, and so on. The full message body is passed
+to the script for processing.
+
+Services are categorised into the following groups:
+
+| Icon | Access |
+|-----------------|----------------------------------------------|
+| :green_circle: | Available to any mail user |
+| :orange_circle: | Available to any PyDis LDAP user |
+| :red_circle: | Only available to members of the DevOps team |
+
+## Available Services
+
+### :green_circle: Fortunes ([`[email protected]`](mailto:[email protected]))
+
+The fortune service responds to an email with a fortune generated by the
+[Fortune](https://en.wikipedia.org/wiki/Fortune_(Unix)) command. It is one of
+the simplest examples of an automatic mail service.
+
+Optionally, if users send to `[email protected]` then their fortune
+response will be wrapped by a cow.
+
+You can trigger this service by sending an email with any subject and any
+content. It will reply to the email address you sent from.
+
+## Security
+
+Mail-available services are generally secure, we apply the same security
+restrictions we do to all inbound mail:
+
+- Validate SPF policy
+- Validate DKIM policy
+- Validate DMARC policy
+
+You can read more about these [here](./components/validation.md).
+
+Ultimately, there is no reason to believe that service mail opens any additional
+vulnerabilities, though it should not be used for tasks requiring fine-grained
+authorization or to trigger actions that are known to cause consequences, no
+matter how small.
+
+Ideal use-cases for service mail are:
+
+- Services that run harmless commands and return the responses (i.e. `fortune`)
+- Services which query information that is non-sensitive (i.e. currently
+ triggered Prometheus alerts)
+
+Anything that is sensitive or otherwise not suited should instead be implemented
+as a feature on King Arthur or any other system with fine-grained access
+control.