diff --git a/reaction-mailcreate/README.md b/reaction-mailcreate/README.md index a94731487228e575ea259c5c2542adada3137c80..f2b4c630806b84bae58b6135c742620dd342e602 100644 --- a/reaction-mailcreate/README.md +++ b/reaction-mailcreate/README.md @@ -176,4 +176,125 @@ DFN-CERT,Tobias,Dussa,dussa@dfn-cert.de ## Example Calls -### +Note: In all examples, the option `--dry-run` will be used if necessary, so +that copy-and-pasting the examples does not lead to e-mails being sent by +mistake. + +The simplest invocation of the script is this: +``` +./createMails.py +``` +Assuming that the sample directory is present and containing the sample +mail template and input list, this call takes all the default values, +creates a mail for each entry in the default input list, and saves that. +Since no sender e-mail and webserver address is given, dry-mode is implied, +so no mails are actually sent, nor is any web call actually made. + +The output should look something like this: +``` +DRY RUN. Not actually sending e-mails or creating targets, just creating mail files and URLs. +Writing mail to Mails/Test/DFN-CERT/2024-08-16T10:23:43Z.eml +``` + +The minimal set of parameters that must be given is the sender e-mail and +the target webserver to be used. To send a mail without any webserver +reference, set the webserver to the empty string; an minimal example +invocation that would actually send e-mails (if `--dry-run` was not set) is +this: +``` +./createMails.py --dry-run --from "Tobias Dussa <dussa@dfn-cert.de>" --webserver "" +``` + +Notice that since no target webserver is specified, the `URL` variable in +the default mail template does not make much sense, but you can still use +it -- it will just not contain any complete URL. + +To be able to identify individual test runs, you can add an infix to the +invocation. This will (by default) insert the infix into several file +names, in particular, into the input file name; therefore, in order to run +the following command, you need to copy the sample input file to a new file +as well. Note that while the infix is just a positional argument, since it +begins with a dash in this example, we need to make sure that it is +interpreted as a positional argument, not as a usage of the `-R` (reply-to) +parameter by adding two dashes first. +``` +cp Mails/Test/Input.lst Mails/Test/Input-Run_A.lst +./createMails.py --dry-run --from "Tobias Dussa <dussa@dfn-cert.de>" --webserver "" -- -Run_A +DRY RUN. Not actually sending e-mails or creating targets, just creating mail files and URLs. +Writing mail to Mails/Test/DFN-CERT/2024-08-16T10:34:11Z-Run_A.eml +``` + +Generally, you will likely want to specify the campaign name. This then +requires a proper directory with the right input files, so it will not work +with the sample files, but you can set the campaign name like this: +``` +./createMails.py --campaign MyCampaign +``` +The relevant files are then expected to be in `Mails/MyCampaign/`, and +mail files are written in that directory as well. + +The following example modifies the mail subject: +``` +./createMails.py --subject "This is just a simple mail subject" +``` + +Likewise, you can specify a reply-to address to be used with the +`-R`/`--reply-to` parameter. + +To add additional mail recipients to the CC header, you can do this: +``` +./createMails.py --cc mail@example.com +``` + +You can use the same mechanism for BCC recipients and for file attachments. +All these parameters can be used multiple times to specify multiple +additional recipients or attachments: +``` +./createMails.py --bcc foo@example.com --bcc bar@example.com --cc baz@example.com --attach createMails.py +``` + +Cryptographic signatures can be added as well. At the moment, the only +supported backend is GPG. The following call will invoke GPG and sign the +mail with the default key. +``` +./createMails.py --sign gpg +``` + +You can also specify a different key to be used by passing call options to +the signing command: +``` +./createMails.py --sign gpg --sign-arg "keyid=0x1234567890ABCDEF" +``` + +By default, mails are sent to localhost on port 25 using plain SMTP. To +use a different mail server, you need to specify the server to be used: +``` +./createMails.py --smtpserver smtp.example.com +``` + +If you need to log in to send a mail, you can do so as well. This will +imply TLS and set the port to 465. To override this, you need to set the +port yourself. +``` +./createMails.py --smtpuser user --smtppass pass +``` + +If you do not want to specify the SMTP password on the command line for +security reasons, you can set the password to a dash, and you will be +prompted for the password interactively: +``` +./createMails.py --smtpuser user --smtppass - +``` + +An actual invocation will obviously combine a lot of the above parameters: +``` +./createMails.py --dry-run \ + --smtpserver smtp.example.com --smtpuser user --smtppass pass \ + --from "Sender Dude <sender@example.com>" \ + --cc "CC Recipient <cc@example.com>" \ + --bcc bcc@example.com \ + --reply-to reply@example.com \ + --sign gpg + --campaign SampleCommsChallenge2024 \ + --webserver https://landing.example.com +```