From bde1eb21e9e400550e107c332a09eab112aa0cec Mon Sep 17 00:00:00 2001
From: Tobias Dussa <tobias@dussa.de>
Date: Thu, 15 Aug 2024 22:26:19 +0200
Subject: [PATCH] Initial readme.
---
reaction-mailcreate/README.md | 174 ++++++++++++++++++++++++++++++++++
1 file changed, 174 insertions(+)
create mode 100644 reaction-mailcreate/README.md
diff --git a/reaction-mailcreate/README.md b/reaction-mailcreate/README.md
new file mode 100644
index 0000000..3e92723
--- /dev/null
+++ b/reaction-mailcreate/README.md
@@ -0,0 +1,174 @@
+# 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.
--
GitLab