Installation

Installation

1. Debian/Ubuntu
2. Docker Compose

High level overview

Three major components are required to use Pupy:

1. Management software (server side)
   • pupysh
2. Agent software (client side)
   • pupy/payload_templates/*pupy*.*
3. Python libraries for various OS/CPU combinations
   • pupy/payload_templates/*OS*-*CPU*.zip

(1) The server is written in python, so only the python extensions and C libraries/headers required to build them should be installed.

The agent (2) and OS/CPU Python libraries (3) should be built using a special environment to be able to work with many ABI combinations. The environment requires docker.

Debian/Ubuntu

Docker

If you don't want to compile the payloads and use pre-build packages, you can skip this part and go directly there.

----- BEGIN IMPORTANT -----

To make client as much compatible as possible it builds with very old toolchain. This toolchain requires vsyscall support.

You can read what is this here.

In case you are using recent kernel you need to pass vsyscall=emulate to your kernel command line:

• https://wiki.archlinux.org/index.php/kernel_parameters
• https://help.ubuntu.com/community/BootOptions
• https://einsteinathome.org/content/vsyscall-now-disabled-latest-linux-distros

----- END IMPORTANT -----

The original instructions that these are based on can be found here.

The following commands should be executed as the root user:

apt-get update && apt-get install curl -y
curl -fsSL https://get.docker.com > docker_installer.sh
chmod +x ./docker_installer.sh && ./docker_installer.sh

Before executing the file, please verify that the content has not been tampered with in transit, as there is no automatic integrity checking.

For the following command, the actual username should be substituted for <username>.

usermod -aG docker <username>

Pupysh system-wide dependencies

The following commands should be executed as the root user:

apt-get install git libssl1.0-dev libffi-dev python-dev \
	python-pip tcpdump python-virtualenv

Pupy setup

The following commands should be executed as a non-root user:

git clone --recursive https://github.com/n1nj4sec/pupy
cd pupy

The script pupy/create-workspace.py will create a Python virutalenv in the selected folder (pupyws in our example). The script also will create symlinks to pupysh at ~/.local/bin.

• If you want a light installation without the build toolchain run: python create-workspace.py -DG pupyw
• Otherwise run ./create-workspace.py pupyws

After successful deployment Pupy can be used in the following ways:

1. export PATH=$PATH:~/.local/bin; pupysh
2. pupyws/bin/pupysh

Docker Compose

It should be possible to run Pupy on any Docker-supported platform.

Docker is a software platform that allows you to build, test, and deploy applications quickly. Docker packages software into standardized units called containers that have everything the software needs to run including libraries, system tools, code, and runtime. Using Docker, you can quickly deploy and scale applications into any environment and know your code will run.

Docker Supported Platforms:

• Windows 10
• Mac
• CentOS
• Debian
• Fedora
• Ubuntu

We only maintain installation instructions for Debian 9 and Kali Linux hosts. Please adapt these instructions for all other platforms.

For the most current information, please reference Docker's official supported platforms.

Installation:

1. Clone the repository.
   • Until compose support is merged upstream, please clone this repository.
2. Install all dependencies and configure environment.
   • ./install.sh
     • Note: For unsupported operating systems, please adapt the install script to download and install dependencies for your platform.
3. Start pupy.
   • Run ./start-compose.sh from the pupy subdirectory.
     • Note: If you receive this error, you need to log out and back in. This will only happen right after installation.

Compose usage:

Temporarily exiting the Docker container shell

To detach from the current container:

• Hit Ctrl+pq

To attach to the container again:

• Type docker attach pupy

Shutting down Pupy

If you would like to safely shut down the Pupy server and Docker container, please do the following:

1. Type exit in Pupy shell.

Alternatively:

1. Hit ctrl+pq to escape the docker container shell.
2. Type docker stop pupy to shutdown the container.

Starting Pupy

1. ./pupy_start_compose.sh

Additional notes:

These instructions are only a brief overview of some of the possible docker commands and configurations. If you are not familiar with the platform, it is highly recommended to review the documentation.