Operating a REVEN installation

This page lists common and advanced procedures for operating a REVEN installation.

Common operations

Stopping REVEN

  • For the Docker package, simply run the ./run.sh script at the root of the Docker package.

  • For the native package, simply run ./stop.sh at the root of the installation directory, with the same user that previously executed start.sh.

Upgrading REVEN

When upgrading to a new version of the package, please refer to the What's new section, and in particular the Upgrading page.

Adding symbol servers

To benefit from symbols when analyzing a trace, you can define a list of PDB servers in the Project Manager's configuration file (located in $CONFIG_PATH/quasar.py which defaults to /.config/tetrane/quasar.py).

NOTE: A default list of servers is already present in the settings file that comes with your installation. You only need to perform this step if you require additional or different servers.

  1. Open the Project Manager's configuration file.
  2. Add a new list variable QUASAR_SYMBOL_SERVERS.
  3. Populate the variable with PDB server addresses, here is a sample configuration:
# Symbol server list
QUASAR_SYMBOL_SERVERS = [
    "https://msdl.microsoft.com/download/symbols",
    "https://chromium-browser-symsrv.commondatastorage.googleapis.com/",
    "https://symbols.mozilla.org/",
    # "https://download.amd.com/dir/bin",
    # "https://driver-symbols.nvidia.com/",
    # "https://software.intel.com/sites/downloads/symbols/",
]

For more information, please refer to the page on Getting OSSI for Windows.

Moving a REVEN installation directory

Due to the presence of Python virtualenvs that don't support being moved, among other reasons, it is not recommended to change the location where a native REVEN package has been extracted after the installation.

If you need to change the location of your REVEN installation, the recommended procedure is to run ./stop.sh from the previous location, and then to install the package again at the desired location. Upon running ./start.sh from the new location, you will be prompted to import the database from your previous installation.

Advanced

Running multiple REVEN instances on the same machine

You can run multiple instances of Project Manager on the same machine, as long as you set the multiple web interfaces to listen on different ports. You have two solutions to do that:

  • Give the port number to start.sh as its first argument: ./start.sh 4000 will make the web interface accessible on port 4000.
  • Set the port number permanently in one of your setting files, with the variable QUASAR_UWSGI_PORT, depending on your deployment configuration.

Running REVEN behind a reverse-proxy

It's no problem running a REVEN instance behind a reverse-proxy, as long as you follow those recommendations:

  • When using the Docker package:
    1. (optional) Change the port on which the web interface listen (e.g. 8888 for both UWSGI and Jupyter)
    2. Ensure the QUASAR_USE_VNC value is set to True (default value)
    3. Set the QUASAR_WEBSOCKIFY_PUBLIC_PORT to the proxied value (e.g. 80)
    4. Set the QUASAR_JUPYTER_PUBLIC_PORT to the proxied value (e.g. 80)
  • When using the native package:
    1. (optional) Change the QUASAR_UWSGI_PORT to a custom value (e.g. 8888)
    2. Ensure the QUASAR_USE_VNC value is True (default value)
    3. Set the QUASAR_WEBSOCKIFY_PORT to a fixed value (e.g. 6080)
    4. Set the QUASAR_WEBSOCKIFY_PUBLIC_PORT to the proxied value (e.g. 80)
    5. Set the QUASAR_JUPYTER_PORT to a fixed value (e.g. 8888)
    6. Set the QUASAR_JUPYTER_PUBLIC_PORT to the proxied value (e.g. 80)

Here is an example of a working nginx configuration using the above example values:

server {
    listen 80;

    client_max_body_size 10G; # You won't be able to upload files bigger than this value.

    location / {
        proxy_pass http://127.0.0.1:8888/;
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;
        proxy_set_header Authorization ""; # Ensure we clear the Authorization header for DRF.
    }

    location /websockify {
        proxy_pass http://127.0.0.1:6080/websockify;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
        proxy_read_timeout 1800s; # Default is 60s, which is really low in this use-case.
    }

    location /jupyter/ {
        proxy_pass http://127.0.0.1:8888/jupyter/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
    }
}

Troubleshooting

If you have any trouble somewhere, don't hesitate to take a look at the logs located in ~/Reven2/<version>/Logs and see the Support page for any help.

©2019-2021 Tetrane