Deploying a Private Burp Collaborator Server

By default, Burp uses the public Collaborator Server provided by PortSwigger, and this option may be suitable for many purposes. See the main Burp Collaborator documentation for more details.

If you wish, you can deploy your own private instance of the Collaborator Server. This documentation describes the process of doing so, and covers the following topics:

• Installation and execution
• Basic set-up on a closed network
• Running on non-standard ports
• DNS configuration
• SSL configuration
• Interaction events and polling
• Metrics
• Logging
• Testing the installation
• Configuration file format

Installation And Execution

The Burp Collaborator server is included in the same executable file as Burp Suite Professional itself. No license key is required to run your own instance of the server. The server can be started directly from the command line using the --collaborator-server argument, for example:

sudo java -jar burp.jar --collaborator-server

The server will fail to start if it cannot bind to the ports it needs to run its services. You will need to stop any other processes that are using these ports. By default, Burp Collaborator server listens on the following ports:

• DNS: UDP port 53
• HTTP: TCP port 80
• HTTP: TCP port 443
• SMTP: TCP ports 25 and 587
• SMTPS: TCP port 465

Further, on Unix-based systems, you may need to run the server with root privileges in order to bind to these ports. Alternatively, you can configure the server to run on non-standard ports, and use port mapping to redirect the original ports.

When launching the Collaborator server, it is desirable to configure the JVM's memory handling and garbage collection, based on the expected usage. If you are running the Collaborator server on a desktop machine for a small number of expected users, you can reduce the amount of memory used by the JVM. The following command allows the heap to fluctuate between 10 and 200 MB, and for the JVM to spend 5% of its time in garbage collection, which typically uses less memory:

sudo java -Xms10m -Xmx200m -XX:GCTimeRatio=19 -jar burp.jar --collaborator-server

If you are running the Collaborator server on a dedicated machine to support a larger number of users, then it is efficient to fix the size of the heap to the amount of physical memory available, typically leaving 1GB available for the operating system, JVM and any other running processes. For example:

sudo java -Xmx3g -Xms3g -jar burp.jar --collaborator-server

If the server is expected to be heavily used and has more than 4GB of physical memory, it is recommended to switch to the G1 garbage collector, which significantly reduces the JVM pauses that can occur during garbage collection. For example:

sudo java -Xmx12g -Xms12g -XX:+UseG1GC -jar burp.jar --collaborator-server

To make full use of the Collaborator server's capabilities, you will generally also need to create a suitable configuration file.

Basic Set-up On A Closed Network

A common use case for a private Collaborator server is to support a single tester (or a small team) working on a private closed network. If you are testing an application on a closed network with no Internet access, then of course the default public Collaborator server cannot be used.

In this situation, you can launch a basic Collaborator server instance using one of the commands in Installation and Execution, without the need for any configuration file. You then simply need to configure Burp to use your machine's IP address as its Collaborator server.

In this set-up, the Collaborator will not support custom DNS resolution or valid trusted HTTPS connections. However, you will still be able to use the basic Collaborator features to detect issues like external HTTP interactions. 

Running On Non-Standard Ports

If you wish to run the Collaborator server as a non-root user, you will need to configure it to run on non-standard ports. You will also need to configure your operating system to map the original ports to the custom ports you are using. Typically, you will need to configure mappings for incoming TCP and UDP connections, and also for outgoing UDP responses.

You can configure the Collaborator server to use non-standard ports using its configuration file. For example:

{
  "serverDomain" : "burpcollaborator.example.com",
  "eventCapture": {
    "http": {
      "ports" : 8080
    },
    "https": {
      "ports" : 8443
    },
    "smtp": {
      "ports" : [8025, 8587]
    },
    "smtps": {
      "ports" : 8465
    }
  },
  "dns": {
    "ports" : 8053
  }
}

Note that the "ports" value can be a single port number or an array of port numbers, if you want to listen for a service on multiple ports. By default, the Collaborator server listens for SMTP interactions on ports 25 and 587.

DNS Configuration

Burp Collaborator by default runs a DNS service for a specific domain, and to make use of this you will need a dedicated domain or subdomain for the Collaborator to use. You can omit the DNS capability and access the Collaborator server only by IP address; however, this configuration is less effective at detecting various vulnerabilities.

