SYSLOG-Tools(at)Work

SYSLOG-Tools(at)Work / Teknisk beskrivelse

SYSLOG-Tools(at)Work

Arkitektur, protokoller, sikkerhet og drift for SYSLOG-Tools(at)Work (Receiver og Sender)

Versjon 2.0.0Revidert 2026-10-03Receiver og Sender

SYSLOG-Tools(at)Work består av to Python-programmer, SYSLOG Receiver og SYSLOG Sender, med hvert sitt web-grensesnitt. Dokumentet beskriver arkitekturen, protokollhåndteringen, sikkerhetsmekanismene, installasjonsmodellen og grensesnittene, og er skrevet for drift, sikkerhetsgjennomgang og videreutvikling.

1. Formål og omfang

Produkt

SYSLOG-Tools(at)Work 2.0.0

Komponenter

SYSLOG Receiver (receiver.py), SYSLOG Sender (sender.py), felles moduler (syslog_common.py, syslog_ui.py, syslog_i18n.py), installasjonsskript

Bruksområde

Testing, feilsøking, demonstrasjon og opplæring i syslog (UDP og TLS 1.3), og validering av syslog-oppsett i nettverksutstyr og servere

Ikke formål

Langtidslagring, SIEM eller loggarkiv. Mottakeren holder meldinger bare i minnet.

Målplattformer

Rocky Linux 9 / RHEL 9 / AlmaLinux 9 (primær), Debian 12, Ubuntu 22.04/24.04, Photon OS – på fysisk server, VMware-VM, Proxmox VE VM og Proxmox VE LXC

Kjøremodell

Vanlige Linux-prosesser styrt av systemd (ingen containere, ingen pip, ingen internettilgang)

Språk

Engelsk og norsk (bokmål) i web-grensesnitt, servermeldinger, manualer og installasjonsskript

2. Arkitektur

2.1. Oversikt

                 avsendere (nettverksutstyr, servere, SYSLOG Sender)
                      │ UDP 514                 │ TLS 1.3 / TCP 6514
                      ▼                         ▼
 ┌───────────────────────────── syslog-receiver.service ─────────────────────────────┐
 │  UDP-tråd ──┐                     TLS-lytter ──► én tråd per tilkobling           │
 │             ├─► parse (RFC 3164/5424) ─► ringbuffer (deque, 2000) + statistikk     │
 │             │                                   ▲                                  │
 │  HTTP-server (ThreadingHTTPServer, 8080) ───────┘  /api/messages, /api/stats …     │
 │     ├─ innlogging, CSRF, Host-sjekk (WebSecurityMixin)                             │
 │     ├─ sertifikat-API (CertAPIMixin) ──► /opt/syslog-tools/certs                   │
 │     └─ HTML/JS-side + manual (EN/NO)                                               │
 └────────────────────────────────────────────────────────────────────────────────────┘

 ┌───────────────────────────── syslog-sender.service ───────────────────────────────┐
 │  HTTP-server (8000) ─► /send ─► SyslogHTTPConfigurator ─► UDP-socket / TLS 1.3     │
 │                       └─► RepeatJob (bakgrunnstråd, fast takt, kan stoppes)       │
 │  sertifikat-API (delt kode) ─► /opt/syslog-tools/certs                            │
 │  kommandolinje: python3 sender.py -d … -m …  (uten web)                           │
 └────────────────────────────────────────────────────────────────────────────────────┘

2.2. Kodemoduler

Fil Linjer (ca.) Innhold

Receiver/receiver.py

1 650

SyslogReceiver (UDP-løkke, TLS-lytter, parser, buffer, statistikk, TLS-oppsett som kan endres mens programmet kjører), HTTPHandler (web/API), generate_certificates() (test-PKI), main()

Sender/sender.py

1 600

SyslogHTTPConfigurator (validering, RFC 3164/5424-formatering, UDP/TLS-sockets), RepeatJob (gjentatt sending), SyslogHTTPHandler (web/API), kommandolinje

Common/syslog_common.py

820

Nettverkshjelpere (IPv4/IPv6, dual stack), CertStore (sertifikatkatalog), WebSecurity/WebSecurityMixin (innlogging, CSRF, Host-sjekk, språk per forespørsel, manual, lisenser, logg, utlogging), CertAPIMixin

Common/syslog_ui.py

700

Felles brukergrensesnitt: tema (CSS), topplinje, bunnlinje, faner, utlogging, sertifikatfanen, loggfanen, sidene /logged-out og /licenses, og LogStore/LogCapture (kopi av programmets utskrift for fanen Logger)

Common/syslog_i18n.py

540

