1.1.11. mailer

This module provides the functionality used to create and sending messages from the client application.

1.1.11.1. Data

MIME_TEXT_PLAIN = 'This message requires an HTML aware email agent to be properly viewed.\r\n\r\n'[source]

The static string to place in MIME message as a text/plain part. This is shown by email clients that do not support HTML.

1.1.11.2. Functions

count_targets_file(target_file)[source]

Count the number of valid targets that the specified file contains. This skips lines which are missing fields or where the email address is invalid.

Parameters

target_file (str) – The path the the target CSV file on disk.

Returns

The number of valid targets.

Return type

int

get_invite_start_from_config(config)[source]

Get the start time for an invite from the configuration. This takes into account whether the invite is for all day or starts at a specific time.

Parameters

config (dict) – The King Phisher client configuration.

Returns

The timestamp of when the invite is to start.

Return type

datetime.datetime

guess_smtp_server_address(host, forward_host=None)[source]

Guess the IP address of the SMTP server that will be connected to given the SMTP host information and an optional SSH forwarding host. If a hostname is in use it will be resolved to an IP address, either IPv4 or IPv6 and in that order. If a hostname resolves to multiple IP addresses, None will be returned. This function is intended to guess the SMTP servers IP address given the client configuration so it can be used for SPF record checks.

Parameters
  • host (str) – The SMTP server that is being connected to.

  • forward_host (str) – An optional host that is being used to tunnel the connection.

Returns

The IP address of the SMTP server.

Return type

None, ipaddress.IPv4Address, ipaddress.IPv6Address

render_message_template(template, config, target=None, analyze=False)[source]

Take a message from a template and format it to be sent by replacing variables and processing other template directives. If the target parameter is not set, a placeholder will be created and the message will be formatted to be previewed.

Parameters
  • template (str) – The message template.

  • config (dict) – The King Phisher client configuration.

  • target (MessageTarget) – The messages intended target information.

  • analyze (bool) – Set the template environment to analyze mode.

Returns

The formatted message.

Return type

str

rfc2282_timestamp(dt=None, utc=False)[source]

Convert a datetime.datetime instance into an RFC 2282 compliant timestamp suitable for use in MIME-encoded messages.

Parameters
  • dt (datetime.datetime) – A time to use for the timestamp otherwise the current time is used.

  • utc – Whether to return the timestamp as a UTC offset or from the local timezone.

Returns

The timestamp.

Return type

str

1.1.11.3. Classes

class MailSenderThread(application, target_file, rpc, tab=None)[source]

Bases: Thread

The King Phisher threaded email message sender. This object manages the sending of emails for campaigns and supports pausing the sending of messages which can later be resumed by unpausing. This object reports its information to the GUI through an optional MailSenderSendTab instance, these two objects are very interdependent.

__init__(application, target_file, rpc, tab=None)[source]
Parameters
count_targets()[source]

Count the number of targets that will be sent messages.

Returns

The number of targets that will be sent messages.

Return type

int

create_message_calendar_invite(target, attachments)[source]

Create a MIME calendar invite to be sent from a set of parameters.

Parameters
  • target (MessageTarget) – The information for the messages intended recipient.

  • uid (str) – The message’s unique identifier.

  • attachments (Attachments) – The attachments to add to the created message.

Returns

The new MIME message.

Return type

email.mime.multipart.MIMEMultipart

create_message_email(target, attachments)[source]

Create a MIME email to be sent from a set of parameters.

Parameters
  • target (MessageTarget) – The information for the messages intended recipient.

  • uid (str) – The message’s unique identifier.

  • attachments (MessageAttachments) – The attachments to add to the created message.

Returns

The new MIME message.

Return type

email.mime.multipart.MIMEMultipart

get_mime_attachments()[source]

Return a MessageAttachments object containing both the images and raw files to be included in sent messages.

Returns

A namedtuple of both files and images in their MIME containers.

Return type

MessageAttachments

iterate_targets(counting=False)[source]

Iterate over each of the targets as defined within the configuration. If counting is False, messages will not be displayed to the end user through the notification tab.

Parameters

