XSS Hunter is Now Open Source – Here’s How to Set It Up!

Recently I opened up XSS Hunter for public registration, this was after publishing a post on how I used XSS Hunter to hack GoDaddy via blind XSS and pointed out that many penetration testers use a very limited alert box-based pentesting methodology which will not detect these types of issues. After cleaning up the source code a bit I’m happy to say that XSS Hunter’s source code is now publicly available for anyone to download and contribute to! However, there is a bit of set up involved and I thought I’d make a post which shows people how to set it up on their own servers. In future versions of XSS Hunter I’m hoping to make this process a lot easier but for now the work is a bit non-trivial. For those of you who aren’t interested in doing the set up feel free to use the official online version.


  • A server running (preferably) Ubuntu.
  • A Mailgun account, for sending out XSS payload fire emails.
  • A domain name, preferably something short to keep payload sizes down. Here is a good website for finding two letter domain names: catechgory.com. For example, the XSSHunter.com domain uses xss.ht to host payloads.
  • A wildcard SSL certificate, here’s a cheap one. This is required because XSS Hunter identifies users based off of their sub-domains and they all need to be SSL-enabled. Sadly, we can’t use Let’s Encrypt for a free certificate because they don’t support wildcard certificates. I’m going to hold off on insulting the CA business model, but rest assured it’s very silly and costs them very little to mint you a wildcard certificate so go with the cheapest provider you can find (as long as it’s supported in all browsers).

Setting Up DNS

The first thing you need to do is set up the DNS for your domain name so it is pointing to the server you’re hosting the software on. Only two records are needed for this:

  • A record:
    • Value: SERVER_IP
  • CNAME record:

Those two records simply state where your server is located and that all subdomains should point to the same server.

Setting Up Dependencies

First, we need to install some dependencies for XSS Hunter to work properly. The two dependencies that XSS Hunter has are nginx for the web server and postgres for the data store. Setting these up is fairly easy, we’ll start with nginx:

sudo apt-get install nginx

After that, install postgres:

sudo apt-get install postgresql postgresql-contrib

Now we’ll set up a new postgres user for XSS Hunter to use:

sudo -i -u postgres
psql template1

Now we have all the dependencies installed, let’s now move on to setting up the software itself.

Setting Up Source Code

Now let’s install git and clone the Github repo:

sudo apt-get install git
git clone https://github.com/mandatoryprogrammer/xsshunter

Now that we’ve cloned a copy of the code, let’s talk about XSS Hunter’s structure. The service is broken into two separate servers, the GUI and the API. This is done so that if necessary the GUI server could be completely replaced with something more powerful without any pain, the same going for the API.

Let’s start by running the config generation script:


Once you’ve run this script you will now have two new files. One is the config.yaml file which contains all the settings for the XSS Hunter service and the other is the default file for nginx to use. Move the default file into nginx’s configuration folder by running the following command:

sudo mv default /etc/nginx/sites-enabled/default

You must also ensure that you also have your SSL certificate and key files in the following locations:

/etc/nginx/ssl/yourdomain.com.crt; # Wildcard SSL certificate
/etc/nginx/ssl/yourdomain.com.key; # Wildcard SSL key

(The config generation script will specify the location you should use for these files.)

Now you need to restart nginx to apply these changes, run the following:

sudo service nginx restart

Awesome! Nginx is now all set up and ready to go. Let’s move on to the actual XSS Hunter service set up.

In order to keep the server running after we disconnect from the box, we’ll start a tmux session by running the following command:


Now let’s start the API server! Run the following commands:

sudo apt-get install python-virtualenv python-dev libpq-dev libffi-dev
cd xsshunter/api/
virtualenv env
. env/bin/activate
pip install -r requirements.txt

Once you’ve run the above commands, type CTRL+B followed by typing C to create a new terminal.

In this new terminal let’s start the GUI server, run the following commands (in a new terminal):

cd xsshunter/gui/
virtualenv env
. env/bin/activate
pip install -r requirements.txt

Congrats! You should now have a working XSS Hunter server. Visit your website to confirm everything is functioning as expected. You can now detach from tmux by typing CTRL+B followed by D.

Problems? Bugs?

If you have an problems or bugs that you encounter in the software please file a Github issue on the official repo: https://github.com/mandatoryprogrammer/xsshunter.

Matthew Bryant (mandatory)

Matthew Bryant (mandatory)
Security researcher who needs to sleep more. Opinions expressed are solely my own and do not express the views or opinions of my employer.