GNSS-förtroende som säkerhetstelemetri

kshana trust-telemetry omvandlar GNSS-förtroendeströmmen per epok (poäng 0-100, band, skäl) till signaler som ett drifts- eller säkerhetscenter redan tar emot: Prometheus-mätvärden, syslog-händelser i CEF eller LEEF för ett SIEM och eventuellt OpenTelemetry. Den läser strömmen; den ändrar aldrig förtroendebedömningen och sänder inget annat än telemetri.

Kör den#

# 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

Indata är live-JSON-radsschemat v1.1 som dokumenteras i docs/MARITIME-TRUST.md. Läser: t_s; state (calibrating|nominal|degraded|untrusted, bandet); score (0-100 eller null); time (epokens tid som den anges); gate (off|passed|withheld); position (lat_deg, lon_deg, height_m eller null); skälen är monitorerna i deductions, därefter eventuella övriga i alarms; från schema 1,3, geometry (status, hdop, pdop, n_used) och varje avdrags class. Övriga nycklar ignoreras, eftersom schemat bara växer genom tillagda nycklar. En rad som inte kan tolkas räknas i kshana_trust_input_errors_total och hoppas över; poäng utanför 0-100 avvisas, inte kläms, så att en formatändring märks. Den enda kod som känner till det här formatet är src/telemetry/sample.rs.

/metrics serveras utan autentisering och har 127.0.0.1:9464 som standard. Att binda någon annanstans skriver ut en varning; lägg den bakom din egen åtkomstkontroll. Ändpunkten hanterar en anslutning åt gången med en läsgräns på 2 s, så en overksam klient kan fördröja en avläsning med upp till så lång tid; den är avsedd för en enda avläsare, inte för det öppna nätet.

Home Assistant och NTP-apparater (MQTT)#

--print-mqtt skriver ut, och --mqtt-tcp <host:port> publicerar, ett JSON-tillståndsdokument och MQTT-upptäcktsmeddelanden för Home Assistant. Upptäckten (kvarhållen, under homeassistant/...) skapar tre entiteter: förtroendepoäng, förtroendeband (med skälen som attribut) och en problemsensor untrusted. Tillståndsdokumentet går till <prefix>/state (standard kshana/trust/state, kvarhållet): state, score (null medan det saknas), untrusted, t_s, time, reasons, gate och den rådgivande uppgiften; positionen ingår aldrig. Alternativ: --mqtt-prefix, --mqtt-node, --mqtt-discovery.

Publiceraren talar MQTT 3.1.1 med QoS 0 och läser bara mäklarens CONNACK. Den har inga inloggningsuppgifter och ingen TLS, så använd en mäklare på det lokala nätverket (eller ett lokalt relä som lägger till dem). Leveransen körs på en egen tråd bakom en kö på 1024: en död mäklare tappar meddelanden, som räknas och rapporteras i slutet, och stannar aldrig strömmen. En NTP-apparat eller annan konsument som vill ha ren JSON kan läsa samma tillståndsrad. Ingenting skrivs till en mottagare eller en klocka. Python, WebAssembly och MCP tar format = "mqtt" och returnerar samma topic<TAB>payload-rader (ingenting publiceras där).

Från Python, WebAssembly och MCP#

Kodarna finns också som anrop med text in och text ut, utan process, socket eller klocka: Python kshana.trust_telemetry(input, format, host="", input_kind="jsonl", expose_position=False, syslog_all=False, unix_nano=0), WebAssembly-exporten trust_telemetry(input, format, host, input_kind, options_json) och MCP-verktyget trust_telemetry (plugin-kommando /kshana-trust-telemetry). format är prometheus, cef, leef eller otlp; input_kind är jsonl (strömmen) eller result (ett batchresultat). De returnerar samma text som kommandoraden skriver ut (--print-metrics, --print-syslog), med samma gränser: syslog-rader har ingen tidsstämpel, host är högst 255 utskrivbara ASCII-tecken utan mellanslag (avvisas annars, här och på kommandoraden), och ett svar som är större än ytans gräns (4 MiB för MCP) avvisas, eftersom CEF och LEEF med syslog_all skriver en händelse per epok. Ingenting skickas, serveras eller skrivs; de pågående exportörerna förblir en process på kommandoraden.

Leveransen stoppar aldrig bedömningen#

Leverans av syslog och OpenTelemetry körs på egna trådar. Inläsningsslingan lämnar bara över ett meddelande eller en ögonblicksbild till dem och väntar aldrig, så en död, långsam eller icke-läsande insamlare kan inte sätta press på live-strömmen eller frysa /metrics:

• varje anslutning och skrivning har en gräns på 2 s; en misslyckad anslutning släpps och återansluts lat, med exponentiell backoff från 1 s upp till 60 s;
• ett meddelande som inte kan levereras (insamlaren nere, skrivningen tog för lång tid, kön på 1024 full) tappas och räknas i kshana_trust_syslog_send_failures_total; larma på dess takt;
• OpenTelemetry-exportören får en kopia av registret, så inget lås hålls under nätverks-I/O; om en export fortfarande pågår hoppas den nya ögonblicksbilden över (nästa har samma kumulativa summor).