Norsk ordliste for brukergrensesnittet (NO_UI), regulære uttrykk for oversettelse av servermeldinger (MESSAGE_PATTERNS), translate_message(), JavaScript-motoren I18N_JS

Det er ingen avhengigheter utenfor Pythons standardbibliotek. Minste Python-versjon er 3.7, kontrollert med vermin.

2.3. Prosess- og trådmodell

  • Receiver: én prosess. Én tråd leser UDP (recvfrom i en løkke), én tråd tar imot TLS-tilkoblinger, og hver TLS-tilkobling får sin egen tråd (daemon-tråder). HTTP håndteres av ThreadingHTTPServer (én tråd per forespørsel). Delte data (buffer og statistikk) beskyttes av én threading.Lock.

  • Sender: én prosess med ThreadingHTTPServer. Enkeltmeldinger sendes i forespørselstråden (serialisert med single_lock). Gjentatt sending kjører i en egen RepeatJob-tråd med egen socket. Bare én jobb kan kjøre om gangen (job_lock).

3. Protokoller

3.1. Mottak (Receiver)

UDP (RFC 5426)

Én melding per datagram, opptil 65 535 byte. Ingen SO_REUSEADDR, så et annet program kan ikke dele porten.

TLS (RFC 5425)

Bare TLS 1.3 (minimum_version = maximum_version = TLSv1_3). Innramming: oktettelling LEN SP MSG, med reserve for meldinger avsluttet med linjeskift (RFC 6587). Maks 64 KiB per ramme.

Klientsertifikat

Valgfritt (CERT_OPTIONAL) når klarerte CA-er/sertifikater er valgt, påkrevd (CERT_REQUIRED) med gjensidig TLS. VERIFY_X509_PARTIAL_CHAIN gjør at et selvsignert klientsertifikat eller mellomliggende sertifikat kan klareres direkte.

Begrensninger

256 samtidige TLS-tilkoblinger, 32 per kildeadresse, 15 s til håndtrykket er ferdig, 600 s inaktivitet (--tls-idle-timeout), maks 10 000 kildeadresser i statistikken (resten telles som «(other)», fordi UDP-adresser kan forfalskes)

