Concepts¶
API Observer connects traffic captured by ModSecurity to searchable logs and rule findings. These concepts explain what each component stores and why a connected node, a log record, and a finding can appear at different times.
Nodes¶
A node is a registered Collector, identified by a persistent ID that Collector stores in its data directory. Collector sends heartbeats containing that ID and an address that Observer can use to query its logs. Observer records the node in its configuration; you can give it a readable name on the Nodes page.
Heartbeats are sent every 15 seconds. The dashboard marks a node connected when Observer has received one within the last 45 seconds. A saved node can remain listed as disconnected after its Collector stops. Explorer and Analysis query connected nodes, so a saved node alone does not make its logs available.
Two network directions matter: Collector must reach Observer's ingest service, and Observer must reach the Collector's query service. The address Collector advertises must be reachable from the Observer host.
Findings¶
A rule describes conditions to check against an event and the finding to produce when they match. Conditions can inspect request properties such as method, path, query, headers, cookies, and body. A rule set is a YAML file containing named rules. Observer loads its configured rule set at startup; an empty set produces no rule findings.
A finding contains a title, message, severity, tags, processing time, and metadata linking it to the matching request or response. For incoming events, Observer's workers evaluate rules and append findings to the configured findings JSONL file. Explorer reads that file to attach existing findings to historical log records with matching request IDs.
ModSecurity's own audit record is the source of traffic data. An API Observer finding is a separate result produced by API Observer's rule engine; it does not change the original audit record or block the HTTP request.
Explorer vs Analysis¶
| View | Reads | Rules used | Result |
|---|---|---|---|
| Log Explorer | Historical records from connected Collectors | Findings already produced by Observer's configured rules | Searchable requests and responses, enriched with saved findings |
| Analysis | The same historical records | Rule set entered for that analysis run | Searchable requests and responses with findings calculated for that run |
Both views let you search across connected nodes and narrow the time range. Their default range is the last 24 hours. Analysis is useful for trying a new rule against traffic already captured; its findings are shown with that run's results and are not appended to Observer's findings log. To apply a rule to future incoming events, add it to Observer's configured rule file and restart Observer.
Where data lives¶
| Data | Location |
|---|---|
| Original traffic records | ModSecurity audit file on each Collector host |
| Collector identity | Collector data directory |
| Node names and addresses | Observer configuration file |
| Findings from incoming events | Observer findings JSONL file |
Explorer and Analysis query the current audit file configured for each Collector. Rotated archive files are outside those searches. Plan audit log retention around the history you need to investigate. For deployment steps and network settings, see Get Started.