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-10 12:39:35 +01:00
parent 42e7e20c1a
commit 12e2df87d8
1 changed files with 60 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
README.md
View File

@@ -1,8 +1,10 @@
# pyquarantine # pyquarantine-milter
A pymilter based sendmail/postfix pre-queue filter with the ability to add, remove and modify e-mail headers. 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.
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.
The basic idea is to define rules with conditions and actions which are processed when all conditions are true. It is useful in many cases due to its flexible configuration and the ability to handle any number of quarantines and/or modifications sequential.
The basic idea is to configure rules with optional conditions. If all conditions match, the configured actions (e.g. quarantine, modify, ...) within the rule are performed on the e-mail. Each action can have its own conditions as well.
## Dependencies ## Dependencies
pyquarantine is depending on these python packages, but they are installed automatically if you are working with pip. pyquarantine is depending on these python packages, but they are installed automatically if you are working with pip.
@@ -21,15 +23,15 @@ cp /etc/pyquarantine/pyquarantine.conf.example /etc/pyquarantine/pyquarantine.co
* Modify /etc/pyquarantine/pyquarantine.conf according to your needs. * Modify /etc/pyquarantine/pyquarantine.conf according to your needs.
## Configuration options ## Configuration options
pyquarantine uses a config file in JSON format. The config file has to be JSON valid with the exception of allowed comment lines starting with **#**. The options are described below. pyquarantine uses a config file in JSON format. The config file has to be JSON valid with the exception of allowed comment lines starting with **#**.
Rules and actions are processed in the given order. Rules and actions are processed in the given order.
### Global ### Global
Config options in **global** section: Global config options:
* **socket** (optional) * **socket** (optional)
The socket used to communicate with the MTA. If it is not specified in the config, it has to be set as command line option. The 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) * **local_addrs** (optional)
A list of hosts and network addresses which are considered local. It is used to for the condition option [local](#Conditions). A list of hosts and network addresses which are considered local. It is used for the condition option [local](#Conditions).
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** 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**
* **loglevel** (optional) * **loglevel** (optional)
Set the log level. This option may be overriden by any rule or action object. Possible values are: Set the log level. This option may be overriden by any rule or action object. Possible values are:
@@ -40,53 +42,57 @@ Config options in **global** section:
Default: **info** Default: **info**
* **pretend** (optional) * **pretend** (optional)
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**
List of rule objects.
### Rules ### Rule
Config options for **rule** objects: Rule config options:
* **name** (optional) * **name** (optional)
Name of the rule. Name of the rule.
Default: **Rule #n** Default: **Rule #n**
* **actions** * **actions**
A list of action objects which are processed in the given order. A list of action objects which are processed in the given order.
* **conditions** (optional) * **conditions** (optional)
A list of conditions which all have to be true to process the actions. A list of conditions which all have to be true to process the rule.
* **loglevel** (optional) * **loglevel** (optional)
As described above in the [Global](#Global) section. See section [Global](#Global).
* **pretend** (optional) * **pretend** (optional)
As described above in the [Global](#Global) section. See section [Global](#Global).
### Actions ### Action
Config options for **action** objects: Action config options:
* **name** (optional) * **name** (optional)
Name of the action. Name of the action.
Default: **Action #n** Default: **Action #n**
* **type** * **type**
Action type. Possible values are: See section [Actions](#Actions).
* **add_header** * **options**
* **del_header** Options for the action according to action type (as described below).
* **mod_header**
* **add_disclaimer**
* **store**
* **conditions** (optional) * **conditions** (optional)
A list of conditions which all have to be true to process the action. A list of conditions which all have to be true to process the action.
* **loglevel** (optional) * **loglevel** (optional)
As described above in the [Global](#Global) section. See section [Global](#Global).
* **pretend** (optional) * **pretend** (optional)
As described above in the [Global](#Global) section. See section [Global](#Global).
Config options for **add_header** actions: ### Actions
The following action types are available.
* **add_header**
Add new header.
* **field** * **field**
Name of the header. Name of the header.
* **value** * **value**
Value of the header. Value of the header.
Config options for **del_header** actions: * **del_header**
Delete header(s).
* **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.
Config options for **mod_header** actions: * **mod_header**
Modify header(s).
* **field** * **field**
Regular expression to match against header names. Regular expression to match against header names.
* **search** (optional) * **search** (optional)
@@ -94,7 +100,8 @@ Config options for **mod_header** actions:
* **value** * **value**
New value of the header. New value of the header.
Config options for **add_disclaimer** actions: * **add_disclaimer**
Append or prepend disclaimer to text and/or html body parts.
* **action** * **action**
Action to perform with the disclaimer. Possible values are: Action to perform with the disclaimer. Possible values are:
* append * append
@@ -104,7 +111,7 @@ Config options for **add_disclaimer** actions:
* **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) * **error_policy** (optional)
Set the error policy in case the disclaimer cannot be added (e.g. if no body part is present in the e-mail). Possible values are: Set the error policy in case the disclaimer cannot be added (e.g. if the html part cannot be parsed). Possible values are:
* **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**
@@ -112,18 +119,40 @@ Config options for **add_disclaimer** actions:
* **reject** * **reject**
Reject the e-mail. Reject the e-mail.
Default: **wrap** Default: **wrap**
* **add_html_body** (optional)
Generate a html body with the content of the text body if no html body is present.
Default: **false**
Config options for **store** actions: * **store**
* **storage_type** Store e-mail.
* **type**
Storage type. Possible values are: Storage type. Possible values are:
* **file** * **file**
* **original** (optional) * **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. 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.
Default: **false**
Config options for **file** storage: * **file**
* **directory** * **directory**
Directory used to store e-mails. Directory used to store e-mails.
* **metadata** (optional)
Store metadata file.
Default: **false**
* **mode** (optional)
Set file mode.
Default: system default
* **metavar** (optional)
If set, some information (e.g. storage id) is saved as meta variables for later use.
* **notify**
Send notification to receiver.
* **quarantine**
Quarantine message.
* **rewrite_links**
Rewrite links in html body part.
### Conditions ### Conditions
Config options for **conditions** objects: Config options for **conditions** objects:
@@ -136,5 +165,6 @@ Config options for **conditions** objects:
* **envto** (optional) * **envto** (optional)
A regular expression to match against all evenlope-to addresses. All addresses must match to fulfill the condition. A regular expression to match against all evenlope-to addresses. All addresses must match to fulfill the condition.
## 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.