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 when you only need a few columns.
- **Alerts and metrics are conventional REST** (`GET`/`POST`/`PUT`/`DELETE` on `/api/v1/alerts` and `/api/v1/metrics`), but metric *evaluation* is v2-only: `POST /api/v2/metrics/evaluate` (one metric across all applicable systems) and `POST /api/v2/metrics/evaluate-systems` (all metrics for a given `SystemIDs` list).
- **Alert rule `Conditions` are keyed by field name with array values** (`{"Severity": ["Critical"], "Type": ["Changed", "Removed"]}`) — a different shape from the `conditions` array used by detection queries. Don't mix them up.

## Common Workflows

### Monitoring for Changes

1. **Query recent detections** - Filter for New status and Critical/High severity
2. **Review changes** - Examine before/after details for each detection
3. **Investigate context** - Check timeline for related events
4. **Take action** - Acknowledge, resolve, or escalate as needed
5. **Document decisions** - Update detection status with resolution notes

See [references/examples.md](references/examples.md) for a worked detection-fetch-and-categorize implementation.

### Setting Up Alert Rules

1. **Identify critical changes** - Determine what changes need immediate attention
2. **Create alert rules** - Configure conditions (severity, inspector, type)
3. **Set notification channels** - Email, webhook, or integration targets
4. **Test alerts** - Verify notifications fire correctly
5. **Review and tune** - Adjust thresholds to reduce noise

### Compliance Auditing

1. **Define compliance metrics** - Create metrics for each compliance requirement
2. **Evaluate across environments** - Run metric evaluations
3. **Identify non-compliant systems** - Filter for Compliant=false
4. **Generate reports** - Export metric results for audit documentation
5. **Track remediation** - Re-evaluate after fixes are applied
6. **Maintain audit trail** - Use timeline for evidence of monitoring

## Gotchas

- **Rate limit is 300 requests/minute.** A 429 means back off and retry; broad detection sweeps across many environments hit this quickly.
- **Metric expressions are JMESPath against system detail data.** A malformed expression returns 422, not an empty result — validate the path against a real system's dataprint first.
- **A metric evaluates to "no data" rather than non-compliant when the system has never been inspected.** Run an inspection before treating an empty evaluation as a compliance failure.
- **Threshold type must match the data type** of the expression result. Comparing a boolean expression against a numeric threshold silently misreports compliance.

See [references/errors.md](references/errors.md) for the complete API and metric-evaluation error tables.

## Best Practices

### Detection Management

1. **Review critical detections daily** - Don't let high-severity items pile up
2. **Acknowledge promptly** - Show clients you're monitoring their environment
3. **Document resolutions** - Record why changes were accepted or rejected
4. **Dismiss noise** - Mark expected changes to reduce alert fatigue
5. **Trend analysis** - Track detection volumes over time

### Alert Configuration

1. **Start conservative** - Begin with Critical/High only to avoid alert fatigue
2. **Use specific conditions** - Target specific inspectors and change types
3. **Set up escalation** - Different channels for different severities
4. **Review regularly** - Tune alert rules based on false positive rates
5. **Test notification channels** - Verify webhooks and emails work

### Metric Design

1. **Align with standards** - Map metrics to CIS benchmarks or client SLAs
2. **Set reasonable thresholds** - Avoid overly strict thresholds that create noise
3. **Evaluate periodically** - Run evaluations on a regular schedule
4. **Track trends** - Monitor compliance percentages over time

## Related Skills

- [Liongard Overview](../overview/SKILL.md) - Platform overview and terminology
- [Liongard Environments](../environments/SKILL.md) - Environment management
- [Liongard Inspections](../inspections/SKILL.md) - Inspectors and launchpoints
- [Liongard Systems](../systems/SKILL.md) - Systems and dataprints