Last updated on 2020-01-19

Why?

The primary motivation for this initiative was to be able to easily deploy an instance of Burp to a cloud provider in order to examine and potentially script/modify traffic originating from external vulnerability assessment services. These services generally launch vulnerability scans from a public IP and expose some configuration interfaces which aren’t detailed enough to know exactly what’s going on; therefore, having visibility into – and being able to manipulate – the generated traffic is a huge boon.

Soon, additional benefits started to reveal themselves:

• Even if the service doesn’t support proxy configuration, I can set up the Burp cloud instance with its own domain name, make it the direct target of the service, and tell Burp to re-route all requests to the real target. Invisible proxying may not even be required.
• Scalability: quickly and consistently deploy additional instances as needed; furthermore, configuring additional listeners in each instance can be done prior to, or after launch. Each listener can direct traffic to a distinct host.
• Burp logs become available to the myriad of cloud provider tools for log collection, queries, archival, and manipulation.
• Docker volumes allow pre-loading configuration files and certificates, and enable data sharing between the Burp container and auxiliary containers.

Auxiliary containers

I created three auxiliary containers in order to fully achieve the “cloud Burp” goal: one running a Secure Shell (SSH) server, in order to remotely manage those configuration files and certificates; and two others running noVNC and a VNC server. The VNC containers are only necessary when running Burp with its graphical interface. I chose noVNC mainly because it runs on browsers, which means nobody has to deal with standalone VNC clients.

These auxiliary containers brought their own benefits, in addition to fulfilling certain requirements:

• SSH access, set up with public keys at container build time, provides a safe mechanism to upload and download configuration files, extensions, certificates, logs, reports, etc.
• Collaboration: multiple people can easily access the same Burp instance at the same time when using VNC. The VNC server provides password-protected access for view-only or full-control sessions.
• Separation of duties between containers allows a single group of auxiliary containers to support multiple Burp instances. For example, the same noVNC instance can connect to multiple Burp instances through different VNC servers.

Despite having been built for cloud deployment, these containers can run completely isolated on a local machine. The Burp container is all you need when running it in headless mode (without the GUI), or with the GUI if your machine provides an X server.

Downsides

To be fair, there are down-sides as well:

• Certificate management is still painful.
• Burp does not provide proxy authentication, as far as I know. If you don’t lock down access to the proxy listener some other way, you’ll end up with an open proxy on the Internet.
• The same goes for noVNC: unless you lock it down using mechanisms from the cloud provider, anyone will be able to access and use your instance as a VNC client.
• I haven’t yet tried to run this setup with Burp Pro. I’m sure there will be licensing issues to overcome.

With that, let’s examine the components of the Burp container itself. While auxiliary containers will be examined in future articles, the whole setup is already here on GitHub.

dockerfile

# Burp issues compatibility warnings for JRE 12 and newer,

# and JRE 11 seems to work best on Debian Stretch.

FROM openjdk:11-jre-stretch

RUN apt-get update \

 && apt-get upgrade -y

RUN apt-get install --no-install-recommends -y \

    libxext6    \

    libxrender1 \

    libxtst6    \

    wget

RUN apt autoremove -y

…

Not much going on here:

• Use OpenJDK 11 for compatibility reasons. Their Docker image is based on Debian Stretch.
• Update the OS and install packages without additional recommended ones.
• The packages libxext6, libxrender1, and libxtst6 are the minimum necessary to run Burp in GUI mode with a “local” X11 Unix socket.
  • The socket isn’t actually local, but accessible through a Docker volume mount. More info in the Volumes section.
• wget to download the latest version of Burp, if one isn’t provided up front.
• apt autoremove for good measure.

…

RUN groupadd burp && mkdir /home/burp       \

 && useradd -s /bin/bash -g burp burp       \

 && cp /etc/skel/.bashrc /home/burp/.bashrc \

 && echo "cd ~/share" >> /home/burp/.bashrc

…

And a few niceties:

• Change the burp user’s shell to bash;
• Copy a default .bashrc to their home directory; and
• Set ~/share as the working directory upon login.

…

COPY ./entrypoint.sh   /home/burp/

COPY ./user_configs    /home/burp/user_configs

COPY ./project_configs /home/burp/project_configs

COPY ./prefs.xml       /home/burp/.java/.userPrefs/burp/prefs.xml

EXPOSE 8080/tcp

ENTRYPOINT ["/bin/bash", "/home/burp/entrypoint.sh"]

• Copy some files and directories to the image.
  • prefs.xml is set up to bypass the EULA prompt.
• Expose 8080/tcp by default, since that’s Burp’s default listening port.
• Set entrypoint.sh to be executed when the container runs.

entrypoint.sh

#! /bin/bash

_shell=""

_home="/home/burp"

headless="-Djava.awt.headless=true"

default_project_json="${_home}/share/project_configs/headless.json"

default_user_json="${_home}/share/user_configs/headless.json"

