Reference: Configuration

This page documents runtime configuration keys and persistence behavior.

Configuration Source

Primary module: src/url_monitor/config.py

Runtime singleton: config = Config()

Persistence file: data/settings.json

Persistence Contract

• get_user_settings() exports mutable runtime keys.
• save_user_settings(settings) validates + applies + persists.
• load_user_settings() loads persisted values on startup.

Core Runtime Keys

Key	Type	Default	Notes
PROXY_HOST	string	127.0.0.1	System proxy host and mitmproxy listen host.
PROXY_PORT	int	8080	Validated to range 1..65535.
PROXY_AUTO_START	bool	false	May trigger monitor auto-start flow.
MONITOR_AUTO_START	bool	false	Starts monitoring after startup checks.
UBLOCK_ENABLED	bool	true	Master uBlock engine toggle.
PHISHTANK_ENABLED	bool	true	Master phishing feed toggle.
PHISHTANK_DOMAIN_MATCH_ENABLED	bool	false	URL-only by default to reduce false positives.
SUSPICIOUS_JS_LEVEL	string	balanced	One of monitor, balanced, strict.
UI_UPDATE_INTERVAL_MS	int	1000	Validated to 100..10000 in config, clamped in panels.
MAX_HISTORY_RECORDS	int	1000	Runtime history cap.
MAX_ALERT_DISPLAY	int	0	<=0 means unlimited display in current session.
DEFAULT_LANGUAGE	string	en	Locale-normalized.
UI_THEME	string	light	Supported: light, soft, contrast.
START_MINIMIZED_TO_TRAY	bool	false	Startup UX behavior.
LOG_LEVEL	string	WARNING	Allowed: DEBUG/INFO/WARNING/ERROR.
LOG_TO_FILE	bool	true	File logging toggle.

Notification Keys

Key	Type	Default	Notes
desktop_notifications_enabled	bool	true	Global notification gate.
NOTIFICATION_BACKEND	string	tray	tray or native.
NOTIFICATION_COOLDOWN_SECONDS	int	20	Dedupe interval for repeated alerts.
phishing_alerts_enabled	bool	true	Per-type toggle.
secret_alerts_enabled	bool	true	Per-type toggle.
malware_alerts_enabled	bool	true	Per-type toggle.
AD_ALERTS_ENABLED	bool	false	Optional ad notifications.
TRACKER_ALERTS_ENABLED	bool	false	Optional tracker notifications.
NOTIF_DURATION	string	5 seconds	Mapped to timeout in ms.
NOTIF_SOUND_ENABLED	bool	true	Plays local beep on notification.

Filtering and Feed Keys

Key	Type	Notes
UBLOCK_FILTER_URLS	list[str]	Source list bundle for ad/tracker filtering.
PHISHTANK_URL	string	JSON feed source.
PHISHINGDATABASE_URL	string	Text feed source.
UBLOCK_AUTO_UPDATE	bool	Auto-update toggle for uBlock bundle.
UBLOCK_UPDATE_FREQUENCY	string	Daily/Weekly/Monthly/Manual.
PHISHTANK_AUTO_UPDATE	bool	Auto-update toggle for phishing feeds.
FILTER_UPDATE_INTERVAL_DAYS	int	Minimum update interval guard.

Stability and False-Positive Controls

Key	Purpose
DEFAULT_WHITELIST	Fully bypass checks for trusted/noisy domains.
PHISHTANK_FALSE_POSITIVE_DOMAINS	Prevent phishing label on known noisy infra.
SILENT_DOMAINS	Check/block but suppress UI alert noise.
SECRET_DETECTION_WHITELIST	Skip secret scanning on selected domains.
SKIP_JS_ANALYSIS_DOMAINS	Skip deep JS analysis for trusted domains.
SKIP_JS_ANALYSIS_URL_KEYWORDS	Keyword-based skip list for JS analysis.

Security Detection Keys

Key	Purpose
TLSH_MIN_SIZE	Minimum payload size for TLSH hashing.
SECRET_PATTERNS	Regex map for secret detection types.
CRITICAL_SECRET_TYPES	Secret types considered high severity.
CRITICAL_SECRETS_ONLY_ALERTS	Focus alerting on critical secret types.

Advanced Network Keys

Key	Purpose
PROXY_TRANSPARENT_MODE	Proxy behavior mode flag.
UPSTREAM_PROXY_ENABLED	Enable upstream proxy chaining.
UPSTREAM_PROXY_HOST	Upstream host.
UPSTREAM_PROXY_PORT	Upstream port (validated).
HTTPS_ONLY_MODE	Strict HTTPS behavior flag.

Operational Notes

• Invalid values are ignored and defaults retained.
• NOTIFICATION_BACKEND is normalized to tray when unknown.
• Locale values pass through canonicalization/fallback chain.