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 eti).
  9. Optional config files (if needed for custom setups):
    • eti.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).

Watchdog Install

  1. Download Binaries: Obtain the binaries for your operating system from the releases.

  2. Extract and Configure: Extract the downloaded zip file. Add your provided BMKEY and AUTHCODE to the configuration file.

  3. Run the Server: Execute the binary to start Watchdog.

./Watchdog --config-path /path/to/watchdog.conf
  1. To generate the SSL certificate run the following command. You can change your cert config in the ssl_config.ini file.
./Watchdog --config-path /path/to/watchdog.conf --generate-ssl

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.

Kafka 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) and eti (for data storage and searching).

The installer supports: 1. Interactive prompts for Docker registry authentication (optional). 2. Enabling/disabling Kafka mode and/or eti mode. 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: 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 modes.
    3. If Kafka mode is enabled, prompt for a KAFKA_EXTERNAL_IP.
    4. If eti mode is enabled, prompt for host, port, passwords, etc.
    5. Create /opt/watchdog, /opt/watchdog/kafka_data, and /opt/watchdog/eti_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 eti was enabled:
    • An eti container (and possibly kibana) should be running (depending on your compose files).

Note: - If you are running the installation in Kafka mode, do not delete or remove the volumes. Doing so may result in the loss of Kafka and MongoDB data, as these services rely on persistent storage to retain information.

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/eti is enabled, you’ll see lines like:

KAFKA_EXTERNAL_IP=your.machine.ip
ELASTIC_HOST=eti
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.

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 : data.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