Guides

Watchdog Server User Guide

Overview

This guide explains how the watchdog server works in simple terms. It focuses on how the server checks a controller's license and provides the correct settings based on which department it belongs to. It also includes a new section on the key expiry feature and instructions on accessing the Grafana dashboard for data analytics.
Workflow
- Step 1: Sending Information from the Controller
The controller gathers details about itself, such as:
```
- Unique ID (GUID)
- Hostname (name of the computer)
- Version (software version)
- IP addresses
- MAC address (unique identifier for network interfaces)
- Operating system (OS)
- Label (a tag to identify the machine)
```
This information is sent to the /api/check-license/ endpoint on the watchdog server.
- Step 2: Checking the License
The server receives the information and checks if the license is valid. It ensures all required details are present and that the GUID is formatted correctly. If everything checks out and the GUID is not already in use, it registers the GUID. If the number of active devices exceeds the allowed limit, the request is denied.
- Step 3: Matching Information to Configuration Settings
The server reads the configuration and mapping files. It uses the details from the controller to find the best matching department based on criteria like label, IP address, hostname, MAC address, and operating system.
- Step 4: Sending Configuration to the Controller
Once the right department is identified, the corresponding settings from the browsermon-watchdog.conf file are selected. These settings are customized based on the controller's operating system (e.g., setting the log directory path differently for Windows and Linux).
- Step 5: Config is sent to Controller
The new config from browsermon-watchdog.conf is sent to the controller along with the valid license message.

Blacklisting Controllers
- Overview
  
  The blacklist feature lets administrators block specific controllers from receiving a license. Blacklisted controllers receive an HTTP 403 from /api/check-license/ and never get a configuration. The list is stored in /opt/watchdog/watchdog/watchdog-blacklist.conf and is loaded once at Watchdog startup — edits to the file require restarting Watchdog to take effect.
- Modes
  
  The mode is selected by blacklist= in watchdog.conf:
  - blacklist=guid — entries are controller GUIDs (UUIDv4). Use this when you want to block a specific endpoint regardless of network.
  - blacklist=ip — entries are IP addresses or CIDR blocks. Use this to block a subnet (for example, a guest network or a decommissioned office range).
  An invalid or missing value causes Watchdog to fail at startup. See Configuration Reference — watchdog-blacklist.conf for file format and examples.

Key Expiry Feature
- Overview
  
  The key expiry feature allows administrators to set an expiry date for the keys used by controllers. This ensures controllers must periodically check in with the watchdog server to renew their keys, enhancing security and control over access.
- Workflow
  - Step 1: Generating and Assigning Keys
  When a controller initially registers with the watchdog server or when a key expires, the server generates a new key with an associated expiry date. This key is then assigned to the controller.
  - Step 2: Checking Expiry
  Each time the controller communicates with the watchdog server, the server checks the expiry date of the assigned key.
  - Step 3: Logging Remaining Days
  Upon successful communication, the watchdog server logs the remaining days until the key expires. This information is logged for monitoring purposes.
  - Step 4: Key Expiry
  Once the expiry date is reached, the key is considered expired. The controller will no longer be able to receive configurations or updates from the watchdog server until a new key is generated and assigned.

Implementation Details
- Configuration
  
  Administrators can configure the expiry duration for keys in the watchdog.conf file.
- Logging
  
  The remaining days until key expiry are logged in the watchdog server's log files. Administrators can monitor these logs to ensure timely renewal of keys.
- Grafana Dashboard
  
  The watchdog server integrates with Grafana to provide a comprehensive interface for viewing history and data analytics.
- Accessing the Grafana Dashboard
  
  Users can view the Grafana dashboard by navigating to http://localhost:1514 in their web browser. This dashboard presents the history and analytics data collected by the watchdog server in an intuitive and visual format.
Benefits of the Grafana Dashboard
- Data Visualization: The Grafana dashboard offers various charts, graphs, and tables to help users visualize historical data and trends.
- Customizable Views: Users can customize the dashboard to display the most relevant metrics and information for their needs.
- Real-Time Monitoring: The dashboard allows for real-time monitoring of data, providing up-to-date insights into the performance and status of the watchdog server.
EUNOMATIX Threat Intel (ETI)

If during installation ETI mode was set, then watchdog will automatically create a threat collector to collect fresh threat intel from phishtank and urlhaus. This data is stored in centralized elastic database running on port 9200. Browsermon endpoints will be able to classify browsed urls into threat categories. The threat collector will collect data daily at midnight to keep the database freshly updated. Inside watchdog.conf you can set the value for eti_index_ttl which represent Time-to-live (TTL) in days for Elasticsearch threat index before deletion. 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
EUNOMATIX URL Classification Service (UCS)

Before Installation if you want to get daily classification updates, set ucs_updates to true in watchdog.conf. If during installation UCS mode was set, then watchdog will automatically create a ucs_client to collect daily classification updates from EUNOMATIX UCS API. Otherwise if ucs_updates is set to false inside watchdog.conf, then no API calls will be made and local snapshot will automatically get restored for UCS Classification. 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

For installation instructions see the Installation Guide. For configuration options see the Configuration Reference. For container troubleshooting see the Troubleshooting Guide.