url="https://portswigger.net/burp/releases/download?product=community&type=jar"

while [[ -n ${1} ]]

do

    arg_name=${1%%=*}

    arg_value=${1#*=}

    if [[ ${arg_name} == "--gui" ]]

    then

        headless="-Djava.awt.headless=false"

        default_project_json="${_home}/share/project_configs/gui.json"

        default_user_json="${_home}/share/user_configs/gui.json"

        # This is the first display attempted by "x11vnc -create",

        # which is what the "novnc_server" container uses.

        export DISPLAY=:20

    fi

    [[ ${arg_name} == "--url" ]] && url=${arg_value}

    [[ ${arg_name} == "--user" && -n ${arg_value} ]] && user_json=${arg_value}

    [[ ${arg_name} == "--proj" && -n ${arg_value} ]] && project_json=${arg_value}

    [[ ${arg_name} == "--shell" ]] && _shell="& exec /bin/bash -i"

    shift

done

[[ -z ${user_json} ]] && user_json=${default_user_json}

[[ -z ${project_json} ]] && project_json=${default_project_json}

…

One item of note is _shell="& exec /bin/bash -i". This sets up the --shell argument. When present, it will cause the container to execute Burp as a background process and, by means of exec, replace the current process with /bin/bash, dropping the container into an interactive shell.

In other words:

• With --shell, the container runs /bin/bash as its primary application, and Burp in the background. When Burp exits, the container continues to run. When the primary shell exits, the container stops.
• Without --shell, the container runs Burp as its primary application. There’s no shell. When Burp exits, the container stops.

…

mkdir -p ${_home}/share/user_configs

mkdir -p ${_home}/share/project_configs

cp -n ${_home}/user_configs/*    ${_home}/share/user_configs/

cp -n ${_home}/project_configs/* ${_home}/share/project_configs/

…

The share directory has no significance until mounted in a Docker volume. See the Volumes section.

…

jar_file="${_home}/share/burpsuite.jar"

[[ -f ${jar_file} ]] || wget ${url} -O ${jar_file}

chown -R burp:burp ${_home}

java_cmd="java ${headless} -jar ${jar_file} --user-config-file=${user_json} --config-file=${project_json}"

exec chroot --userspec=burp:burp / env HOME=${_home} /bin/bash -c "${java_cmd} ${_shell}"

Let’s unpack that last line, which causes the container to…

Run as a normal user

Here’s what that looks like without the --shell argument:

exec
 |__chroot
     |__env (now running as 'burp:burp')
         |__bash
             |__java (becomes parent process)

And with the --shell argument:

exec
 |__chroot
     |__env (now running as 'burp:burp')
         |__bash
             |__java (in background)
             |__exec
                 |__bash (becomes parent process)

Volumes

Docker volumes allow file sharing between the host and the container as well as among containers, so long as the volume is mounted in all applicable containers.

With a simple setup, we can:

• Load Burp configuration and JAR files before and after running the container.
• Download Burp logs, project files, modified options, etc.
• Run Burp’s GUI on a different X11 Unix socket, such as the host’s or another container’s.

For file sharing

• Create the volume:
  sudo docker volume create burp_share
• When issuing docker run, include the following argument:
  --mount src=burp_share,dst=/home/burp/share,ro=false
  (this is why we create ~/share here)

When running the container locally, you can access the volume’s mountpoint directly:

$ sudo docker volume inspect -f {{.Mountpoint}} burp_share
/var/lib/docker/volumes/burp_share/_data

$ sudo tree /var/lib/docker/volumes/burp_share/_data
/var/lib/docker/volumes/burp_share/_data
├── burpsuite.jar
├── project_configs
│   ├── default.json
│   ├── gui.json
│   └── headless.json
└── user_configs
    ├── default.json
    ├── gui.json
    └── headless.json

2 directories, 7 files

When running the container remotely, you’ll also need to mount the volume onto the SSH container. Then, via SSH, you can access files on the Burp container!

For GUI display

• Create the volume:
  sudo docker volume create x11_socket
• When issuing docker run…
  • if running the container locally, include the following argument:
    ‐-mount type=bind,src=/tmp/.X11-unix/X0,dst=/tmp/.X11-unix/X20,ro=true
    (To facilitate a remote setup, X20 is the destination socket. No need to change it for a local setup.)
  • if running the container remotely, include this instead:
    --mount src=x11_socket,dst=/tmp/.X11-unix,ro=true

When running the container remotely, you’ll need another container, like the VNC ones, to provide the display. The Burp container alone has no graphical interface. The volume must be mounted on both containers.

Building and running

$ sudo docker volume create burp_share
$ sudo docker volume create x11_socket
$ sudo docker build -t burp:latest .

Note the trailing ., which just represents the current directory.
-t burp:latest tags the build so we can reference it when issuing docker run. See below.

Headless

GUI

That’s that! Once again, definitions for all containers as well as interactive build and run scripts are present at github.com/elespike/burp_containers.