Skip to content

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.

watchdog_config

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

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:8092
kafka_username=browsermon
kafka_password=browsermon
verify_certs=false
eti_mode=false
ucs_mode=false
extension_read_mode=false
extensions_scheduler=24h
artifact_read_mode=false
artifacts_scheduler=1h
cache_ttl=30d
cache_max_size=1000
kafka_server_url=localhost:8092
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.
  • kafka_username: SASL username used to authenticate to the Kafka broker. Must match the broker's JAAS configuration.
  • kafka_password: SASL password used to authenticate to the Kafka broker.
  • verify_certs: When true, BrowserMon verifies TLS server certificates (Watchdog, Kafka, Elasticsearch) against <install_dir>/ca.crt. When false, TLS is still used but the server cert chain is not verified. Default: false.
  • eti_mode: Enables (true) or disables (false) EUNOMATIX Threat Intel service.
  • ucs_mode: Enables (true) or disables (false) EUNOMATIX URL Classification Service.
  • extension_read_mode: Enables (true) or disables (false) Extension reading mode.
  • 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 sent as payload to the Watchdog server, which uses it to match the controller to a configuration profile. Read only from browsermon-local.conf (falls back to DefaultLabel if unset).
  • extensions_scheduler: Defines the time delay between every extensions data read iteration. e.g., 24h means BrowserMon will log extension data once every 24 hours. Like artifacts_scheduler, the interval is measured from the last successful read rather than from process start
  • artifact_read_mode: Enables (true) or disables (false) browser profile artifact collection: downloads, cookies, bookmarks and the derived user agent, for every profile of every user on the machine. Only changes are recorded (added, updated, removed), to browsermon_<browser>_<artifact>.json in logdir. Cookie values are never read or decrypted — only metadata such as host, name, path, flags and timestamps. Default: false.
  • artifacts_scheduler: Defines the time delay between every artifact collection iteration, e.g., 1h collects once an hour. Default: 1h. The interval is measured from the last successful collection rather than from process start, so a configuration change does not restart it. A machine that last collected 20 minutes ago on a 1h schedule collects again in 40 minutes, whether or not BrowserMon was restarted in between. On Windows, Chromium keeps its Cookies database open with an exclusive lock while the browser is running, and the operating system will not allow even a copy of it. Cookie collection for a running Chrome or Edge profile is therefore reported as unavailable for that pass rather than as empty, and succeeds on a later pass once the browser is closed. Downloads, bookmarks and user agent are unaffected. An unavailable section never produces removed events, so a locked database is never mistaken for the user clearing their cookies.

!!! warning "artifact_read_mode and artifacts_scheduler cannot be set from the Watchdog console" The console writes each department section in browsermon-watchdog.conf from a fixed field list that does not include these two keys, and it rewrites the whole section on save. Adding them to that file by hand works until the next time that department is saved from the web UI, at which point they are dropped without warning. Set them in browsermon.conf or browsermon-local.conf instead.

Only the [default]-stanza keys above can be overridden in browsermon-local.conf. The [server] keys (watchdog_ip, watchdog_port), the [installation] key (install_dir), and the [elastic] keys (host, port, username, password, eti_index, ucs_index) are read from browsermon.conf only and cannot be overridden through the local or watchdog files. machine_label is read directly from browsermon-local.conf; see Order of Precedence.

Order of Precedence

BrowserMon resolves its configuration from three files. When the same [default] setting appears in more than one file, the file with the higher precedence wins.

The three configuration files

  • browsermon.conf (baseline, lowest precedence): Holds the fall-back defaults for every setting, and its [default] stanza is marked "not recommended to modify". It is also the only source for the [server] keys (watchdog_ip, watchdog_port), the [installation] key (install_dir), and the [elastic] keys (host, port, username, password, eti_index, ucs_index).
  • browsermon-watchdog.conf (centralized push, middle precedence): Written into the installation directory by the Watchdog server when it matches the controller to a department (see Config Push Protocol). It overrides browsermon.conf for every [default] key, including verify_certs, kafka_username, and kafka_password.
  • browsermon-local.conf (local override, highest precedence): Where an administrator sets machine-specific values, and the recommended place to change any [default] setting. A key set here wins over both the watchdog and the baseline.

How a value is resolved

For each [default] key, BrowserMon checks browsermon-local.conf first, then browsermon-watchdog.conf, then browsermon.conf, and uses the first file that sets it. This applies to [default] keys only. The [server], [installation], and [elastic] keys are read from browsermon.conf once at startup and are never overridden.

The [default] values are re-read on the periodic configuration refresh, roughly every two hours. The [server], [installation], and [elastic] keys are fixed for the life of the process.

machine_label is a special case. It is read directly from browsermon-local.conf (falling back to DefaultLabel when unset) and is not part of the merge.

flowchart TB
    L["browsermon-local.conf<br/>(highest precedence)"]
    W["browsermon-watchdog.conf<br/>(middle precedence)"]
    D["browsermon.conf [default]<br/>(lowest precedence)"]
    E["Effective [default] configuration"]

    L -- "wins over" --> W
    W -- "wins over" --> D
    L --> E
    W --> E
    D --> E

    S["browsermon.conf [server] and [elastic]<br/>read once at startup, never overridden"]
    S --> E

Worked example

Given the following values spread across the three files, each key resolves as follows:

Key browsermon.conf browsermon-watchdog.conf browsermon-local.conf Effective value Why
log_level INFO DEBUG INFO INFO local wins over watchdog
kafka_mode false true (unset) true watchdog wins over baseline
cache_ttl 30d (unset) (unset) 30d only the baseline sets it
verify_certs false false true true local wins over the watchdog push
verify_certs false true (unset) true watchdog pushes it; wins over the baseline
watchdog_ip 0.0.0.0 (ignored) (ignored) 0.0.0.0 [server] key, browsermon.conf only
host (elastic) localhost (ignored) (ignored) localhost [elastic] key, browsermon.conf only