/detections

name: "Liongard Detections"
description: >
  Liongard's change and anomaly detection layer: detections generated by
  inspection-to-inspection comparison, detection types/severities/status
  lifecycle, configurable alert rules and notification channels, custom
  metrics with JMESPath expressions and threshold evaluation, and the
  platform timeline audit trail.
when_to_use: >-
  When investigating configuration changes, tuning alert rules, defining or evaluating
  compliance metrics, or pulling audit-trail events from a Liongard instance.
  Use when: liongard detection, liongard change, liongard alert, liongard metric, liongard
  timeline, change monitoring liongard, liongard anomaly, liongard compliance, or liongard audit.

Liongard Change Detection & Alerts

Overview

Detections are Liongard's automated change and anomaly detection system. Every time an inspection runs, Liongard compares the new data with previous inspection results and identifies changes. Those changes become detections that MSPs monitor, investigate, and act upon. Around detections sit **alerts** (configurable rules that turn detections into notifications), **metrics** (custom measurements evaluated across systems for compliance reporting), and the **timeline** (a platform-wide audit trail of inspections, detections, and user actions).

Anti-triggers

• **Security detections and EDR alerts** — a Liongard detection is a

configuration *change*, not a threat. Malicious activity is `huntress-signals`, `huntress-incidents`, `sentinelone-alerts`, or `rocketcyber-incidents`.

• **RMM threshold and availability alerts** — disk-full, offline, and

service-down alerts come from the RMM: `atera-alerts`, `superops-alerts`, `ncentral-monitoring-tasks`, `ninjaone-alerts`, or `datto-rmm-alerts`.

• **Compliance frameworks** — Liongard metrics are custom JMESPath

measurements over inspection data; mapping evidence to CIS, NIST, or SOC 2 controls is `scalepad-controlmap`.

• **Why the underlying data changed at all** — the inspection that

produced the comparison is `liongard-inspections`.

Key Concepts

Detections

A detection records a specific change identified between inspection runs. Examples:

• A new user account was created in Active Directory
• A firewall rule was modified on a SonicWall
• An MFA policy was disabled in Microsoft 365
• A backup job failed on a Datto appliance
• A new device joined the network on Meraki
• A certificate is expiring within 30 days

Detection Types

| Type | Description | Example | |------|-------------|---------| | `Added` | New item discovered | New user account created | | `Removed` | Item no longer present | Device removed from network | | `Changed` | Existing item modified | Firewall rule updated | | `Threshold` | Value crossed a defined threshold | Disk usage exceeded 90% |

Detection Severity Levels

| Severity | Description | Typical Use | |----------|-------------|-------------| | `Critical` | Immediate action required | Security policy disabled, admin account compromised | | `High` | Urgent attention needed | MFA disabled, backup failure | | `Medium` | Review within business hours | Configuration change, new admin user | | `Low` | Informational but notable | New standard user, minor setting change | | `Info` | Routine change logged | Regular updates, expected modifications |

Detection Status Transitions

New ───────────────────> Dismissed
  |                          |
  v                          v
Acknowledged ──────> Resolved

• **New** - Freshly detected, awaiting review
• **Acknowledged** - Reviewed by an MSP technician
• **Resolved** - Change has been addressed or accepted
• **Dismissed** - Change is expected or irrelevant

Each detection carries a `Details` object holding the `Before` and `After` values of whatever changed — that is the payload worth reading when investigating.

See [references/fields.md](references/fields.md) for the complete detection field reference, the full timeline event-type catalog, and the entity relationship map.

Alerts

Alert rules define which detections should trigger notifications. A rule specifies which environments to monitor, what detection types and severities to watch for, what conditions must be met, and what notification channels to use (email, webhook, or integration target). Rules can be enabled/disabled without deletion, and each firing produces a *triggered alert* record linked back to the originating detection.

Metrics

Metrics are custom measurements tracked across systems and environments. A metric binds an `InspectorID`, a JMESPath `Expression` evaluated against a system's detail data (e.g. `Data.PasswordPolicy.MinimumLength`), and a `Threshold` plus comparison `Operator`. Evaluation returns a `Value` and a `Compliant` boolean per system, which is what drives compliance reporting and trend analysis.

Timeline

The timeline is a comprehensive audit trail of all events within Liongard — inspection runs, detection triggers, user actions, configuration changes, and agent connectivity events.

API Patterns

The full endpoint catalog with request/response bodies lives in [references/api.md](references/api.md). The non-obvious parts:

• **Detections and timeline are queried by POST, not GET.** `POST /api/v1/detections` and `POST /api/v2/timelines-query` take a JSON filter body. Only the v1 timeline (`GET /api/v1/timeline`) is a plain GET with query params.
• **Filter syntax is `conditions: [{path, op, value}]`** with `orderBy: [{path, direction}]`. Operators include `eq`, `in`, and `gte`. Timestamps are ISO-8601 UTC strings.
• **`Pagination` is PascalCase and nested** — `{"Pagination": {"Page": 1, "PageSize": 100}}`. Response envelopes are PascalCase too: `Data`, `TotalRows`, `HasMoreRows`, `CurrentPage`, `TotalPages`, `PageSize`. Page through until `HasMoreRows` is false.
• **v2 adds a `fields` array** for field selection on detections — use it to cut response size wh