Receiver trust: assessing a real GNSS receiver log

kshana receiver-trust reads a log from a real global navigation satellite system (GNSS) receiver, runs trust monitors over it epoch by epoch, and says when and why the receiver's fix stopped being trustworthy. It can also score the log against events and predictions you state before the run: whether each event was detected in time, and whether a modelled carrier-to-noise density (C/N0) drop agrees with what the receiver measured.

The observables are the receiver's own; the monitors and their thresholds are the engine's and yours. Every result carries that label, the SHA-256 of the log, and every threshold it ran with, so a run can be repeated and audited.

For a vessel under way, with a live score and an optional gate in front of a chart system, see MARITIME-TRUST.md.

Run it#

kshana receiver-trust examples/receiver-trust/session.toml

This writes session.result.json, session.trust.csv (one row per epoch) and session.trust.svg (mean C/N0 over time with the trust state underneath) next to the scenario, and prints a one-line verdict. The example log is synthetic, made to show the format; point path at your own receiver's log.

The figure above is the vessel demo of MARITIME-TRUST.md: a made-up log, an advisory score.

The same scenario runs from Python (kshana.receiver_trust(toml)), from the WebAssembly package (receiver_trust(toml), with the log inline) and from the Model Context Protocol (MCP) server's assess_receiver_log tool.

Logs it reads#

Each epoch the readers produce also carries source_span, [start, end) byte offsets into the input: the smallest contiguous range holding the records that contributed to it, so the exact raw slice can be hashed for an event window. NMEA: every line read while the epoch is current (a superset where an unrelated line sits between its sentences). UBX: the frames of the epoch. RINEX 3: the epoch records from each > line to the next. Android: the epoch's Raw rows (a Fix row only for an epoch with no Raw rows). Absent for a live stream and wherever it is not well defined (RINEX 2).

The file goes in by path (resolved against the scenario's own folder), or inline as text or base64 (the only choices in a browser).

Platform: static or vessel#

The monitors above assume a fixed antenna. A scenario states the platform before the run in a top-level [platform] table; without one the platform is static and nothing changes.

[platform]
kind = "vessel"            # "static" (default) or "vessel"
max_speed_kn = 30.0        # default 30
max_accel_mps2 = 0.5       # default 0.5
max_turn_rate_dps = 6.0    # default 6
antenna_height_m = 18.0    # no default: without it the sea-level monitor does not run
heading_sensor = false     # true: the stream carries a gyro heading (HDT or THS)

The vessel keys are rejected under kind = "static". For a vessel the position-jump monitor does not run, because it measures distance from the calibration mean, which is wrong on a moving antenna; the result's monitor_config records the platform and the limits used.

The synthetic NMEA streams from kshana nmea-scenario, made for crew training, are accepted by the NMEA reader and can be run through this kind like any NMEA log.

Monitors#

Each monitor needs its data; a monitor whose data is not in the log is not run and not listed in monitors_run. The first calibration_s seconds (default 60) set the baseline and never alarm.

For a vessel platform the moving-platform monitors also run (thresholds in a top-level [maritime] table, every default documented in src/receiver_trust/maritime.rs); each needs its data and is listed in monitors_run only when it decided:

An epoch is untrusted when RAIM, the clock monitor, a solve failure or a position jump alarms, or the C/N0 drop reaches twice its threshold; degraded on any other alarm; and nominal otherwise.

The engine path (raim, solve-failure, clock) is the same computation as the JammerTest 2024 spoofing oracle in tests/jammertest_spoof_oracle_support: tests/receiver_trust_jammertest.rs checks that, on all eight published onsets, the first alarm falls on the same epoch and is of the same kind.

Trust score (vessel platform)#

For a vessel every epoch after calibration also gets a score from 0 to 100 and the reasons it is not 100. The mapping is deterministic and fixed before any log is scored: no learning, nothing fitted to events. Each monitor reduces its evidence to a ratio statistic / threshold (an alarm at 1 or more); a ratio costs the score

points = weight * clamp((ratio - onset_ratio) / (full_ratio - onset_ratio), 0, 1)
score  = round_to_0.1( clamp(100 - sum of points, 0, 100) )

so a monitor costs nothing while below onset_ratio of its threshold (default 0.5), half its weight at its threshold, and all of it at full_ratio times the threshold (default 1.5); the score is non-increasing in every statistic. A source that does not report at an epoch keeps its last statistic for evidence_hold_s (default 10 s: two cycles of a C/N0 sentence sent every 5 s), as an alarm and as a deduction alike.

The rounding is half up (floor(x * 10 + 0.5) / 10), the band is that of the rounded score, and the clamp comes before the rounding. Only monitors whose points are above zero are listed in the deductions, with their ratio and unrounded points, largest points first; deductions with equal points are listed in the order of the monitor names cn0-drop, agc, jam-ind, loss-of-lock, position-jump, raim, clock, solve-failure, kinematic, heading-course, speed-log, sea-level, cn0-spread, cn0-rise, time-consistency, osnma. A monitor whose test is pass or fail (a failed solve, a failed authentication) is given the ratio 1.5, the full weight. The listed points are those before the clamp at 0.

[score]
nominal_min = 90.0         # score >= 90: nominal
degraded_min = 55.0        # 55 <= score < 90: degraded; below 55: untrusted
onset_ratio = 0.5
full_ratio = 1.5
evidence_hold_s = 10.0
[score.weights]            # overrides; a monitor not listed keeps its default
sea-level = 30.0

The band edges follow from the weights: the lightest monitor at its threshold costs 12.5 points, so any alarm leaves the nominal band; no single monitor under 60 points can reach the untrusted band alone (several together can). The result records the score model (score_model) and each epoch carries score.deductions: which monitors deducted, their ratios and their points. For a vessel the epoch's state is the band of its score.

Stating events and predictions#

[[events]]
label = "jammer on"
kind = "jamming"            # jamming, spoofing or other
onset_s = 120.0             # seconds since the first epoch of the log
end_s = 240.0               # optional; otherwise onset_s + compare.horizon_s
predicted_cn0_drop_db = 12.0  # optional, e.g. from a `jamming` scenario's link budget

[compare]
detect_tol_s = 10.0         # an alarm this soon after onset counts as a detection
cn0_tol_db = 3.0            # predicted and observed drops agree within this

For each event the result gives the false alarms between calibration and onset, the first alarm and its monitors, the latency, the outcome (detected, late, missed or not-evaluable), and the observed median C/N0 drop against the prediction (agree, disagree, no-prediction or not-evaluable). Disagreement is reported, never tuned away: the tolerances are in the scenario, and the scenario is in the result's hash.

What this does not claim#

The trust monitors are MODELLED: their thresholds are inputs, and their detection performance on real interference is what the event scoring measures, not something this kind asserts. On the JammerTest 2024 spoofing sessions the engine-path monitors catch some onsets within 10 s and are late on others; see the "Clock-aided χ², RAIM, AGC, SQM fused per-epoch security FoM" row in VERIFICATION-MATRIX.md for the numbers. A prediction that agrees with one log is one data point, not a validation.