Skip to content

Installation

Prerequisites

Following are prerequsites for Watchdog Install.

  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).
    • docker-compose.eti.yml (if enabling ETI).
    • docker-compose.ucs.yml (if enabling UCS).
  9. Optional config files (if needed for custom setups):
    • eti.yml (if eti_mode=true and you want to override default ES config).
    • Any custom .conf files for Watchdog (placed in deps/watchdog before running the script).

Watchdog Install

This guide explains how to install and configure Watchdog using the watchdog-installer Python script. Watchdog can optionally integrate with Kafka (for data ingestion), eti (for threat classification) and ucs (for domain level url classification).

The installer supports:

  1. Interactive prompts for Docker registry authentication (optional).
  2. Enabling/disabling Kafka mode, ETI mode and UCS mode. (optional)
  3. Automatic creation of necessary directories under /opt/watchdog.
  4. File-by-file copy of important Watchdog files (prompts only for /opt/watchdog/watchdog/ overwrites).
  5. Automatic generation of a .env file in your current directory, containing the environment variables Docker Compose will need.
  6. A final Docker Compose deployment that launches the selected services.

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/ETI/UCS modes.
    3. If Kafka mode is enabled, prompt for a KAFKA_EXTERNAL_IP.
    4. If ETI/UCS mode is enabled, prompt for username, 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 and threat_collector or ucs_client containers should be running, depending upon modes you selected.

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_USERNAME=Browsermon
ELASTIC_USER_PASSWORD=BrowsermonElasticUser
ELASTIC_SCHEME=https

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

Updating the Installation

If you are performing an upgrade or have installed Watchdog before and want to preserve configuration and data, you should go to the previous release directory from where you installed the older version and run: 

sudo ./watchdog-installer clean
This will clean all the containers, networks, and volumes, and ask if you also want to clean the images. Then, run the installer again. It will ask you for the upgrade; proceed with it. If you want to replace any file, press y, otherwise skip the prompts.

If you re-run the installer and /opt/watchdog is detected, the script enters Update Mode.

Example: 

sudo ./watchdog-installer install
If it sees an existing installation, you’ll be asked:

Existing installation detected at /opt/watchdog
Do you want to proceed with the update? (y/n)

  • Prompt you for Docker registry authentication (optional).
  • Prompt whether to enable Kafka/ETI/UCS modes.
  • If Kafka mode is enabled, prompt for a KAFKA_EXTERNAL_IP.
  • If ETI/UCS mode is enabled, prompt for username, passwords, etc.
  • Prompted for overwriting files inside /opt/watchdog/watchdog.
  • Other files (like init-kafka-connect.sh or connect-jars) are overwritten automatically.
  • The script will then re-run Docker Compose to update containers.

Note: If there is any change in conf files then you should press y when installer prompt you to replace that file.

Offline Image Deployment (Optional)

If you have Docker images saved locally (e.g., .tar files) for offline deployment: 1. Load them: 

docker load -i your_offline_watchdog_image.tar

Note: The offline images from the Eunomatix has the following naming convention watchdog-{version}.img

  1. Skip Docker Hub Login during the script’s prompts.
  2. Ensure the Docker Compose files reference the images you loaded (matching tags).

Uninstalling / Cleaning Up

To stop and remove the Watchdog containers (Kafka/Elasticsearch included), run: 

sudo ./watchdog-installer clean
This will: 1. Look for docker-compose.base.yml, docker-compose.kafka.yml, and docker-compose.elastic.yml in your current directory. 2. Run docker compose down -v with whichever files are found, removing containers and volumes.

Note: This does not delete /opt/watchdog or the data directories. If you want to remove them entirely, you can do so manually: 

sudo rm -rf /opt/watchdog

Kafka Install

Browsermon Inspect and Kafka is packeged with the Watchdog to use as a replacement for Splunk. Kafka processes data from all the endpoints and sends it to a central storage. Using Browsermon inspect you can query data and view it in grafana dashboard from all the endpoints.

Configuration

You should set the Kafka_External_IP to your machine IP. Make sure that browsermon endpoints can connect to this IP.

Default Port

The default port for kafka is 8092

The default port for Grafna is 1514

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. You should clean first before install as having multiple containers with same name can cause issue.

Authentication Requirments

In order for endpoints to use EUNOMATIX ETI service Username, Password Host and Port needs to be written in browsermon.conf file under elastic section.

Example: 

[elastic]
host=localhost
port=9200
username=Browsermon
password=BrowsermonElasticUser
eti_index=threat_index
ucs_index=eunomatix_ucs

Default Port

By default ETI service utilizes the centralized elastic database running 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.

  • ETI API : eti.eunomatix.com

Important: If watchdog is behind a proxy server, relevant proxy settings must be enabled in watchdog.conf file before installation.

Example: 

[proxy]
proxy_mode=false
http_proxy=http://10.10.10.10:1234
https_proxy=https://10.10.10.10:1234

  • If proxy server has aunthentication, user should enter url according to it e.g http://username:[email protected]:8080.

  • Both http and https proxies should be specified in watchdog.conf even if you only have http proxy.

  • If proxy is running on your host machine you should use host.docker.internal or host.containers.internal depends on your docker setup as host of proxy instead of localhost

Threat 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

UCS Install

UCS is packaged along with the Watchdog and runs as a separate docker. It operates independently while integrating with the Watchdog to provide insightful URL classifications. You should clean first before install as having multiple containers with same name can cause issue.

Authentication Requirments

In order for endpoints to use EUNOMATIX UCS service Username, Password Host and Port needs to be written in browsermon.conf file under elastic section.

Example: 

[elastic]
host=localhost
port=9200
username=Browsermon
password=BrowsermonElasticUser
eti_index=threat_index
ucs_index=eunomatix_ucs

Default Port

By default UCS service utilizes the centralized elastic database running on port 9200.

UCS Updates

To fetch daily URL classification updates from EUNOMATIX Cloud API, ucs_updates option must be set true before installation in watchdog.conf. Upon Installation if UCS mode is enabled, classification updates will be fetched daily at midnight by using UCS API. For air-gapped networks that are isolated from external networks, ucs_updates must be set to false before installation in watchdog.conf. Upon installation if UCS mode is enabled, local snapshot index will get restord.

Enabling/Disabling UCS

UCS can be enabled/disabled by setting ucs_mode inside browsermon.conf to true or false.

Cloud Access

To get UCS daily updates, following cloud URL (https://ucs.eunomatix.com) should be a accessible to the centralized watchdog instance.

  • UCS API : ucs.eunomatix.com

Important: If watchdog is behind a proxy server, relevant proxy settings must be enabled in watchdog.conf file before installation.

[proxy]
proxy_mode=false
http_proxy=http://10.10.10.10:1234
https_proxy=https://10.10.10.10:1234
  • If proxy server has aunthentication, user should enter url according to it e.g http://username:[email protected]:8080.
  • Both http and https proxies should be specified in watchdog.conf even if you only have http proxy.
  • If proxy is running on your host machine you should use host.docker.internal or host.containers.internal depends on your docker setup as host of proxy instead of localhost