Overview
Ever find yourself on a computer where you only have access to e-mail? That’s where FTPoverEmail shines. I frequently find myself in situations where I only have access to e-mail, but I still want to interact with my home server in an FTP-like fashion. You may be in a hotel business center or you may be a pentester and you want to drop FTPoverEmail on a box so that you have reached back via a protocol that’s a bit more innocuous. In the future, I plan on adding SSHoverEmail capability, which makes the application all the more practical for a pentesting scenario and more useful for the common case.
How It Works
I wrote FTPoverEmail in Python. The server reaches out to an email account the user specifies and polls the account via imap for commands. Right now, the server supports the following commands:
FTP cd path
FTP dir [path]
FTP pwd
FTP get [path/]file_name
FTP put [path/]file_name
The server requires the FTP prefix before the command. I added this because I plan to add other protocols in the future and the server needs a way to distinguish between them. The user simply sends any of these commands in the body of an email to the address the user set the server to poll. The subject of the e-mail doesn’t matter. The user can send from any e-mail address they choose and the server responds to that address. I plan to add an authentication feature to add a measure of protection to the service. The response includes any output from the command. If the user performed a get command, the server includes the file as an attachment in the response. If the user performs a put command, the server places the file wherever the command specifies and sends a response acknowledging the command completed successfully.
Future Work
Below is a list of features I plan to add:
Support for the following commands:
- FTP delete file_name
- FTP mkdir directory
- FTP rmdir directory
- FTP ls <—– This will just be an alias for dir, but it makes life easier
- FTP mget file_list
- A configuration file where the user can set any pertinent variables.
- Support for all services instead of just gmail.
- A fix for the Windows Phone, which adds some funky formatting I haven’t figured out
- A GUI interface in the browser
- Database support
- SSH over Email capability
The Code
I did my best to comment thoroughly to make the program as readable as possible. Comment if you have questions. Here is a link to the download:
FTPoverEmail.py
# __author__ = 'gecman'
import smtplib
import email
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart
from email.mime.base import MIMEBase
from email import encoders
import mimetypes
import os
import imaplib
import time
import sys
# TODO: Windows-1252 encoding adds an = sign which the program can't handle.
# Find a way to take care of it.
# TODO: Test more rapidly sent email
# Global Variables
from_name = ''
to_name = ''
subject = ''
user = "whatever_email@gmail.com"
password = "whatever_email_password"
# sendresponse sends text based responses to the client
# response: The response text to send in the body of the mail
def sendresponse(response):
# Create a response email from the response string
response_email = MIMEText(response)
print(subject)
# Configure the message header fields
response_email['Subject'] = subject
response_email['From'] = to_name
response_email['To'] = from_name
# Declare an instance of the SMTP class and connect to the smtp server
smtp = smtplib.SMTP('smtp.gmail.com')
# Start the TLS connection
smtp.starttls()
# Login to the server
smtp.login(user, password)
# Attempt to send the email in the try block
# noinspection PyBroadException
try:
# Send the response email
smtp.sendmail(to_name, from_name, response_email.as_string())
# Catch all exceptions. I could have only done SMTP exceptions,
# but I'm not sure if they'll add more in the future
# so I thought it better to just catch all of them for this one line.
except:
# The following lines dump the details of the error to stdout
print(
"Server encountered the following error while attempting to
send email: \nType: {0}\nValue: {1}\nTraceback: {2}".format(
str(sys.exc_info()[0]), str(sys.exc_info()[1]), str(sys.exc_info()[2])))
finally:
# Close the smtp connection
smtp.close()
# sendfile Instead of just sending text, sends a file. Primarily used for the FTP get functionality.
# file_name: The name of the file to be attached to the email.
def sendfile(file_name):
# Declare the mime class and message header fields
response = MIMEMultipart()
response['Subject'] = subject
response['From'] = to_name
response['To'] = from_name
# Attach the text portion of the message. Alerts the user of the file name and that it is attached.
response.attach(MIMEText("Grabbed file " + file_name + ". See attachment."))
# Define the major and minor mime type
# attachment = MIMEBase('application', "octet-stream")
# This command uses the mimetypes module to attempt to guess the mimetype of the file.
# The strict=False argument
# tells the mimetypes module to include modules not officially registered with IANA
# The file_type variable will be in the format of a tuple #major type#/#sub type# , #encoding#
file_type = mimetypes.guess_type(file_name, strict=False)
main_type = None
# mimetypes.guess_type returns None if it doesn't recognize the file type.
# In this case I chose to use the generic
# application octect-stream type, which should be safe.
if file_type is None:
attachment = MIMEBase('application', 'octet-stream')
else:
main_type = file_type[0].split('/')[0]
sub_type = file_type[0].split('/')[1]
# This pulls the major type and sub type and splits them around the
# '/' character providing the major type in the
# first argument and the sub type in the second argument
attachment = MIMEBase(main_type, sub_type)
# Read the file from disk and set it as the payload for the email
# The with statement ensures the file is properly closed even if an exception is raised.
try:
f = open(file_name, "rb")
attachment.set_payload(f.read())
f.close()
except OSError:
print(
"Server encountered the following error while attempting to
open the file you asked for: \nType: {0}\nValue: {1}\nTraceback: {2}".format(
str(sys.exc_info()[0]), str(sys.exc_info()[1]), str(sys.exc_info()[2])))
# TODO: Fix the fact that this shows the newlines as \n instead of properly adding newlines
sendresponse(
"Server encountered the following error while attempting to open the file
you asked for: \nType: {0}\nValue: {1}\nTraceback: {2}".format(
str(sys.exc_info()[0]), str(sys.exc_info()[1]), str(sys.exc_info()[2])))
# Check to see if the attachment requires encoding
if main_type == 'application' or main_type == 'audio' or main_type == 'image':
# Encode the attachment
encoders.encode_base64(attachment)
# This sets the header. The output will be in the following format:
# Content-Disposition: attachment; file_name="the_file_name"
# The os.path.basename(file_name) portion strips the leading part of the
# file path and just gives the actual file name
attachment.add_header('Content-Disposition', 'attachment; file_name="%s"'
% os.path.basename(file_name))
# A ttach the attachment to the response message
response.attach(attachment)
# Declare an instance of the SMTP class and connect to the smtp server
smtp = smtplib.SMTP('smtp.gmail.com')
# Start the TLS connection
smtp.starttls()
# Login to the server
smtp.login(user, password)
# Attempt to send the email
# noinspection PyBroadException
try:
# Send the response email
smtp.sendmail(to_name, from_name, response.as_string())
# Close the smtp connection
smtp.close()
# Catch all exceptions. I could have only done SMTP exceptions,
# but I'm not sure if they'll add more in the future
# so I thought it better to just catch all of them for this one line.
except:
# Close the smtp connection
smtp.close()
# The following lines print all of the error details to stdout and
# also send them back to the user
print(
"Server encountered the following error while attempting to
send email: \nType: {0}\nValue: {1}\nTraceback: {2}".format(
str(sys.exc_info()[0]), str(sys.exc_info()[1]), str(sys.exc_info()[2])))
# TODO: Fix the fact that this shows the newlines as \n instead of properly adding newlines
sendresponse(
"Server encountered the following error while attempting to send
email: \nType: {0}\nValue: {1}\nTraceback: {2}".format(
str(sys.exc_info()[0]), str(sys.exc_info()[1]), str(sys.exc_info()[2])))
# Responsible for connecting to the server via IMAP and actually grabbing the e-mail.
# It then passes the text or
# content of the e-mail to proccommand for processing.
def getemail():
# Declare as global variables. They are originally defined at the beginning.
# Without these the values won't
# carry over to other functions.
global from_name
global to_name
global subject
# Connect to Google's imap server
# TODO: This needs to be generic
mail = imaplib.IMAP4_SSL('imap.gmail.com')
# Login to the imap server
mail.login(user, password)
# List all mailbox (folder) names. In gmail these are called labels.
mail.list()
# Select the inbox folder
mail.select("inbox")
# Grab an ordered list of all mail. The search function returns an ordered list
# from newest to oldest. Only grab new mail.
result, data = mail.search(None, "UNSEEN")
# Check to see if there was new mail or not. If there wasn't return None.
if not data[0].split():
return None
# Data[0] is a list of email IDs in a space separated string.
id_list = data[0].split()
# Grab the latest email
# TODO add support for queuing
latest_email_id = id_list[-1]
# Fetch the email body for the given ID
result, data = mail.fetch(latest_email_id, "(RFC822)")
raw_email = data[0][1]
# Grab the body of the email including the raw text, headers, and payloads
# The following line converts the email from a string into an email message object
email_message = email.message_from_bytes(raw_email)
if email_message['To'] is not None:
print(email_message['To'])
to_name = email_message['To']
else:
print("Received email with an empty To address. Ignoring the message.")
return
if email_message['Return-Path'] is not None:
print(email_message['Return-Path'])
from_name = email_message['Return-Path']
else:
print("Received email with an empty Return-Path. Ignoring the message.")
return
if email_message['Subject'] is not None:
# If there is already a Re in the subject don't add it again
if email_message['Subject'].find("Re:") == -1:
subject = "Re: " + email_message['Subject']
else:
subject = email_message['Subject']
print(subject)
else:
subject = ''
# Check to see if this is a multipart email message. If it isn't just return the text portion.
if email_message.get_content_maintype() == 'multipart':
# Used to determine whether a command was found in the email
found_command = False
# Walk the various sections of the email.
# The enumerate function here returns a number for each email part walked through.
# IE 0 for the first part in
# the email, 1 for the next, and so on.
for index, part in enumerate(email_message.walk()):
# The multipart section is just a container so we can skip it.
if part.get_content_maintype() is 'multipart':
continue
# Check to see if we have reached the text body of the message
if part.get_content_type() == 'text/plain':
found_command = True
message = part.get_payload()
proccommand(message.split('\n')[0].rstrip(), index, email_message)
#This does not need to continue after this run
break
# If a command was found and successfully processed simply return
if found_command:
return
else:
sendresponse("Error: No command was found in multipart email. Was it there?")
print("Error: Server encountered a multipart email that did not appear
to have a command in it")
# Return the text payload
elif email_message.get_content_main_type() == 'text':
print(email_message.get_payload())
# Pass the command to proccommand. rstrip removes any whitespace characters from the tail.
proccommand(email_message.get_payload().split('\n')[0].rstrip())
# It wasn't text - do not process the email
else:
print("Error processing email in getemail. Encountered unrecognized content type.")
sendresponse("Error processing email in getemail. Encountered unrecognized content type.")
return
# Processes the command retrieved from the email server
# message: The message from the email server in the form of [type] [command(s)]
# index: This is an index into a multipart email's parts.
# getemail may have already processed some of them and it is
# unnecessary to reprocess those parts
# email_message: This is an email_message passed from getemail.
# In terms of FTP, this is used for the put command
def proccommand(message, index=None, email_message=None):
command = message.split(' ')
# Used for logging to determine whether a command was successful or not
errors = False
# Process an FTP command
if command[0].upper() == "FTP":
# cd command ---------------------------
# TODO: Test cd with shortcuts such as ..
# Process the command "cd"
if command[1].lower() == "cd":
# Ensure the correct number of arguments was passed"
if len(command) != 3:
sendresponse("Error: Incorrect number of arguments for cd")
errors = True
# Make sure the path exists
elif not os.path.exists(command[2]):
sendresponse("Error: The path: \"" + command[2] + "\" does not exist")
errors = True
# Process the "cd" command
else:
os.chdir(command[2])
sendresponse("CD completed successfully. Directory is now: " + os.getcwd())
# dir command ---------------------------
# Process the command "dir"
if command[1].lower() == "dir":
# Ensure the correct number of arguments was passed"
if len(command) < 2 or len(command) > 3:
sendresponse("Error: Incorrect number of arguments for dir")
errors = True
else:
# If no arguments are passed to dir then list the current directory
if len(command) == 2:
response = ""
for file in os.listdir(os.getcwd()):
# Contains newline delimited directory listing at end
response = response + file + "\n"
sendresponse(response)
# Process the dir command with directory argument
else:
# Make sure the path exists
if not os.path.exists(command[2]):
sendresponse("Error: The path: \"" + command[2] + "\" does not exist")
errors = True
# If the path does exist then list the directory
else:
response = ""
for file in os.listdir(command[2]):
# Contains newline delimited directory listing at end
response = response + file + "\n"
sendresponse(response)
# pwd command ---------------------------
# Process the pwd command
if command[1].lower() == "pwd":
# Ensure correct number of arguments was passed
if len(command) != 2:
sendresponse("Error: Incorrect number of arguments for pwd")
errors = True
else:
# Get current directory and respond
sendresponse(os.getcwd())
# get command ---------------------------
# Process the get command
if command[1].lower() == "get":
# Ensure correct number of arguments was passed
if len(command) != 3:
sendresponse("Error: Incorrect number of arguments for get")
errors = True
else:
# Make sure the file exists
if not os.path.exists(command[2]):
sendresponse("Error: The path: \"" + command[2] + "\" does not exist")
errors = True
else:
sendfile(command[2])
# put command ---------------------------
if command[1].lower() == "put":
# Ensure correct number of arguments was passed
if len(command) != 3:
sendresponse("Error: Incorrect number of arguments for put")
errors = True
else:
# There may be a better way to do this, but I'm using this
# to inform the functionality below whether it
# should actually execute. This defaults to true,
# but gets set to False if the path is determined to be
# non-valid
valid_path = True
# The line below splits command[2] into two pieces. For example say the path is
# C:\Users\randomUser\Downloads\tryMe.exe. The split command will split this into
# C:\Users\randomUser\Downloads\ and tryMe.exe.
# The [0] index grabs just the path prefix. In this case
# bool will return true IF there is a path prefix and false if there isn't.
# We don't want to check if the path exists if the user didn't provide
# any path (because a path of '' will return false. If the
# user didn't provide a path we want to just dump the file
# in the current directory whatever it is.
if bool(os.path.split(command[2])[0]):
# Make sure the path exists exists
if not os.path.exists(os.path.split(command[2])[0]):
valid_path = False
sendresponse("Error: The path: \"" + os.path.split(command[2])[0] +
"\" does not exist")
errors = True
# Only execute this if a valid path is supplied (or no path as the case may be)
if valid_path:
# getemail already parsed some of the sections.
# The index comes from the getemail function and
# allows this section to skip the parts of the email that were already processed.
# email_message.walk() is a generator, but we want to index into it
# so we use the list function.
# This turns it into a list, which we are permitted to index into
for part in list(email_message.walk())[index:]:
# The multipart section is just a container so we can skip it.
if part.get_content_maintype() is 'multipart':
continue
# Grab the file name from the section
file_name = part.get_filename()
# Make sure the file name actually exists and if it does write the file.
if bool(file_name):
try:
fp = open(command[2], 'wb')
# Get the payload of the email and write it.
# The decode=True argument basically says if
# the payload is encoded, decode it first otherwise,
# it gets returned as is.
fp.write(part.get_payload(decode=True))
fp.close()
sendresponse("Successfully procced the put command: " + message)
except OSError:
errors = True
print(
"Server encountered the following error while attempting
to write the file you uploaded: \nType:
{0}\nValue: {1}\nTraceback: {2}".format(
str(sys.exc_info()[0]), str(sys.exc_info()[1]),
str(sys.exc_info()[2])))
# TODO: Fix the fact that this shows the newlines as \n
# instead of properly adding newlines
sendresponse(
"Server encountered the following error while attempting to write
the file you uploaded: \nType: {0}\nValue:
{1}\nTraceback: {2}".format(
str(sys.exc_info()[0]), str(sys.exc_info()[1]),
str(sys.exc_info()[2])))
# Break out of the for loop. We should only need to write one file.
break
# If the protocol or desired action did not match anything...
else:
sendresponse("Error: Bad or nonexistent command: " + message)
print("Server received an email which matched no commands.")
# Used server side for logging purposes
if errors:
print("Failed to process command \"" + message + "\"")
else:
print("Successfully processed command: " + message)
# This is the main section
while 1:
getemail()
time.sleep(5)
