Config Reference

Config Push Protocol

Users can customize the information sent from the controller to get different settings based on their department. The information should include fields like guid, hostname, version, ip_addresses, mac_address, os, and label.

Label Matching: This is the highest priority. If the controller's label field matches the label specified in the mapping.conf file, the department associated with that label is selected immediately.
Hostname Matching: If no label match is found, the system checks if the controller's hostname matches the pattern defined for a department. A wildcard (*) can be used in the hostname pattern to allow for partial matching.
IP Address Matching: If neither label nor hostname matches, the IP address is compared. The controller's IP addresses are checked to see if any of them fall within the subnet ranges specified for a department.
MAC Address Matching: If the IP address does not match, the system will try to match the controller's MAC address using a pattern that can include wildcards.
Operating System (OS) Matching: As the last option, the controller's OS is compared against the OS specified for the department. The system performs a partial match if a wildcard (*) is used, ensuring that different versions of the same OS can be grouped together.

The matching process in NOT case-sensitive.

The process follows a first-match-wins strategy. As soon as a match is found, the department associated with that match is selected, and the remaining conditions are ignored.

Example Workflow of Matching

Here’s a simple example to illustrate how the matching process works:

Controller Information:
Label: "hr"
Hostname: "newyork-hr1"
IP Addresses: ["123.11.219.5"]
MAC Address: "23:ab:123:45:67:89"
OS: "linux"
Matching Process:
Label Matching: The system checks the label "hr". It finds that the HR department has a matching label, so it immediately selects the HR department.
Hostname, IP, MAC, and OS: Since the label matched, the system does not proceed to check the other conditions (hostname, IP, MAC, or OS).

The HR department is selected based on the label match, even though other conditions might also match.

mappings.conf

This file contains mappings for different departments, specifying conditions like the hostname pattern, label, operating system, IP address range, and MAC address pattern.

# mappings.conf
# File to define groups for the browsermon controllers
# based on any criteria (guid, hostname, mac, version, ip, os, label)

[Staff]
host=austin-*
label=staff
os=windows

[HR]
host=newyork-*
os=linux
label=hr
address=123.11.219.0/24
mac=23:ab:123:*

[Accounts]
host=sunnyvale-*
os=linux

[CEO]
host=chicago-ceo*
label=ceo
os=windows

watchdog.conf

Watchdog relies on the watchdog.conf configuration file for essential settings. Here are the key configuration parameters:

[default]
mode=local
bmkey= 
authcode=
blacklist=None
logdir=logs
loglevel=INFO
maxBytes=5242880
backupCount=5 Set the rotating copies count of the logs (default: 5)
limit=True Enable the rate limiting.
rate=100/m Give the rate at which API is accessible.
allowedhosts=['*']
[eti]
eti_index_ttl=90
[ucs]
ucs_updates=false
ucs_host=dev1.eunomatix.com
ucs_port=8000
[proxy]
proxy_mode=false
http_proxy=http://10.10.10.10:1234
https_proxy=https://10.10.10.10:1234
[GunicornConfig]
watchdog_port=8900
certfile=./cert/cacert.crt
keyfile=./cert/private.key
sslconfig=/etc/watchdog/ssl-config.ini

Configuration Explanation

mode: Set the mode to either ‘local’ or ‘cloud’ based on your deployment.
bmkey: Provide the Base64-encoded license key.
authcode: Add the Base64-encoded authorization code.
blacklist: Specify the blacklist configuration.
logdir: Defines the path to the log dir
loglevel: Set the desired log level. Set it to DEBUG if the program doesn’t work the intended way.
maxbytes: Set the rotating size of logs in Bytes (default: 5242880)
backupCount: Set the rotating copies count of the logs (default: 5)
limit: Enable the rate limiting.
rate: Give the rate at which API is accessible.
allowedhosts: List of hosts that can access default to all if leave empty
eti_index_ttl: Time-to-live (TTL) in days for Elasticsearch threat index before deletion (default: 90)
ucs_updates: Enable or disable daily UCS (URL Classification Service) updates. Should be set to false on airgapped systems. When enabled, the watchdog service will perform a daily sync with the UCS API. (default: false)
ucs_host: Hostname or IP where the UCS API is running
ucs_port: Port number the UCS API listens on
proxy_mode: Enable or disable proxy mode.
http_proxy: URL for http proxy server
https_proxy: URL for https proxy server
watchdog_port: Port number where watchdog runs
certfile: Path to the SSL Certificate File
keyfile: Path to the SSL Key File

browsermon-watchdog.conf

This file defines the settings for each department, including the browser type, mode, schedule window, log directory, log mode, rotation interval, Kafka mode, elastic_search_mode, cache_ttl and cache_max_size.

