ENTERPRISEPROFESSIONAL

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:

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.

General set-up steps

To run a private Burp Collaborator server to use all Collaborator functionality, be accessible on the Internet or support multiple users, you will need to follow these steps:

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 command above will launch the Collaborator server using the default configuration file. To add a custom configuration, add the following argument:

--collaborator-config

However, depending on your use case, there may be more than this to setting up a private Collaborator server. See the previous section for what you need to do to set the server up and the Collaborator configuration file section for details on creating your own configuration file.

Collaborator server ports and firewall rules

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:

Your firewall needs to allow inbound communication from any network on these ports. The applications that you are testing (and their DNS servers) also have to be able to access the Collaborator server, and you will need to adjust your firewall rules so that this happens. 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.

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.

Collaborator server resources

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.

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"
}

The details of the DNS configuration will vary depending on your domain registrar, but you must have the following entries:

For example, the public collaborator domain is burpcollaborator.net:

dig burpcollaborator.net NS +noall +answer +short
burpcollaborator2.portswigger.net
burpcollaborator1.portswigger.net

Both of these records resolve to the collaborator's public IP address:

dig burpcollaborator1.portswigger.net A +noall +answer +short
52.16.21.24

dig burpcollaborator2.portswigger.net A +noall +answer +short
52.16.107.92

It is essential that the collaborator server is authoritative for the domain specified within the Collaborator configuration file in order that all queries for it's domain are resolved by the server. The details of setting this up 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.

Collaborator configuration file

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"]

The Collaborator configuration file uses the following fields:

Field Meaning Example
Your_Collaborator_Domain This is the server domain for which the Collaborator is authoritative. somedomain.net
NS_record_label_1 This is the label(s) for the first entry within the server domain's NS record. ns1 (somedomain.net would have an NS record containing ns1.somedomain.net
NS_record_label)_2 This is the label(s) for the second entry within the server domain's NS record. ns2 (somedomain.net would have an NS record containing ns2.somedomain.net
External_IP_Nameserver_A_Record1 The public UP address of the Collaborator server and the corresponding A record entry. This would be the A (or AAAA) record for the ns1.somedomain.net
External_IP_Nameserver_A_Record2 The public UP address of the Collaborator server and the corresponding A record entry. This would be the A (or AAAA) record for the ns2.somedomain.net
Local_IP_1 The actual IP address of your Collaborator server. 10.20.0.160
Local_IP_2 The actual IP address of your Collaborator server. 10.20.0.161 (This should be different from Local_IP_1)
Collaborator_External_IP One of your Collaborator server's public addresses. 10.20.0.162
path_to_key_file Path to file containing the Collaborator's key. /opt/collaborator/collaborator.key
path_to_certificate_file Path to file containing the Collaborator's certificate. /opt/collaborator/collaborator.crt

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

{
 "serverDomain" : "Your_Collaborator_Domain",
  "workerThreads" : 10,
 "eventCapture": {
  "localAddress" : "Local_IP",
  "publicAddress" : "Collaborator_External_IP",
  "http": {
   "ports" : 80
  },
  "https": {
   "ports" : 443
  },
  "smtp": {
   "ports" : [25, 587]
  },
  "smtps": {
   "ports" : 465
  },
  "ssl": {
   "certificateFiles" : [
    "path_to_key_file",
    "path_to_certificate_file" ]
  }
 },
 "dns": {
  "interfaces" : [
   {
    "name": "NS_record_label_1",
    "localAddress" : "Local_IP_1",
    "publicAddress" : "External_IP_Nameserver_A_Record1"
   },
   {
    "name" : "NS_record_label_2",
    "localAddress" : "Local_IP_2",
    "publicAddress" : "External_IP_Nameserver_A_Record2"
   }
  ],
  "ports" : 53
 },
 "logLevel" : "INFO"
}

The definitions of the supported fields in the configuration file are shown below:

serverDomain The domain or subdomain which the Collaborator server will control DNS for. This setting is required for DNS functionality.
workerThreads The number of threads used by the Collaborator to process incoming requests.
eventCapture.localAddress By default, the Collaborator will listen on all local interfaces for capturing interaction events. If specified, it will only listen on the configured interfaces.
eventCapture.publicAddress The public IP address used for capturing interaction events.
eventCapture.http.ports The ports for listening for HTTP interaction events. This should only be changed from the default if port 80 is being forwarded.
eventCapture.https.ports The ports for listening for HTTPS interaction events. This should only be changed from the default if port 443 is being forwarded.
eventCapture.smtp.ports The ports for listening for SMTP interaction events. This should only be changed from the default if ports 25 and 587 are being forwarded.
eventCapture.smtps.ports The ports for listening for SMTPS interaction events. This should only be changed from the default if port 465 is being forwarded.
eventCapture.https.hostname Used to generate a self-signed certificate. See TLS configuration for more details.
polling.localAddress By default, the Collaborator will use the same network interface for capturing interaction events and serving polling requests. If specified, it will use a different interface for polling requests.
polling.publicAddress The public address used for serving polling requests.
polling.http.port The port to be used for polling over HTTP. This can be non-standard and Burp Suite will need to be configured to use it.
polling.https.port The port to be used for polling over HTTPS. This can be non-standard and Burp Suite will need to be configured to use it.
polling.https.hostname Used to generate a self-signed certificate. See TLS configuration for more details.
metrics.path URL path under at which the metrics page can be accessed.
metrics.whitelist A whitelist of client IP addresses allowed to access the metrics page.
dns.ports Ports for listening for DNS queries. This should only be changed from the default if port 53 is being forwarded.
dns.interfaces A list of local interfaces for listening for DNS queries. If your registrar requires that you configure a different IP address for each authoritative name server, you can use multiple network interfaces and configure their locations with this option.
dns.interfaces.name The hostname to use for the name server running on this interface. A different hostname should be used for each name server (e.g. ns1, ns2, etc.).
dns.interfaces.localAddress The local address to bind to for this name server.
dns.interfaces.publicAddress The public IP address corresponding to the configured local address. Typically, you will need to use the configured hostname and public IP address in your DNS record for your domain.
logLevel The level of logging required to standard output.
customDnsRecords.label This is the DNS label for the custom content, e.g. _acme-challenge.
customDnsRecords.record This is the custom DNS record for the corresponding label.
customDnsRecords.type This is the type of the custom DNS record. Currently either TXT or CNAME.
customDnsRecords.ttl This is the time to live for the record in seconds.
customHttpContent.path This is the path for the custom HTTP content.
customHttpContent.contentType This is the MIME type to add to the response header for the custom content.
customHttpContent.base64content This is the BASE64 encoded content that will be decoded and served for a request to path.

