GNSS-vertrouwen als beveiligingstelemetrie

kshana trust-telemetry zet de GNSS-vertrouwensstroom per epoch (score 0-100, band, redenen) om in signalen die een operations- of beveiligingscentrum al verwerkt: Prometheus-metrics, syslog-gebeurtenissen in CEF of LEEF voor een SIEM, en optioneel OpenTelemetry. Het leest de stroom; het wijzigt de vertrouwensbeoordeling nooit en zendt niets uit behalve telemetrie.

Uitvoeren#

# live stream on stdin -> /metrics on localhost:9464
kshana receiver-trust live <args> | kshana trust-telemetry

# replay a batch result (the score is the epoch's own for a vessel platform, absent otherwise)
kshana trust-telemetry --result session.result.json --print-metrics
kshana trust-telemetry --result session.result.json --print-syslog --format leef

# SIEM over UDP, one event per band change
kshana trust-telemetry --input stream.jsonl --syslog-udp siem.example:514 --format cef --host ops-gw1

De invoer is het live JSON-lines-schema v1.1 dat is beschreven in docs/MARITIME-TRUST.md. Gelezen wordt: t_s; state (calibrating|nominal|degraded|untrusted, de band); score (0-100 of null); time (de tijd van de epoch zoals opgegeven); gate (off|passed|withheld); position (lat_deg, lon_deg, height_m, of null); de redenen zijn de monitors in deductions, daarna eventuele verdere in alarms; vanaf schema 1,3 geometry (status, hdop, pdop, n_used) en de class van elke aftrek. Andere sleutels worden genegeerd, omdat het schema alleen groeit door toegevoegde sleutels. Een regel die niet kan worden geparseerd, wordt geteld in kshana_trust_input_errors_total en overgeslagen; scores buiten 0-100 worden afgewezen en niet afgekapt, zodat een formaatwijziging wordt opgemerkt. De enige code die dit formaat kent, is src/telemetry/sample.rs.

/metrics wordt zonder authenticatie aangeboden en staat standaard op 127.0.0.1:9464. Binden aan een ander adres drukt een waarschuwing af; plaats het achter uw eigen toegangsbeheer. Het eindpunt verwerkt één verbinding tegelijk met een leeslimiet van 2 s, zodat een niet-actieve client een scrape tot zo lang kan vertragen; het is bedoeld voor één scraper, niet voor het open netwerk.

Home Assistant en NTP-apparaten (MQTT)#

--print-mqtt drukt een JSON-statusdocument en Home Assistant MQTT-discoveryberichten af, en --mqtt-tcp <host:port> publiceert ze. Discovery (behouden, onder homeassistant/...) maakt drie entiteiten aan: vertrouwensscore, vertrouwensband (met de redenen als attributen) en een probleemsensor untrusted. Het statusdocument gaat naar <prefix>/state (standaard kshana/trust/state, behouden): state, score (null zolang er geen is), untrusted, t_s, time, reasons, gate en de adviserende verklaring; de positie wordt nooit opgenomen. Opties: --mqtt-prefix, --mqtt-node, --mqtt-discovery.

De publisher spreekt MQTT 3.1.1 met QoS 0 en leest alleen de CONNACK van de broker. Hij heeft geen inloggegevens en geen TLS, dus gebruik een broker op het lokale netwerk (of een lokaal relay dat die toevoegt). De aflevering draait op een eigen thread achter een wachtrij van 1024: een niet-reagerende broker laat berichten vallen, die worden geteld en aan het eind gerapporteerd, en houdt de stroom nooit tegen. Een NTP-apparaat of elke andere afnemer die gewone JSON wil, kan dezelfde statusregel lezen. Er wordt niets naar een ontvanger of een klok geschreven. Python, WebAssembly en MCP accepteren format = "mqtt" en geven dezelfde topic<TAB>payload-regels terug (daar wordt niets gepubliceerd).

Vanuit Python, WebAssembly en MCP#

