Email Remote Access

Control remote computer using email

View Demo · Documentation · Report Bug · Request Feature

📔 Table of Contents

• About the Project
  • Screenshots
  • Tech Stack
  • Features
  • Environment Variables
• Getting Started
  • Prerequisites
  • Run Locally
• Usage
  • Server
  • Server App
  • Client App
  • Mail App
    • Authorize the app
    • Connect to the server
    • Send mail
    • Instruction format
    • Supported instructions
    • Fetch mail
    • Execute instructions
  • Mail Server
    • Authorization
    • Connect to the server
    • Fetch mail
    • Execute instructions
  • Dear PyGui Demo
  • CLI
• Roadmap
• Contributing
  • Code of Conduct
• FAQ
• License
• Contact
• Acknowledgements

🌟 About the Project

📷 Screenshots

• Server App:

• Client App:

• Mail App:

👾 Tech Stack

Client

• Python
• SocketIO
• Tkinter
• Dear PyGui

Server

• Python
• SocketIO
• FastAPI
• uvicorn

🎯 Features

• Client App: A simple GUI app to control a remote computer

  • Linux support.
  • Shutdown/logout:
    • Shutdown computer.
    • Logout computer.
  • MAC address:
    • Get the computer's MAC address.
  • Live screen:
    • Live stream computer's screen.
    • Save the screenshot.
  • Directory:
    • List all files in a directory.
    • Copy files to the client computer.
    • Copy files to the server computer.
    • Delete files.
  • App process:
    • List all processes.
    • List applications.
    • Kill processes.
  • Registry:
    • Create a registry key.
    • Delete registry key.
    • Get registry value.
    • Set registry value.

• Mail App: A simple GUI app to control a remote computer using email

  • Shutdown/logout:
    • Shutdown computer.
    • Logout computer.
  • MAC address:
    • Get the computer's MAC address.
  • Live screen:
    • Live stream computer's screen. (Won't do)
    • Save the screenshot.
  • Directory:
    • List all files in a directory.
    • Copy files to the client computer.
    • Copy files to the server computer.
    • Delete files.
  • App process:
    • List all processes.
    • List applications.
    • Kill processes.
  • Registry:
    • Create a registry key.
    • Delete registry key.
    • Get registry value.
    • Set registry value.

🔑 Environment Variables

To run this project, you will need to add the following environment variables to your .env file:

• App configs:

  TEST_VAR: Description of this environment variable.

E.g:

# .env
TEST_VAR="my secret key"

You can also check out the file .env.example to see all required environment variables.

🧰 Getting Started

‼️ Prerequisites

• Python: >= 3.12.

• This project uses Poetry as package manager:

  Linux, macOS, Windows (WSL)

  curl -sSL https://install.python-poetry.org | python3 -

  Read more about installation on Poetry documentation.

🏃 Run Locally

Clone the project:

git clone https://github.com/DuckyMomo20012/email-remote-access.git

Go to the project directory:

cd email-remote-access

Install dependencies:

poetry install

pre-commit install

OR:

Install dependencies with pip:

pip install -r requirements.txt

Export dependencies from pyproject.toml

Export Poetry dependencies to file requirements.txt:

poetry export -f requirements.txt --output requirements.txt

[!NOTE]

You can add option: --dev to include development dependencies.

---

Activate the virtual environment:

poetry shell

Start the program:

• Server App:

  poe dev

  OR

  poe dev server

• Client App:

  poe dev client

• Mail App:

  poe dev mail

• Mail Server:

  poe dev server:mail

• Dear PyGui Demo:

  poe demo

👀 Usage

Server:

⬆️ Back to top

You will have to start the server manually by running the src/server/server.py:

python src/server/server.py

This will start an uvicorn server with port 5656 and with host 0.0.0.0, which is the IP address of your local machine.

Server App

⬆️ Back to top

This app allows you to start and stop the Server manually.

Run the server:

poe dev

OR

poe dev server

After the app starts, you will have to start the server manually by clicking the Start server button.

The app will start the server from Server. The server still runs with port 5656 and with host 0.0.0.0, which is the IP address of your local machine.

To stop the server, click the Stop server button.

Behind the scene

When you click the Start server button, the app will start an uvicorn server in different process, and store the process ID for later use.

When you click the Stop server button, the app will find child processes from the parent process the ID stored before and kill it, then terminate the parent process.

Client App

This app will connect to the server and allow you to control the server machine with supported commands.

Run the client app:

poe dev client

Connect to the server by entering the server's IP address and port:

• IP address: The IP address of your server machine.
• Port: 5656.

Mail App

⬆️ Back to top

This app will connect to the server and allow you to control the server machine by running commands sent from email.

Note

To use this app, you need to provide the credentials.json file in the root directory. Please follow the instructions on the page: Python quickstart to create your own App and download the credentials.json file.

Run the mail app:

poe dev mail

Authorize the app

If this is the first time you run the app, you will be asked to authorize the app. The app will open a browser window and ask you to log in to your Google account.

After you log in, you will be asked to give the app permissions:

• Read all resources and their metadata—no write operations.
• Send messages only. No read or modify privileges on mailbox.

The token will be saved in the file token.json in the root directory of the project.

Warning

The file credentials.json and token.json are sensitive files, DO NOT share them with anyone.

Connect to the server

Connect to the server by entering the server's IP address and port:

• IP address: The IP address of your server machine.
• Port: 5656.

The Server or Server App should be running before you run the Mail App to accept the connection.

Send mail

You can send an email to the address you logged in to the app. The instruction in the email MUST follow the instruction format.

Kitchen sink example

(shutdown:)(logout)
(sys_info)
(screenshot)
(list_directory:C:\Users\VINH\Desktop)
(list_process:)
(list_application)
(kill_process:1234)
(copy_file_to_server:C:\Users\VINH\Desktop\cli.py;C:\Users\VINH\Desktop\foo\)
(copy_file_to_client:C:\Users\VINH\Desktop\cli.py;C:\Users\VINH\Desktop\bar\)
(delete_file:C:\Users\VINH\Desktop\tmp.txt)
(create_registry_key:HKEY_CURRENT_USER\Software\MyKey)
(set_registry_value:HKEY_CURRENT_USER\Software\MyKey;foo;bar;REG_SZ)
(set_registry_value:HKEY_CURRENT_USER\Software\MyKey;foo;foo\nbar\nbaz;REG_MULTI_SZ)
(get_registry_value:HKEY_CURRENT_USER\Software\MyKey;foo)
(delete_registry_key:HKEY_CURRENT_USER\Software\MyKey)

Instruction format

The instruction in the email MUST follow the format:

Note

Each instruction doesn't have to be on a separate line.

<autoRun>(<type>:<options>)

• autoRun: Whether to run the command automatically after receiving the email. The allowed values are #.

  • If the value is #, the command will be executed automatically.
  • If the value is !, the command will NOT be executed automatically on the Mail server.
  • If the value is empty, the command will be executed when you click the Run button.

  Note: The # character must be exactly before the ( character.

• type: The type of command to execute. The type is case-sensitive. For the list of supported commands, see Supported instructions.

• options: The options of the command. The options are separated by ;. The allowed characters are alphanumeric characters, \, :, ;, and .. Currently, not support multiline options.

  Note: The options is optional and can be omitted.

E.g.:

#(command) # run automatically
# (command) # not a valid instruction
!(command) # not run automatically
! (command) # not a valid instruction

(command) # without options
(command:option1;option2) # with multiple options
(command1:) # with an empty option
(command1:)(command2) # multiple instructions on the same line

Regex pattern

The regex pattern is defined in the file src/shared/mail_processing/utils.py:

cmdPattern = "|".join(DEFAULT_COMMANDS)
pattern = (
    rf"(?P<autoRun>#)?\((?P<type>{cmdPattern})(?:\:(?P<options>[\w\\:;\.]*))?\)"
)

Supported instructions

• shutdown: Shut down the server machine.

  • Instruction:

    (shutdown)
    

  • Example:

    (shutdown)
    

• logout: Log out the current user.

  • Instruction:

    (logout)
    

  • Example:

    (logout)
    

• sys_info: Get information of the server machine (MAC address, CPU, RAM).

  • Instruction:

    (sys_info)
    

  • Example:

    (sys_info)
    

• screenshot: Take a screenshot of the server machine.

  • Instruction:

    (screenshot)
    

  • Example:

    (screenshot)
    

• list_directory: List directories and files in the given path.

  • Instruction:

    (list_directory:<path>)
    

    • path: The path to the list.

  • Example:

    (list_directory:C:\Users\Alice\Desktop)
    

