maltrail v3.2
Sistema di rilevamento del traffico malevolo in tempo reale che utilizza blacklist pubbliche, tracce statiche di malware e analisi euristica per identificare minacce nel traffico DNS, HTTP e IP.
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
Le prestazioni dipendono da processore, composizione del traffico, dimensione del trail-set, driver di cattura e interfaccia di rete. Le cifre seguenti misurano il percorso di elaborazione dei pacchetti del sensore in isolamento; non sono misurazioni end-to-end di cattura live.
Misurazioni rappresentative su un AMD Ryzen 7 PRO 4750U con euristiche abilitate e un trail set da 1,5 milioni di righe:
| Traffico | Tempo per pacchetto |
|---|---|
| ICMP echo, 58 byte | 101 ns |
| TCP SYN, 70 byte | 302 ns |
| TLS in blocco, 1.473 byte | 402 ns |
| Query DNS con cache calda, 93 byte | 452 ns |
| Traffico misto, media 866 byte | 552 ns |
| Richiesta HTTP, 169 byte | 602 ns |
| Query DNS con nome univoco, 93 byte | 1.102 ns |
Esecuzioni di confronto offline usando la stessa cattura generata, configurazione e trail set hanno misurato un
costo per pacchetto a regime inferiore di 14–37× rispetto al sensore Python dismesso sui sistemi testati.
Quelle cifre separano il tempo dell'intero processo dallo stato stazionario, perché il caricamento del trail domina un
replay breve. Il rilevamento stesso è verificato separatamente, dal corpus di 42 casi in
sensor/tests/replay.rs.
Misuralo sul sistema di destinazione con:```bash cargo bench --manifest-path sensor/Cargo.toml --bench hotpath
Un capture worker viene utilizzato per impostazione predefinita. Worker aggiuntivi possono aumentare la capacità di cattura, ma l'hashing dei flussi di Linux divide lo stato per sorgente tra i worker e quindi riduce la sensibilità di alcune euristiche di scansione. Nel test documentato, il 91% degli avvisi euristici con un singolo worker è rimasto con due worker, l'86% con quattro e il 65% con otto. La corrispondenza esatta delle tracce è rimasta invariata. Aumentare `CAPTURE_FANOUT` solo quando le metriche di perdita di cattura mostrano che è necessario.
La metodologia di benchmark, i risultati hardware, l'output del profiler, le misurazioni della memoria e i controlli di fanout in tempo reale sono documentati in [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md).
## Installazione
### Installer
L'installer è verificato su dodici distribuzioni Linux — Debian, Ubuntu, Fedora, Rocky, AlmaLinux, Arch, openSUSE Leap e Tumbleweed, e Alpine — più FreeBSD e macOS, a ogni rilascio, con il risultato completo registrato in [`docs/compat`](https://github.com/stamparm/maltrail/blob/master/docs/compat). Raspberry Pi OS e altri sistemi ARM a 64 bit utilizzano la build `aarch64`; ARM a 32 bit non ha un sensore precompilato e deve compilarlo dal sorgente.```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh
Installa le dipendenze, crea un checkout gestito sotto /opt/maltrail, verifica il checksum
del sensore precompilato, crea un account maltrail non privilegiato, installa le unit systemd, prepara
le directory di log e di stato, e avvia il sensore e il server. Rieseguire l'installer aggiorna
il checkout gestito.
Esamina lo script prima di eseguirlo con privilegi elevati. Da un checkout esistente, la dry run mostra i comandi senza modificare il sistema:```bash sh install.sh --dry-run
Opzioni comuni dell'installer:```bash
sh install.sh --role sensor # Install only the sensor
sh install.sh --ref 3.1.2 # Install a release tag instead of master
sh install.sh --no-service # Install without changing systemd
sh install.sh --dry-run # Print commands without applying them
sh install.sh --uninstall # Remove the managed installation; keep logs and state
La dashboard è disponibile all'indirizzo http://127.0.0.1:8338 dopo l'installazione. Si noti che il valore predefinito di
HTTP_ADDRESS è 0.0.0.0, quindi è raggiungibile su ogni interfaccia, non solo su loopback — e
le credenziali predefinite sono admin / changeme!. Modificare USERS e impostare HTTP_ADDRESS su
127.0.0.1 (oppure mettere il server dietro un reverse proxy con TLS), prima che l'host si trovi su una
rete non attendibile.
La build iniziale del trail può richiedere diversi minuti. Il sensore non rileva corrispondenze nel trail finché non è
disponibile un set di trail valido. L'unità systemd esegue la validazione -T del sensore prima dell'avvio, in modo
che privilegi mancanti, una directory di log non scrivibile o un set di trail non valido causino un fallimento
visibile all'avvio.
L'harness di test dell'installer copre dodici distribuzioni, e "si è installato" non è l'asserzione: in
ciascuna il server viene avviato e viene interrogato su /ping, al sensore viene chiesto di validarsi con
-T, si verifica che i percorsi delle unità siano risolvibili, l'installer viene rieseguito per dimostrare che un aggiornamento
mantiene la configurazione dell'operatore, e viene eseguito --uninstall. Ogni risultato è registrato per piattaforma in
docs/compat, e la pagina lì presente è generata da quelle righe anziché scritta
a mano.
Alpine e altri sistemi musl ricevono una build del sensore -musl. In precedenza veniva detto loro che il binario precompilato
era collegato a glibc e di compilarne uno proprio; il sensore si compila e funziona nativamente su musl, quindi quello era
un artefatto mancante piuttosto che un limite della piattaforma.
Compilazione dal sorgente
Il sensore richiede Rust 1.74 o successivo, gli header di sviluppo di libpcap e gli strumenti di capability del sistema. Il server e l'aggiornatore dei trail richiedono Python 3.6 o successivo.
Installare i pacchetti della distribuzione:```bash
Debian / Ubuntu / Raspberry Pi OS
sudo apt-get install cargo libpcap-dev libcap2-bin python3
RHEL / Fedora
sudo dnf install cargo libpcap-devel libcap python3
openSUSE / SLES
sudo zypper install cargo rust libpcap-devel libcap-progs python311
Poi compila e convalida il sensore:```bash
git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail
cargo build --release --manifest-path sensor/Cargo.toml
sudo setcap cap_net_raw,cap_net_admin=eip \
sensor/target/release/maltrail-sensor
sudo install -d -o "$USER" -g "$(id -gn)" -m 750 /var/log/maltrail
sensor/target/release/maltrail-sensor -T
sensor/target/release/maltrail-sensor
Avvia il server in un altro terminale o su un altro host:```bash python3 server.py
I binari precompilati del sensore sono allegati alle release correnti con checksum SHA-256: Linux `x86_64`
e `aarch64` sia per glibc che per musl, macOS su Apple silicon e Intel, FreeBSD `amd64` e
Windows `x86_64`.
Le build glibc collegano libpcap staticamente e hanno come target glibc 2.28, quindi la libreria C è l'unica cosa
di cui hanno bisogno — nulla da installare, su RHEL 8+, Debian 10+, Ubuntu 18.04+ e Leap 15.x allo stesso modo. Le build
musl sono completamente statiche, quindi Alpine non necessita di nulla. La build Windows è a 64-bit e richiede Windows 10 o successivo più
[Npcap](https://npcap.com) installato prima di avviarsi — `wpcap.dll` è una dipendenza a load-time,
quindi senza di essa il loader rifiuta l'eseguibile anziché fallire alla cattura. Lo dice anche
l'archivio.
I binari dalla **3.1.1 e precedenti** no: collegavano libpcap dinamicamente e la richiedevano con
il nome usato dal loro host di build AlmaLinux. Debian e Ubuntu distribuiscono la libreria identica sotto il
vecchio nome `libpcap.so.0.8`, quindi quei binari si fermano prima di partire —```
./maltrail-sensor: error while loading shared libraries: libpcap.so.1: cannot open shared object file
— su una macchina che ha libpcap installato. install.sh collega il nome mancante per te. Manualmente:```bash
adjust the directory for your architecture: aarch64-linux-gnu, or /usr/lib64 on RPM distributions
sudo ln -sf /usr/lib/x86_64-linux-gnu/libpcap.so.0.8 /usr/lib/x86_64-linux-gnu/libpcap.so.1 sudo ldconfig
### Systemd
Le unit `packaging/systemd/` fornite eseguono entrambi i processi come
utente non privilegiato `maltrail`. Systemd crea `/var/log/maltrail` e `/var/lib/maltrail`, limita
l'accesso al filesystem e concede al sensore `CAP_NET_RAW` e `CAP_NET_ADMIN`.
L'installer configura automaticamente queste unit. Per un'installazione da sorgente esistente, seguire
la procedura manuale del servizio in [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md).
Verificare lo stato del servizio e i log con:```bash
systemctl status maltrail-sensor maltrail-server
journalctl -u maltrail-sensor -f
Docker
Avvia il deployment Compose fornito con:```bash docker compose -f docker/docker-compose.yml up -d
La configurazione del container, lo storage, i privilegi e gli health check sono documentati in
[`docker/README.md`](https://github.com/stamparm/maltrail/blob/master/docker/README.md).
## Configurazione
Maltrail legge `maltrail.conf`, che contiene impostazioni separate `[Sensor]` e `[Server]`. L'
installer colloca la configurazione gestita in `/etc/maltrail.conf`.
Le opzioni del sensore usate più frequentemente includono:
| Opzione | Scopo |
| --- | --- |
| `MONITOR_INTERFACE` | Interfaccia o interfacce di cattura; `any` seleziona tutte le interfacce supportate |
| `CAPTURE_FILTER` | Filtro di cattura BPF |
| `CAPTURE_FANOUT` | Numero di socket di cattura Linux; il valore predefinito è uno |
| `CAPTURE_WORKERS` | Worker di cattura, un socket ciascuno; il valore predefinito è `CAPTURE_FANOUT`, quindi uno a meno che non venga impostato l'uno o l'altro |
| `LOG_DIR` | Directory locale dei log degli eventi |
| `TRAILS_FILE` | Database delle trail generato |
| `LOG_SERVER` | Server eventi Maltrail remoto |
| `SYSLOG_SERVER` | Destinazione o destinazioni syslog CEF |
| `LOGSTASH_SERVER` | Destinazione o destinazioni Logstash JSON |
| `STATS_ADDRESS` | Listener delle metriche Prometheus; disabilitato se non configurato |
| `UPDATE_PERIOD` | Intervallo di aggiornamento delle trail |
| `STATIC_TRAILS_URL` | Da dove viene recuperato l'insieme statico di trail assemblato; fissalo a una release datata per controllare quando arrivano nuovi contenuti |
| `USER_WHITELIST` | Indicatori gestiti dall'operatore che non devono generare alert |
| `CUSTOM_TRAILS_DIR` | Directory delle trail gestita dall'operatore |
| `STATIC_TRAILS_DIR` | Checkout opzionale del repository delle trail; usato solo per mostrare la citazione della fonte di una trail nell'interfaccia |
`PROCESS_COUNT` si applica al sensore Python dismesso e al throttle legacy dei log degli eventi; **non**
imposta il numero di worker del sensore Rust. Configura i worker di cattura con `CAPTURE_FANOUT` o
`CAPTURE_WORKERS`.
Esegui il controllo di deployment dopo aver modificato la configurazione:```bash
sensor/target/release/maltrail-sensor -T
Il controllo convalida configurazione, trail, voci della whitelist, filtro di cattura, privilegi, archiviazione dei log, supporto agli aggiornamenti e impostazioni dei worker. Un controllo riuscito include conteggi positivi di trail e whitelist, non solo la conferma che i file esistano.
Trails
Un trail è un singolo indicatore — un dominio, URL, indirizzo IP, coppia IP:port, User-Agent, impronta JA3/JA4 o hash di certificato — insieme a ciò che significa e da dove proviene. L'updater unisce quattro fonti in TRAILS_FILE, in questo ordine:
| fonte | da dove proviene |
|---|---|
| Feed | feeds/*.py, recuperati direttamente dalla tua distribuzione da ciascun publisher |
| Custom | CUSTOM_TRAILS_DIR e CUSTOM_TRAILS_URL, i tuoi indicatori |
| Static | l'insieme assemblato da stamparm/trails, recuperato da STATIC_TRAILS_URL; con licenza separata |
| Engine lists | data/mass_scanner*.txt, inclusi qui perché cambiano raramente |
I trail statici risiedono in un repository separato. Il contenuto di rilevamento cambia decine di volte al giorno; il motore no, e tenerli insieme significava che aggiornare il rilevamento richiedeva di scaricare il codice e rendeva inutilizzabile la cronologia di questo repository. STATIC_TRAILS_URL punta all'insieme pubblicato più recente:```text
STATIC_TRAILS_URL https://github.com/stamparm/trails/releases/latest/download/trails.csv.gz
Puntalo a una release specifica `content-YYYYMMDD-HHMM` per fissare una versione, così una pubblicazione errata
non diventa immediatamente globale. Il set viene memorizzato nella cache accanto a `TRAILS_FILE`, ed è ciò che rende possibile una ricostruzione offline
o air-gapped; lo `sha256` pubblicato viene verificato prima del download, quindi un deployment
che si aggiorna più spesso di quanto cambi il contenuto trasferisce 65 byte anziché 11 MB, e un
payload che non corrisponde al suo digest viene rifiutato in favore della cache.
`update_trails()` pubblica un nuovo `TRAILS_FILE` in modo atomico e solo dopo una build riuscita. I feed
che non restituiscono nulla vengono segnalati per nome, così un deployment non dipende silenziosamente da una fonte che
si è ritirata senza avvisare.
Aggiungi i tuoi indicatori sotto `CUSTOM_TRAILS_DIR`, e qualsiasi cosa che non debba mai generare un evento a
`USER_WHITELIST`. Mantieni entrambi fuori dalla directory di installazione in modo che un aggiornamento non possa sovrascriverli.
I contributi di trail statici vanno a [stamparm/trails](https://github.com/stamparm/trails); i nuovi feed
vanno qui. In entrambi i casi un indicatore necessita di una classificazione e di una fonte che qualcuno possa verificare — vedi
[Contributing](#contributing).
## Events and API
Maltrail registra un evento separato da spazi bianchi per ogni rilevamento, usando la quotatura CSV dove un valore
contiene spazi:```text
"<time>" <sensor> <src_ip> <src_port> <dst_ip> <dst_port> <proto> <type> <trail> "<info>" <reference>
Il campo type identifica ciò che ha corrisposto, inclusi DNS, IP, IPORT, URL, PATH, HTTP,
UA, PORT, CERT, JA3 e JA4. Il campo info contiene la classificazione della traccia, e
reference identifica la lista statica, il feed, la sorgente personalizzata o l'euristica che l'ha prodotta. I
tipi JA3/JA4 si attivano sulle impronte TLS del client: lo stack TLS di un impianto sopravvive a ogni
rotazione di indirizzo e dominio, quindi il suo hash hello continua a corrispondere dopo che tutto il resto è stato bruciato
(pubblicato dal feed abuse.ch SSLBL JA3).
Ricerca degli indicatori
Usa /check per interrogare un dominio, un indirizzo IP o un URL:```bash
curl 'http://127.0.0.1:8338/check?q=www.sub.evil.example'
- **`--proxy`** — instrada il traffico attraverso un proxy HTTP/SOCKS5 (ad es. `--proxy http://127.0.0.1:8080` o `--proxy socks5://127.0.0.1:1080`).
- **`--proxy-auth`** — credenziali per il proxy (`user:pass`).
- **`--proxy-insecure`** — salta la verifica del certificato TLS quando si parla con un proxy HTTPS.
- **`--timeout`** — timeout per richiesta in secondi (predefinito: 30).
- **`--retries`** — numero di tentativi per le richieste non riuscite (predefinito: 3).
- **`--delay`** — ritardo tra le richieste in millisecondi (predefinito: 0).
- **`--concurrency`** — numero di richieste concorrenti (predefinito: 10).
- **`--user-agent`** — stringa User-Agent personalizzata.
- **`--random-agent`** — seleziona casualmente uno User-Agent da una lista integrata.
- **`--header`** — intestazione personalizzata (può essere ripetuta).
- **`--cookie`** — stringa di cookie da inviare con ogni richiesta.
- **`--follow-redirects`** — segui i reindirizzamenti HTTP (predefinito: true).
- **`--max-redirects`** — numero massimo di reindirizzamenti da seguire (predefinito: 10).
- **`--insecure`** — disabilita la verifica del certificato TLS.
- **`--output`** — file di output per i risultati (predefinito: stdout).
- **`--format`** — formato di output: `text`, `json`, `csv` (predefinito: text).
- **`--verbose`** — abilita l'output dettagliato.
- **`--quiet`** — sopprime l'output non essenziale.
- **`--no-color`** — disabilita l'output colorato.
- **`--config`** — percorso di un file di configurazione.
- **`--version`** — mostra la versione del programma ed esce.
- **`--help`** — mostra il messaggio di aiuto ed esce.```json
{
"query": "www.sub.evil.example",
"found": true,
"trail": "evil.example",
"info": "asyncrat (malware)",
"reference": "(static)",
"confidence": 100
}
Il campo confidence (0-100, o null quando non disponibile) indica quanto fortemente le fonti supportano la voce: 40 per un singolo feed, +15 per ogni feed aggiuntivo che concorda in modo indipendente fino a 100, e punteggio pieno per le voci personalizzate e statiche dell'operatore. Viene calcolato al momento dell'aggiornamento dei trail dalla concordanza dei feed in un sidecar trails.confidence accanto a trails.csv; un server che estrae i trail da un UPDATE_SERVER non ha provenienza da valutare e riporta null. Usalo per dare priorità al triage - una voce da un singolo feed a 40 merita un secondo controllo prima di guadagnarsi una regola firewall.
Una ricerca di sottodominio può corrispondere al suo parent elencato. Le ricerche URL controllano host/path prima di controllare il solo host. Il server legge il database dei trail memory-mapped e osserva gli aggiornamenti dei trail senza un riavvio.
I trail statici pubblici e dei feed sono disponibili senza autenticazione, coerentemente con l'endpoint /trails usato dai sensori remoti. I trail personalizzati richiedono una sessione autorizzata; una ricerca solo personalizzata non autorizzata viene riportata come mancata corrispondenza. I dati degli eventi rimangono autenticati.
Operazioni
Monitoraggio
Usa maltrail-sensor -T come gate di deployment e configurazione. L'unità systemd fornita lo esegue come ExecStartPre.
Per confermare che il rilevamento stesso funzioni — non solo che i processi si avviino — esegui:```bash python3 server.py --detect-test
Riproduce un pcap creato ad hoc di traffico malevolo emulato (corrispondenze su una query DNS, un IP, un
`IP:port`, un percorso URL e un header `Host`, più le euristiche di SQL-injection, traversal, RCE, XSS, proxy-probe,
sinkhole, `Host` mancante e port/web/infection-scanning) attraverso il sensore installato
e verifica che ogni rilevamento atteso scatti. Non richiede root, né interfaccia, né un proprio set di trail. Un'installazione sana stampa `20/20 detection(s) fired`.
Quando `STATS_ADDRESS` è configurato, monitora almeno queste metriche Prometheus:
| Metrica | Significato operativo |
| --- | --- |
| `maltrail_up == 0` | Nessun worker di cattura è in esecuzione |
| `maltrail_capture_dropped_total` in aumento | Il ring di cattura sta scartando pacchetti |
| `maltrail_local_log_errors_total` in aumento | Gli eventi sono stati prodotti ma non è stato possibile scriverli localmente |
| `maltrail_remote_log_errors_total` in aumento | Gli eventi non sono stati consegnati a un sink remoto; con `DISABLE_LOCAL_LOG_STORAGE` vengono persi |
| `maltrail_trail_generation` che non avanza | Il set di trail attivo non viene aggiornato |
| `maltrail_log_dir_free_bytes` | Capacità residua per l'archiviazione locale degli eventi |
| `maltrail_state_saturations_total` in aumento | È stato raggiunto un limite di stato dell'euristica |
| `maltrail_throttle_evictions_total` in aumento | La tabella di throttling degli eventi è al limite, quindi gli eventi vengono aggregati prima di quanto configurato |
La saturazione dello stato influisce sull'euristica corrispondente; la corrispondenza esatta dei trail rimane attiva.
Invia `SIGHUP` o usa `systemctl reload maltrail-sensor` per richiedere un ricaricamento dei trail. I file di trail
aggiornati da un altro processo vengono rilevati automaticamente e pubblicati ai worker senza riavviare
il sensore.
Lo store osservabile condensato (`USE_CONDENSED_STORAGE`, `meta.sqlite`) supporta le viste di novità e retro-hunt del
server. L'indice sidecar del registro eventi giornaliero (`USE_EVENT_INDEX`,
`LOG_DIR/index/*.sqlite`, all'incirca il doppio della dimensione dei log su disco) è ciò che rende `/counts` esatto e
`/hunt` veloce; viene mantenuto in modo incrementale dai log stessi e può essere ricostruito con
`server.py --rebuild-index`. La compatibilità con il sensore ritirato è documentata in
[`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md).
### Conservazione degli eventi
Maltrail non ruota né elimina i registri eventi. Gli operatori sono responsabili della definizione di conservazione,
archiviazione ed eliminazione in base ai requisiti di archiviazione e alle politiche organizzative.
Pratiche consigliate:
- Invia la copia durevole degli eventi a un server Maltrail remoto o a un SIEM con `LOG_SERVER`,
`SYSLOG_SERVER` o `LOGSTASH_SERVER`.
- Attiva avvisi su `maltrail_log_dir_free_bytes` con margine sufficiente per il tasso di eventi previsto.
- Ruota, archivia o rimuovi i log giornalieri locali usando strumenti esterni.
- Mantieni non compressi in `LOG_DIR` i file necessari all'interfaccia di reporting; archivia i file compressi
altrove.
Quando il filesystem dei log è pieno, il sensore non può aggiungere eventi. I registri eventi possono anche contenere indirizzi
IP e domini che in alcune giurisdizioni sono regolati come dati personali; la politica di conservazione
dovrebbe tenere conto dei requisiti applicabili.
### Traffico sintetico
Per verificare che il rilevamento e la dashboard funzionino ancora, senza attendere traffico reale:```bash
python3 server.py --detect-test # assert every detection fires, then exit
python3 server.py --detect-test --keep DIR --serve # ...and keep the events, serving them on :8338
--keep riproduce anche sensor/tests/corpus/ nello stesso log e stampa quali delle forme che la
dashboard renderizza diversamente hanno un evento dietro di esse, così un'icona, un colore o un glifo mancante è
visibile anziché presunto. I timestamp vengono spostati in modo che il giorno più recente sia oggi. È richiesto un binario del sensore
(cargo build --release --manifest-path sensor/Cargo.toml).
I dati della demo pubblica vengono rigenerati da un'esecuzione di questo tipo:```bash python3 sensor/tools/gen_demo_js.py --from DIR/logs # tops up html/js/demo.js
## Documentazione
| Documento | Contenuto |
| --- | --- |
| [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md) | Installazione, privilegi, configurazione e risoluzione dei problemi |
| [`sensor/docs/ARCHITECTURE.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ARCHITECTURE.md) | Funzionamento interno del sensore e flusso dei dati |
| [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md) | Differenze deliberate rispetto al sensore Python dismesso |
| [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md) | Misurazioni, profili e risultati dei test |
| [`sensor/docs/ROADMAP.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ROADMAP.md) | Lavori aperti sul sensore |
| [`SekuriPy Labs`](https://www.sekuripy.hr/labs/maltrail/) | Note di ingegneria, benchmark e approfondimenti |
## Contribuire
Aggiunte di trail, manutenzione dei feed, segnalazioni di bug, documentazione e miglioramenti al sensore sono benvenuti.
Le proposte di trail dovrebbero includere una fonte affidabile e dovrebbero utilizzare la classificazione
più ristretta appropriata.
Esegui i controlli pertinenti prima di inviare il codice. Il gate completo del sensore è:```bash
bash sensor/tools/check.sh
Esegue la formattazione, Clippy con i warning negati, e le suite di test debug e release. Esegui la suite del server Python con:```bash bash tests/run.sh python3
La build Windows può essere esercitata da Linux, ed è lì che sono stati trovati i suoi bug:```bash
sh sensor/tools/check_windows.sh
Viene eseguita la cross-compilazione del sensore con mingw-w64, si estrae la libreria userspace di Npcap dal suo installer
(un archivio NSIS, quindi non viene installato nulla), e si esegue il risultato sotto Wine — l'intera suite di unit,
-T rispetto alla configurazione fornita, il corpus pcap confrontato byte per byte con il binario nativo,
e il server che risponde a /ping sotto un Python Windows. La cattura live è l'unica cosa che non
può coprire; quella richiede il driver kernel di Npcap e una vera macchina Windows. I prerequisiti sono
gcc-mingw-w64-x86-64, wine, e p7zip-full.
Progetto
Licenza
TL;DR: Maltrail è distribuito con licenza MIT, ma il dataset Maltrail Trails ha termini separati. La ricerca/riferimento IOC indipendente va bene; l'uso sistematico di Trails come fonte di intelligence in un prodotto o servizio commerciale richiede permesso/licenza.
Maltrail è distribuito sotto la Licenza MIT. Vedi LICENSE.
Questo è il motore. Il set statico di trail è un lavoro separato sotto termini separati: gratuito per uso
difensivo interno, ricerca e insegnamento, ma un prodotto commerciale, servizio, offerta MSSP o MDR, o un
feed ridistribuito necessita di una licenza. Un motore MIT non rende il contenuto libero da vendere — vedi
LICENSE.md in
stamparm/trails prima di distribuirlo in qualcosa per cui fai
pagare.
Maintainer
- Miroslav Stampar (@stamparm)
- Mikhail Kasimov (@MikhailKasimov)
Sponsor
Presentazioni e pubblicazioni
- 47th TF-CSIRT Meeting, Praga, 2016 (slides)
- Detect attacks on your network with Maltrail, Linux Magazine, 2022 (articolo)
- Best Cyber Threat Intelligence Feeds, Silent Push, 2022 (recensione)
- Research on Network Malicious Traffic Detection System Based on Maltrail, Nanotechnology Perceptions, 2024 (paper)
Integrazioni di terze parti
- FreeBSD Port
- OPNsense Gateway Plugin
- D4 Project
- BlackArch Linux
- Validin
- Maltrail Add-on for Splunk
- Maltrail decoder and rules for Wazuh
- GScan (solo trails)
- MalwareWorld (solo trails)
- oisd domain blocklist (solo trails)
- NextDNS (solo trails)
- NoTracking (solo trails)
- OWASP Mobile Audit (solo trails)
- Mobile Security Framework MobSF (solo trails)
- pfBlockerNG-devel (solo trails)
- Sansec eComscan (solo trails)
- Palo Alto Networks Cortex XSOAR (connettore trail)
Riconoscimenti
- Thomas Kristner
- Eduardo Arcusa Les
- James Lay
- Ladislav Baco (@laciKE)
- John Kristoff (@jtkdpu)
- Michael Münz (@mimugmail)
- David Brush
- @Godwottery
- Chris Wild (@briskets)
- Keith Irwin (@ki9us)
- Simon Szustkowski (@simonszu)