[HR]
browser=firefox
mode=scheduled
schedule_window=1m
logdir=/opt/browsermon/logs
logmode=json
rotation=1h
kafka_mode=false
eti_mode=false
ucs_mode=false
cache_ttl=30d
cache_max_size=1000

[Accounts]
browser=chrome
mode=scheduled
schedule_window=1m
logdir=/opt/browsermon/logs
logmode=csv
rotation=1h
kafka_mode=true
eti_mode=false
ucs_mode=false
cache_ttl=30d
cache_max_size=1000

[CEO]
browser=firefox
mode=scheduled
schedule_window=1m
logdir=C:\\browsermon\\history
logmode=csv
rotation=1h
kafka_mode=true
eti_mode=false
ucs_mode=false
cache_ttl=30d
cache_max_size=1000

browsermon.conf

[server]
watchdog_ip=0.0.0.0
watchdog_port=8900
[installation]
install_dir=C:\\browsermon
[elastic]
host=localhost
port=9200
username=Browsermon
password=BrowsermonElasticUser
eti_index=threat_index
ucs_index=eunomatix_ucs
[default]
browser=firefox
mode=scheduled
schedule_window=1m
logdir=C:\\browsermon\\history
logmode=csv
rotation=1h
backup_count=0
log_level=DEBUG
kafka_mode=true
kafka_server_url=localhost:9092
eti_mode=false
ucs_mode=false
cache_ttl=30d
cache_max_size=1000
kafka_server_url=localhost:9092
machine_label=DefaultLabel

Configuration Explanation

watchdog_ip: IP address of the Watchdog server.
watchdog_port: Port number where Watchdog service listens for connections.
install_dir: Directory where you want to install browsermon into
host: eti/ucs server hostname or IP address
port: Port number on which eti/ucs is listening
username: Username for eti/ucs authentication
password: Password for eti/ucs authentication
eti_index: Name of the eti index where threat intel data will be fetched from
ucs_index: Name of the ucs index where classification data will be fetched from
browser: Specifies the browser(s) to monitor, such as Firefox, Chrome, or Edge.
mode: Determines whether BrowserMon operates in scheduled mode (default) or real-time mode.
schedule_window: Sets the interval between each browser data collection iteration.
logdir: Defines the directory where browser history log files are stored.
logmode: Specifies the format of the history log files (CSV or JSON).
rotation: Sets the interval for rotating history log files.
backup_count: Defines the number of backup copies of history log files to retain.
log_level: Specifies the logging level (INFO or DEBUG).
kafka_mode: Enables (true) or disables (false) Kafka integration for centralized logging.
kafka_server_url: URL of the bootstrap Kafka server.
eti_mode: Enables (true) or disables (false) EUNOMATIX Threat Intel service.
ucs_mode: Enables (true) or disables (false) EUNOMATIX URL Classification Service.
cache_ttl: Amount of time for which url will remain in cache
cache_max_size: Upper bound the cache can grow to e.g if set to 100 that means 100 urls will be cached
machine_label: The label you will sent as a payload to the watchdog server (This can be set by the controller in the browsermon-local.conf and browsermon.conf file).

*All these config variables can be changed in browsermon-local.conf file except watchdog_ip and watchdog_port.

API Reference

Check License: The check-license API endpoint is designed to verify the validity of controllers' licenses. Also return the controller config.
- Endpoint: POST /api/check-license/
Parameters:
- guid (UUID v1) - Required. Controller Guid.
- hostname (String) - Required System Hostname
- version (String) - Required Controller Version
- ip_addresses (List) - Required List of Controller IPs
- mac_address (String) - Required Mac Address of the Controller
- os (String) - Required OS of the Controller
- label (String) - Required Label of the Machine
- logdir (String) - Required Logdir of Controller
Get Active GUIDs: The get-licenses API endpoint retrieves the list of active GUIDs.
- Endpoint: GET /api/get-licenses/
Description:: Display the list of active licensed controllers.

Order of Precedence

BrowserMon 3.0 supports different types of configurations to tailor settings based on organizational needs (browsermon-watchdog.conf and browsermon-local.conf files can be configured at run time and will be updated after every 30 min) :

Default Configuration (browsermon.conf): Provides baseline settings for all deployments.
Central Watchdog Configuration (browsermon-watchdog.conf): Overrides default configurations for centralized management this configuration is recieved from the watchdog server and written in the browsermon-watchdog.conf file in your installation directory.
Local Configuration (browsermon-local.conf): Allows local administrators to customize settings for specific requirements, overriding both default and watchdog configurations.