• copy_file_to_server: Copy a file from the client machine to the server machine.

  • Instruction:

    (copy_file_to_server:<srcPath>;<destPath>)
    

    • srcPath: The path to the file on the client machine.

    • destPath: The directory path to the file on the server machine.

      Note: The file name from srcPath will be appended to the destPath.

  • Example:

    (copy_file_to_server:C:\Users\Alice\Desktop\test.txt;C:\Users\Alice\Desktop\)
    

    This will copy the file test.txt from the client machine to the directory C:\Users\Alice\Desktop\ on the server machine. The final path of the file is: C:\Users\Alice\Desktop\test.txt.

Warning

The file size MUST be less than 1MB.

• copy_file_to_client: Copy a file from the server machine to the client machine.

  • Instruction:

    (copy_file_to_client:<srcPath>;<destPath>)
    

    • srcPath: The path to the file on the server machine.

    • destPath: The directory path to the file on the client machine.

      Note: The file name from srcPath will be appended to the destPath.

  • Example:

    (copy_file_to_client:C:\Users\Alice\Desktop\test.txt;C:\Users\Alice\Desktop\)
    

    This will copy the file test.txt from the server machine to the directory C:\Users\Alice\Desktop\ on the client machine. The final path of the file is: C:\Users\Alice\Desktop\test.txt.

Warning

The file size MUST be less than 1MB.

• delete_file: Delete a file on the server machine.

  • Instruction:

    (delete_file:<path>)
    

    • path: The path to the file on the server machine.

  • Example:

    (delete_file:C:\Users\Alice\Desktop\test.txt)
    

• list_process: List all the processes on the server machine.

  • Instruction:

    (list_process)
    

  • Example:

    (list_process)
    

• list_application: List all the applications on the server machine.

  • Instruction:

    (list_application)
    

  • Example:

    (list_application)
    

• kill_process: Kill a process on the server machine.

  • Instruction:

    (kill_process:<pid>)
    

    • pid: The process ID of the process to kill.

  • Example:

    (kill_process:1234)
    

• create_registry_key: Create a registry key on the server machine.

  • Instruction:

    (create_registry_key:<keyPath>)
    

    • keyPath: The key path to create.

  • Example:

    (create_registry_key:HKEY_CURRENT_USER\Software\MyKey)
    

• delete_registry_key: Delete a registry key on the server machine.

  • Instruction:

    (delete_registry_key:<keyPath>)
    

    • keyPath: The key path to delete.

  • Example:

    (delete_registry_key:HKEY_CURRENT_USER\Software\MyKey)
    

• set_registry_value: Set a registry value on the server machine.

  • Instruction:

    (set_registry_value:<keyPath>;<valueName>;<valueData>;<valueType>)
    

    • keyPath: The key path to set the value.

    • valueName: The name of the value to set.

    • valueData: The data of the value to set.

    • valueType: The type of the value to set. The value type is case-sensitive.

      • The supported value types are:

        • REG_SZ.

        • REG_BINARY.

        • REG_DWORD.

        • REG_QWORD.

        • REG_EXPAND_SZ.

          Note: server does support expand variables but the client app and mail app don't.

        • REG_MULTI_SZ. Use \n to separate the values. E.g. foo\nbar.

  • Example:

    (set_registry_value:HKEY_CURRENT_USER\Software\MyKey;MyValue;Hello;REG_SZ)
    

• get_registry_value: Get a registry value on the server machine.

  • Instruction:

    (get_registry_value:<keyPath>;<valueName>)
    

    • keyPath: The key path to get the value.
    • valueName: The name of the value to get.

  • Example:

    (set_registry_value:HKEY_CURRENT_USER\Software\MyKey;MyValue)
    

Fetch mail:

By default, the app will fetch 5 latest emails from the INBOX label of the email account.

• You can change the number of emails to change the Last mails dropdown.

• You can change the label to fetch emails from the Label dropdown. User's labels are not supported.

If you want to refresh the email list, you can click the Refresh button in the Actions tab.

When parsing the email, the app will try to get as much text from the email body as possible. The text will be parsed as instructions.

• When parsing the instruction, the app will remove duplicate instructions.

Execute instructions

You can execute instructions by clicking the Run button on the right side of the parsed instructions from received messages.

