From 77f4e29696e19405f0e394b25983b282f8821d4d Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Wed, 13 Dec 2023 21:56:17 -0500 Subject: [PATCH 1/4] Aligned CI dependencies with docs and Docker --- .github/workflows/ci.yml | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index deb8b3620..0c4ffda0a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -54,13 +54,12 @@ jobs: - name: Update apt run: sudo apt update -y - - name: Install setuptools - run: sudo apt install python3-setuptools - name: Install PyRDP dependencies - run: sudo apt install libgl1-mesa-glx libegl1 git python3-dev - - name: Install wheel - working-directory: . - run: pip install wheel + run: | + sudo apt-get update && sudo apt-get install -y --no-install-recommends \ + build-essential python3-dev \ + libegl1 libxcb-cursor0 libxkbcommon-x11-0 libxcb-icccm4 libxcb-keysyms1 \ + libavcodec58 libavdevice58 - name: Install PyRDP working-directory: . run: pip install -U -e .[full] @@ -121,9 +120,6 @@ jobs: run: python --version - name: Pip version run: pip --version - - name: Install wheel - working-directory: . - run: pip install wheel - name: Install PyRDP working-directory: . run: pip install -U -e .[full] From 5330ecfcef318f29140d07632b44df85a7ab3ec9 Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Wed, 13 Dec 2023 22:00:52 -0500 Subject: [PATCH 2/4] doc: pipx install, moved stuff to development guide --- README.md | 148 +++++++++++++----------------------------------- docs/devel.adoc | 125 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 163 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index 9022202ce..62ce4a5ab 100644 --- a/README.md +++ b/README.md @@ -62,34 +62,19 @@ research use cases in mind. ## Supported Systems PyRDP should work on Python 3.7 and up on the x86-64, ARM and ARM64 platforms. -This tool has been tested to work on Python 3.7 on Linux (Ubuntu 20.04, 22.04), Raspberry Pi and Windows -(see section [Installing on Windows](#installing-on-windows)). It has not been tested on macOS. +This tool has been tested to work on Python 3.7 on Linux (Ubuntu 20.04, 22.04), Raspberry Pi and Windows. It has not been tested on macOS. -## Installing - -### Using the Docker Image - -This is the easiest installation method if you have docker installed and working. - -``` -docker pull gosecure/pyrdp:latest -``` -As an alternative we have a slimmer image without the GUI and ffmpeg dependencies. -This is the only provided image on ARM platforms. +## Installing -``` -docker pull gosecure/pyrdp:latest-slim -``` +Two installation techniques are recommended via `pipx` or using docker containers. +Installing from source or building docker containers yourself is covered in the [development documentation](docs/devel.adoc). -You can find the list of all our Docker images [on the gosecure/pyrdp DockerHub page](https://hub.docker.com/r/gosecure/pyrdp/tags). -The `latest` tag refers to the latest released version while the `devel` tag is the docker image built out of our `main` branch. +### Using pipx -### From Git Source +#### Dependencies -We recommend installing PyRDP in a -[virtualenv environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) -to avoid dependency issues. +##### Linux First, make sure to install the prerequisite packages (these are listed for Ubuntu 22.04, you might need to adjust for other distros). We provide two types of installs a full one and a slim one. Install the dependencies according to your use case. @@ -97,138 +82,81 @@ slim one. Install the dependencies according to your use case. ``` # Full install (GUI, convert captures to video) sudo apt install python3 python3-pip python3-venv \ - build-essential python3-dev git openssl \ - libgl1-mesa-glx \ + build-essential python3-dev openssl \ + libegl1 libxcb-cursor0 libxkbcommon-x11-0 libxcb-icccm4 libxcb-keysyms1 \ libnotify-bin \ - libxkbcommon-x11-0 libxcb-xinerama0 \ - libxcb-icccm4 libxcb-image0 libxcb-util1 libxcb-keysyms1 \ - libxcb-randr0 libxcb-render-util0 \ - libavformat-dev libavcodec-dev libavdevice-dev \ - libavutil-dev libswscale-dev libswresample-dev libavfilter-dev + libavcodec58 libavdevice58 # Slim install (no GUI, no conversion to video possible) sudo apt install python3 python3-pip python3-venv \ build-essential python3-dev git openssl ``` -Grab PyRDP's source code: - -``` -git clone https://github.com/gosecure/pyrdp.git -``` - -Then, create your virtual environment in the `venv` directory inside PyRDP's directory: - -``` -cd pyrdp -python3 -m venv venv -``` - -*DO NOT* use the root PyRDP directory for the virtual environment folder (`python3 -m venv .`). You will make a mess, -and using a directory name like `venv` is more standard anyway. - -Before installing the dependencies, you need to activate your virtual environment: - -``` -source venv/bin/activate -``` - -Finally, you can install the project with Pip: - -``` -pip3 install -U pip setuptools wheel - -# Without GUI and video conversion dependencies -pip3 install -U -e . - -# With GUI and video conversion dependencies -pip3 install -U -e '.[full]' -``` - This should install the dependencies required to run PyRDP. If you choose to install without the GUI or video conversion dependencies, it will not be possible to use `pyrdp-player` without headless mode (`--headless`) or `pyrdp-convert` to produce video output. -If you ever want to leave your virtual environment, you can simply deactivate it: +Make sure you have `pipx` installed. On Ubuntu 22.04: ``` -deactivate +python3 -m pip install --user pipx +python3 -m pipx ensurepath ``` -Note that you will have to activate your environment every time you want to have the PyRDP scripts available as shell -commands. - -### Installing on Windows - -The steps are almost the same. There are two additional prerequisites. - -1. A working Python environment ([python.org installer recommended](https://www.python.org/downloads/windows/)) -2. [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) -3. [OpenSSL](https://wiki.openssl.org/index.php/Binaries). Make sure it is reachable from your `$PATH`. +##### Windows -Then, create your virtual environment in PyRDP's directory: +Make sure you have Python installed. +Windows Store Python didn't work for me on Windows 11. +We recommend installing Python via [Scoop](https://scoop.sh/). ``` -cd pyrdp -python -m venv venv +scoop install python # if not installed already +scoop install pipx +pipx ensurepath ``` -*DO NOT* use the root PyRDP directory for the virtual environment folder (`python3 -m venv .`). You will make a mess, -and using a directory name like `venv` is more standard anyway. +Log out and log back in (to update your PATH). -Before installing the dependencies, you need to activate your virtual environment: +##### Other OS -``` -venv\Scripts\activate -``` +To install `pipx` on other operating systems see here: https://github.com/pypa/pipx#install-pipx -Finally, you can install the project with Pip: -``` -python -m pip install -U pip setuptools wheel -pip install -U -e ".[full]" -``` +#### Install -This should install all the dependencies required to run PyRDP. -For example, to open the player: +For the full PyRDP experience with the QT GUI and the ability to convert captures to video: ``` -python venv\Scripts\pyrdp-player +pipx install pyrdp-mitm[full] ``` -If you ever want to leave your virtual environment, you can simply deactivate it: +For the compact version meant to be run in headless environments (servers, RaspberryPi): ``` -deactivate +pipx install pyrdp-mitm ``` -Note that you will have to activate your environment every time you want to have the PyRDP scripts available as shell -commands. - -### Building the Docker Image +You are ready to go! See the [usage instructions](#using-pyrdp). -First of all, build the image by executing this command at the root of PyRDP (where Dockerfile is located): -``` -docker build -t pyrdp . -``` +### Using the Docker Image -As an alternative we have a slimmer image without the GUI and ffmpeg dependencies: +This is the easiest installation method if you have docker installed and working. ``` -docker build -f Dockerfile.slim -t pyrdp . +docker pull gosecure/pyrdp:latest ``` -Afterwards, you can execute PyRDP by invoking the `pyrdp` docker container. See [Usage instructions](#using-pyrdp) and the [Docker specific instructions](#docker-specific-usage-instructions) for details. - -Cross-platform builds can be achieved using `buildx`: +As an alternative we have a slimmer image without the GUI and ffmpeg dependencies. +This is the only provided image on ARM platforms. ``` -docker buildx create --name mybuilder --use --platform linux/amd64,linux/arm64 -docker buildx inspect --bootstrap -docker buildx build --platform linux/arm,linux/amd64 -t pyrdp -f Dockerfile.slim . +docker pull gosecure/pyrdp:latest-slim ``` +You can find the list of all our Docker images [on the gosecure/pyrdp DockerHub page](https://hub.docker.com/r/gosecure/pyrdp/tags). +The `latest` tag refers to the latest released version while the `devel` tag is the docker image built out of our `main` branch. + ## Using PyRDP diff --git a/docs/devel.adoc b/docs/devel.adoc index d213637e1..4492f344f 100644 --- a/docs/devel.adoc +++ b/docs/devel.adoc @@ -1,5 +1,130 @@ = Development guide +== Install from git source on Linux + +We recommend installing PyRDP in a https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/[virtualenv environment] to avoid dependency issues. + +First, make sure to install the prerequisite packages (these are listed for Ubuntu 22.04, you might need to adjust for other distros). We provide two types of installs a full one and a +slim one. Install the dependencies according to your use case. + +``` +# Full install (GUI, convert captures to video) +sudo apt install python3 python3-pip python3-venv \ + build-essential python3-dev git openssl \ + libgl1-mesa-glx \ + libnotify-bin \ + libxkbcommon-x11-0 libxcb-xinerama0 \ + libxcb-icccm4 libxcb-image0 libxcb-util1 libxcb-keysyms1 \ + libxcb-randr0 libxcb-render-util0 \ + libavformat-dev libavcodec-dev libavdevice-dev \ + libavutil-dev libswscale-dev libswresample-dev libavfilter-dev + +# Slim install (no GUI, no conversion to video possible) +sudo apt install python3 python3-pip python3-venv \ + build-essential python3-dev git openssl +``` + +Grab PyRDP's source code: + +``` +git clone https://github.com/gosecure/pyrdp.git +``` + +Then, create your virtual environment in the `venv` directory inside PyRDP's directory: + +``` +cd pyrdp +python3 -m venv venv +``` + +*DO NOT* use the root PyRDP directory for the virtual environment folder (`python3 -m venv .`). You will make a mess, +and using a directory name like `venv` is more standard anyway. + +Before installing the dependencies, you need to activate your virtual environment: + +``` +source venv/bin/activate +``` + +Finally, you can install the project with Pip: + +``` +pip3 install -U pip setuptools wheel + +# Without GUI and video conversion dependencies +pip3 install -U -e . + +# With GUI and video conversion dependencies +pip3 install -U -e '.[full]' +``` + +This should install the dependencies required to run PyRDP. If you choose to +install without the GUI or video conversion dependencies, it will not be possible to use +`pyrdp-player` without headless mode (`--headless`) or `pyrdp-convert` to produce video output. + + +== Install from git source on Windows + +The steps are almost the same. There are two additional prerequisites. + +1. A working Python environment https://www.python.org/downloads/windows/[python.org installer recommended] +2. https://visualstudio.microsoft.com/visual-cpp-build-tools/[Microsoft C++ Build Tools] +3. https://wiki.openssl.org/index.php/Binaries[OpenSSL]. Make sure it is reachable from your `$PATH`. + +Then, create your virtual environment in PyRDP's directory: + +``` +cd pyrdp +python -m venv venv +``` + +*DO NOT* use the root PyRDP directory for the virtual environment folder (`python3 -m venv .`). You will make a mess, +and using a directory name like `venv` is more standard anyway. + +Before installing the dependencies, you need to activate your virtual environment: + +``` +venv\Scripts\activate +``` + +Finally, you can install the project with Pip: + +``` +python -m pip install -U pip setuptools wheel +pip install -U -e ".[full]" +``` + +This should install all the dependencies required to run PyRDP. +For example, to open the player: + +``` +python venv\Scripts\pyrdp-player +``` + + +== Building the Docker Image + +First of all, build the image by executing this command at the root of PyRDP (where Dockerfile is located): + +``` +docker build -t pyrdp . +``` + +As an alternative we have a slimmer image without the GUI and ffmpeg dependencies: + +``` +docker build -f Dockerfile.slim -t pyrdp . +``` + +Cross-platform builds can be achieved using `buildx`: + +``` +docker buildx create --name mybuilder --use --platform linux/amd64,linux/arm64 +docker buildx inspect --bootstrap +docker buildx build --platform linux/arm,linux/amd64 -t pyrdp -f Dockerfile.slim . +``` + + == Making a release NOTE: This is a work in progress From f8be085714f26b37e67270b01d38a8db469c8914 Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Wed, 13 Dec 2023 22:02:12 -0500 Subject: [PATCH 3/4] Fixed docker-compose.yml example Now using new script names (w/o .py) --- docker-compose.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index eeb2a6bfb..876287b4a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -27,6 +27,6 @@ services: # The path before the ':' is the destination of the log on the host side. - ./pyrdp_log:/home/pyrdp/log # Place the command you want to execute here: - # ex: pyrdp-player.py - # ex: pyrdp-mitm.py - command: ["pyrdp-mitm.py", "-h"] + # ex: pyrdp-player + # ex: pyrdp-mitm + command: ["pyrdp-mitm", "-h"] From 55f27f6183d9f71367b92aa27904076fda4e31cd Mon Sep 17 00:00:00 2001 From: Olivier Bilodeau Date: Wed, 13 Dec 2023 22:15:45 -0500 Subject: [PATCH 4/4] doc: updated TOC in README, added one to dev guide --- README.md | 18 ++++++++---------- docs/devel.adoc | 7 +++++++ 2 files changed, 15 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 62ce4a5ab..546ca68b2 100644 --- a/README.md +++ b/README.md @@ -40,23 +40,21 @@ research use cases in mind. ## Table of Contents -- [Supported Systems](#supported-systems) -- [Installing](#installing) +* [Supported Systems](#supported-systems) +* [Installing](#installing) + * [Using pipx](#using-pipx) * [Using the Docker Image](#using-the-docker-image) - * [From Git Source](#from-git-source) - * [Installing on Windows](#installing-on-windows) - * [Building the Docker Image](#building-the-docker-image) -- [Using PyRDP](#using-pyrdp) - * [Using the PyRDP Monster-in-the-Middle](#using-the-pyrdp-monster-in-the-middle) +* [Using PyRDP](#using-pyrdp) + * [Using the PyRDP Monster\-in\-the\-Middle](#using-the-pyrdp-monster-in-the-middle) * [Using the PyRDP Player](#using-the-pyrdp-player) * [Using the PyRDP Certificate Cloner](#using-the-pyrdp-certificate-cloner) * [Using PyRDP Convert](#using-pyrdp-convert) * [Configuring PyRDP](#configuring-pyrdp) * [Advanced Usage](#advanced-usage) * [Docker Specific Usage Instructions](#docker-specific-usage-instructions) -- [PyRDP Lore](#pyrdp-lore) -- [Contributing to PyRDP](#contributing-to-pyrdp) -- [Acknowledgements](#acknowledgements) +* [PyRDP Lore](#pyrdp-lore) +* [Contributing to PyRDP](#contributing-to-pyrdp) +* [Acknowledgements](#acknowledgements) ## Supported Systems diff --git a/docs/devel.adoc b/docs/devel.adoc index 4492f344f..18a9232cd 100644 --- a/docs/devel.adoc +++ b/docs/devel.adoc @@ -1,5 +1,12 @@ = Development guide +:toc: +:toc-placement!: + +This is a guide with quick recipes meant for PyRDP developers. + +toc::[] + == Install from git source on Linux We recommend installing PyRDP in a https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/[virtualenv environment] to avoid dependency issues.