If you are running Burp Collaborator on the public Internet, you can purchase a dedicated domain (e.g. example.com), or use a subdomain of a domain that you already own and use (e.g. burpcollaborator.example.com). If your installation will be restricted to an internal network, you can choose any dedicated internal domain.

The Collaborator server needs to know which domain it controls so that it can serve the appropriate DNS records. This is configured in the Collaborator configuration file. For example:

{
  "serverDomain": "burpcollaborator.example.com"
}

You will also need to configure your domain so that DNS for the domain is delegated to your Collaborator server. The details of this will depend on your set-up. Most domain registrars provide a web interface allowing you to configure the authoritative DNS servers for your domain.

If you are using example.com as the domain for your Collaborator server, you will need to configure the domain to use the following name servers:

ns1.example.com
ns2.example.com

You will also need to configure glue records to associate each of these with the IP address of your Collaborator server. If your domain registrar requires each configured DNS server for the domain to reside on a different IP address, then you might need to configure two public IP addresses on your Collaborator server.

Note: It is not possible to avoid the use of the Collaborator DNS service by simply editing the hosts file of the target server being tested. When employing the Collaborator server in its testing, Burp uses randomly generated subdomains of the main configured domain. Host files do not support wildcards and so cannot be used to route queries with randomly generated subdomains.

SSL Configuration

Burp Collaborator runs HTTPS and SMTPS services for capturing interactions initiated by tested systems, and to serve polling requests made by Burp Suite. Typically, SSL connections to the Collaborator server will only succeed if the Collaborator has been configured with a valid wildcard SSL certificate for the domain name being used. SSL certificates can be configured using the Collaborator configuration file.

If you do not have a valid wildcard SSL certificate for your domain, then Burp Collaborator can create a self-signed certificate. For example, the following configuration will create a self-signed wildcard certificate for *.burpcollaborator.example.com:

"ssl": {
  "hostname" : "burpcollaborator.example.com"
}

Using a self-signed certificate may be sufficient if you are able to install the certificate as trusted on the target server you are testing, or if the target application does not validate SSL certificates.

If you have purchased a valid wildcard SSL certificate for your domain, you can obtain the certificate from your Certificate Authority (CA), and install it in your Collaborator server. In this example, we have generated a Certificate Signing Request (CSR) using OpenSSL, and the CA has provided the certificate and an intermediate certificate.

With OpenSSL, the default format for keys is the traditional SSLeay format. These need to be converted to PKCS8 before the Collaborator server can import them. The OpenSSL command to do this conversion is:

openssl pkcs8 -topk8 -inform PEM -in keys/burpcollaborator.example.com.key -outform PEM -out keys/burpcollaborator.example.com.key.pkcs8 -nocrypt

SSL certificates can be configured using the Collaborator configuration file. The following example configuration file demonstrates how to load the private key, the certificate, and the intermediate certificate:

"ssl": {
  "certificateFiles" : [
    "keys/burpcollaborator.example.com.key.pkcs8",
    "keys/burpcollaborator.example.com.crt",
    "keys/intermediate.crt"]
}

Note: The certificate files must be specified in the correct order: private key, certificate, intermediate certificate(s).

Alternatively, you can generate a CSR using the Java keytool, and import the resulting certificate into the Java keystore of the server. In this situation, you can configure the Collaborator to load the certificate using:

