Documentation › Anomaly Detection

Anomaly Detection

BunkerM includes a smart anomaly detection system that continuously analyzes your MQTT traffic patterns and flags unusual behavior. Instead of combing through raw logs, you get a curated list of meaningful anomalies with context about what was detected and when.

What Smart Anomaly Detection Is

Smart anomaly detection observes your broker's normal traffic patterns over time and identifies deviations that may indicate a problem. It learns what "normal" looks like for your specific setup - your typical connection counts, message rates, topic activity patterns, and client behavior - and raises alerts when something does not fit.

This is different from simple threshold alerts. The system looks at patterns in context, not just individual readings. A sudden spike in messages from a single client is only flagged as unusual if it deviates significantly from that client's own historical pattern.

No data leaves your BunkerM container. All analysis runs locally.

What Anomalies Are Detected

Connection anomalies

  • Unusual number of simultaneous connections
  • Rapid connect-disconnect cycles from a single client (potential reconnect loop)
  • Connections from new or unrecognized IP addresses
  • Authentication failures above the normal baseline

Message rate anomalies

  • Sudden spikes in publish rate from a client or topic
  • Unusual drops in message rate from clients that normally publish regularly
  • Topics receiving messages far outside their normal frequency

Topic activity anomalies

  • Messages on topics that have been inactive for a long time
  • New topics appearing that have not been seen before
  • Unusually large payloads on topics that normally carry small messages

Broker health anomalies

  • Subscription count changes that do not match expected patterns
  • Retained message accumulation beyond normal levels

Viewing Detected Anomalies

Navigate to Tools > Anomalies in the sidebar. Each entry shows:

  • Severity - how significant the anomaly is (Critical, High, Medium, Low)
  • Type - the category of anomaly detected
  • Description - a plain-language explanation of what was detected
  • Client / Topic - the specific client or topic involved, if applicable
  • Detected At - timestamp when the anomaly was identified
  • Status - whether the anomaly is active, acknowledged, or dismissed

The list is sorted by severity and recency by default. You can filter by severity, type, or status.

Severity Levels

  • Critical - requires immediate attention. Indicates a possible security incident or serious system failure.
  • High - significant deviation from normal behavior. Should be investigated soon.
  • Medium - noticeable but potentially benign. Worth reviewing when convenient.
  • Low - minor deviation. Informational. May be expected given recent changes to your setup.

Acknowledging and Dismissing

Acknowledge - mark an anomaly as seen and under review. The anomaly stays in the list but is marked as acknowledged. Use this when you have seen the alert and are investigating.

Dismiss - remove an anomaly from the active list. Use this when you have investigated and determined the anomaly is a false positive or an expected change. Dismissed anomalies are archived, not deleted, and can be reviewed from the history view.

How Detection Works

The system collects broker metrics and client activity data continuously. It builds a baseline model of your environment's normal behavior over time. When new observations fall significantly outside established patterns, an anomaly is raised.

The detection becomes more accurate as it collects more data about your specific setup. In the first days of operation, you may see some false positives as the baseline is still being established. Dismissing these helps the system learn what is normal for your environment.

Practical Examples

  • Compromised device - a sensor that normally publishes once a minute starts publishing thousands of times per second. The message rate spike is flagged so you can identify and disable the client.
  • Traffic spike investigation - your broker's message rate doubles. The anomaly alert helps you catch it early before delivery delays affect clients.
  • Unexpected topic activity - a topic that has been silent for six months suddenly receives messages. Could be a device coming back online, a misconfiguration, or unauthorized access.
  • Auth failure monitoring - multiple failed authentication attempts from an IP you do not recognize. The pattern is flagged before it becomes a brute-force concern.

Anomalies vs Broker Logs

Broker logs are raw events from Mosquitto - comprehensive but require you to know what you are looking for. Anomalies are intelligent alerts generated by analyzing patterns across many log events. Use broker logs for detailed forensic investigation and anomalies for proactive monitoring and early warning.

← Connected Clients Agents →