Initial commit of source code and docs

README.md

@@ -0,0 +1,100 @@
+# pyquarantine-milter
+A pymilter based sendmail/postfix pre-queue filter with the ability to quarantine e-mails, sending notifications
+to recipients and respond with a milter-action (ACCEPT, DISCARD or REJECT).
+
+It is useful in many cases because of its felxible configuration and the ability to handle any number of quarantines.
+The MTA can check e-mail headers using regular expressions to determine if and which quarantine to use. 
+Each quarantine can be configured with a quarantine type, notification type, whitelist and an action to respond with.
+
+The project is currently in alpha status, but will soon be used in a productive enterprise environment and possibly existing bugs will be fixed.
+
+## Requirements
+* pymilter <https://pythonhosted.org/pymilter/>
+* peewee <https://github.com/coleifer/peewee/>
+* BeautifulSoup <https://www.crummy.com/software/BeautifulSoup/>
+
+## Configuration
+The pyquarantine module uses an INI-style configuration file. The sections are described below.
+
+### Section "global"
+Any available configuration option can be set in the global section as default instead of in a quarantine section.  
+
+The following configuration options are mandatory in the global section:
+* **quarantines**  
+  Comma-separated, ordered list of active quarantines. For each, there must be a section of the same name in the configuration.
+* **smtp_host**  
+  SMTP host to inject original e-mails. This is needed if not all recipients of an e-mail are whitelisted
+* **smtp_port**  
+  SMTP port
+
+### Quarantine sections
+The following configuration options are mandatory in each quarantine section:
+* **regex**  
+  Regular expression to filter e-mail headers.
+* **type**  
+  One of the quarantine-types described below.
+* **action**  
+  One of the actions described below.
+* **notification**  
+  One of the notification types described below.
+* **whitelist**  
+  Database connection string (e.g. mysql://user:password@host:port) or NONE to disable whitelist.
+
+### Quarantine types
+* **NONE**  
+  Original e-mails scrapped, sent to nirvana, black-holed or however you want to call it.
+
+* **FILE**  
+  Original e-mails are stored on the filesystem with a unique filename. The filename is available as a
+  template variable used in notifiaction templates.  
+  The following configuration options are mandatory for this quarantine type:
+  * **directory**  
+    The directory in which quarantined e-mails are stored.
+
+
+### Notification types
+* **NONE**  
+  No quarantine notifications will be sent.
+
+* **EMAIL**  
+  Quarantine e-mail notifications are sent to recipients. The SMTP host and port, E-mail template, from-address and the subject are configurable for each quarantine. The templates must contain the notification e-mail text in HTML form.  
+
+  The following template variables are available:
+  * **{EMAIL_FROM}**  
+    E-mail from-address received by the milter (envelope-from).
+  * **{EMAIL_TO}**  
+    E-mail recipient address of this notification.
+  * **{EMAIL_SUBJECT}**  
+    Configured e-mail subject.
+  * **{EMAIL_QUARANTINE_ID}**  
+    Quarantine-ID of the original e-mail if available, empty otherwise.
+
+The following configuration options are mandatory for this notification type:
+* **notification_email_from**  
+  Notification e-mail from-address.
+* **notification_email_subject**  
+  Notification e-mail subject.
+* **notification_email_template**  
+  Notification e-mail template to use.
+* **notification_email_replacement_img**  
+  An image to replace images in e-mail.
+
+
+### Actions
+Every quarantine responds with a milter-action if an e-mail header matches the configured regular expression.  
+The following actions are available:
+* **ACCEPT**  
+  Continue processing e-mails.
+* **DISCARD**  
+  Silently discard e-mails.
+* **REJECT**  
+  Reject e-mails.
+
+
+### Whitelist
+If a whitelist database connection string is configured, the following configuration options are mandatory:
+* **whitelist_table**  
+  Database table to use.
+
+## Developer information
+Everyone who wants to improve or extend this project is very welcome.