Guide¶

Use this guide after Get Started has connected at least one API Collector. It covers the three main workflows in the dashboard: investigate captured traffic in Log Explorer, try detections against historical traffic in Analysis, and maintain the rule set used for incoming events.

Log Explorer¶

Open Explorer from the dashboard sidebar. Explorer reads historical ModSecurity audit records from connected Collector nodes. Observer asks each Collector for records in the selected time range, merges the streams into one time-ordered view, and attaches findings already saved by Observer. The original audit records stay on the Collector hosts.

Search captured traffic¶

Open Advanced Settings and set Start Date and End Date. The initial range is the last 24 hours.
Enter a query in the search field, or leave it empty to see all records in the range.
Select Search. Results from connected nodes appear together. The Node column shows which Collector supplied each record.
Select a row to inspect its request or response details and any attached findings.

A ModSecurity transaction appears as separate request and response rows with the same request ID. Request rows contain method, URL, headers, and body. Response rows contain status, headers, and body. A rule finding appears on the matching row when it was produced during incoming-event processing and is still present in Observer's findings log.

Explorer queries only connected nodes and the current audit file configured for each Collector. If a node is disconnected, its records cannot be fetched until it reconnects. Rotated archive files are not included.

Filter with the query language¶

The search field accepts comparisons joined by AND, OR, and NOT; parentheses group expressions. Put string values in double quotes and use unquoted numbers for numeric fields. An empty query matches all records in the selected time range.

Example	Use
`type = "request" AND method = "POST"`	Find POST request rows
`type = "response" AND status >= 400`	Find error response rows
`node = "payments" AND findings > 0`	Find saved findings on a named node
`path = "/users/{id}"`	Match request paths with one variable segment
`(status = 404 OR status >= 500) AND findings > 0`	Investigate error responses with findings

Supported fields are type, node, method, path, status, timestamp, and findings. node uses the readable name shown on the Nodes page. method and path apply to request rows; status applies to response rows. findings is the number of findings attached to that row. For timestamp, use a quoted RFC 3339 value such as "2026-10-29T12:00:00Z".

Query comparisons differ from detection rules. For example, path = "/users/{id}" in a search matches one path segment in place of {id}, while string_equal in a YAML rule compares the literal path. Use the date controls to restrict the time range before applying a query.

Investigate a finding¶

A useful starting query is findings > 0. Expand a result to read the finding's title, severity, message, and tags alongside the traffic that produced it. Then narrow by node, method, path, or time range to inspect related activity. If a record has no finding, it can still appear in Explorer; findings are not required for a log to be searchable.

Analysis¶

Open Analysis to evaluate a rule set against traffic already stored in Collector audit files. This lets you test a detection before adding it to Observer's active rule file.

Open Advanced Settings and choose the time range to inspect. The initial range is the last 24 hours.
Select the Rules tab. Replace the starter rules: text with a complete YAML rule set, such as the example in Write a rule set. You can paste YAML from a file; the current page does not load a file directly.
Return to Logs. Enter a query if you want to filter the results, or leave it empty to inspect all records in the range.
Select Search. Analysis reads records from connected Collectors, evaluates the entered rules, and shows matching findings on the result rows. Expand a row to inspect them.

The query filters displayed rows after rules are evaluated. For example, findings > 0 shows rows where the Analysis rule set produced at least one finding. Analysis findings belong to that run; they are not appended to Observer's findings JSONL file. Running the same search with different YAML lets you compare detection behavior against the same traffic.

To use a tested rule for future incoming events, add it to the YAML file named by rules in Observer's configuration and restart Observer. Searches in Explorer then attach findings saved from that active rule set. Editing the Analysis rule set does not change Observer's active rules.

Rules¶

A rule set is a YAML document with a top-level rules map. Each key is a unique rule name. A rule defines its match conditions and the finding produced on a match. Observer loads the configured file at startup; the Rules page lists the currently loaded rules and their details.

Write a rule set¶

This example detects requests to an admin path and SQL injection patterns in a query string. It can be pasted into Analysis or saved as Observer's configured rule file:

rules:
  admin-path:
    disabled: false
    scope:
      - request
    description: Flag requests to the admin endpoint.
    match:
      mode: all
      conditions:
        - target: path
          operator: string_equal
          value: /admin
    finding:
      title: Admin endpoint requested
      message: A client requested the admin endpoint.
      severity: medium
      tags:
        - admin
        - review

  query-sqli:
    disabled: false
    scope:
      - request
    description: Detect possible SQL injection in query parameters.
    match:
      mode: any
      conditions:
        - target: query
          operator: detect_sqli
    finding:
      title: Possible SQL injection
      message: A query parameter matched a SQL injection pattern.
      severity: high
      tags:
        - attack-sqli

Use disabled: true to leave a rule in the file without evaluating it. match.mode: all requires every condition to match; any requires at least one. A condition names a target and operator, and often a value. For a specific header, query parameter, or cookie, add key. The rule engine supports targets including method, path, query, header, body, body_length, cookie, and cookie_name. Common operators include string_equal, regex, detect_sqli, and numeric comparisons for suitable targets.

Choose a finding title and message that help an investigator understand why the rule matched. Severity and tags are labels recorded with the finding; they do not block the request. Finding metadata links the result to the matching event's request ID, source Collector, and timestamp. Request and response events from the same ModSecurity transaction share a request ID.

Current request and response behavior

The YAML parser accepts request and response values in scope, but the current evaluator does not use scope to filter events. Its match conditions read request fields, so response-only events do not satisfy them. Test rules against representative traffic in Analysis before relying on them.

Review and import rules¶

The dashboard Rules page shows the active rule names, descriptions, scopes, enabled state, match conditions, and finding details. The Import Rules page can translate pasted Core Rule Set (CRS) SecRule directives into YAML. Review the generated YAML and any translation warnings before copying it into Analysis or the configured rule file. Translation does not save or activate rules automatically.

For the difference between saved and run-specific findings, see Concepts. For the production configuration path and deployment steps, see Get Started.