3.1.1. Tolking

  1. <PRI> (0–191) gir facility = PRI ÷ 8 og alvorlighet = PRI mod 8. Mangler PRI eller er den ugyldig, brukes USER.NOTICE og meldingen merkes NO-PRI (RFC 3164 §4.3.3).

  2. RFC 5424: 1 TIMESTAMP HOST APP PROCID MSGID SD [MSG]. Strukturerte data tolkes med anførselstegn og escape-tegn (\", \], \\), og en eventuell BOM foran meldingen fjernes.

  3. RFC 3164: Mmm dd hh:mm:ss eller ISO-tidsstempel, deretter vert og TAG[PID]:. Alle deler er valgfrie i praksis.

Feltene i en tolket melding: id, received_at, source_ip, transport, tls_version, tls_cipher, client_cn, facility, severity, rfc_type, timestamp, hostname, app_name, procid, msgid, structured_data, message, raw.

3.1.2. Buffer og fortløpende visning

Meldingene ligger i en collections.deque(maxlen=N) (standard 2000, --buffer). Nettleseren spør /api/messages?since=<siste id> hvert sekund og får bare nye meldinger. En «epoke» (start_token-clear_count) forteller nettleseren om bufferen er tømt eller tjenesten startet på nytt, slik at hele listen da lastes på nytt. Statistikk hentes hvert annet sekund. Nye spørringer sendes først når den forrige er ferdig, så de ikke hoper seg opp på trege linjer.

3.2. Sending (Sender)

RFC 3164

<PRI>Mmm dd hh:mm:ss HOST TAG[PID]: MSG – engelsk månedsnavn, dag fylt ut med mellomrom, TAG maks 32 tegn uten [, ] og :

RFC 5424

<PRI>1 ISO8601-med-tidssone HOST APP PROCID MSGID SD MSG, feltlengder etter RFC 5424 §6 (255/48/128/32), bare utskrivbare ASCII-tegn i hodefeltene, - for tomme felt

MAC-adresse

RFC 3164: [MAC:XX:…] foran teksten. RFC 5424: [device@32473 mac="…"] (32473 = nummeret for dokumentasjon, RFC 5612).

UDP

Adressen slås opp én gang per socket. Valgfri kildeadresse (bind). Maks 65 507 byte.

TLS 1.3

create_connection med 10 s tidsavbrudd, SNI/vertsnavnsjekk mot målet eller forventet servernavn, og verifisering mot valgt CA eller systemets CA-lager. Etter håndtrykket ventes det 0,3 s på en eventuell alert, fordi en TLS 1.3-mottaker avviser klientsertifikater etter håndtrykket. Forbindelsen gjenbrukes og sjekkes før hver melding, og kobles opp på nytt én gang ved feil.

Gjentatt sending

Meldingene planlegges mot starttiden (start + i × 60/takt), så takten ikke forskyves over tid. Stopp kan avbryte ventingen. 1–1000 meldinger per minutt i 1–1440 minutter.

4. Web-grensesnitt

4.1. Oppbygning

Hver side er ett selvstendig HTML-dokument, satt sammen av programmet ved første forespørsel og deretter mellomlagret. Delte deler fra syslog_ui.py settes inn via plassholdere: {{THEME_CSS}}, {{NAVBAR}}, {{FOOTER}}, {{I18N_JS}}, {{FETCH_JS}}, {{APP_JS}}, {{CERT_PANEL}}, {{CERT_JS}}, {{LOG_PANEL}}, {{LOG_JS}}, {{APP_TITLE}}, {{APP_ICON}}, {{HOSTNAME}}, {{VERSION}} og {{DEFAULT_LANG}}. Sidene laster ingen eksterne ressurser og har ingen JavaScript-biblioteker. Ikonene er egne SVG-tegninger i siden, og pilen i nedtrekkslistene er en innebygd SVG (data:-URI).

Design

Samme visuelle språk som SNMP-Trap-Tools(at)Work: topplinje #084f39 med ikon, navn, statusmerke og vertsnavn; ? Brukermanual, EN | NO og Logg ut til høyre; faner; tabeller, skjema og knapper i Bootstrap-lignende stil (primærfarge #0d6efd, kanter #dee2e6, info #0dcaf0); systemets egne skrifttyper.

Faner

Tabs i APP_JS. Valgt fane lagres i adressen (#tab=navn). Hver fane har data-help med avsnitts-id-en i manualen (s3-1, s3-3, s4, s5, s6), som brukes av ? Brukermanual.

Meldingstabell

Én <tbody class="row-main"> per melding (hovedrad og eventuell detaljrad). Nye meldinger settes inn øverst, og meldinger som har falt ut av bufferen, fjernes nederst, uten at resten av tabellen tegnes på nytt. Åpne rader huskes (openIds).

Utlogging

HTTP Basic har ingen utlogging. Knappen Logg ut sender en XMLHttpRequest med et ugyldig brukernavn/passord til /api/logout, som alltid svarer 401 uten WWW-Authenticate (ingen dialog). Nettleseren erstatter da den lagrede innloggingen. Deretter vises /logged-out, som ikke krever innlogging. Dette virker i Chrome, Edge og Firefox. Lukk nettleseren for å være helt sikker.

Logger

install_log_capture() legger en LogCapture rundt sys.stdout/sys.stderr. Alt som skrives, går fortsatt til journalen, og de siste 2000 linjene holdes i minnet med tidsstempel. GET /api/log?since=N gir nye linjer.

Manual

tools/build-manuals.py lager manual.html (engelsk) og manual.no.html (norsk) fra Markdown med pandoc, i samme design: sidemeny med søk (skjuler kapitler som ikke passer og markerer treff), innholdsliste og Tilbake til applikasjonen. Skjermbildene er innebygd, så hver manual er én fil på omtrent 0,4 MB.

4.2. Språk (i18n)

Kildespråk

Engelsk. Alle tekster skrives på engelsk i HTML/JS og oversettes med NO_UI.

Statisk tekst

I18N.capture() går ved oppstart gjennom alle tekstnoder og attributtene placeholder, title og aria-label, og husker dem som har en norsk oversettelse. I18N.apply(lang) bytter verdiene uten å bygge siden på nytt. Elementer med data-i18n="nøkkel" byttes som HTML (hjelpetekster med <code>). data-no-i18n stenger av oversettelsen for et område (f.eks. stier og sertifikatnavn).

Dynamisk tekst

t('Engelsk tekst', {var: verdi}) med plassholdere. Verdier som kommer fra nettverket, escapes (esc()) før de settes inn.

Språkbytte

Lyttere (I18N.onChange) tegner opp igjen meldingslisten, statistikken, TLS-skjemaet, sertifikatlisten, jobbstatusen og resultatboksen.

Lagring

localStorage (syslog_tools_lang) og en informasjonskapsel med samme navn (SameSite=Strict), slik at /manual også følger språket

Servermeldinger

fetch sender X-UI-Lang. WebSecurityMixin._send_json() og _deny() oversetter feltet message med translate_message(), som går gjennom regulære uttrykk i rekkefølge. Gruppene oversettes rekursivt (maks dybde 4), og ukjente tekster (f.eks. feil fra OpenSSL) returneres uendret.

Standardspråk

--lang en|no (fra install.sh --lang/--web-lang)

Lokale formater

Klokkeslett med toLocaleTimeString('nb-NO' / 'en-GB')

4.3. HTTP-API

Se Brukermanual, kapittel 8, for alle endepunkter. Alle svar er JSON (application/json; charset=utf-8), og tilstandsendrende kall er POST.

5. Sikkerhet

5.1. Tilgangskontroll i web-laget

Innlogging

HTTP Basic, bruker admin. Passordet ligger i en fil (600, eid av tjenestebrukeren) og sammenlignes med hmac.compare_digest. Ved feil passord ventes det 1 s for å bremse gjetting.

CSRF

POST krever hodet X-Requested-With: syslog-ui, som andre nettsteder ikke kan sette uten CORS. Er Origin satt, må den stemme med Host.

DNS rebinding

Host må være en IP-adresse eller et kjent vertsnavn (localhost, maskinens navn, --allowed-host).

Klikkapring m.m.

X-Frame-Options: DENY, Content-Security-Policy: frame-ancestors 'none', X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer

XSS

All tekst fra nettverket (syslog-meldinger, filnavn, sertifikatfelt) escapes før den settes inn i HTML.

Filvalg

TLS-filer valgt i nettleseren må ligge direkte i sertifikatkatalogen (CertStore.resolve_web, realpath-sjekk), eller være oppgitt av administrator på kommandolinjen.

Opplasting

Maks 1 MiB, filnavn etter ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$ med tillatte endelser. Innholdet kontrolleres (PEM-blokker eller DER). Nøkler skrives med O_EXCL|O_NOFOLLOW og modus 600 fra første øyeblikk, og flyttes atomisk på plass.

Nedlasting

Filer som inneholder en privat nøkkel, kan aldri lastes ned.

Sertifikatgenerering

openssl kjøres med argumentliste (aldri skall), og alle verdier valideres med regulære uttrykk.

Skrivebeskyttet modus

--no-cert-upload stenger opplasting, sletting, generering og TLS-endringer.

5.2. Prosessisolasjon (systemd)

Bruker

syslog-tools (systembruker, ingen innlogging)

Rettigheter

AmbientCapabilities=CAP_NET_BIND_SERVICE og CapabilityBoundingSet=CAP_NET_BIND_SERVICE – bare retten til porter under 1024

Profil full

NoNewPrivileges, ProtectSystem=strict (alt skrivebeskyttet unntatt ReadWritePaths=/opt/syslog-tools/certs), ProtectHome, PrivateTmp, PrivateDevices, ProtectKernelTunables/Modules/Logs, ProtectControlGroups, ProtectClock, ProtectHostname, RestrictNamespaces, RestrictRealtime, RestrictSUIDSGID, LockPersonality, SystemCallArchitectures=native, RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK, UMask=0027

Profil basic

NoNewPrivileges, UMask=0027 og rettighetene over. Brukes i LXC, der navnerom og mounts ofte er sperret (226/NAMESPACE).

Valg av profil

auto: systemd-detect-virt --container → basic, ellers full. Starter ikke tjenesten med full, skriver installasjonsprogrammet tjenestefilene på nytt med basic.

SELinux

/usr/bin/python3 startet av systemd kjører som unconfined_service_t, så ingen egen policy trengs. restorecon setter riktige merker på /opt/syslog-tools.

5.3. Kjente begrensninger

  • Web-grensesnittet bruker vanlig HTTP (ikke HTTPS). Passord og opplastede nøkler går ukryptert over nettet. Tiltak: eget administrasjonsnett, --admin-net, eller en omvendt proxy med TLS foran.

  • HTTP Basic har ingen utlogging eller tidsavbrudd for økten (nettleseren husker innloggingen til den lukkes).

  • UDP-syslog er verken autentisert eller kryptert, og kildeadresser kan forfalskes.

  • Meldinger lagres bare i minnet.

6. Installasjon og filstruktur

6.1. Installert struktur

Sti Eier/modus Innhold

/opt/syslog-tools/

root 755

VERSION, install.conf, uninstall.sh, check-prereqs.sh, firewall-open.sh, lib/, docs/

/opt/syslog-tools/receiver/

root 755

receiver.py, syslog_common.py, syslog_i18n.py, manual.html, manual.no.html

/opt/syslog-tools/receiver/web-password

syslog-tools 600

Passord til web-grensesnittet

/opt/syslog-tools/sender/

root 755

Tilsvarende for senderen

/opt/syslog-tools/certs/

syslog-tools 750

Sertifikater og nøkler (600), receiver-tls.json

/etc/systemd/system/syslog-receiver.service

root 644

Tjeneste

/etc/systemd/system/syslog-sender.service

root 644

Tjeneste

6.2. Installasjonsprogrammet

install.sh går gjennom 8 trinn: forutsetninger, bruker og kataloger, programfiler, sertifikater, systemd, start (med reserve til basic), brannmur og verifisering. Det kan kjøres på nytt så mange ganger du vil (idempotent): valg fra install.conf blir standardverdier, passord og sertifikater beholdes, og tjenestene startes på nytt. Verifiseringen sender en testmelding over UDP og leter etter den med /api/messages.

Plattformgjenkjenning (lib/common.sh):

  • /etc/os-release (leses i et underskall) → OS_FAMILY = rhel / debian / photon / suse / other

  • systemd-detect-virt → VIRT = none / vmware / kvm / lxc …, og IS_CONTAINER

  • brannmur: aktiv firewalld → firewall-cmd, aktiv ufw → ufw, ellers ingen endring

6.3. Oppgradering fra 1.x

Når /opt/syslog-infrastructure finnes og den nye sertifikatkatalogen er tom, kopieres sertifikatene, og stiene i receiver-tls.json skrives om. Web-passordene kopieres. Tjenestenavnene er de samme som før og skrives over. Programmene ser også etter den gamle sertifikatkatalogen hvis den nye mangler (LEGACY_ROOT).

7. Konfigurasjon

7.1. Receiver – kommandolinje

Valg Standard Beskrivelse

--listen

0.0.0.0

Lytteadresse (:: = dual stack)

--syslog-port

514

UDP-port

--http-port / --http-bind

8080 / 0.0.0.0

Web-grensesnitt

--buffer

2000

Meldinger i minnet

--quiet

av

Ikke skriv hver melding til journalen

--tls, --tls-port, --tls-cert, --tls-key, --tls-ca (kan gjentas), --tls-require-client-cert

TLS ved oppstart (overstyres av receiver-tls.json)

--tls-idle-timeout

600

Sekunder før en inaktiv TLS-tilkobling lukkes

--cert-dir

/opt/syslog-tools/certs

Sertifikatkatalog

--no-cert-upload, --ignore-saved-tls

Skrivebeskyttet / ignorer lagrede TLS-innstillinger

--gen-certs DIR --cert-names LISTE

Lag test-PKI og avslutt

--auth-file, --no-auth, --allowed-host

Innlogging og vertsnavn

--lang

en

Standardspråk i web-grensesnittet (en/no)

7.2. Sender – kommandolinje

--http, --port, --http-bind, --lang, --auth-file, --no-auth, --allowed-host, --cert-dir og --no-cert-upload styrer web-modus. -d, -s, -t, -p, -m, --rfc, --facility, --severity, --hostname, --app, --mac, --procid, --msgid, --repeat, --duration og --tls- styrer kommandolinjemodus. I web-modus brukes --tls- som standardverdier i skjemaet.

7.3. Lagret tilstand

receiver-tls.json

TLS-innstillinger fra web-grensesnittet (enabled, port, cert, key, trusted[], require_client_cert)

install.conf

Valgene fra installasjonen (KEY="verdi"). Leses linje for linje uten source.

Nettleseren

syslog_tools_lang (språk), syslog-sender-tls (senderens TLS-valg)

8. Drift

  • Logg: fanen Logger i web-grensesnittet (siste 2000 linjer), eller journalctl -u syslog-receiver / -u syslog-sender. Hver melding (med mindre --quiet er brukt), hver TLS-tilkobling, hvert mislykket håndtrykk og hver sertifikatendring logges på engelsk.

  • Overvåking: GET /api/stats (krever innlogging) gir tellere og status (udp_status, tls_status).

  • Ressursbruk: En melding tar typisk 1–2 KiB i minnet, så standardbufferen på 2000 meldinger bruker bare noen få MiB. Hele prosessen bruker typisk 20–40 MiB RAM. CPU-bruken øker med meldingsraten. Ved høy trafikk bør --quiet brukes, fordi skriving til journalen ellers dominerer.

  • Sikkerhetskopi: /opt/syslog-tools/certs og web-password-filene. Alt annet kan installeres på nytt fra pakken.

9. Kvalitetssikring

Se Revisjonsrapport.md for kodegjennomgang, sikkerhetsvurdering og testresultater.

Skjermbilder, installasjon og hvordan de to verktøyene brukes sammen: Tilbake til forsiden