Deploying xsshunter on Docker

xsshunter-express is a lightweight, easy-to-deploy version of XSS Hunter, designed for automated detection and exploitation of Cross-Site Scripting (XSS) vulnerabilities. Built on Docker, it sets up in minutes and runs with minimal maintenance.

This guide walks you through installing Docker, configuring xsshunter-express with Docker Compose, and securing your instance with Let's Encrypt. By the end, you'll have a fully functional XSS monitoring platform accessible via HTTPS.

Install Docker

Update your package index and install required dependencies:

sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release

Add Docker's official GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Add the Docker repository to your APT sources:

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Update APT and install Docker CE:

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

Alternative for Debian: If you're on Debian, use:

echo "deb [arch=amd64] https://download.docker.com/linux/debian buster stable" | sudo tee /etc/apt/sources.list.d/docker-ce.list
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -

Verify Docker Installation

Test that Docker is working correctly:

docker run hello-world:latest

This downloads and runs a test container. If successful, Docker is ready to use.

Check Docker and containerd service status:

sudo systemctl status docker.service
sudo systemctl status containerd.service

Install Docker Compose

Download the latest version of Docker Compose (replace 1.29.0 with a newer version if needed):

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Make it executable:

sudo chmod +x /usr/local/bin/docker-compose

Verify installation:

docker-compose --version

Configure xsshunter-express

Clone or navigate to the xsshunter-express repository:

git clone https://github.com/mandatoryprogrammer/xsshunter-express.git
cd xsshunter-express

Edit the docker-compose.yaml file:

sudo nano docker-compose.yaml

Update the following environment variables:

Variable	Description
`HOSTNAME`	Your domain (e.g., `xss.yourdomain.com`). Must resolve to your server's IP via DNS A record.
`SSL_CONTACT_EMAIL`	Email for Let's Encrypt certificate registration and renewal notifications.
`SMTP_EMAIL_NOTIFICATIONS_ENABLED`	Set to `true` to enable email alerts.
`SMTP_HOST`	SMTP server (e.g., `smtp.gmail.com`).
`SMTP_PORT`	Port (e.g., `465` for SSL, `587` for TLS).
`SMTP_USE_TLS`	Set to `true` if using TLS (e.g., on port 587).
`SMTP_USERNAME`	Email account username.
`SMTP_PASSWORD`	App password or account password.
`SMTP_FROM_EMAIL`	Sending email address (e.g., `admin@yourdomain.com`).
`SMTP_RECEIVER_EMAIL`	Destination for XSS alert emails.
`CONTROL_PANEL_ENABLED`	Set to `false` to disable the admin panel and reduce attack surface.

Run xsshunter

Start the PostgreSQL database in detached mode:

sudo docker-compose up -d postgresdb

Start the main xsshunter service:

sudo docker-compose up xsshunterexpress

Port Conflict? If Nginx is running on port 80/443, stop it temporarily:

sudo systemctl stop nginx

If everything succeeds, you'll see output including the admin panel password. Save it securely.

Your xsshunter instance is now available at:

https://your-hostname.com/admin/

The first time you access it, Let's Encrypt will automatically issue a valid TLS certificate.

On This Page