Registres estructurats de protocols

lippycat pot escriure metadades normalitzades de protocols al costat de les sortides de paquets, PCAP, TUI, interfície virtual i LI. Els fitxers utilitzen noms de flux i semàntica de camps familiars de Zeek, però no substitueixen el seu ecosistema d’analitzadors i scripts. En particular, una captura filtrada o iniciada tard produeix observacions útils de límit inferior en lloc de mesuraments complets de connexió.

Activació dels registres

El registre està desactivat per defecte. Proporcionar --log-dir l’activa per a process, tap i sniff; el directori es crea si cal.

Per a un processador terminal en un desplegament distribuït:

lc process --listen :55555 --log-dir /var/log/lippycat

Per a captura local amb JSONL i fluxos seleccionats:

sudo lc tap dns -i eth0 --insecure \
  --log-dir /var/log/lippycat --log-format json --log-streams conn,dns

Per a captura CLI fora de línia o en viu, amb la sortida estàndard de paquets sense canvis:

lc sniff http -r capture.pcap --log-dir ./logs --log-streams conn,http,files

Les opcions compartides són:

Les claus YAML equivalents són events.queue_size, events.drop_policy, logs.dir, logs.format, logs.streams, logs.rotate_interval, logs.queue_size, logs.emit_stage, logs.post_rotate_command, logs.include_http_headers, logs.include_email_body_preview, i files.extract, files.extract_dir, files.max_size i files.total_size.

events:
  queue_size: 20000
  drop_policy: drop_new
logs:
  dir: /var/log/lippycat
  format: tsv
  streams: [conn, dns, ssl, http, smtp, files, radius]
  rotate_interval: 1h
  queue_size: 10000
  emit_stage: terminal
  post_rotate_command: "gzip %log%"
  include_http_headers: false
  include_email_body_preview: false
files:
  extract: false
  extract_dir: /var/lib/lippycat/files
  max_size: 10485760
  total_size: 104857600

En una jerarquia de processadors, terminal evita fitxers duplicats escrivint només en un node que no reenvia cap amunt. Utilitzeu all deliberadament per registrar en cada etapa activada, o none per suprimir la sortida de fitxers.

Codificacions de sortida

