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.

Kafka Install

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: bash 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): bash 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 Elasticsearch 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: bash 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).

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, 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.

  • PhishTank : data.phishtank.com

  • URLHaus : urlhaus.abuse.ch

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.

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.

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:8000) should be a accessible to the centralized watchdog instance.

  • EUNOMATIX Cloud : ucs.eunomatix.com:8000

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.

Browsermon Install

Browsermon Enterprise Version runs in a client-server model, where Browsermon Controller(s) run on all enterprise endpoints for local browser history log collection. Whereas a central Browsermon Watchdog server is installed to perform health checking and distributed management of all Browsermon controllers installed endpoints.

Important: For optimal continuity, maintain the same logdir path as used in previous versions. This ensures the new version will resume log processing from the last recorded position.

Windows

  1. Download the latest release of Browsermon Private based on your system architecture and extract the files.
  2. Populate the browsermon.conf file with the required parameters.
  3. Open the Administrative PowerShell in the Browsermon Private directory and execute the following command to install: bash Set-ExecutionPolicy RemoteSigned -Force ; .\win_install.ps1
  4. Verify the installation by checking the Browsermon service in the Windows service manager to ensure it is installed and functioning correctly.
  5. Configure your watchdog_ip and watchdog_port in the Browsermon Config file browsermon.conf to integrate Watchdog.

Linux

  1. Download the latest release of Browsermon Private from GitHub according to your architecture and extract the files.
  2. Populate the browsermon.conf file with the necessary parameters.
  3. Open the terminal in the Browsermon Private directory and run the following command: bash sudo ./linux_install.sh
  4. Run systemctl status browsermon to check the status of your service.
  5. Configure your watchdog_ip and watchdog_port in the Browsermon Config file browsermon.conf to integrate Watchdog.