counting (bool) – Whether or not to iterate strictly for counting purposes.

Returns

Each message target.

Return type

MessageTarget

missing_files()[source]

Return a list of all missing or unreadable files which are referenced by the message template.

Returns

The list of unusable files.

Return type

list

pause()[source]

Sets the running and paused flags correctly to indicate that the object is paused.

paused[source]

A threading.Event object indicating if the email sending operation is or should be paused.

process_pause(set_pause=False)[source]

Pause sending emails if a pause request has been set.

Parameters

set_pause (bool) – Whether to request a pause before processing it.

Returns

Whether or not the sending operation was cancelled during the pause.

Return type

bool

run()[source]

The entry point of the thread.

running[source]

A threading.Event object indicating if emails are being sent.

send_message(target_email, msg)[source]

Send an email using the connected SMTP server.

Parameters
  • target_email (str) – The email address to send the message to.

  • msg (mime.multipart.MIMEMultipart) – The formatted message to be sent.

server_smtp_connect()[source]

Connect and optionally authenticate to the configured SMTP server.

Returns

The connection status as one of the ConnectionErrorReason constants.

server_smtp_disconnect()[source]

Clean up and close the connection to the remote SMTP server.

server_smtp_reconnect()[source]

Disconnect from the remote SMTP server and then attempt to open a new connection to it.

Returns

The reconnection status.

Return type

bool

server_ssh_connect()[source]

Connect to the remote SMTP server over SSH and configure port forwarding with SSHTCPForwarder for tunneling SMTP traffic.

Returns

The connection status as one of the ConnectionErrorReason constants.

smtp_connection[source]

The smtplib.SMTP connection instance.

stop()[source]

Requests that the email sending operation stop. It can not be resumed from the same position. This function blocks until the stop request has been processed and the thread exits.

tab[source]

The optional MailSenderSendTab instance for reporting status messages to the GUI.

tab_notify_sent(emails_done, emails_total)[source]

Notify the tab that messages have been sent.

Parameters
  • emails_done (int) – The number of emails that have been sent.

  • emails_total (int) – The total number of emails that are going to be sent.

tab_notify_status(message)[source]

Handle a status message regarding the message sending operation.

Parameters

message (str) – The notification message.

tab_notify_stopped()[source]

Notify the tab that the message sending operation has stopped.

target_file[source]

The name of the target file in CSV format.

unpause()[source]

Sets the running and paused flags correctly to indicate that the object is no longer paused.

class MessageAttachments(files, images)[source]

A named tuple for holding both image and file attachments for a message.

files[source]

A tuple of MIMEBase instances representing the messages attachments.

images[source]

A tuple of MIMEImage instances representing the images in the message.

class MessageTarget(first_name, last_name, email_address, uid=None, department=None, line=None)[source]

Bases: object

A simple class for holding information regarding a messages intended recipient.

__init__(first_name, last_name, email_address, uid=None, department=None, line=None)[source]
department[source]

The target recipient’s department name.

email_address[source]

The target recipient’s email address.

first_name[source]

The target recipient’s first name.

last_name[source]

The target recipient’s last name.

line[source]

The line number in the file from which this target was loaded.

uid[source]

The unique identifier that is going to be used for this target.

class MessageTargetPlaceholder(uid=None)[source]

Bases: MessageTarget

A default MessageTarget for use as a placeholder value while rendering, performing tests, etc.

__init__(uid=None)[source]
department[source]

The target recipient’s department name.

email_address[source]

The target recipient’s email address.

first_name[source]

The target recipient’s first name.

last_name[source]

The target recipient’s last name.

line[source]

The line number in the file from which this target was loaded.

uid[source]

The unique identifier that is going to be used for this target.

class TopMIMEMultipart(mime_type, config, target)[source]

Bases: MIMEMultipart

A mime.multipart.MIMEMultipart subclass for representing the top / outer most part of a MIME multipart message. This adds additional default headers to the message.

__init__(mime_type, config, target)[source]
Parameters
  • mime_type (str) – The type of this part such as related or alternative.

  • config (dict) – The King Phisher client configuration.

  • target (MessageTarget) – The target information for the messages intended recipient.