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 17:48:42 +01:00
parent 57b74a83ba
commit 5ede9ac0f7
1 changed files with 121 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

239
README.md
View File

@@ -1,5 +1,8 @@
# pyquarantine-milter # pyquarantine-milter
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. 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 quarantine e-mails, send notifications and modify e-mail headers and/or bodies.
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 useful in many cases due to its flexible configuration and the ability to handle any number of quarantines and/or modifications sequential and conditional.
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.
@@ -29,25 +32,25 @@ pyquarantine uses a config file in JSON format. It has to be JSON valid with the
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.
* **local_addrs** (optional, default: **[fe80::/64, ::1/128, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16]**) * **local_addrs** (optional, default: [fe80::/64, ::1/128, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16])
List of hosts and network addresses which are considered local. It is used for the condition option [local](#Conditions). List of hosts and network addresses which are considered local. It is used for the condition option [local](#Conditions).
* **loglevel** (optional, default: **info**) * **loglevel** (optional, default: "info")
Set the log level. This option may be overriden by any rule or action object. Set the log level. This option may be overriden by any rule or action object.
Possible values: Possible values:
* **error** * **error**
* **warning** * **warning**
* **info** * **info**
* **debug** * **debug**
* **pretend** (optional, default: **false**) * **pretend** (optional, default: false)
Pretend actions, for test purposes. This option may be overriden by any rule or action object. Pretend actions, for test purposes. This option may be overriden by any rule or action object.
* **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.
@@ -60,7 +63,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.
@@ -75,7 +78,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**.
@@ -95,150 +98,150 @@ 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.
Options: Options:
* **field** * **field**
Name of the header. Name of the header.
* **value** * **value**
Value of the header. Value of the header.
* **del_header** ##### del_header
Delete header(s). Delete header(s).
Options: Options:
* **field** * **field**
Regular expression to match against header names. Regular expression to match against header names.
* **value** (optional) * **value** (optional)
Regular expression to match against the headers value. Regular expression to match against the headers value.
* **mod_header** ##### mod_header
Modify header(s). Modify header(s).
Options: Options:
* **field** * **field**
Regular expression to match against header names. Regular expression to match against header names.
* **search** (optional) * **search** (optional)
Regular expression to match against header values. You may use subgroups or named subgroups (python syntax) to include parts of the original value in the new value. Regular expression to match against header values. You may use subgroups or named subgroups (python syntax) to include parts of the original value in the new value.
* **value** * **value**
New value of the header. New value of the header.
* **add_disclaimer** ##### add_disclaimer
Append or prepend disclaimer to text and/or html body parts. Append or prepend disclaimer to text and/or html body parts.
Options: Options:
* **action** * **action**
Action to perform with the disclaimer. Action to perform with the disclaimer.
Possible values: Possible values:
* append * append
* prepend * prepend
* **html_template** * **html_template**
Path to a file which contains the html representation of the disclaimer. Path to a file which contains the html representation of the disclaimer.
* **text_template** * **text_template**
Path to a file which contains the text representation of the disclaimer. Path to a file which contains the text representation of the disclaimer.
* **error_policy** (optional, default: **wrap**) * **error_policy** (optional, default: "wrap")
Set the error policy in case the disclaimer cannot be added (e.g. if the html part cannot be parsed). Set the error policy in case the disclaimer cannot be added (e.g. if the html part cannot be parsed).
Possible values: Possible values:
* **wrap** * **wrap**
A new e-mail body is generated with the disclaimer as body and the original e-mail attached. A new e-mail body is generated with the disclaimer as body and the original e-mail attached.
* **ignore** * **ignore**
Ignore the error and do nothing. Ignore the error and do nothing.
* **reject** * **reject**
Reject the e-mail. Reject the e-mail.
* **add_html_body** (optional, default: **false**) * **add_html_body** (optional, default: false)
Generate a html body with the content of the text body if no html body is present. Generate a html body with the content of the text body if no html body is present.
##### store
Store e-mail.
Options:
* **type**
See section [Storages](#Storages).
* **original** (optional, default: false)
If set to true, store the message as received by the MTA instead of storing the current state of the message, that may was modified already by other actions.
* **metadata** (optional, default: false)
Store metadata.
* **metavar** (optional)
Prefix for the metavariable names. If not set, no metavariables will be provided.
The storage provides the following metavariables:
* **ID** (the storage ID of the e-mail)
* **DATAFILE** (path to the data file)
* **METAFILE** (path to the meta file if **metadata** is set to **true**)
##### notify
Send notification.
Options:
* **type**
See section [Notifications](#Notifications).
##### quarantine
Quarantine e-mail.
Options:
* **store** * **store**
Store e-mail. Options for e-mail storage, see action **store** in section [Actions](#Actions).
Options: * **smtp_host**
* **type**
See section [Storages](#Storages).
* **original** (optional, default: **false**)
If set to true, store the message as received by the MTA instead of storing the current state of the message, that may was modified already by other actions.
* **metadata** (optional, default: **false**)
Store metadata.
* **metavar** (optional)
Prefix for the metavariable names. If not set, no metavariables will be provided.
The storage provides the following metavariables:
* **ID** (the storage ID of the e-mail)
* **DATAFILE** (path to the data file)
* **METAFILE** (path to the meta file if **metadata** is set to **true**)
* **notify**
Send notification.
Options:
* **type**
See section [Notifications](#Notifications).
* **quarantine**
Quarantine e-mail.
Options:
* **store**
Options for e-mail storage, see action **store** in section [Actions](#Actions).
* **smtp_host**
SMTP host used to release e-mails from quarantine. SMTP host used to release e-mails from quarantine.
* **smtp_port** * **smtp_port**
SMTP port used to release e-mails from quarantine. SMTP port used to release e-mails from quarantine.
* **notify** (optional) * **notify** (optional)
Options for e-mail notifications, see action **notify** in section [Actions](#Actions). Options for e-mail notifications, see action **notify** in section [Actions](#Actions).
* **milter_action** (optional) * **milter_action** (optional)
Final milter action to perform. If set, no further rules or actions will be processed. Final milter action to perform. If set, no further rules or actions will be processed.
Possible values: Possible values:
* **ACCEPT** (Tell MTA to accept the e-mail, skip following rules/actions.) * **ACCEPT** (Tell MTA to accept the e-mail, skip following rules/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 used 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.
Options: Options:
* **directory** * **directory**
Directory used to store e-mails. Directory used to store e-mails.
* **metadata** (optional, default: **false**) * **metadata** (optional, default: false)
Store metadata file. Store metadata file.
* **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 #### Notifications
Available notification types: Available notification types:
* **email** ##### email
E-Mail notification. E-Mail notification.
Options: Options:
* **smtp_host** * **smtp_host**
SMTP host used to send notifications. SMTP host used to send notifications.
* **smtp_port** * **smtp_port**
SMTP port used to send notifications. SMTP port used to send notifications.
* **envelope_from** * **envelope_from**
Envelope-From address. Envelope-From address.
* **from_header** * **from_header**
Value of the From header. Value of the From header.
* **subject** * **subject**
Subject of the notification. Subject of the notification.
* **template** * **template**
Notification template. Notification template.
* **repl_img** (optional) * **repl_img** (optional)
Replacement image used to replace all images in the e-mail body. Replacement image used to replace all images in the e-mail body.
* **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.
Options: Options:
* **connection** * **connection**
Database connection string, see [Peewee Playhouse Extension](https://docs.peewee-orm.com/en/latest/peewee/playhouse.html#db-url). Database connection string, see [Peewee Playhouse Extension](https://docs.peewee-orm.com/en/latest/peewee/playhouse.html#db-url).
* **table** * **table**
Database table to use. Database table to use.
## Developer information ## Developer information
Everyone who wants to improve or extend this project is very welcome. Everyone who wants to improve or extend this project is very welcome.