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

Addionally, pyquarantine-milter provides a sanitized, harmless version of the text parts of e-mails, which can be embedded in e-mail notifications. This makes it easier for users to decide, if a match is a false-positive or not. If a matching quarantine provides a quarantine ID of the original e-mail, it is also available as a template variable. This is useful if you want to add links to a webservice to notification e-mails, to give your users the ability to release e-mails or whitelist the from-address for example. The webservice then releases the e-mail from the quarantine.

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. If you have to specify a path in the config, you can always use a relative path to the last loaded config file.

### 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.
* **preferred_quarantin_action**  
  Defines which quarantine action should be preferred if multiple quarantines are matching for multiple recipients.  
  If at least one recipient receives the original e-mail due to whitelisting, the action is always ACCEPT.
  Possible values are:
  * **first**
  * **last**

### Quarantine sections
The following configuration options are mandatory in each quarantine section:
* **regex**  
  Regular expression to filter e-mail headers.
* **quarantine_type**  
  One of the quarantine-types described below.
* **action**  
  One of the actions described below.
* **notification_type**  
  One of the notification types described below.
* **whitelist_type**  
  One of the whitelist types described below.
* **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 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:
  * **quarantine_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.
  * **{EMAIL_HTML_TEXT}**  
    Sanitized version of the e-mail text part of the original e-mail. Only harmless HTML tags and attributes are included. Images are replaced with the image set by notification_email_replacement_img option.

  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**  
    Path to the notification e-mail template. It is hold in memory during runtime.
  * **notification_email_replacement_img**  
    Path to the image to replace images in e-mails. It is hold in memory during runtime. Leave it empty to disable.
  * **notification_email_embedded_imgs**  
    Comma-separated list of images to embed into the notification e-mail. The Content-ID of each image will be set to the filename, so you can reference it from the e-mail template. All images are hold in memory during runtime.  
    Leave empty to disable.

### Actions
Every quarantine responds with a milter-action if an e-mail header matches the configured regular expression. Please think carefully what you set here or your MTA will do something you do not want.  
The following actions are available:
* **ACCEPT**  
  Tell the MTA to continue processing the e-mail.
* **DISCARD**  
  Tell the MTA to silently discard the e-mail.
* **REJECT**  
  Tell the MTA to reject the e-mail.


### Whitelist types
* **NONE**  
  No whitelist will be used.

* **DB**  
  A database whitelist will be used. All database types supported by peewee are available.  

  The following configuration options are mandatory for this whitelist type:
  * **whitelist_db_connection**  
  Database connection string (e.g. mysql://user:password@host:port).  

  * **whitelist_db_table**  
  Database table to use.

## Developer information
Everyone who wants to improve or extend this project is very welcome.