De encoders zijn ook beschikbaar als aanroepen met tekst erin en tekst eruit, zonder proces, socket of klok: Python kshana.trust_telemetry(input, format, host="", input_kind="jsonl", expose_position=False, syslog_all=False, unix_nano=0), de WebAssembly-export trust_telemetry(input, format, host, input_kind, options_json) en de MCP-tool trust_telemetry (pluginopdracht /kshana-trust-telemetry). format is prometheus, cef, leef of otlp; input_kind is jsonl (de stroom) of result (een batchresultaat). Ze geven dezelfde tekst terug als de opdrachtregel afdrukt (--print-metrics, --print-syslog), met dezelfde beperkingen: syslog-regels hebben geen tijdstempel, host bestaat uit hooguit 255 afdrukbare ASCII-tekens zonder spaties (anders geweigerd, hier en op de opdrachtregel), en een antwoord dat groter is dan de limiet van het oppervlak (4 MiB bij MCP) wordt geweigerd, omdat CEF en LEEF met syslog_all één gebeurtenis per epoch schrijven. Er wordt niets verzonden, aangeboden of geschreven; de draaiende exporters blijven een proces op de opdrachtregel.

Aflevering houdt de beoordeling nooit tegen#

Syslog- en OpenTelemetry-aflevering draaien op eigen threads. De invoerlus geeft hun alleen een bericht of een momentopname en wacht nooit, zodat een niet-reagerende, trage of niet-lezende collector de live stroom niet kan terugdrukken of /metrics kan bevriezen:

• voor elke verbinding en elke schrijfactie geldt een limiet van 2 s; een mislukte verbinding wordt verbroken en lui opnieuw opgezet, met exponentiële backoff van 1 s tot 60 s;
• een bericht dat niet kan worden afgeleverd (collector uit de lucht, schrijfactie verlopen, wachtrij van 1024 vol) wordt weggegooid en geteld in kshana_trust_syslog_send_failures_total; laat een alarm afgaan op de snelheid ervan;
• de OpenTelemetry-exporter krijgt een kopie van het register, zodat tijdens netwerk-I/O geen lock wordt vastgehouden; als een export nog loopt, wordt de nieuwe momentopname overgeslagen (de volgende bevat dezelfde cumulatieve totalen).

Aan het einde van de invoer krijgen de verzendthreads hun resterende tijdlimieten om af te ronden.

Prometheus-metrics#

Het geometrielabel is de hoofdzaak. Maak grafieken en alarmen op kshana_trust_geometry_label (OTLP kshana.geometry.label, CEF het derde veld cs6, LEEF geoLabel): poor is het enige label waarvoor de score aftrekt. De geometriestatus is beschrijvend: degraded omvat het informatieve geval sky-blocked, dat kan voorkomen bij goede of redelijke DOP, dus laat geen oproep afgaan op kshana_trust_geometry_degraded alleen.

Bij invoer met schema 1,3 heeft kshana_trust_reason_active ook een label class (geometry, environment, inconsistency) bij elke reden die er een meekreeg: de klasse van de aftrek bij de laatste epoch. De geometriereeksen komen na alle andere en alleen zodra een invoerepoch geometry bevat (live schema 1,3, een resultaat van engine 0,36 of later), zodat een stroom of resultaat van 0,35 byte voor byte hetzelfde wordt weergegeven als voorheen. Labelwaarden zijn vaste verzamelingen (een onbekende status geeft unknown; een onbekende klasse wordt weggelaten). Laat een alarm afgaan op kshana_trust_reason_active{class="inconsistency"} in plaats van op de band alleen, zodat een slechte hemel niet als aanval wordt gemeld; een klasse geometry is een uitspraak over de hemel, niet een bevinding dat er geen aanval is geweest (zie docs/RECEIVER-TRUST.md).

