Pupy : Multi-Platform Remote Administration Tool [TUTORIAL/HowTo]


Features :

  • On windows, the Pupy payload is compiled as a reflective DLL and the whole python interpreter is loaded from memory. Pupy does not touch the disk

  • Pupy can reflectively migrate into other processes

  • Pupy can remotely import, from memory, pure python packages (.py, .pyc) and compiled python C extensions (.pyd). The imported python modules do not touch the disk. (.pyd mem import currently work on Windows only, .so memory import is not implemented).

  • modules are quite simple to write and pupy is easily extensible.

  • Pupy uses rpyc and a module can directly access python objects on the remote client

  • communication channel currently works as a ssl reverse connection, but a bind payload will be implemented in the future

  • all the non interactive modules can be dispatched on multiple hosts in one command

  • Multi-platform (tested on windows 7, windows xp, kali linux, ubuntu)

  • modules can be executed as background jobs

  • commands and scripts running on remote hosts are interruptible

  • auto-completion and nice colored output

  • commands aliases can be defined in the config

  • we can also access remote objects interactively from the pupy shell and even auto completion of remote attributes works !

Implemented Modules :

  • migrate

  • keylogger

  • persistence

  • screenshot

  • webcam snapshot

  • in memory execution of PE exe both x86 and x64

  • command execution

  • download

  • upload

  • socks5 proxy

  • local port forwarding

  • interactive shell (cmd.exe, /bin/sh, …)

  • interactive python shell

  • shellcode exec (thanks to @byt3bl33d3r)

  • inter process architecture injection also works (x86->x64 and x64->x86)

Quick start

In these examples the server is running on a linux host (tested on kali linux) and it’s IP address is The clients have been tested on (Windows 7, Windows XP, kali linux, ubuntu, Mac OS X 10.10.5)

generate/run a payload

for Windows

./pupygen.py -p 443 -t exe_x86 -o pupyx86.exe

you can also use -t dll_x86 or dll_x64 to generate a reflective DLL and inject/load it by your own means.

for Linux

pip install rpyc #(or manually copy it if you are not admin) python reverse_ssl.py

for MAC OS X

easy_install rpyc #(or manually copy it if you are not admin) python reverse_ssl.py

start the server

  1. eventually edit pupy.conf to change the bind address / port
  2. start the pupy server :



Some screenshots

list connected clients






execute python code on all clients



execute a command on all clients, exception is retrieved in case the command does not exists



use a filter to send a module only on selected clients



migrate into another process



interactive shell



interactive python shell



upload and run another PE exe from memory



list available modules (the list is not up to date)


Example: How to write a MsgBox module

first of all write the function/class you want to import on the remote client in the example we create the file pupy/packages/windows/all/pupwinutils/msgbox.py

import ctypes
import threading

def MessageBox(text, title):     t=threading.Thread(target=ctypes.windll.user32.MessageBoxA, args=(None, text, title, 0))     t.daemon=True     t.start()

then, simply create a module to load our package and call the function remotely

class MsgBoxPopup(PupyModule):     """ Pop up a custom message box """
    def init_argparse(self):         self.arg_parser = PupyArgumentParser(prog=“msgbox”, description=self.__doc__)         self.arg_parser.add_argument('–title', help=‘msgbox title’)         self.arg_parser.add_argument(‘text’, help=‘text to print in the msgbox :)')    

@windows_only     def is_compatible(self):         pass    

def run(self, args):       self.client.load_package(“pupwinutils.msgbox”)         self.client.conn.modules[‘pupwinutils.msgbox’].MessageBox(args.text, args.title)         self.log(“message box popped !")