TLS 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, TLS connections to the Collaborator server will only succeed if the Collaborator has been configured with a valid wildcard TLS certificate for the domain name being used. TLS certificates can be configured using the Collaborator configuration file.

If you do not have a valid wildcard TLS 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 TLS certificates.

If you have purchased a valid wildcard TLS 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

TLS 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 TLS separately for each interface.

Interaction events and polling

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

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 TLS 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. This is done as follows:

"polling" : {
 "publicAddress" : "<External_IP>"
},

The following example polling interface uses custom ports, HTTPS and self-signed certificates:

"polling" : {
 "localAddress" : "<Local_IP>",
 "publicAddress" : "<External_IP>",
 "http": {
  "port" : 9090
 },
 "https": {
  "port" : 9443
 },
 "ssl": {
  "hostname" : "collaboratorpolling.example.com"
 }
},

The following example polling interface uses custom ports, HTTPS and CA issued certificates.

"polling" : {
 "localAddress" : "<Local_IP>",
  "publicAddress" : "<External_IP>",
  "http": {
   "port" : 9090
  },
 "https": {
  "port" : 9443
 },
 "ssl": {
  "certificateFiles" : [
   "path_to_key_file",
   "Path_to_certificate_file"
  ]
  }
},

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:

"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:

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.

Add custom HTTP content

By default, most URLs on your private Collaborator server simply point to a generic page, which provides some basic information about Burp Collaborator. However, you can also define custom URLs that point to bespoke content. For example, you could create your own index page identifying your organization and the purpose of the service.

You can also use this capability to host files at arbitrary URLs. For example, in order to validate TLS certificate requests, a CA might ask you to host a file at a specific URL to prove that you own the domain. Hosting custom robots.txt and crossdomain.xml files is also supported.

You define custom URLs by adding the array customHttpContent to the top level of the configuration file. In this array, you create an object for each URL that you want to define. For each object, you have to specify the following properties:

For example, adding the following configuration sets a custom index page to the root path and adds a readme file at /info/readme.txt:

"customHttpContent":[
    {
        "path":"/",
        "contentType":"text/html",
        "base64Content":"PCFkb2N0eXBlIGh0bWw+Cgo8aHRtbCBsYW5nPSJlbiI+CjxoZWFkPgogIDxtZXRhIGNoYXJzZXQ9InV0Zi04Ij4KICA8dGl0bGU+RXhhbXBsZSBQYWdlPC90aXRsZT4KCiAgPGxpbmsgcmVsPSJzdHlsZXNoZWV0IiBocmVmPSJjc3MvbXlzdHlsZXNoZWV0LmNzcyI+CjwvaGVhZD4KPGJvZHk+CjxoMT5XZWxjb21lIHRvIG15IGV4YW1wbGUgcGFnZTwvaDE+CjxwPlRoYW5rcyBmb3IgdmlzaXRpbmcgbXkgZXhhbXBsZSBwYWdlLjwvcD4KPC9ib2R5Pgo8L2h0bWw+"
    },
    {
        "path":"/info/readme.txt",
        "contentType":"text/plain",
        "base64Content":"VGhpcyBpcyB0aGUgcmVhZG1lIGZpbGUgZm9yIG15IGNvbGxhYm9yYXRvciBzZXJ2ZXIu"
    }
]

Add custom DNS records

It is possible to add custom TXT and CNAME DNS records. This is intended to allow the collaborator to respond to DNS challenges as part of domain validation. You can specify multiple TXT records for a single label, but only one CNAME record. Here is a sample configuration:

"customDnsRecords": [
 {
  "label": "_acme-challenge",
  "record": "275fe5b909adb10e41c78066e9485f7d",
  "type": "TXT",
  "ttl": 60
 },
 {
  "label": "patrick",
  "record": "dolphin",
  "type": "TXT"
  },
 {
   "label": "test",
  "record": "hackxor.net",
  "type": "CNAME"
  }
]

The ttl value is optional and is in seconds.

Troubleshooting your server

If you have problems with your Collaborator server, try the following: