Installation

Prerequisites

Following are prerequsites for Watchdog Install.

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.
Docker and Docker Compose
Docker installed and running (docker ps should work).
Docker Compose plugin or Docker Compose CLI installed.
Optionally, Docker registry credentials if you plan to pull images from a private Docker registry.
Local Files/Directories
A local deps/ directory that contains:
- deps/connect-jars/ (Kafka connector JARs).
- deps/watchdog/ (Watchdog source files).
- deps/init-kafka-connect.sh (initialization script).
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).
no-proxy.env — must be present alongside the Docker Compose files. This file clears host-level proxy variables inside containers to prevent them from breaking container-to-container networking.
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 watchdog-installer.sh. Watchdog can optionally integrate with Kafka (for data ingestion), eti (for threat classification) and ucs (for domain level url classification).

Note: If you require a pre-hardened environment or are deploying into an air-gapped network, consider using the VM (OVA) Install method instead, which ships with Docker and all Watchdog images pre-loaded on a CIS Level 1 hardened Ubuntu 24.04 LTS image.

The installer supports:

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

Installation Steps

Place the watchdog-installer.sh script in the same directory where your docker-compose.*.yml and no-proxy.env files exist (because it writes a .env file locally and references the compose files in the current directory).
Ensure the script is executable:
```
chmod +x watchdog-installer.sh
```
Run the installer (as root):
```
sudo ./watchdog-installer.sh install
```
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.
Verify installation:
Check running containers:
```
docker ps
```
If Kafka was enabled:
- kafka, zookeeper, and kafka-connect containers should be running.
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.sh 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.sh 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

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

Tip: For a fully air-gapped deployment with a pre-hardened OS, consider using the VM (OVA) Install which ships with all images pre-loaded and CIS Level 1 hardening applied out of the box.

VM (OVA) Install

Watchdog is available as a pre-built virtual machine image for environments that require a hardened, ready-to-deploy setup or have no internet access during installation. The OVA is built on Ubuntu Server 24.04.4 LTS, hardened to CIS Level 1 standards, and ships with Docker and all Watchdog images pre-loaded.

VM Image Details

Property	Value
Base OS	Ubuntu Server 24.04.4 LTS
Hardening Standard	CIS Level 1 (235 rules applied)
Lynis Hardening Score	81
Docker	Pre-installed
Watchdog Images	Pre-loaded
SSH Access	Key-based authentication only (by default)

Note: Three CIS rules that conflict with Docker networking and storage requirements are intentionally overridden. All other 235 rules are applied and verified via Lynis. The full Lynis report is available alongside the VM image download.

Hypervisor Requirements

The OVA is built with hardware version vmx-13 and is compatible with the following VMware platforms:

Hypervisor	Minimum Supported Version
VMware ESXi	6.5 or later
VMware Workstation	12 or later
VMware Fusion	8.5 or later

Note: The OVA uses VMware specific OVF schema extensions. Import into VirtualBox or other non-VMware hypervisors may not work as expected and is not officially supported.

VM Specifications (OVA)

The following resources are declared in the OVA and will be allocated to the VM on import:

Resource	Value
vCPUs	2
RAM	4 GB
Disk Size	40 GB
Network Adapter	1 × E1000 (VM Network)
Guest OS	Ubuntu 24.04 LTS (64-bit)

Note: Disk usage will grow over time depending on the number of monitored endpoints and data retention period. Monitor available disk space and expand the volume as needed.

Default Credentials

The OVA ships with the following default login credentials for console and SSH access:

Field	Value
Username	`watchdog`
Password	`watchdog`

Important: On first login, you will be prompted to change the password immediately. The system will not proceed until a new password is set. Choose a strong password before continuing with the installation steps.

Step 1: Download the VM Image

Download the release zip folder from the Watchdog release page:

Release zip: watchdog-v4.0.2.zip

Contact our team to request the OVA image directly at: support@eunomatix.com

Verify the SHA-256 checksum of the release zip before proceeding

Step 2: Import the OVA into Your Hypervisor

Import the .ova file into your hypervisor. Steps vary by platform:

VMware ESXi: Navigate to Virtual Machines → Create / Register VM → Deploy a virtual machine from an OVF or OVA file → select the .ova file
VMware Workstation / Fusion: Go to File → Open (or Import) → select the .ova file

Step 3: Add Your SSH Public Key

Important: Password-based SSH login is disabled by default. You must add your SSH public key via the hypervisor console or GUI before attempting any remote SSH connection.

Use your hypervisor's console to log in locally and add your public key to ~/.ssh/authorized_keys, or configure it through your hypervisor's guest customization options if available.

Step 4: Boot and Connect

Start the VM, then connect via SSH using your private key:

ssh -i /path/to/your/private_key <username>@<vm-ip-address>

Step 5: Transfer and Extract the Installer Package

Copy the release zip to the VM and extract it:

scp -i /path/to/your/private_key watchdog-v4.0.2.zip <username>@<vm-ip>:~/
ssh -i /path/to/your/private_key <username>@<vm-ip>
unzip watchdog-v4.0.2.zip
cd watchdog-v4.0.2

Step 6: Run the Watchdog Installer

Make the installer executable and run it:

chmod +x watchdog-installer.sh
sudo ./watchdog-installer.sh install

When prompted about Docker registry authentication, you can skip it — all images are already pre-loaded on the VM. Follow the remaining prompts as described in the Watchdog Install section above (enabling Kafka/ETI/UCS modes, setting KAFKA_EXTERNAL_IP, etc.).

Step 7: Verify Installation

Check that the expected containers are running:

docker ps

Refer to the Watchdog Install verification steps for details on which containers should be present based on the modes you selected.

Air-Gapped Deployment Notes

All Docker images are pre-loaded on the VM — no registry or internet access is needed during installation.
If using UCS in an air-gapped environment, set ucs_updates=false in watchdog.conf before running the installer. The local UCS snapshot index will be restored automatically upon installation.
ETI will function with locally available data. External access to eti.eunomatix.com is only required if you intend to fetch live threat intelligence updates.

Security Notes

SSH key-based authentication is enforced by default; password login is disabled.
The kafka-connect REST API (port 8083) is bound to localhost only and is not externally accessible.
Host proxy environment variables are isolated from containers via no-proxy.env, preventing interference with container-to-container networking.
CIS Level 1 hardening has been validated with Lynis (score: 81). The full Lynis report is available on the VM Images release page.

Uninstalling / Cleaning Up

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

sudo ./watchdog-installer.sh 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:password@proxy.example.com: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:password@proxy.example.com: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