check-sieve
^{_{Because breaking your sieve in production sucks.}}

This project aims to make checking mail Sieve syntax easy and painless. Because breaking your sieve in production sucks.

Particular attention is paid to the quality of errors generated. For example:

Errors found in "testsieve":

Incorrect syntax for command "convert".
On line 2:
convert image image ["pix-x=320","pix-y=240"];
^^^^^^^
Usage: convert  <quoted-from-media-type: string>                                      
         <quoted-to-media-type: string>                                        
         <transcoding-params: string-list>  

For a web-based demonstration of check-sieve which is entirely browser-based, visit https://checksieve.com.

Usage

Usage: check-sieve [options] file1 [file2 ...]

Options:
  -h, --help               Show this message
  --max-list-length N      Flag lists over a certain length (default: none)
  --server <host>:<port>   Only allow capabilities advertised by the specified
                           server.
  --trace-parser           Trace the operation of the parser
  --trace-scanner          Trace the operation of the scanner
  --trace-tree             Trace the abstract-syntax-tree
  --simulate <email-file>  Simulate sieve processing against an email (.eml)
  --test-dir <dir>         Run simulation for all .eml files in dir and diff
                           against matching .out files; exit 1 if any differ
  --rebase <dir>           Regenerate all .out files in dir from current
                           simulation output
  --version                Print out version information

Features

Supported RFCs

• Sieve: An Email Filtering Language (RFC 5228)
• Variables Extension (RFC 5229)
• Date and Index Extensions (RFC 5260)
• Vacation Extension (RFC 5230)
• Vacation "Seconds" Parameter (RFC 6131)
• Include Extension (RFC 6609)
• Copying Without Side Effects (RFC 3894)
• Reject and Extended Reject Extensions (RFC 5429)
• Body Extension (RFC 5173)
• Relational Extension (RFC 5231)
• MIME Part Tests, Iteration, Extraction, Replacement, and Enclosure (RFC 5703)
• Imap4flags Extension (RFC 5232)
• Editheader Extension (RFC 5293)
• Regex Extension (DRAFT)
• Spamtest and Virustest Extensions (RFC 5235)
• Extensions for Notifications (RFC 5435)
• Subaddress Extension (RFC 5233)
• Ihave Extension (RFC 5463)
• Environment Extension (RFC 5183)
• Sieve Notification Mechanism: mailto (RFC 5436)
• Extensions for Checking Mailbox Status and Accessing Mailbox Metadata (RFC 5490)
• Internet Message Access Protocol (IMAP) Events (RFC 6785)
• Converting Messages before Delivery (RFC 6558)
• Detecting Duplicate Deliveries (RFC 7352)
• Delivering to Special-Use Mailboxes (RFC 8579)
• File Carbon Copy (FCC) (RFC 8580)
• Delivery by MAILBOXID (RFC 9042)
• Delivery Status Notifications and Deliver-By Extensions (RFC 6009)
• Extension for Processing Calendar Attachments (RFC 9671)
• Proton Expiration Extension (vnd.proton.expire)
• Proton Eval Extension (vnd.proton.eval)
• Dovecot Invoking External Programs (vnd.dovecot.{pipe,filter,execute})

Note

If you find any discrepancies with these RFCs, have a request for an RFC not included, or have test-cases that should work but don't, please file an issue.

Server capability matching

Some mail servers support a subset of the above capabilities. You can use the --server flag to have check-sieve match the capabilities of your sieve server. This helps avoid cases where your sieve might break because you use a feature your server doesn't support!

Mail sorting simulation

You can simulate sorting a particular email by passing --simulate <path/to/email.eml>. check-sieve will parse your sieve script(s), and print out a list of matched tests, and actions taken.

Additionally, you can maintain a directory of "test" email files, which can function as regression tests with the --test-dir flag. Simply run check-sieve <sieve-file> --test-dir <path/to/dir>, and check-sieve will simulate mail sorting, comparing output to any .out files in the same directory. Rebase the .out files with the --rebase flag.

Note

This feature is experimental, and does not currently implement all of the RFCs listed above. If you'd like your RFC of choice to be prioritized, leave a note in issue #30.

Development

Dependencies

check-sieve minimally depends on having a modern C++ compiler and the Make build automation software.

On BSD-like systems such as FreeBSD, the gmake tool is required.

Building check-sieve only depends on those aforementioned tools. Developing check-sieve requires addition dependencies:

• GNU Bison >= v3.0.4
• Flex >= v2.5.35
• Python >= 3.7
• Python development headers (for testing)

Additionally, Emscripten is required to generate the Check Sieve JavaScript library.

Installing dependencies

Ubuntu and Debian-based distributions

# Synchronize mirrors
sudo apt-get update

# Core development dependencies
sudo apt-get install make gcc g++ bison flex python3 libpython3-dev 

# JavaScript dependencies
sudo apt-get install emscripten

Arch Linux

# Synchronize mirrors, and
# Core development dependencies
sudo pacman -Syu make gcc bison flex python 

# JavaScript dependencies
sudo pacman -Sy emscripten

Fedora / RHEL

sudo dnf install make gcc bison flex python3 python3-devel

There is no package providing emscripten, so you will need to install the emsdk.

Compiling

At the moment, there are four targets for this project:

1. check-sieve -- This is a command-line program you can use to verify sieves.
2. libchecksieve.a -- A statically linked library for embedding in other programs (like check-sieve).
3. checksieve.so -- This is a python extension created for use by the unit tests in the test directory
4. wasm -- This builds a webassembly javascript library using emscripten.

To build check-sieve simply run make. This will also build the static library. Running make test will compile checksieve.so and run the python tests in the tests directory. Finally, running make all will run all of the other targets.

Installing

To install to /usr/local/, simply run the following:

make install

To install to a custom location, build and install with INSTALL_PREFIX set in your environment to the desired location.

Packages

• Arch Linux (community repository)

Snap

Installation of the latest edge snap from snapcraft can be done with the following command:

snap install --edge check-sieve