spacefreak/pyquarantine-milter
1
0
Fork 0
Code Issues Pull Requests Releases Activity

change README.md

Browse Source
This commit is contained in:
Thomas Oettli
2022-01-11 18:33:25 +01:00
parent 5ede9ac0f7
commit 78647e4017
1 changed files with 23 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
README.md
View File

@@ -1,9 +1,15 @@
# pyquarantine-milter # pyquarantine-milter
A pymilter based sendmail/postfix pre-queue filter with the ability to quarantine e-mails, sending notifications and modify e-mail headers and bodies. A pymilter based sendmail/postfix pre-queue filter with the ability to ...
* modify e-mail headers (add, modify, delete)
* store e-mails
* send e-mail notifications
* append and prepend disclaimers to e-mail text parts
* quarantine e-mails (store e-mail, optionally notify receivers)
It is useful in many cases due to its flexible configuration and the ability to handle any number of quarantines and modifications sequential and conditional. Storages and whitelists used by quarantines can be managed with the built-in CLI.
A pymilter based sendmail/postfix pre-queue filter with the ability to quarantine e-mails, send notifications and modify e-mail headers and/or bodies. Addionally, pyquarantine-milter provides a sanitized, harmless version of the text parts of e-mails as template variable, 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.
It is useful in many cases due to its flexible configuration and the ability to handle any number of quarantines and/or modifications sequential and conditional. It is also possible to use any metavariable as template variable (e.g. storage ID, envelope-from address, ...). This may be used to give your users the ability to release e-mails or whitelist the from-address for example. A webservice then releases the e-mail from the quarantine.
The project is currently in beta status, but it is already used in a productive enterprise environment that processes about a million e-mails per month. The project is currently in beta status, but it is already used in a productive enterprise environment that processes about a million e-mails per month.
@@ -30,9 +36,9 @@ pyquarantine-milter -t
## Configuration ## Configuration
pyquarantine uses a config file in JSON format. It has to be JSON valid with the exception of allowed comment lines starting with **#**. pyquarantine uses a config file in JSON format. It has to be JSON valid with the exception of allowed comment lines starting with **#**.
The basic idea is to configure rules that contain actions. Both rules and actions may have conditions. An example of using rules is separating incoming and outgoing e-mails using the **local** condition. Rules and actions are always processed in the given order. The basic idea is to configure rules that contain actions. Both rules and actions may have conditions. An example of using rules is separating incoming and outgoing e-mails using the local condition. Rules and actions are always processed in the given order.
#### Global ### Global
Global config options: Global config options:
* **socket** (optional) * **socket** (optional)
Socket used to communicate with the MTA. If it is not specified in the config, it has to be set as command line option. Socket used to communicate with the MTA. If it is not specified in the config, it has to be set as command line option.
@@ -50,7 +56,7 @@ Global config options:
* **rules** * **rules**
List of rule objects. List of rule objects.
#### Rule ### Rule
Config options for rule objects: Config options for rule objects:
* **name** * **name**
Name of the rule. Name of the rule.
@@ -63,7 +69,7 @@ Config options for rule objects:
* **pretend** (optional) * **pretend** (optional)
See section [Global](#Global). See section [Global](#Global).
#### Action ### Action
Config options for action objects: Config options for action objects:
* **name** * **name**
Name of the action. Name of the action.
@@ -78,7 +84,7 @@ Config options for action objects:
* **pretend** (optional) * **pretend** (optional)
See section [Global](#Global). See section [Global](#Global).
#### Conditions ### Conditions
Config options for conditions objects: Config options for conditions objects:
* **local** (optional) * **local** (optional)
Matches outgoing e-mails (sender address matches **local_addrs**) if set to **true** or matches incoming e-mails if set to **false**. Matches outgoing e-mails (sender address matches **local_addrs**) if set to **true** or matches incoming e-mails if set to **false**.
@@ -98,12 +104,12 @@ Config options for conditions objects:
Prefix for the name of metavariables which are possibly provided by the **envfrom**, **envto** or **headers** condition. Meta variables will be provided if the regular expressions contain named subgroups, see [python.re](https://docs.python.org/3/library/re.html) for details. Prefix for the name of metavariables which are possibly provided by the **envfrom**, **envto** or **headers** condition. Meta variables will be provided if the regular expressions contain named subgroups, see [python.re](https://docs.python.org/3/library/re.html) for details.
If not set, no metavariables will be provided. If not set, no metavariables will be provided.
#### Whitelist ### Whitelist
Config options for whitelist objects: Config options for whitelist objects:
* **type** * **type**
See section [Whitelists](#Whitelists). See section [Whitelists](#Whitelists).
#### Actions ### Actions
Available action types: Available action types:
##### add_header ##### add_header
Add new header. Add new header.
@@ -175,13 +181,14 @@ Options:
Send notification. Send notification.
Options: Options:
* **type** * **type**
See section [Notifications](#Notifications). See section [Notification types](#Notification types).
##### quarantine ##### quarantine
Quarantine e-mail. Quarantine e-mail.
Options: Options:
* **store** * **store**
Options for e-mail storage, see action **store** in section [Actions](#Actions). Options for e-mail storage, see action **store** in section [Actions](#Actions).
If the option **metadata** is not specificall set for this storage, it will be set to true.
* **smtp_host** * **smtp_host**
SMTP host used to release e-mails from quarantine. SMTP host used to release e-mails from quarantine.
* **smtp_port** * **smtp_port**
@@ -195,11 +202,11 @@ Options for e-mail storage, see action **store** in section [Actions](#Actions).
* **REJECT** (Tell MTA to reject the e-mail.) * **REJECT** (Tell MTA to reject the e-mail.)
* **DISCARD** (Tell MTA to discard the e-mail.) * **DISCARD** (Tell MTA to discard the e-mail.)
* **reject_reason** (optional, default: "Message rejected") * **reject_reason** (optional, default: "Message rejected")
Reject message used if milter_action is set to reject. Reject message sent to MTA if milter_action is set to reject.
* **whitelist** (optional) * **whitelist** (optional)
Options for a whitelist, see **whitelist** in section [Conditions](#Conditions). Options for a whitelist, see **whitelist** in section [Conditions](#Conditions).
#### Storages ### Storages
Available storage types: Available storage types:
##### file ##### file
File storage. File storage.
@@ -211,7 +218,7 @@ Options:
* **mode** (optional, default: system default) * **mode** (optional, default: system default)
File mode when new files are created. File mode when new files are created.
#### Notifications ### Notification types
Available notification types: Available notification types:
##### email ##### email
E-Mail notification. E-Mail notification.
@@ -233,7 +240,7 @@ Options:
* **embed_imgs** (optional) * **embed_imgs** (optional)
List of images to embed into the notification e-mail. List of images to embed into the notification e-mail.
#### Whitelists ### Whitelists
Available whitelist types: Available whitelist types:
##### db ##### db
Whitelist stored in database. The table is created automatically if it does not exist yet. Whitelist stored in database. The table is created automatically if it does not exist yet.