Vid slutet av indata får sändartrådarna sina återstående tidsgränser för att bli klara.

Prometheus-mätvärden#

Geometrietiketten är huvudsignalen. Rita och larma på kshana_trust_geometry_label (OTLP kshana.geometry.label, CEF det tredje fältet cs6, LEEF geoLabel): poor är den enda etikett som poängen drar av för. Geometristatusen är beskrivande: degraded omfattar det informativa fallet sky-blocked, som kan förekomma med god eller skaplig DOP, så larma inte enbart på kshana_trust_geometry_degraded.

Från indata enligt schema 1,3 bär kshana_trust_reason_active också en etikett class (geometry, environment, inconsistency) på varje skäl som kom med en: avdragets klass vid senaste epoken. Geometriserierna kommer efter alla andra och först när en indataepok bär geometry (live-schema 1,3, ett resultat från motor 0,36 eller senare), så en ström eller ett resultat från 0,35 återges byte för byte som förut. Etikettvärden är fasta mängder (en okänd status läses unknown; en okänd klass släpps). Larma på kshana_trust_reason_active{class="inconsistency"} i stället för på bandet ensamt, så att en dålig himmel inte larmar som en attack; en klass geometry är ett uttalande om himlen, inte ett fastställande att ingen attack inträffade (se docs/RECEIVER-TRUST.md).

Etiketten class är en del av en series identitet: när ett skäls klass ändras mellan epoker (loss-of-lock från environment till geometry när de förlorade satelliterna stod lågt, eller geometry till inconsistency när den angivna HDOP inte stämmer med den angivna himlen) exporteras den gamla serien inte längre och en ny börjar. Fråga efter reason med max by (reason) när klassen inte spelar roll, och räkna med att ett sådant byte ser ut som att en serie slutar och en annan börjar. Serierna enligt schema 1,3, etiketten class och CEF/LEEF-geometrifälten kontrolleras av motorns egna tester och av CEF-referenserna (pycef, Logstash); de externa Prometheus- och OTLP-referenserna har ännu ingen ström enligt 1,3.

Skälnamn kapas vid 128 tecken, och högst 64 skilda skäl får egna serier; senare räknas under reason="other" och i kshana_trust_reason_overflow_total, så att en fientlig eller felaktig indata inte kan skapa obegränsad etikettkardinalitet.

band är en av calibrating, nominal, degraded, untrusted, unknown. Skälnamnen är strömmens monitornamn (kinematic, heading-course, ...; för batchresultatet cn0-drop, agc, raim).

En exempelinstrumentpanel finns i deploy/grafana/kshana-gnss-trust.json (importera den och välj din Prometheus-datakälla).

Syslog: CEF och LEEF#

Händelser skickas i ett RFC 5424-kuvert (facility local0, app kshana, meddelande-id GNSSTRUST) över UDP (ett datagram vardera; IPv4 eller IPv6) eller TCP, som standard avslutade med radbrytning eller, med --syslog-octet-counting, inramade som <length> <message> enligt RFC 6587. Som standard skickas en händelse per bandbyte; --syslog-all skickar en per epok. Tillverkaren skrivs Ashforde OU (ASCII) så att inget SIEM avkodar den fel.

Fältmappning (händelse-id är gnss-trust.<band>):

I CEF använder geometrin bara anpassade fält ur ordboken (inga påhittade nycklar); etiketten färdas i cs6 snarare än flexString1 eftersom Logstash CEF-kodek inte mappar fälten flexString. Geometrihändelserna enligt 1,3, etikettfallen inräknade, ingår i den VALIDATED CEF-raden: båda referensparserna läser tillbaka dem som skrivna (tests/cef_reference.rs, ändringarna 4 och 5, vardera registrerad innan någon av parserna kördes på dess fall). Fälten för etikett, VDOP och antal satelliter läggs till efter alla tidigare fält och serier, och bara för indata som bär etiketten, så indata utan en återges exakt som förut.

Tomma fält utelämnas (ingen cs2= utan skäl). Värdnamnet kapas vid 255 tecken. Rubrikvärden i CEF escapar \ och |; tilläggsvärden escapar \, = och radbrytningar. I LEEF-värden ersätts ^ och radbrytningar med mellanslag.

OpenTelemetry (av som standard)#

Bygg med --features otlp och ange --otlp http://host:4318/v1/metrics. Exportören postar OTLP/HTTP-JSON (kshana.trust.score, kshana.trust.band, kshana.trust.epochs, kshana.trust.reason.epochs, och för indata enligt schema 1,3 kshana.geometry.status, kshana.geometry.degraded, kshana.geometry.signal_loss, kshana.geometry.hdop, kshana.geometry.pdop, kshana.geometry.used_satellites samt, från indata som bär etiketten (0,36), kshana.geometry.label (attribut label) och kshana.geometry.vdop; de kumulativa summorna bär startTimeUnixNano) var --otlp-every:e epok (standard 10) och vid slutet av indata. Den lägger inte till något beroende och har ingen TLS: skicka till en insamlare på samma värd eller ett betrott segment, som vidarebefordrar över TLS. Ändpunkter med https:// avvisas.