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

Detection Severity Levels

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 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. 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 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 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 - Platform overview and terminology
• Liongard Environments - Environment management
• Liongard Inspections - Inspectors and launchpoints
• Liongard Systems - Systems and dataprints