"ssl": {
  "keystore": {
    "path" : "myKeystore.jks",
    "password" : "myPassword"
}

If you have configured separate network interfaces for interaction events and polling, you will need to configure SSL separately for each interface.

Interaction Events and Polling

The Collaborator server supports two types of incoming communications from clients:

• Interaction events - These occur when a target application being tested initiates some kind of interaction with the Collaborator server, for example a DNS lookup or an HTTP request.
• Polling requests - These occur when an instance of Burp asks the Collaborator server whether any interaction events have occurred resulting from its payloads.

By default, the Collaborator server handles both interaction events and polling requests on the same network interface. If you wish, you can configure the Collaborator to use different interfaces (or ports) for serving polling requests. This facility can be used to work around firewall restrictions, or to control access to the polling function at the network layer.

You can configure a separate polling interface using the optional "polling" section of the Collaborator configuration file. If you do this, you can use the same wildcard SSL certificate for both interfaces, and let the Collaborator server's DNS service direct polling requests to the correct interface. With this set-up, you will only need to configure the server location in the Burp Collaborator Server options, and Burp will automatically prepend "polling." to the server domain when performing polling requests. The Collaborator's DNS service will resolve the polling subdomain to the public IP address of the separate polling interface. This provides the benefit of using separate interaction and polling interfaces while simplifying the configuration of the Burp client.

Metrics

The Collaborator server captures various usage metrics allowing administrators to monitor the performance and load of the server. These metrics can be useful to validate that the Collaborator machine is sufficiently powerful for its level of usage. Note that the metrics do not contain any data extracted from specific interaction events and polling requests.

Metrics data is accessible via the polling interface of the Collaborator server, and access can be controlled through the use of a shared secret URL path and a client IP address whitelist. Metrics are disabled by default but can be enabled using the optional "metrics" section of the Collaborator configuration file. For example:

"polling" : {
  "publicAddress" : "10.20.0.159"
},
"metrics": {
  "path" : "jnaicmez8",
  "addressWhitelist" : ["21.10.23.0/24"]
},

With this configuration, metrics would be available to clients on the 21.10.23.0/24 network at the URL:

https://10.20.0.159/jnaicmez8/metrics

Collaborator logging

You can configure logging to standard output, via the logLevel value in the configuration file. The available values are:

• OFF - Nothing is logged.
• ERROR - Unexpected exceptions are logged.
• INFO - Information about configuration and services is logged at startup. This is the default value.
• DEBUG - Details of Collaborator interactions and polling are logged, including source IP address and interaction IDs. Note that this might disclose sensitive information in the log output.

Testing the Installation

When the server is deployed, you can use Burp Suite to test that is operating correctly. In Burp Suite Professional, configure the details of your server in the Burp Collaborator Server options, and run the health check function. Burp will then attempt to exercise each of the expected Collaborator functions, and will provide feedback of the success or failure of each function.

Collaborator configuration File Format

All options for Burp Collaborator server are controlled using a configuration file. By default, the Collaborator server looks for a file called collaborator.config in the current working directory. This location can be overridden from the command line using the --collaborator-config argument, for example:

sudo java -jar burp.jar --collaborator-server --collaborator-config=myconfig.config

The configuration file uses a JSON format, with support for comments. Where IP addresses are required, you can configure either a single address or a list of addresses. For example, either of the following could be used to configure the local address(es) of a network interface:

"localAddress" : "10.20.0.159"
"localAddress" : ["10.20.0.159", "127.0.0.1"]

A complete sample configuration file, together with an explanation of each available option, is shown below:

{
  "serverDomain" : "burpcollaborator.example.com",
  "workerThreads" : 10,
  "eventCapture": {
    "localAddress" : ["10.20.0.159", "127.0.0.1"],
    "publicAddress" : "10.20.0.159",
    "http": {
      "ports" : 80
    },
    "https": {
      "ports" : 443
    },
    "smtp": {
      "ports" : [25, 587]
    },
    "smtps": {
      "ports" : 465
    },
    "ssl": {
      "certificateFiles" : [
        "keys/burpcollaborator.example.com.key.pkcs8",
        "keys/burpcollaborator.example.com.crt",
        "keys/intermediate.crt" ]
    }
  },
  "polling" : {
    "localAddress" : "127.0.0.1",
    "publicAddress" : "10.20.0.159",
    "http": {
      "port" : 9090
    },
    "https": {
      "port" : 9443
    },
    "ssl": {
      "hostname" : "collaboratorpolling.example.com"
    }
  },
  "metrics": {
    "path" : "jnaicmez8",
    "addressWhitelist" : ["21.10.23.0/24"]
  },
  "dns": {
    "interfaces" : [{
      "name": "ns1",
      "localAddress" : "34.23.11.6",
      "publicAddress" : "98.87.76.55"
    }, {
      "name" : "ns2",
      "localAddress" : "34.23.11.6",
      "publicAddress" : "98.87.11.00"
    }],
    "ports" : 53
  },
  "logLevel" : "INFO"
}