TSV és el valor per defecte. Escriu capçaleres Zeek (#separator, #set_separator, #empty_field, #unset_field, #path, #open, #fields i #types) i un peu #close. Els temps són segons Unix amb sis decimals, els intervals són segons, els booleans són T/F, i els vectors/conjunts se separen per comes. - significa sense establir, (empty) significa present però buit, i els bytes de control s’escapen com \xHH.

JSON és JSON Lines: un objecte per fila. Utilitza els mateixos noms de camp, incloent-hi claus com id.orig_h; els booleans, números i matrius tenen tipus JSON natius. Els valors sense establir són null, mentre que els valors presents buits són "" o []. Els fitxers JSON continuen utilitzant noms compatibles amb Zeek com dns.log.

Fluxos i camps

Tot l’ordre i els tipus de camps següents estan fixats per internal/pkg/logschema. uid és un identificador de connexió d’estil Zeek generat per lippycat. community_id és Community ID v1 per a unions entre eines, i node_id identifica la font de captura original, no necessàriament el processador que escriu el fitxer. Els valors no disponibles queden sense establir.

conn.log

Un resum de cicle de vida per flux observat (caducitat, expulsió o aturada ordenada).

L’orientació d’iniciador/responent segueix el SYN TCP quan és visible i, si no, el primer paquet observat. Els valors de bytes i paquets són recomptes observats. service és el protocol d’aplicació detectat; conn_state i history resumeixen el comportament TCP visible; els booleans d’adreça local poden quedar sense establir quan es desconeix la localitat.

capture_scope=full significa que la font pretenia observar tot el flux de la interfície. filtered significa que un filtre BPF, de protocol, d’objectiu o distribuït ha restringit la captura. Això no demostra una transmissió sense pèrdues. partial=true significa que la connexió va començar abans de l’observació, no es va veure un SYN TCP, només es va veure una direcció, se sap que es van descartar paquets o el còmput és incomplet d’una altra manera. Tracteu tots els comptadors i la durada de les files parcials com límits inferiors. Un àmbit full encara pot ser parcial.

dns.log

Una observació de transacció DNS. trans_id és l’identificador de transacció DNS; rtt és el temps de resposta correlacionat. La classe/tipus de consulta i el codi de resposta apareixen com valors numèrics i descriptius. AA, TC, RD, RA i Z són indicadors de la capçalera DNS; answers i TTLs són vectors de resposta; rejected marca una transacció rebutjada.

ssl.log

Una observació de negociació TLS. Inclou version, cipher, curve negociats, SNI server_name, estat de represa/alerta/ALPN, estat d’establiment, identificadors i identitats dels fitxers de certificat, resultat de validació i empremtes JA3/JA3S/JA4. Les empremtes són extensions habituals de lippycat, no camps bàsics de Zeek.

http.log

Una observació de transacció HTTP. trans_depth ordena les transaccions d’una connexió. Les columnes de petició/resposta descriuen mètode, autoritat i URI, capçaleres estàndard seleccionades, versió, longituds observades del cos, estat de resposta i resposta informativa. tags i proxied contenen anotacions de l’analitzador/proxy; els vectors de fitxers s’uneixen a files.log. password no es recull per defecte.

smtp.log

Una observació de transacció SMTP. Registra la profunditat de transacció, HELO i remitent/destinataris del sobre, capçaleres de missatge seleccionades i salts d’encaminament, última resposta del servidor, estat TLS, identificadors de fitxers adjunts i classificació de correu web. No registra el cos del missatge.

files.log

Una observació limitada d’entitat HTTP o adjunt SMTP. fuid és l’identificador del fitxer; source indica el protocol que el transporta; depth i parent_fuid descriuen la imbricació; analyzers descriu el processament. Les columnes de mida i pèrdua indiquen bytes observats, declarats, absents i de desbordament. Els hashes cobreixen els bytes recuperats; hash_complete només és cert quan se sap que aquests bytes representen tota l’entitat descodificada. Un valor fals significa que els hashes identifiquen un prefix observat i no s’han de comparar com hashes de fitxers sencers. extracted només s’estableix quan l’extracció explícita té èxit.

Rotació i operacions

Transport remot d’esdeveniments i retenció TUI

Els nodes Hunter i Tap poden reenviar registres normalitzats amb --forward-mode=events. El receptor obté esdeveniments, no els paquets originals: no estan disponibles l’escriptura PCAP superior, la injecció en interfícies virtuals ni l’anàlisi que necessita bytes de paquets. Un node Tap pot retenir PCAP local mentre reenvia esdeveniments quan calen totes dues coses.

El transport d’esdeveniments negocia compatibilitat d’API i semàntica. El reenviament de paquets és el valor per defecte compatible amb versions antigues; --event-fallback-to-packets permet un recurs explícit i registrat. El mode fiable utilitza spool limitat del productor i WAL d’entrada del processador, mentre que el mode només en memòria no resisteix caigudes.

La versió 1 de la subscripció d’esdeveniments TUI és només en viu i no ofereix reproducció. El recompte de pèrdua de transport representa buits o omissions abans de la visualització. El recompte separat d’expulsió local representa esdeveniments rebuts que han sortit de l’anell TUI limitat per antiguitat i no indica pèrdua de transport.

Cada flux activat té una cua limitada no bloquejant i un únic escriptor. Una cua d’esdeveniments o de flux plena descarta treball nou i incrementa comptadors; els avisos periòdics resumeixen els descarts. El control de flux del processador considera la pressió sostinguda de les cues d’esdeveniments i registres, incloent-hi cada cua de sortida del distribuïdor, però cap configuració de registre pot garantir sortida sense pèrdues. events.drop_policy accepta actualment drop_new; les polítiques no admeses fallen durant la inicialització.

L’anàlisi de fitxers HTTP i SMTP requereix bytes del cos a l’analitzador de captura. En un desplegament distribuït, inicieu l’ordre de protocol pertinent del node Hunter amb --capture-body i un --max-body-size adequat; el processador no pot recuperar posteriorment cossos que el node Hunter ha omès. L’anàlisi MIME SMTP també està condicionada per privadesa amb --log-include-email-body-preview. Les capçaleres HTTP i les previsualitzacions del cos del correu continuen desactivades llevat que s’estableixin les opcions d’activació respectives.

Els fitxers actius s’anomenen conn.log, dns.log, etc. A l’interval configurat, es tanca i reanomena un fitxer actiu, per exemple a conn-2026-08-22-14-30-00.log, i després s’obre un fitxer actiu nou en el registre següent. L’aturada ordenada amb SIGINT/SIGTERM buida les cues, escriu els registres pendents i els peus TSV. SIGKILL, una caiguda o un sistema de fitxers ple no ho poden fer.

L’ordre posterior a la rotació s’executa de manera asíncrona mitjançant /bin/sh; cada marcador %log% se substitueix per un camí amb cometes per a l’intèrpret d’ordres. Per exemple:

lc process --log-dir /var/log/lippycat \
  --log-post-rotate-command 'gzip %log%'

L’ordre té exactament els mateixos privilegis que el procés lippycat. Utilitzeu una ordre fixa controlada per l’administrador, eviteu secrets als arguments i superviseu els registres d’error de les accions. La retenció i la gestió de l’espai de disc continuen sent responsabilitat de l’operador.

Exemples d’entrada a SIEM

Per a JSONL, apunteu un agent a /var/log/lippycat/*.log, analitzeu un objecte JSON per línia i utilitzeu el nom del fitxer com conjunt de dades. Exemple de font/transformació Vector:

[sources.lippycat]
type = "file"
include = ["/var/log/lippycat/*.log"]
read_from = "beginning"

[transforms.lippycat_json]
type = "remap"
inputs = ["lippycat"]
source = '''
. = parse_json!(.message)
'''

Per a TSV, utilitzeu una entrada/analitzador que entengui les capçaleres Zeek i els fitxers rotats. El mòdul Zeek de Filebeat o una cadena Vector/Fluent Bit compatible amb Zeek són adequats; no tracteu les línies de capçalera com dades. Preserveu uid, community_id i node_id com cadenes exactes. Com que uid és local a un cicle de vida de flux observat, community_id és la clau preferida d’unió entre productes; incloeu el temps i node_id en resoldre col·lisions o connexions repetides.

Privadesa i seguretat

Els registres estructurats poden contenir dades personals: adreces IP, noms DNS, SNI, URL, adreces i assumptes de correu, agents d’usuari, noms de fitxer, identitats de certificat i identificadors estables de flux. Les cadenes de consulta i els camins poden contenir credencials o tokens. Restringiu els permisos del directori, xifreu l’emmagatzematge i el transport, definiu una política de retenció i recolliu només els fluxos justificats per la finalitat del monitoratge.

Els valors per defecte conservadors mantenen el registre i l’extracció desactivats, ometen capçaleres HTTP arbitràries, limiten tota l’anàlisi/extracció de fitxers i mai no posen càrregues útils de paquets, cossos HTTP/correu, RTP/contingut multimèdia ni bytes extrets a les files de registre de metadades. Activar l’extracció de fitxers crea fitxers de contingut separats i requereix controls d’accés proporcionalment més estrictes. Les opcions de fitxers estructurats no autoritzen el lliurament LI; les metadades LI continuen condicionades independentment per compilació, execució, tasca activa, objectiu i perfil de lliurament.

Observacions RADIUS

lc sniff radius -r radius.pcap --log-dir ./logs --log-streams radius selecciona el flux addicional d’observacions RADIUS de versió 1. Cada missatge vàlid seleccionat té el seu propi registre; els atributs utilitzen instàncies hexadecimals ordenades incloses en una llista permesa. La subordre específica sniff radius aplica la selecció ordinària abans d’escriure registres i comparteix la mateixa observació/àmbit amb les sortides CLI i de paquets, sense recomptes duplicats de validació. Les credencials, els autenticadors, les proves de tasca i els atributs desconeguts s’ometen dels registres habituals. PCAP i X2 mantenen els seus contractes separats de sortida de bytes. Consulteu Operacions RADIUS per veure selecció, àmbit, estat i comptadors.

DHCP, NTP i inventaris locals

La selecció per defecte continua sent conn,dns,ssl,http,smtp,files,radius. Quatre fluxos addicionals són opcionals: dhcp, ntp, known_hosts i known_services. Seleccioneu-los amb --log-streams; no calen subordres de protocol noves. Les observacions DHCP/NTP tipades també estan disponibles per als subscriptors d’esdeveniments i la TUI quan el registre de fitxers està desactivat.

lc sniff -r network.pcap --log-dir ./logs --log-streams dhcp,ntp
sudo lc tap -i eth0 --insecure --inventory \
  --inventory-local-cidrs 192.0.2.0/24,2001:db8::/32 \
  --log-dir ./logs --log-streams dhcp,ntp,known_hosts,known_services

Registres de missatge i associació

DHCP i NTP escriuen un registre per missatge acceptat, incloent-hi retransmissions del protocol. A diferència de l’agregació de transaccions/sessions de Zeek, una resposta afegeix un registre nou i mai no reescriu ni consumeix una petició. El sobre conserva els extrems UDP observats, l’UID del flux, Community ID, l’àmbit de captura i la font. Els identificadors d’associació proporcionen un context d’intercanvi separat i limitat; els reintents de transport conserven la identitat original de transmissió i es dedupliquen a l’entrada.

DHCP cobreix els tipus de missatge DHCPv4 1–8, incloent-hi decline, release i inform. DHCPv6 i BOOTP pur s’exclouen d’aquest registre; la detecció BOOTP continua disponible. Els registres mantenen separades les adreces next-server i server-identifier. Els identificadors de maquinari/client utilitzen sortida hexadecimal, sense assumir mai que són text imprimible. Les opcions absents queden sense establir; una concessió present de valor zero continua sent zero. Les opcions repetides i les àrees d’opcions sobrecarregades es validen dins de lectors limitats. Els missatges malformats acceptats mostren partial i, per a entrada incompleta, truncated; no es registren bytes d’opcions desconegudes o de fabricant.

L’associació DHCP separa autoritat/època/font de captura, identitat de client, identificador de transacció, context de retransmissor i distincions de servidor. Mai no uneix clients utilitzant només l’identificador de transacció ni fabrica un únic UID de flux entre difusions i canvis d’adreça. La caducitat o expulsió de l’associació no suprimeix el missatge actual. No es promet un historial complet de concessions.

NTP cobreix els modes de missatge de temps 1–5. S’exclouen modes de control/privats, anàlisi NTS, autenticació, conclusions de qualitat del rellotge i càlculs de desplaçament del rellotge del client. Els valors de poll/precision i retard arrel amb signe conserven el signe; la dispersió arrel i les marques de temps 32.32 en brut conserven els valors exactes de la xarxa. Les marques de temps en brut són cadenes hexadecimals. Les marques zero no estan disponibles; les conversions no zero utilitzen l’era més pròxima al temps de captura. Els identificadors de referència continuen sent quatre bytes en brut perquè la interpretació depèn de la versió i l’estrat.

L’associació client/servidor NTP requereix àmbits coincidents, extrems invertits i la marca de temps de petició retornada. Les marques de temps duplicades són ambigües. Els missatges sense coincidència, de difusió i simètrics continuen generant registres. Tots dos protocols utilitzen els estats d’associació request, unique, missing, ambiguous, expired, capacity_suppressed i not_applicable; aquests estats mai no afirmen autenticació.

Proves i política d’inventari

Els esdeveniments d’inventari estan activats per defecte per a tots els amfitrions i serveis unicast observats que compleixin els requisits. Desactiveu-los amb --inventory=false, o restringiu opcionalment els subjectes amb IPv4/IPv6 --inventory-local-cidrs. Els CIDR no restringeixen la captura de paquets. Només els CIDR configurats explícitament classifiquen els extrems de connexió com locals; una llista buida no marca totes les adreces observades com locals, i l’espai privat no és implícitament local. S’exclouen subjectes no especificats, multicast i de difusió. Els fluxos de registre d’inventari continuen sent opcionals i requereixen una política local compatible o fonts d’esdeveniments compatibles que produeixin inventari. Configureu els nodes Hunter pel seu camí normal de configuració; els processadors no els distribueixen aquesta política.

L’activació de l’inventari és una política d’anàlisi, no una petició de sortida. sniff sense consumidors no crea cap entorn opcional d’esdeveniments; els registres estructurats, una sortida explícita d’esdeveniments o l’extracció de fitxers sol·licitada l’activen. La descodificació ordinària de protocols, la selecció i la sortida de paquets continuen disponibles sense aquest entorn. Les altres topologies conserven els seus propis consumidors d’esdeveniments i cicle de vida. L’equivalent YAML de --inventory=false és events.inventory.enabled: false. Els CIDR delimiten els subjectes d’inventari, no la captura de paquets ni el cost de l’anàlisi de connexions i protocols.

Els amfitrions coneguts requereixen una negociació TCP completa observada o totes dues direccions UDP. Els serveis coneguts requereixen addicionalment un responent orientat de manera fiable, el seu port i un protocol sustentat per anàlisi real. Un SYN aïllat, una adreça de destinació, una oferta DHCP, una pista de port o una etiqueta de protocol en cau són insuficients. Els registres de servei UDP requereixen un intercanvi DNS, NTP o DHCP admissible descodificat i associat correctament. S’ometen responents ambigus i conjectures de servei de client de difusió/retransmissor. Els valors de prova són tcp_handshake, udp_bidirectional, dns_exchange, ntp_exchange i dhcp_exchange.

Els esdeveniments d’inventari s’emeten tan aviat com estan disponibles les proves de paquets necessàries, sense esperar la caducitat de la connexió. Els resums ordinaris de connexió conserven el comportament existent de caducitat, expulsió, EOF, reinicialització o tancament. En mode remot de paquets, la TUI deriva localment esdeveniments d’inventari dels paquets rebuts; utilitzeu la vista All i filtreu per known per trobar-los. La connexió que compleix els requisits proporciona el sobre; el camp separat host és el subjecte. La captura parcial continua visible. L’entrada d’esdeveniments i els retransmissors jeràrquics reenvien els esdeveniments d’inventari derivats a la font sense derivar-ne una segona còpia.

La deduplicació d’amfitrions inclou àmbit i adreça; les claus de servei també inclouen port del responent, transport i protocol. L’àmbit separa nodes d’origen, èpoques de productor/captura i interfícies o entrades fora de línia. S’emet la primera observació que compleix els requisits dins de la finestra de retenció; la caducitat o expulsió permet una reemissió posterior. És un inventari limitat d’observacions, no una identitat permanent d’actius. Els límits d’entrades i bytes comptabilitzats s’apliquen globalment i per àmbit.

Les marques de progrés del temps de captura mai no retrocedeixen, incloent-hi la reproducció fora de línia; l’entrada tardana no pot reactivar estat caducat. La reinicialització esborra l’estat d’associació/deduplicació, i EOF/tancament buiden els resums de connexió. La identitat fora de línia inclou la política efectiva i la revisió d’anàlisi; els canvis de política en viu requereixen un límit de sessió del productor. Els CIDR invàlids i els límits d’estat o temps d’espera zero/negatius fallen la validació. L’inventari desactivat no reté estat d’inventari. La pressió d’associació, la pèrdua d’esdeveniments i l’expulsió de l’anell TUI tenen comptadors diferents. Consulteu les opcions compartides i les opcions d’ordres.

Privadesa i compatibilitat

Els identificadors DHCP de maquinari/client, el nom d’amfitrió i el domini requereixen tant una petició del subscriptor de camps sensibles com permís del servidor mitjançant --event-allow-sensitive-fields. Els detalls de subjecte/servei d’inventari utilitzen la mateixa política: s’ometen esdeveniments d’inventari no autoritzats amb còmput explícit de pèrdua per política. La projecció no modifica els esdeveniments compartits ni desactiva la correlació interna. Les metadades de capçalera NTP no requereixen cap activació addicional de camps sensibles. Els registres locals seleccionats explícitament inclouen aquests camps sensibles; restringiu l’accés als fitxers, l’emmagatzematge i la retenció.

Els quatre tipus amplien la versió 1 de l’API d’esdeveniments sense renumerar tipus existents ni canviar el perfil semàntic. Els tipus admesos són diferents dels requisits dels consumidors configurats. Els interlocutors antics poden continuar les càrregues existents quan els tipus nous són opcionals, amb informes explícits de pèrdua de compatibilitat per omissions. Els fluxos obligatoris no disponibles rebutgen la negociació o utilitzen un recurs a paquets configurat explícitament; mai no tenen èxit silenciosament amb sortida absent. Les regles existents de confirmació de spool/WAL i preservació de camps desconeguts continuen aplicant-se.