The result will be sent back to the email sender. By default, the message will be sent as a reply to the received message. The reply message may have attachments.

To change the email reply type to a separate email, you can uncheck the setting: Settings > Send response as reply.

Note

There is a known issue when executing multiple instructions at the same time, it will cause the SSL error. So please execute one instruction after a short time (about ~2 seconds).

Mail Server

⬆️ Back to top

This is the server that will do everything that the Mail App can do, but it will not have the GUI, and it will automatically execute the email instructions.

Run the mail server:

poe dev server:mail

Authorization

Like the Mail App, the mail server will need to be authorized to be able to access the email account. Please follow the Authorize the app section to authorize the app.

Connect to the server

The mail server will automatically connect to the server when it starts. The host will be localhost and the port will be 5656. So the server and the mail server MUST be run on the same machine.

Fetch mail

By default, the mail server will ONLY fetch the 5 latest emails from the INBOX label. You will have to change the code to change the number of emails to fetch and the label to fetch.

Execute instructions

The mail server will automatically execute the instructions from the received emails.

As the known issue mentioned in the Mail App section, the instruction shouldn't be executed at the same time. So the mail server will delay about 2 seconds before executing the next instructions.

Each executed instruction will be logged to the file tmp/log.txt to prevent it from being executed again by checking the email's sent date.

Dear PyGui Demo

⬆️ Back to top

The demo will demonstrate all the features of the Dear PyGui library. This was for development purposes only.

Run the demo:

poe dev demo

CLI

⬆️ Back to top

Usage: cli.py [OPTIONS]
              [SERVICE]:[server|server:mail|server:legacy|client|mail]

Arguments:
  [SERVICE]:[server|server:mail|server:legacy|client|mail]
                                  Service to run  [default: server]

Options:
  --help  Show this message and exit.

Note

This is an entry point for all the services. Each service should be run from this entry point to make the absolute import work.

🧭 Roadmap

• Rebuild the server with Dear PyGui.
• Rebuild the client app with Dear PyGui.
• Support more features for Mail App.
  • Copy files to the client computer.
  • Copy files to the server computer.
  • Delete files.
• Linux support.

👋 Contributing

Contributions are always welcome!

📜 Code of Conduct

Please read the Code of Conduct.

❔ FAQ

• Why do you migrate to SocketIO?

  • The server and client app are built with normal socket, the dataflow is somewhat harder to track, debug and maintain. So I decided to migrate to SocketIO for better dataflow management.

• Why do you migrate to Dear PyGui?

  • The server and client app is built with tkinter, which is a bit hard to use and maintain. The tkinter's mainloop is quite hard to close manually, and it's not shut down properly when the program is closed. So I decided to migrate to Dear PyGui for better UI and better dataflow management.

• Mail App or Mail Server got an HttpError: 403 Insufficient Permission error when trying to send the email.

  • Make sure the file token.json is in the root directory of the project.

  • Make sure the token.json file is created with these scopes:

    https://www.googleapis.com/auth/gmail.send
    https://www.googleapis.com/auth/gmail.readonly
    

  • Make sure the expiry field in the token.json file is not expired. If it is, you can restart the app to refresh the token.

• Execute multiple instructions at the same time will cause the SSL error.

  • There is a known issue when executing multiple instructions at the same time, it will cause the SSL error. So please execute one instruction after a short time (about ~2 seconds).

• File size must be less than 1MB.

  • The file size must be less than 1MB when copying files from client to server or from server to client. This is the default max_http_buffer_size of the AsyncServer the python-socketio library.

⚠️ License

Distributed under MIT license. See LICENSE for more information.

🤝 Contact

Duong Vinh - @duckymomo20012 - tienvinh.duong4@gmail.com

Project Link: https://github.com/DuckyMomo20012/email-remote-access.

💎 Acknowledgements

Here are useful resources and libraries that we have used in our projects:

• Awesome Readme Template: A detailed template to bootstrap your README file quickly.
• Dear PyGui: Dear PyGui is an easy-to-use, dynamic, GPU-Accelerated, cross-platform graphical user interface toolkit(GUI) for Python. It is “built with” Dear ImGui.
• SocketIO: Python client and server for Socket.IO.
• FastAPI: FastAPI framework, high performance, easy to learn, fast to code, ready for production.
• uvicorn: An ASGI web server, for Python.