Maltrail

Maltrail è un sistema di rilevamento del traffico di rete che identifica la comunicazione con infrastrutture malevole note e segnala specifiche anomalie di traffico. Confronta domini, URL, indirizzi IP, coppie IP:port e valori User-Agent osservati sulla rete con un insieme di indicatori chiamati trails.

Un rilevamento viene registrato come un singolo evento contenente l'origine, la destinazione, il protocollo, il trail corrispondente, la classificazione e la fonte del trail:```text "2026-08-07 09:14:22.117034" gw 10.13.13.2 57809 1.1.1.1 53 UDP DNS malware.bakewithdavid.com "asyncrat (malware)" (static)

Maltrail è progettato per il monitoraggio di rete basato su indicatori. Le sue rilevazioni euristiche integrano
la corrispondenza dei trail, ma non sostituiscono la telemetria degli endpoint o un sistema di prevenzione
delle intrusioni generico.

## Funzionalità

- Una build completa dei trail che combina più di 3.000 file statici inclusi, 42 integrazioni con feed pubblici
  e trail opzionali forniti dall'operatore.
- Un sensore Rust multithread che utilizza libpcap, con worker di cattura Linux `PACKET_FANOUT` opzionali.
- Un server Python che fornisce l'interfaccia di reporting, l'acquisizione degli eventi e l'API HTTP.
- Trail personalizzati e whitelist in testo semplice che possono essere revisionati e versionati.
- Euristiche per lo scanning, l'esaurimento DNS, le ricerche di tipo DGA, i download sospetti, le sonde proxy,
  i valori User-Agent sospetti e attività di rete correlate.
- Logging locale degli eventi, logging remoto Maltrail, CEF su syslog e output Logstash JSON.
- Validazione del deployment con `maltrail-sensor -T` e metriche Prometheus opzionali.

## Contenuti

- [Architettura](#architecture)
- [Interfaccia di reporting](#reporting-interface)
- [Prestazioni](#performance)
- [Installazione](#installation)
  - [Installer](#installer)
  - [Compilazione dai sorgenti](#building-from-source)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [Configurazione](#configuration)
- [Trail](#trails)
- [Eventi e API](#events-and-api)
- [Operazioni](#operations)
  - [Monitoraggio](#monitoring)
  - [Conservazione degli eventi](#event-retention)
- [Documentazione](#documentation)
- [Contribuire](#contributing)
- [Progetto](#project)
  - [Licenza](#license)
  - [Maintainer](#maintainers)
  - [Sponsor](#sponsors)
  - [Presentazioni e pubblicazioni](#presentations-and-publications)
  - [Blacklist derivata](#derived-blacklist)
  - [Integrazioni di terze parti](#third-party-integrations)
  - [Ringraziamenti](#acknowledgements)

## Architettura

Maltrail è composto da due processi indipendenti che possono essere eseguiti sullo stesso host o su host separati:```text
   ┌──────────┐   events (UDP or file)   ┌──────────┐
   │  sensor  │ ───────────────────────► │  server  │ ◄── browser
   └──────────┘                          └──────────┘
    Rust                                  Python
    libpcap + PACKET_FANOUT               reporting UI + API
    trail matching + heuristics

Il sensore cattura il traffico, esegue il trail matching e l'analisi euristica e produce eventi. Può scrivere gli eventi localmente (LOG_DIR), inviarli a un server Maltrail remoto (LOG_SERVER) o entrambe le cose. Può anche emettere CEF su syslog (SYSLOG_SERVER) e JSON verso Logstash (LOGSTASH_SERVER).

Il server riceve e memorizza gli eventi remoti, serve i log degli eventi disponibili localmente e fornisce l'interfaccia web e l'API.

Interfaccia di reporting

Maltrail include un'interfaccia di reporting basata su browser per esplorare il traffico rilevato, con aggiornamenti in tempo reale, ricerca per campo, retro hunting, viste geografiche, triage, viste salvate ed esportazione.

L'interfaccia è servita da server.py su HTTP_ADDRESS:HTTP_PORT. È JavaScript puro con una singola dipendenza runtime di terze parti (PapaParse, per il parsing CSV) e nessuna fase di build. Si visualizza un giorno alla volta, selezionato con un date picker che funge anche da griglia di densità degli eventi sui log giornalieri disponibili. Gli eventi sono trasmessi in streaming da /events e aggregati nel browser in threat — una riga per ogni distinta coppia (source, trail) — mostrate in una griglia ordinabile con un pannello di dettaglio.

Funzionalità	Note
Modalità live	Gli eventi aggiunti vengono inviati tramite Server-Sent Events (/live) e uniti alla vista corrente. Se SSE non è disponibile, o per le sessioni che lo stream non riesce a servire, si passa al polling di intervalli di byte del log giornaliero. Le nuove threat ad alta severità possono generare una notifica desktop e un avviso sonoro; entrambi possono essere silenziati
Ricerca	Token con ambito di campo (src: dst: port: proto: type: trail: info: family: tag: uid: sev: dir: status:; family:interlock include interlock-1/-2, gli shard in cui arriva suddiviso un dump di feed) combinati con lo spazio come AND, - per escludere, wildcard *, CIDR (src:10.0.0.0/8) e intervalli e confronti numerici (port:>1024, count:>=100). I filtri attivi appaiono come chip rimovibili
Retro hunt	Cerca in tutti i log giornalieri conservati un indicatore (/hunt), non solo nel giorno visualizzato. Limitato da un limite di giorni, un budget di tempo reale e un tetto di campioni; un giorno interrotto dal budget viene riportato separatamente dai giorni completati anziché essere conteggiato come totale completato. Un indice sidecar per giorno (LOG_DIR/index/, USE_EVENT_INDEX) consente alla scansione di saltare ogni riga non corrispondente e rende /counts esatto
Mappa mondiale	Densità degli eventi per paese per il giorno selezionato (/geo), posizionando l'endpoint esterno di ogni evento. Gli eventi che non possono essere attribuiti a un indirizzo esterno vengono riportati come non mappati anziché essere indovinati. Imposta HOME_LAT / HOME_LON per disegnare gli archi di origine
Triage	Stato per threat (nuova / in analisi / risolta / falso positivo), note libere, tag e occultamento. Le regole di whitelist e i pivot OSINT sono disponibili dal menu contestuale della riga
Viste salvate	Preset di filtri con nome
Esportazione	La vista filtrata corrente come CSV, JSON o indicatori defanged
Aspetto	Temi scuro e chiaro e passi discreti di dimensione del testo

Lo stato di triage, le viste salvate, i tag e le impostazioni di aspetto sono memorizzati nel browser (localStorage), non sul server: sono per browser e per origine, e non sono condivisi tra gli analisti.

Le sessioni limitate con un filtro di rete vedono solo gli eventi provenienti dalle proprie reti, e tale restrizione si applica anche agli endpoint counts, map e blacklist oltre che all'elenco degli eventi.

L'arricchimento con paese e ASN per singoli indirizzi viene cercato su stat.ripe.net dal server, che memorizza i risultati nella cache e li serve all'interfaccia dal proprio endpoint /ripe; il browser non comunica con nient'altro che Maltrail. Imposta DISABLE_RIPE_LOOKUPS per disattivare del tutto le ricerche in uscita. Senza di esse — o su un host senza accesso a Internet — le bandiere provengono invece dalla tabella RIR locale e tutto il resto nell'interfaccia funziona offline.

Prestazioni