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: threading.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 = None[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 = None[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 = None[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 = None[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 = None[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]

Initialize self. See help(type(self)) for accurate signature.

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: king_phisher.client.mailer.MessageTarget

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

__init__(uid=None)[source]

Initialize self. See help(type(self)) for accurate signature.

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

Bases: email.mime.multipart.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.