Initial readme.

reaction-mailcreate/README.md

+# Reaction-Mailcreate
+
+This script is used to send a challenge mail to the participating sites.
+
+To do this, the script takes a mail template and a list of
+participating sites as file input and an identifier for the run as
+command-line argument, generates a mail for each site, saves the mail for
+reference, sends it, and calls a URL on the target webserver to "arm" the
+challenge for the site.
+
+The exact behavior can be fine-tuned with lots of parameters.  The
+parameters can be queried with the `-h/--help` option, like this:
+```
+./createMails.py --help
+```
+All options are briefly described, and the default values are given.
+
+If not all necessary options are passed on the command line, the script
+reverts to "dry-run mode," which means it only generates and stores the
+e-mail files, but does not send them or interact with the target
+webserver.
+
+
+## Input Formats
+
+The script takes two files as input, namely (by default):
+ - `{basedir}/{campaign}/Mail.template`, the mail template file, and
+ - `{basedir}/{campaign}/Input{infix}.lst`, the list of participating
+   sites.
+(The `basedir` variable is set to `Mails` by default, while the `campaign`
+variable is set to `Test` by default.)
+
+In addition, `infix` needs to be specified on the command line as a
+positional parameter, but it can be empty (i. e., specified as `""`).  The
+idea is that this allows separate runs of the comms challenge to be clearly
+separated.
+
+### Mail Template
+
+The mail template is expected to be in Jinja2 format.  It can be as simple
+(and functionally useless for a comms challenge) as
+```
+Hello there,
+
+this is a trivial mail.
+
+Yours,
+The Sender.
+```
+but a reasonable example would be
+```
+Dear security contact for {{site}},
+
+you have received this message to verify the security contact data set in
+the eduGAIN Database for your Identity Federation.
+
+Please confirm that this contact is still correct by clicking the following 
+URL and following the instructions:
+
+  {{URL}}
+
+No further action is required except for the above. 
+
+Sincerely yours,
+the eduGAIN Security Team.
+```
+
+A lot of variables are passed to Jinja2, in particular
+ - `site`,
+ - `firstname`,
+ - `lastname`,
+ - `email`,
+ - `URL`,
+among other variables.  The first four variables are taken straight from
+the input file, while the `URL` variable is generated according to the
+command-line parameters (or defaults).
+
+### Participant List
+
+The list of participating sites is expected to be a CSV file with four
+columns: `site` ,`firstname`, `lastname`, and `email`, in that order (and
+with the column titles in the first row).
+
+`site`, `firstname` and `lastname` may be empty (though the `site` value is
+used to separate the mail files into directories by default, so if this
+should be empty, the `output` option must be set to something that does not
+include `site`).  So, an example for a valid site input file (containing
+only one participating site) would be
+```
+site,firstname,lastname,email
+DFN-CERT,Tobias,Dussa,dussa@dfn-cert.de
+```
+
+
+## Parameters
+
+### General Parameters
+
+ - `-b`/`--basedir`: The base directory for all the input/output data.
+   Defaults to `Mails`.
+ - `c`/`--campaign`: The campaign identifier. Defaults to `Test`.
+ - `d`/`--dry-run`: Toggle to force dry-run mode (no mails are actually
+   sent, no web calls are actually made).  Useful to test whether the input
+   data and the mail template used actually generate sensible mails.
+ - `-h`/`--help`: Displays the help text and exits the script.
+ - `-i`/`--input`: The input file for the participating sites.  Defaults
+   to `{basedir}/{campaign}/Input{infix}.lst`.
+ - `-o`/`--output`: The output file name template to be used when
+   generating the mail files.  Defaults to
+   `{basedir}/{campaign}/{site}/{timestamp}{infix}.eml`.
+ - `-t`/`--template`: The mail template file to be used.  Defaults to
+   `{basedir}/{campaign}/Mail.template`.
+ - `--timestamp`: The format used for the `timestamp` variable.  Defaults
+   to `%Y-%m-%dT%H:%M:%SZ` (ISO 8601).
+ - `-v`, `--verbose`: Makes the script more verbose.
+
+### Mail-Generation Parameters
+
+ - `-a`/`--attach`: Add the specified files as attachment to the generated
+   mails.  Can be specified multiple times.  Defaults to none.
+ - `-B`/`--bcc`: Add the specified recipients to the BCC list.  Can be
+   specified multiple times.  Defaults to none.
+ - `-C`/`--cc`: Add the specified recipients to the CC list.  Can be
+   specified multiple times.  Defaults to none.
+ - `-f`/`--from`: Specifies the sender mail address to be used.  If not
+   explicitly set, implies dry-run mode.  Defaults to
+   `Nobody <nobody@example.com>`.
+ - `-R`/`--reply-to`: Specifies the reply-to mail address to be used.
+   Defaults to none.
+ - `--sign`: Specifies the cryptographic signature method to be used.  Can
+   be empty (`""`) or `gpg`.  Defaults to none.
+ - `--sign-arg`: Specifies additional arguments to be passed to the function
+   call that signs the mail.  Defaults to none.
+ - `-s`/`--subject`: Specifies the mail subject to be used.  Defaults to
+   `Security Challenge Message -- {campaign}{infix}`.
+ - `-T`/`--to`: Specifies the recipient mail address to be used.  Defaults
+   to `{firstname} {lastname} <{email}>`.
+
+### SMTP-Related Parameters
+
+ - `-F`/`--force`: Forces to use insecure login if no TLS/SSL is enabled.
+   Defaults to false.
+ - `-S`/`--smtpserver`: Specifies the SMTP server to be used for sending
+   the mails.  If a port is explicitly specified with the `<host>:<port>`
+   syntax, it takes precedence over any implied and explicit port
+   specification using the `smtpport` switch.  Defaults to `localhost`.
+ - `--smtpport`: Specifies the SMTP port to be used.  Takes precedence over
+   implied ports (but not over the explicit port specification in the
+   server specification, if present).  Defaults to 25.
+ - `--smtpuser`: Specifies the SMTP user to be used for sending mails.
+   Implies TLS and port 465 unless STARTTLS is specified.  Defaults to
+   none.
+ - `--smtppass`: Specifies the SMTP password to be used for sending mails.
+   Implies TLS and port 465 unless STARTTLS is specified.  Will be queried
+   interactively if set to `-`.  Defaults to none.
+ - `--starttls`: Use STARTTLS to send mails.  Implies port 587.  Defaults
+   to none.
+
+### Webserver-Related Parameters
+
+ - `-H`/`--hashstring`: Specifies the string to be hashed for the URL.
+   Defaults to `{salt}{campaign}{infix}-{site}`.
+ - `--salt`: Specifies the salt value to be used for hashing.  Defaults to
+   a random 8-byte hex string.
+ - `-u`/`--url`: Specifies the URL template to use for the target
+   webserver.  Defaults to `{webserver}/{campaign}{infix}-{hash}`.
+ - `-U`/`--createurl`: Specifies the URL to be used for "activating" each
+   site's challenge.  Defaults to
+   `{webserver}/{campaign}{infix}-{hash}/create`.
+ - `-w`/`--webserver` Specifies the web server to use as target.  If not
+   set, implies dry-run mode.  To suppress web-hook calling in general
+   (for instance, just to send out a batch of mails without any intended
+   web interaction), set to empty string (`""`).  Defaults to
+   `https://challenge.example.com.