/inspections

name: "Liongard Inspections"
description: >
  Liongard's inspection pipeline: inspector templates and their credential
  and agent requirements, launchpoint configuration that binds inspector +
  environment + agent + credentials + cron schedule, on-demand inspection
  runs and their status lifecycle, and the failure modes behind failed runs.
when_to_use: >-
  When configuring or scheduling what Liongard inspects, triggering a run by hand,
  migrating inspections between agents, or diagnosing an inspection that failed.
  Use when: liongard inspection, liongard inspector, launchpoint,
  inspection schedule, run inspection, liongard launchpoint, trigger inspection, inspection
  template, or liongard cron.

Liongard Inspections & Launchpoints

Overview

Inspections are the core mechanism by which Liongard captures IT documentation. The system has three parts: **inspectors** (templates defining what to inspect), **launchpoints** (configured instances tying an inspector to an environment, agent, credentials, and schedule), and **inspections** (individual execution runs that produce system data and potentially trigger detections). The relationship flows: **Inspector** (template) -> **Launchpoint** (configuration) -> **Inspection** (execution) -> **System** (discovered data).

Anti-triggers

• **"Run" meaning execute a script on an endpoint** —

`liongard_inspections_run` collects configuration data. It runs no operator-supplied code and changes nothing on the target. Script execution is `immybot-script-execution`, `ncentral-monitoring-tasks`, `superops-runbooks`, `atera-agents`, `syncro-assets`, `connectwise-automate-scripts`, or `datto-rmm-jobs`.

• **Scheduled maintenance on endpoints** — a launchpoint cron schedules

data collection, not patching or reboots; use `immybot-maintenance-sessions` or `ncentral-monitoring-tasks`.

• **What an inspection produced** — `liongard-systems` for the data,

`liongard-detections` for the changes it surfaced.

Key Concepts

Inspectors

Inspectors are pre-built templates provided by Liongard that define what technology platform to inspect and what data to collect. There are hundreds, spanning identity, email/collaboration, networking, virtualization, backup/DR, security, cloud, and core infrastructure.

Two inspector fields drive launchpoint design: `RequiresAgent` (whether a locally deployed agent must run it, or Liongard can reach the target directly — Active Directory needs an agent, Microsoft 365 does not) and `CredentialType` (what kind of authentication the target expects, e.g. Domain Admin vs App Registration). `DataPoints` — the list of what the inspector collects — is returned only on the single-inspector GET, not in the list response.

See [references/fields.md](references/fields.md) for the complete inspector and launchpoint field references, the full inspector category table, and the entity relationship map.

Launchpoints

A launchpoint brings together everything needed to run an inspection:

| Component | Purpose | |-----------|---------| | **Inspector** | Which template to use | | **Environment** | Which customer this is for | | **Agent** | Which agent runs the inspection | | **Credentials** | How to authenticate to the target | | **Schedule** | When to run inspections | | **Configuration** | Inspector-specific settings |

`InspectorID`, `EnvironmentID`, and `Name` are required; `AgentID` is required only when the inspector's `RequiresAgent` is true. Inspector-specific settings and credentials go in a nested `Configuration` object whose keys vary per inspector. `LastInspection` and `NextInspection` are read-only and are the fastest way to spot a launchpoint that has silently stopped running.

Inspection Status Values

| Status | Description | |--------|-------------| | `Queued` | Inspection is waiting to be picked up by agent | | `Running` | Inspection is currently executing | | `Completed` | Inspection finished successfully | | `Failed` | Inspection encountered an error | | `Timeout` | Inspection exceeded maximum runtime |

Scheduling

Cron Expression Format

Launchpoints use standard cron expressions for scheduling:

┌───────── minute (0-59)
│ ┌─────── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌─── month (1-12)
│ │ │ │ ┌─ day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Common Schedules

| Cron Expression | Description | |-----------------|-------------| | `0 2 * * *` | Daily at 2:00 AM | | `0 */6 * * *` | Every 6 hours | | `0 0 * * 0` | Weekly on Sunday at midnight | | `0 8 1 * *` | Monthly on the 1st at 8:00 AM | | `*/30 * * * *` | Every 30 minutes | | `0 2 * * 1-5` | Weekdays at 2:00 AM |

Scheduling Best Practices

1. **Stagger inspection times** - Avoid running all launchpoints at the same time 2. **Use off-peak hours** - Schedule during client off-hours (e.g., 2:00 AM) 3. **Match frequency to change rate** - Daily for AD/O365, weekly for static infrastructure 4. **Consider agent load** - Don't overload agents with concurrent inspections 5. **Account for time zones** - Schedule based on the client's local time

API Patterns

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

• **Inspectors are read-only** (`GET /api/v1/inspectors`) — they are Liongard-supplied templates, not something you create. Launchpoints are full CRUD at `/api/v1/launchpoints`.
• **On-demand runs are an action sub-resource**: `POST /api/v1/launchpoints/{id}/run` with no body. It returns immediately with an `InspectionID` and `Status: "Queued"` — it does not wait for the inspection to finish, so poll or check the timeline for the outcome.
• **Launchpoint filtering uses the camelCase `environmentId` query param** while response bodies are PascalCase (`Data`, `TotalRows`, `HasMoreRows`, `CurrentPage`, `TotalPages`, `PageSize`).
• **There is no batch-run endpoint** — trigger each launchpoint individually and stagger the ca