REVEN Docker installation instructions

The Docker package allows you to install and run REVEN on any Linux distribution, while the system prerequisite to install the default REVEN package is Debian 10 "Buster" release.

Configuration

Before starting the Docker package, you can optionally change some of its configuration.

Changing the default paths for VMs and other resources

In the run.sh script contained in the Docker package, you can modify the following variables to change the paths to various resources if you need them to point to specific locations:

• VM_PATH=~/VMs: the directory where the registered QEMU Virtual Machines (VMs) are stored. It is advised to set this path to a big enough storage location.
• REVEN2_PATH=~/Reven2: the directory where most of REVEN data is stored:
  • The record and replay data of scenarios.
  • The extracted filesystem.
  • The exported scenario archives. Due to this directory containing the replay data of scenarios, it is advised to set its path to a fast and plentiful storage location.
• CONFIG_PATH=~/.config/tetrane: the directory where the user-wide settings are stored. These are typically small and not performance sensitive.
• SYMBOL_PATH=~/.local/share/reven/symbols: the directory where the debug symbol files recovered from symbol servers are stored. It is advised to set this path to a big enough storage location.

The default locations should be fine in a typical setup.

Starting the server

Launch the run.sh script at the root of the Docker package and then follow the instructions from the script.

Once the container started, you can reach the REVEN Project Manager by opening its URL (defaults to http://<your_reven_host>:8880), and you can then finalize the installation by installing your REVEN license.

Advanced Docker Installation

Changing the port on which the web interface listens

Changing the ports on which the web interface listens is generally not required, as the default ports will work if available. However, should the default ports already be in used by some other applications, this section will guide you through the process of changing the port numbers.

Because the docker runs with its own internal network interface, you must consider two sets of addresses and port:

• The internal address and ports of the docker, that you'll never need to change. It is what is displayed by ./run.sh when starting the conatiner, e.g. http://172.17.0.2:8880.
• The address and ports of the docker bound to the host, that use the host's network and is potentially accessible from other machines, e.g. http://127.0.0.1:8880. This is the set of ports we are interested in changing.

1. In the run.sh script contained in the Docker package, find the if ! $SUDO $DOCKER run command that spans multiple lines, then look for the lines -p 8880:8880 that binds UWSGI's port (Project Manager) to the host, -p 8881:8881 that binds Jupyter's port (Python notebooks) to the host, and -p 6080:6080 that binds websockify's port to the host.

For each of these lines, change the first value to the port you want to connect to.

For example, to have the Project Manager listen on port 2000, change the first line to read: -p 2000:8880. To have the Jupyter interface listen on port 2001, change the second line to read: -p 2001:8881. To have the websockify bound to port 2002, change the third line to read: -p 2002:6080.

2. If you changed Jupyter's port, you also need to define the QUASAR_JUPYTER_PUBLIC_PORT variable in ~/.config/tetrane/quasar.py to the same value, e.g. QUASAR_JUPYTER_PUBLIC_PORT=2001.
3. If you changed websockify's port, you also need to define the QUASAR_WEBSOCKIFY_PUBLIC_PORT variable in ~/.config/tetrane/quasar.py to the same value, e.g. QUASAR_WEBSOCKIFY_PUBLIC_PORT=2002.
4. Note that even if you changed UWSGI's port (Project Manager), you do not need to change any variable in the user-wide configuration.

NOTE: Even when changing the port on which the web interface listens, the address and port displayed when running ./run.sh will remain the internal address and port of the docker, e.g. http://172.17.0.2:8880. For connecting to the web interface after changing the ports, you need to use the address and port of the docker that are bound to the host, e.g. http://127.0.0.1:2000.

Docker vs Podman

Docker is a well-known container technology. Podman is a more recent one, less spread, that aims at fixing some of Docker's caveats like its daemon that runs as root.

Our REVEN image is built with Docker, but has been tested already with Podman, and both have been observed to work, but it strongly depends on the distribution you are using, the Linux kernel version, each technology's version, and the overall environment, like kernel boot command line, configuration in /etc/subuid and /etc/subgid, your user ID, or the filesystem you are using (ext4, btrfs...)

In a nutshell, if you have an already working Docker daemon, this one should work fine. If you don't and/or want to use Podman with a rootless container, it has been known to work fine on Fedora 31 and CentOS 8.1.1911, but had problems on OpenSUSE Tumbleweed snapshot 20200326, and an up-to-date Manjaro as of 2020-04-07. Just update the DOCKER variable in the run.sh script to make the switch to podman.

About Axion using your host's X server instead of VNC

It is possible to have the container use your host's X server to spawn Axion. But as this heavily depends on the host's configuration, it cannot be enabled by default. To do that, the steps are basically the following:

1. Run the container: ./run.sh
2. Get your container's name: docker ps | grep tetrane
3. Disable the use of VNC in the settings of the container: docker exec <container-name> sed -i '/QUASAR_USE_VNC/cQUASAR_USE_VNC = False' /reven/settings.py
4. Commit your running container to a new image: docker commit <container-name> tetrane/reven2:2.4.0-withX
5. Stop your running container: ./run.sh
6. Edit the run.sh script:
   1. Update the REVEN_VERSION variable to match your new image's name: e.g. REVEN_VERSION="2.4.0-withX"
   2. Find the part of the script that runs the container to give it your host's X server. This boils down to adding the following options to to the $DOCKER run command:
      • -v /tmp/.X11-unix:/tmp/.X11-unix
      • -e DISPLAY="$DISPLAY"
7. Run the container again: ./run.sh. Axion should now open as a native X window in your desktop environment. If it does not and instead logs an error like "could not connect to display", you may have to play with X permissions, running something like xhost +, but which would allow only what's good for your setup.

About VirtualBox

VirtualBox is currently not supported by the REVEN container installation. Please perform a regular REVEN installation to use this feature.

Personalizing the REVEN image efficiently

Some networks, or company policies, may require you to customize the REVEN Docker image. A common use-case is adding a CA root certificate to access local services, such as a PDB server. In order to industrialize these customizations upon each upgrade of REVEN, an elegant solution is to leverage the docker build command, with a Dockerfile, to add your own layer of customization on top of the REVEN image. The full documentation of this is here: https://docs.docker.com/engine/reference/builder/

Here is a concrete example of a procedure to add a custom certificate so that REVEN can connect to an internal PDB server. You can adapt it to your own customization needs:

1. Go to your REVEN Docker package folder: cd path/to/reven/package
2. Start your REVEN container at least once with the stock image: ./run.sh This ensures that the stock image will be loaded into your Docker installation. You can verify this by running docker images:

   $ docker images
   REPOSITORY                                            TAG                            IMAGE ID       CREATED         SIZE
   tetrane/reven2                                        2.7.1-enterprise               954572ebb0a1   2 months ago    3.4GB
   

3. Stop the running container: ./run.sh
4. Create a working directory and get into it: mkdir ~/reven_docker && cd ~/reven_docker
5. Copy your custom certificate to this directory: cp path/to/cert.crt .
6. Create a new Dockerfile file with the following content:

   FROM tetrane/reven2:2.8.0-enterprise
   
   ADD cert.crt /tmp/cert.crt
   RUN cat /tmp/cert.crt >> /reven/share/reven/quasar/venv/lib/python3.7/site-packages/certifi/cacert.pem
   

7. Build your new image: docker build -t tetrane/reven2:2.8.0-enterprise-with-ca .
8. Go to your REVEN Docker package folder: cd path/to/reven/package
9. Change the REVEN_VERSION variable in the run.sh script with the new image version you just built: 2.8.0-enterprise-with-ca
10. Enjoy your new container with the patched REVEN image: ./run.sh

In the future, to upgrade the patched REVEN image with e.g. REVEN 2.9.0, simply repeat the above steps with the new REVEN package and image name.