Skip to content

Installation

Prerequisites

  1. Root/Sudo Access
    The installer must be run as root (or with sudo). It manages system directories (e.g., /opt/watchdog) and sets ownership of data directories.

  2. Docker and Docker Compose

  3. Docker installed and running (docker ps should work).
  4. Docker Compose plugin or Docker Compose CLI installed.

  5. Optionally, Docker registry credentials if you plan to pull images from a private Docker registry.

  6. Local Files/Directories

  7. A local deps/ directory that contains:
    • deps/connect-jars/ (Kafka connector JARs).
    • deps/watchdog/ (Watchdog source files).
    • deps/init-kafka-connect.sh (initialization script).
  8. Docker Compose YAML files in the same directory from which you run the installer:
    • docker-compose.base.yml (required).
    • docker-compose.kafka.yml (if enabling Kafka).
    • docker-compose.elastic.yml (if enabling Elasticsearch).
  9. Optional config files (if needed for custom setups):
    • elasticsearch.yml (if elastic_mode=true and you want to override default ES config).
    • Any custom .conf files for Watchdog (placed in deps/watchdog before running the script).

Installation Steps

  1. Clone or place the watchdog-installer script in the same directory where your docker-compose.*.yml files exist (because it writes a .env file locally and references the compose files in the current directory).

  2. Ensure the script is executable: 

    chmod +x watchdog-installer

    If you’re using the Python file directly, you can just run python watchdog-installer install without chmod +x.

  3. Run the installer (as root): 

    sudo ./watchdog-installer install

  4. The script will:

    1. Prompt you for Docker registry authentication (optional).
    2. Prompt whether to enable Kafka/Elasticsearch modes.
    3. If Kafka mode is enabled, prompt for a KAFKA_EXTERNAL_IP.
    4. If Elasticsearch mode is enabled, prompt for host, port, passwords, etc.
    5. Create /opt/watchdog, /opt/watchdog/kafka_data, and /opt/watchdog/elasticsearch_data as needed.
    6. Copy files from deps/ into /opt/watchdog.
      • connect-jars and init-kafka-connect.sh are forced overwrites (no prompt).
      • The watchdog directory is copied file-by-file with a prompt for each existing file.
    7. Generate a .env file in your current directory (where Docker Compose can see it).
    8. Finally, run docker compose up -d using docker-compose.base.yml, plus the Kafka and/or Elastic Compose files if those modes were selected.

  5. Verify installation:

  6. Check running containers: 
    docker ps
  7. If Kafka was enabled:
    • kafka, zookeeper, and kafka-connect containers should be running.
  8. If Elasticsearch was enabled:
    • An elasticsearch container should be running (depending on your compose files).

Environment Variables and .env File

The script automatically writes environment variables to a .env file in the current working directory. Docker Compose will automatically load them. If Kafka/Elasticsearch is enabled, you’ll see lines like:

KAFKA_EXTERNAL_IP=your.machine.ip
ELASTIC_HOST=elasticsearch
ELASTIC_PORT=9200
ELASTIC_PASSWORD=BrowsermonElasticAdmin
ELASTIC_USER_PASSWORD=BrowsermonElasticUser
ELASTIC_SCHEME=https

You can modify these directly if needed (though re-running the script may overwrite them).

ETI Install

ETI is packaged along with the Watchdog and runs as a separate docker. It operates independently while integrating with the Watchdog to enhance threat intelligence gathering.

Authentication Requirments

In order for endpoints to use EUNOMATIX ETI service Username and Password needs to be written in browsermon.conf file under eti or elasticsearch section.

Default Port

By default ETI service runs on port 9200

Threat Intelligence Fetch Frequency

ETI service fetches threat intel after 24 hours at midnight.

Enabling/Disabling ETI

ETI can be enabled/disabled by setting eti_mode inside browsermon.conf to true or false.

Required Domain Access

For the functioning of the ETI, the following domains must be accessible from the network where your watchdog is deployed.

  • PhishTank : phishtank.com

  • URLHaus : urlhaus.abuse.ch

URL Classification Categories

Category Description
phish URL is classified as a phish
malware_download URL is classified as a malware
unknown URL is not listed in ETI
unset ETI mode is turned off
failed Classification failed due to some error