Het label class maakt deel uit van de identiteit van een reeks: wanneer de klasse van een reden tussen epochs verandert (loss-of-lock van environment naar geometry wanneer de verloren satellieten laag stonden, of geometry naar inconsistency wanneer de opgegeven HDOP niet overeenkomt met de opgegeven hemel), wordt de oude reeks niet meer geëxporteerd en begint een nieuwe. Vraag op reason met max by (reason) wanneer de klasse er niet toe doet, en verwacht dat zo'n wissel eruitziet als een reeks die eindigt en een andere die begint. De reeksen van schema 1,3, het label class en de CEF/LEEF-geometrievelden worden gecontroleerd door de eigen tests van de engine en door de CEF-orakels (pycef, Logstash); de externe Prometheus- en OTLP-orakels hebben nog geen stroom van 1,3.

Redennamen worden afgekapt tot 128 tekens, en hooguit 64 verschillende redenen krijgen een eigen reeks; latere worden geteld onder reason="other" en in kshana_trust_reason_overflow_total, zodat een vijandige of foutieve invoer geen onbegrensde labelcardinaliteit kan veroorzaken.

band is er een van calibrating, nominal, degraded, untrusted, unknown. Redennamen zijn de monitornamen van de stroom (kinematic, heading-course, ...; voor het batchresultaat cn0-drop, agc, raim).

Een voorbeelddashboard staat in deploy/grafana/kshana-gnss-trust.json (importeer het en kies uw Prometheus-gegevensbron).

Syslog: CEF en LEEF#

Gebeurtenissen worden verzonden in een RFC 5424-envelop (facility local0, app kshana, bericht-id GNSSTRUST) via UDP (één datagram per gebeurtenis; IPv4 of IPv6) of TCP, standaard afgesloten met een nieuwe regel of, met --syslog-octet-counting, ingekaderd als <length> <message> zoals in RFC 6587. Standaard wordt één gebeurtenis per bandwijziging verzonden; --syslog-all verzendt er één per epoch. De leverancier wordt geschreven als Ashforde OU (ASCII), zodat geen enkele SIEM hem verkeerd decodeert.

Veldtoewijzing (gebeurtenis-id is gnss-trust.<band>):

In CEF gebruikt de geometrie alleen aangepaste woordenboekvelden (geen verzonnen sleutels); het label gaat in cs6 in plaats van flexString1 omdat de Logstash-CEF-codec de flexString-velden niet toewijst. De 1,3-geometriegebeurtenissen, inclusief de labelgevallen, maken deel uit van de rij VALIDATED CEF: beide orakelparsers lezen ze terug zoals ze zijn geschreven (tests/cef_reference.rs, amendementen 4 en 5, elk vastgelegd voordat een van beide parsers op zijn gevallen werd gedraaid). De velden label, VDOP en aantal satellieten worden achter alle eerdere velden en reeksen toegevoegd, en alleen voor invoer die het label meegeeft, zodat invoer zonder label precies zo wordt weergegeven als voorheen.

Lege velden worden weggelaten (geen cs2= zonder redenen). De hostnaam wordt afgekapt tot 255 tekens. CEF-headerwaarden escapen \ en |; extensiewaarden escapen \, = en regeleinden. In LEEF-waarden worden ^ en regeleinden vervangen door spaties.

OpenTelemetry (standaard uit)#

Bouw met --features otlp en geef --otlp http://host:4318/v1/metrics mee. De exporter post OTLP/HTTP-JSON (kshana.trust.score, kshana.trust.band, kshana.trust.epochs, kshana.trust.reason.epochs, en voor invoer met schema 1,3 kshana.geometry.status, kshana.geometry.degraded, kshana.geometry.signal_loss, kshana.geometry.hdop, kshana.geometry.pdop, kshana.geometry.used_satellites en, van invoer die het label meegeeft (0,36), kshana.geometry.label (attribuut label) en kshana.geometry.vdop; de cumulatieve sommen hebben startTimeUnixNano) elke --otlp-every epochs (standaard 10) en aan het einde van de invoer. Het voegt geen afhankelijkheid toe en heeft geen TLS: verzend naar een collector op dezelfde host of een vertrouwd segment, die verder doorstuurt via TLS. Eindpunten met https:// worden geweigerd.