Concepts: journeys, Watches, Observations, Events and Evidence
The ScoutSentinel object model, every status and kind it uses, and how state flows from a probe run to an Event you can act on.
v1Updated
ScoutSentinel organises everything around the customer capability rather than around scripts. This page defines the objects you will meet in the app and the API, with the exact values each field can take.
Organisation, Environment and Subject
An Organisation is the tenant, policy and billing boundary. Every record you own carries its organisation id and every query is scoped to it. An Environment (for example Production, Staging) scopes Journeys, Watches, integrations and API reads; requests name one with X-Environment-Id or fall back to the default. A Subject is the thing being assured, identified by a name and a registrable domain or service identifier. Subjects group Journeys and discovered assets.
Journey
A Journey is a customer capability such as Get a quote, Buy online or Submit a claim, on one or more channels (web, api, voice, email). It is the primary object in the interface. A Journey has no status of its own: it is derived from the latest state of its active Watches, and outcome and behaviour stay separate.
| Status | Derived when |
|---|---|
critical |
Any active Watch has an open Event of severity critical |
degraded |
Any active Watch’s latest outcome is fail, or an open Event is high or medium |
unknown |
No active Watch has a passing outcome (all unknown, or nothing has run yet) |
changed |
Every active Watch passes and at least one reports behaviour changed |
healthy |
Every active Watch passes with stable behaviour |
paused |
The Journey has Watches but none is active |
Alongside status, a Journey carries behaviourState (stable, changed, unknown) aggregated from its Watches, and per-channel states so a partial channel failure is visible. Status chips always pair colour with an icon and a label.
Watch
A Watch is your intent and policy for what must be true: the probes and their steps, the assertions, the schedule, the location policy, the materiality policy and the notification policy, all in one JSON definition (see the step DSL). Watch states are draft, active, paused and retired; retiring keeps history.
Watches are versioned. Every edit creates a new numbered version with a changeNote and a provenance (observed from a guided run, configured in the app, declared through the API, or inferred by the composer or a repair). A Watch reports currentVersion (the latest) and activeVersion (the one scheduled to run); they differ while a change is awaiting approval. GET /v1/watches/{watchId}/versions/diff?from=&to= shows the change as JSON pointer operations, each marked low or high impact.
Approvals. High-impact changes (removing an assertion, deleting a step, relaxing the schedule) can require an admin’s approval before they become active. An approval is pending, approved, rejected or superseded by a later version, and records who requested it, who decided and the note.
AI healing. In Journey Settings, administrators choose Off, Suggest repairs or Automatically apply verified repairs. Steps inherit that policy with individual overrides; Journey Off stops all healing. Repairs may change only the failed eligible browser action’s locator, not success criteria, entered values, destinations or phone scripts. Application requires a passing verification and unchanged policy/version, then creates an audited Watch version while preserving the failed result. Suggest mode requires human acceptance; automatic mode requires explicit opt-in and a real AI provider. Verification currently supports one browser probe, not mixed-channel journeys, and may repeat configured actions such as form submissions. High-impact changes are blocked from this repair path.
Probe and ProbeRun
A Probe is one executor inside a Watch. Types: http, api, dns, tls, browser, ct (certificate transparency), origin_bypass, voice, email. ScoutSentinel prefers the cheapest probe that can prove an assertion and uses a browser only where rendering or interaction is required. Each scheduled execution of a probe from one location is a ProbeRun, identified by an idempotency key of probe id and schedule slot so a re-delivered job never runs twice.
Observation
A ProbeRun produces an Observation: a time-bound, append-only record of what was seen from one runner. Observations are never updated; a correction is a new Observation. Each one records:
| Field | Values |
|---|---|
outcome |
pass, fail, unknown |
unknownReason |
runner_error, timeout_before_first_byte, browser_capacity, blocked_by_bot_protection, runner_disconnected, secret_unavailable, internal_error |
behaviourState |
stable, changed, unknown, derived from the fingerprint diff and kept separate from outcome |
steps[] |
Per step: status (pass, fail, skipped, error), timings, a redacted message and details |
failureBoundary |
stepIndex, stepId, reason of the first step that failed or errored |
runner |
Provider, region, network class, runner, browser and probe versions; see runner locations |
locationKey |
provider:networkClass:region |
http, dns, tls |
The last summary of each kind: status, headers and timings; answers and resolver; issuer, validity, SANs and protocol |
metrics |
Numbers such as totalMs, ttfbMs, third-party host count, evidence bytes |
fingerprint |
The behaviour fingerprint when captured |
evidence[] |
References to Evidence, each with its hash |
summaryHash |
SHA-256 of the canonical summary, so two runs that saw the same facts hash the same |
A step that failed because the target misbehaved is fail; a step that could not be executed for runner or platform reasons is error, which makes the outcome unknown. The outcome of a run is unknown if any step errored, fail if any step failed, otherwise pass. Unknown is a state, not a failure.
Assertion and AssertionResult
An Assertion is an explicit rule with a kind (outcome, behaviour, change, exposure, coverage), a severity (critical, high, medium, low, info), a description and a typed definition. Each evaluation is stored as an AssertionResult with result (pass, fail, not_applicable, unknown), a confidence (always 1 for the deterministic evaluators), the evaluatorVersion and a message. See the assertions reference.
Outcome and behaviour are separate
A journey can still succeed while becoming materially different: a new interstitial, a different redirect chain, a changed response shape. ScoutSentinel reports two states, never one merged status. Outcome tells you whether customers get through; behaviour tells you whether something changed that deserves review. Accepting a behaviour change resets the baseline and records who accepted it.
Event
An Event is a correlated, material condition that requires attention or record. Correlation groups related Observations and opens an Event only when the Watch’s materiality policy is met.
| Field | Values |
|---|---|
kind |
outcome (customers cannot get through), behaviour (passing but materially changed), change (a recorded difference such as a DNS answer or certificate issuer), exposure (an externally observable exposure fact), coverage (the Watch could not produce enough evidence) |
status |
open, acknowledged, resolved, dismissed |
severity |
critical, high, medium, low, info |
resolvedBy |
auto after the configured passes, user, or dismissed |
| Dismiss reason | expected_change, test_traffic, duplicate, not_actionable, false_positive, other, optionally creating a suppression for the same pattern |
Every Event shows the failure boundary (step index, step, reason and the assertion that caught it), what still works, confidence with the reasons behind it, coverage (what was tested, from where, and what was not), the evidence behind the conclusion and change context (release markers and behaviour fingerprint status). Its timeline lists each Observation with a role: causal (same failure boundary), supporting (a different failure or an unknown while open), contradicting (a pass while open), resolving (the pass that closed it) and before (the last good run linked for comparison).
unknown Observations never open an outcome Event. Three consecutive unknowns open a low-severity coverage Event so a persistent gap is visible. Titles are deterministic, for example Get a quote: step 4 "Get quote" button not found (2 consecutive runs, 2 locations).
Evidence
Evidence is an artefact owned by an Observation, never edited by the application once stored, and cited by Events. Kinds: screenshot, html, har, trace, recording, audio, transcript, response, dns, tls, config, diff, email. Each reference carries kind, sha256, bytes, mediaType, the storage key, and optionally the stepId and a label; the stored row adds capturedAt, retentionUntil, the runner identity, whether a redaction pass modified the object, and objectAvailable, which turns false when the bulky object expires while the row and hash remain. Text objects are redacted for known secret values before they are hashed, so the hash you verify is the hash of what you can download.
The object is written to storage and hashed before its metadata row is committed. Downloads go through the API with a short-lived token (POST /v1/evidence/{evidenceId}/download-token) and produce an access log entry; shares are expiring links, optionally passphrase-protected, and are logged too.
Assets and relationships
Passive discovery (certificate transparency, DNS, TLS, HTTP fingerprints) records Assets and evidence-backed Relationships between them, each with a provenance of observed, configured, declared or inferred. Exposure Events connect a new hostname, certificate or reachable origin to the Journey it may affect. We say no identified path, never no path exists.