1.1.11. mailer
¶
This module provides the functionality used to create and sending messages from the client application.
1.1.11.1. Data¶
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: Returns: The IP address of the SMTP server.
Return type:
-
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:
-
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: - dt (
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: - application (
KingPhisherClientApplication
) – The GTK application that the thread is associated with. - target_file (str) – The CSV formatted file to read message targets from.
- tab (
MailSenderSendTab
) – The GUI tab to report information to. - rpc (
KingPhisherRPCClient
) – The client’s connected RPC instance.
- application (
-
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: - target (
-
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: - target (
-
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
-
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
-
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_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:
-
-
class
MessageAttachments
(files, images)[source]¶ A named tuple for holding both image and file attachments for a 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.
-
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.
-
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.
-