Velociraptor: Digital Forensics in 12 Passi [2026]

Ad agosto 2025 un gruppo di attaccanti ha sfruttato una catena di falle in Microsoft SharePoint (la campagna nota come “ToolShell”) per entrare nelle reti di decine di organizzazioni. Una volta dentro, invece di installare un classico malware, hanno distribuito una copia obsoleta di Velociraptor, lo stesso strumento open source che migliaia di team di incident response usano ogni giorno per fare digital forensics. Il caso ha reso Velociraptor improvvisamente familiare anche a chi non lavora nel DFIR, e ha mostrato quanto sia importante saperlo installare, configurare e aggiornare nel modo corretto.

Questa guida ti porta dall’installazione del server fino al primo hunt su più endpoint, passando per la distribuzione dei client su Windows e Linux, l’uso pratico del linguaggio VQL e l’hardening del server stesso. Alla fine troverai un progetto funzionante da riusare in laboratorio, oltre a una sezione di troubleshooting per i problemi che incontrerai quasi certamente al primo tentativo.

Cos’è Velociraptor e perché conviene impararlo ora

Velociraptor è una piattaforma open source per digital forensics e incident response (DFIR) creata da Mike Cohen e sviluppata oggi dal team Velocidex, con il supporto di Rapid7. A differenza di un antivirus o di un EDR commerciale, Velociraptor non blocca minacce: raccoglie prove forensi da centinaia o migliaia di endpoint Windows, Linux e macOS in pochi minuti, usando un linguaggio di query proprietario chiamato VQL (Velociraptor Query Language). Lo stesso Cohen lo ha descritto così durante una presentazione a linux.conf.au: “Velociraptor is the new open source DFIR framework that everyone is talking about!”

Il punto di forza di Velociraptor è la scala: un analista può lanciare una singola query su tutta l’infrastruttura e ottenere, ad esempio, l’elenco dei processi sospetti attivi su 500 macchine in un’unica schermata. In un’altra occasione, durante OSDFCon 2021, Cohen ha riassunto così la filosofia dello strumento: “Velociraptor is a unique Free and Open Source DFIR tool, giving you power and flexibility through the Velociraptor Query Language”. È questa flessibilità, unita al fatto che è gratuito e distribuito come singolo binario, ad averlo reso lo strumento scelto da molti CSIRT europei per la gestione degli incidenti, spesso al fianco di piattaforme SIEM come Wazuh.

La release corrente al momento della stesura di questo articolo è la 0.77.2, pubblicata il 10 agosto 2026 sul repository ufficiale su GitHub. È la versione che useremo in tutti i comandi di questa guida: se stai leggendo tra qualche mese, sostituisci semplicemente il numero di versione con quello più recente disponibile nella pagina dei rilasci.

In Europa lo strumento è entrato stabilmente nel toolkit di CSIRT nazionali e team di risposta agli incidenti presso studi di consulenza, proprio per la combinazione di costo zero e capacità di raccolta a scala che normalmente si trova solo in prodotti commerciali molto più costosi. Un secondo motivo di interesse è più difensivo che offensivo: capire come funziona Velociraptor, quali porte usa e come si comporta un client legittimo aiuta un blue team a riconoscere più in fretta un’installazione non autorizzata, cosa che, come vedremo al Passo 12, è esattamente ciò che è successo nella campagna ToolShell.

Quando conviene usare Velociraptor (e quando no)

Velociraptor rende meglio in scenari precisi: un’organizzazione con più di una ventina di endpoint che ha bisogno di rispondere in fretta a domande come “questo indicatore di compromissione è presente da qualche altra parte nella rete”, oppure un consulente di incident response che arriva presso un cliente senza un EDR già installato e deve ottenere visibilità in poche ore invece che in giorni. Anche i team che già usano un EDR commerciale spesso affiancano Velociraptor per raccolte forensi più profonde, quando serve estrarre artefatti che l’EDR non espone nella sua interfaccia standard.

Non è invece lo strumento giusto se cerchi una protezione automatica in tempo reale: Velociraptor non blocca un ransomware mentre cifra i file, raccoglie prove e permette di cacciare attivamente le minacce, ma la risposta rimane guidata da un analista. Su un singolo laptop personale, poi, la complessità di un’architettura client-server è ingiustificata: la modalità standalone menzionata più avanti nelle domande frequenti risolve casi così piccoli in modo più diretto. Per una panoramica più ampia su come si struttura la sicurezza informatica oltre al solo DFIR, la nostra sezione dedicata alla sicurezza online raccoglie gli approfondimenti su violazioni, autenticazione e protezione delle reti.

Prerequisiti: versioni e requisiti minimi

Prima di iniziare, prepara un ambiente di laboratorio isolato: non installare Velociraptor per la prima volta su sistemi di produzione. Un server Ubuntu con 2 vCPU e un paio di macchine client (una Windows, una Linux) bastano per seguire ogni passo di questa guida.

Componente	Versione o requisito minimo	Note
Velociraptor	0.77.2 (agosto 2026)	Scarica sempre l’ultima release, mai versioni precedenti a 0.74.3
Sistema operativo server	Ubuntu 22.04 LTS o successivo, AMD64	Funziona su qualunque distribuzione Linux successiva al 2018
CPU server	2 vCPU	Sufficienti per laboratori fino a poche centinaia di endpoint
RAM server	4-8 GB	Aumenta con il numero di hunt paralleli
Spazio disco	20-50 GB	Cresce in base ai dati raccolti dagli endpoint
Client supportati	Windows 10/11, Windows Server, Linux, macOS	Binario dedicato per ogni piattaforma
Accesso di rete	Porta TLS del frontend aperta tra client e server	Di solito la 8000, configurabile
Permessi	Accesso sudo sul server	Necessario per creare utente di sistema e servizio systemd

Passo 1 – Scaricare e installare il binario su Ubuntu

Velociraptor gira come un singolo binario statico, senza dipendenze esterne da installare e senza database da configurare a parte. Il primo passo è scaricarlo dalla pagina delle release ufficiali e renderlo eseguibile.

# Imposta la versione in una variabile per riprodurre il comando facilmente
VELOCIRAPTOR_VERSION="0.77.2"

# Scarica il binario Linux AMD64
wget https://github.com/Velocidex/velociraptor/releases/download/v${VELOCIRAPTOR_VERSION}/velociraptor-v${VELOCIRAPTOR_VERSION}-linux-amd64 -O /tmp/velociraptor

# Sposta il binario e assegna i permessi di esecuzione
sudo mv /tmp/velociraptor /usr/local/bin/velociraptor
sudo chmod +x /usr/local/bin/velociraptor

# Verifica l'installazione
velociraptor --version

Se il comando restituisce il numero di versione, il binario è pronto. In caso contrario controlla di aver scaricato l’architettura corretta: i server ARM richiedono l’asset linux-arm64, non quello AMD64. Puoi consultare l’elenco completo delle build disponibili nella pagina ufficiale delle release su GitHub.

Prima di distribuire il binario su altre macchine, confronta l’hash SHA-256 del file scaricato con quello pubblicato nella pagina delle release. È un controllo che richiede trenta secondi ma che, alla luce del caso ToolShell descritto più avanti in questa guida, vale la pena rendere un passaggio obbligatorio in ogni procedura di deployment aziendale, non un’opzione lasciata alla buona volontà del singolo tecnico.

Passo 2 – Generare la configurazione con config generate

Velociraptor separa sempre due file di configurazione: uno per il server e uno per i client. Il comando config generate crea entrambi in un colpo solo, con TLS autofirmato e credenziali GUI casuali.

sudo mkdir -p /etc/velociraptor /var/lib/velociraptor

# Modalita interattiva: risponde a poche domande su nome host, porte e credenziali
sudo velociraptor config generate -i

# Sposta i file generati nella cartella definitiva
sudo mv server.config.yaml /etc/velociraptor/server.config.yaml
sudo mv client.config.yaml /etc/velociraptor/client.config.yaml

Durante la procedura guidata, annota username e password amministratore che vengono generati: ti serviranno al Passo 5 per il primo accesso alla GUI. Se preferisci uno script non interattivo per l’automazione, puoi reindirizzare l’output di config generate direttamente su file, ma dovrai poi modificare a mano i campi di rete descritti nel passo successivo.

Il file client.config.yaml generato in questo passaggio è quello che distribuirai su ogni endpoint ai Passi 6 e 7: contiene l’indirizzo del server e la chiave pubblica necessaria per stabilire un canale TLS mutuamente autenticato. Conservalo con cura, perché chiunque lo ottenga può, in teoria, configurare un client che si connette al tuo server come se fosse legittimo.

Passo 3 – Correggere bind_address e public_url

Questo è il pitfall più comune tra chi installa Velociraptor per la prima volta. Il file server.config.yaml generato al passo precedente punta di default a 127.0.0.1, quindi la GUI risulta raggiungibile solo dal server stesso. Apri il file con un editor e cerca le sezioni GUI e Frontend.

# Apri il file di configurazione
sudo nano /etc/velociraptor/server.config.yaml

# Cerca e sostituisci:
# bind_address: 127.0.0.1  ->  bind_address: 0.0.0.0
# public_url: https://127.0.0.1:8000/  ->  public_url: https://IP-O-DOMINIO-SERVER:8000/

Se il server ha un nome DNS pubblico, usalo al posto dell’IP: il certificato TLS autofirmato viene generato in base al valore che imposti qui, quindi un disallineamento tra questo campo e l’indirizzo effettivo con cui i client si connettono è la causa più frequente di errori “handshake failed” lato endpoint.

Dopo aver salvato le modifiche, riavvia il servizio con sudo systemctl restart velociraptor perché Velociraptor legge la configurazione solo all’avvio del processo. Un errore comune a questo punto è modificare il file ma dimenticare il riavvio, per poi passare venti minuti a cercare un problema di rete che in realtà non esiste: il vecchio bind_address resta attivo finché il processo non viene ricaricato.

Passo 4 – Creare l’utente di sistema e il servizio systemd

Eseguire il server come root non è una buona pratica. Creiamo un utente dedicato con permessi minimi e un unit file systemd che lo tenga sempre attivo, anche dopo un riavvio.

# Crea un utente di sistema senza shell di login
sudo useradd -r -s /bin/false velociraptor
sudo chown -R velociraptor:velociraptor /etc/velociraptor /var/lib/velociraptor

# Crea il file di servizio
sudo tee /etc/systemd/system/velociraptor.service << 'EOF'
[Unit]
Description=Velociraptor DFIR server
After=network.target

[Service]
Type=simple
User=velociraptor
Group=velociraptor
Restart=always
RestartSec=10
LimitNOFILE=20000
ExecStart=/usr/local/bin/velociraptor --config /etc/velociraptor/server.config.yaml frontend -v
WorkingDirectory=/var/lib/velociraptor

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable velociraptor
sudo systemctl start velociraptor
sudo systemctl status velociraptor

Output atteso dal comando status, che conferma il servizio attivo e in ascolto:

● velociraptor.service - Velociraptor DFIR server
     Loaded: loaded (/etc/systemd/system/velociraptor.service; enabled)
     Active: active (running) since ...
   Main PID: 18420 (velociraptor)
      Tasks: 12
     Memory: 210.4M
        CPU: 3.812s

Passo 5 - Primo accesso alla GUI web

Apri il browser e vai su https://IP-SERVER:8000. Il certificato è autofirmato, quindi il browser mostrerà un avviso di sicurezza: in un laboratorio puoi procedere accettando l'eccezione, in produzione sostituisci il certificato con uno emesso da una CA fidata prima di esporre la GUI oltre la rete di gestione. Accedi con le credenziali generate al Passo 2.

Una volta dentro, la barra laterale mostra le voci principali: Clients (endpoint connessi), Hunt Manager (caccia su più endpoint), Server Artifacts e Notebooks. All'inizio la lista dei client sarà vuota: la popoleremo nei due passi successivi installando gli agent.

Vale la pena dedicare qualche minuto a esplorare la sezione Server Artifacts prima ancora di collegare un endpoint: mostra l'elenco completo degli artifact predefiniti forniti da Velocidex, organizzati per sistema operativo e categoria (persistenza, rete, memoria, log). Conoscere questo catalogo prima di scrivere query personalizzate ti evita di reinventare artifact che esistono già, spesso già testati e ottimizzati dalla community.

Passo 6 - Distribuire il client su Windows

Il client Windows è un eseguibile che incorpora la configurazione generata dal server. Il processo si chiama "repack": si prende il binario generico e gli si inietta il file client.config.yaml, in modo che sappia già a quale server connettersi.

# Sul server, scarica il binario Windows e crea il client "impacchettato"
wget https://github.com/Velocidex/velociraptor/releases/download/v0.77.2/velociraptor-v0.77.2-windows-amd64.exe -O velociraptor-windows.exe

./velociraptor-windows.exe config repack --exe velociraptor-windows.exe \
  /etc/velociraptor/client.config.yaml velociraptor-client-windows.exe

Copia velociraptor-client-windows.exe sull'endpoint Windows (via GPO, RMM o semplice condivisione di rete) ed eseguilo con privilegi amministrativi passando l'opzione di installazione come servizio, così si registra come processo permanente e riparte a ogni riavvio. Entro un minuto la macchina comparirà nell'elenco Clients della GUI, identificata da un client ID che inizia con "C.".

Per un rollout su decine o centinaia di postazioni, il pacchetto MSI generato dallo stesso comando repack (aggiungendo l'estensione .msi al file di output) si integra meglio con Group Policy o con strumenti di distribuzione software aziendali rispetto al semplice eseguibile. In entrambi i casi, il client si connette in uscita al server: non è necessario aprire porte in ingresso sui firewall degli endpoint, un dettaglio che semplifica parecchio l'adozione in reti segmentate con policy di sicurezza restrittive.

Passo 7 - Distribuire il client su Linux

Su endpoint Linux il procedimento è simile a quello del server, ma con il sottocomando client invece di frontend.

# Sull'endpoint Linux
sudo wget https://github.com/Velocidex/velociraptor/releases/download/v0.77.2/velociraptor-v0.77.2-linux-amd64 -O /usr/local/bin/velociraptor
sudo chmod +x /usr/local/bin/velociraptor
sudo mkdir -p /etc/velociraptor

# Copia qui il client.config.yaml generato dal server
sudo cp client.config.yaml /etc/velociraptor/client.config.yaml

sudo tee /etc/systemd/system/velociraptor-client.service << 'EOF'
[Unit]
Description=Velociraptor DFIR client
After=network.target

[Service]
Type=simple
User=root
Restart=always
ExecStart=/usr/local/bin/velociraptor --config /etc/velociraptor/client.config.yaml client -v

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now velociraptor-client

Anche in questo caso, se il client non compare nella GUI entro un paio di minuti, il problema è quasi sempre di rete: verifica che l'endpoint riesca a raggiungere la porta TLS del server con un semplice curl -v https://IP-SERVER:8000, oppure con una scansione mirata della porta con Nmap se sospetti un blocco a livello di firewall di rete.

Su flotte Linux gestite con strumenti di configuration management come Ansible o Puppet, conviene incapsulare questi passaggi in un ruolo o modulo dedicato, distribuendo lo stesso client.config.yaml a tutti gli host tramite un canale già cifrato (ad esempio un vault di segreti), invece di copiarlo manualmente host per host. Questo riduce il rischio di errori di battitura nel percorso del file, una causa di malfunzionamento più comune di quanto sembri quando il deployment coinvolge più di una decina di macchine.

Passo 8 - VQL: il linguaggio che muove tutto

VQL (Velociraptor Query Language) è il cuore dello strumento. Ha una sintassi simile a SQL ma è pensato per interrogare lo stato di un endpoint: processi in esecuzione, chiavi di registro, log eventi di Windows, file sul disco. Ogni query può essere eseguita al volo in un notebook oppure incapsulata in un "artifact", un pacchetto YAML riutilizzabile con parametri propri.

La differenza principale rispetto a un normale SQL su database relazionale è che qui le tabelle non esistono già: le crea il plugin al momento dell'esecuzione, leggendo direttamente lo stato del sistema operativo. Questo significa che una query VQL non interroga mai dati storici o cache, ma sempre lo stato reale dell'endpoint nell'istante in cui gira, un dettaglio importante da spiegare a chi nel team arriva da un background puramente SIEM e si aspetta query su log già indicizzati.

Ecco un esempio realistico: una query che cerca esecuzioni sospette di PowerShell analizzando i log Sysmon, alla ricerca di pattern tipici di comandi offuscati o di download in memoria.

SELECT
  EventID,
  System.TimeCreated AS Timestamp,
  EventData.CommandLine AS CommandLine,
  System.Computer AS Hostname
FROM windows_events()
WHERE
  ProviderName = "Microsoft-Windows-Sysmon" AND
  EventID = 1 AND
  EventData.Image =~ "powershell.exe" AND
  EventData.CommandLine =~ "(EncodedCommand|Invoke-Expression|IEX)"

Questa query, se salvata come artifact personalizzato (ad esempio Windows.Sysmon.SuspiciousPowerShell), può essere lanciata su un singolo client per un controllo puntuale oppure su un intero parco endpoint tramite un hunt, come vedremo nel Passo 10. La documentazione completa del linguaggio, con tutti i plugin disponibili, è consultabile nella sezione VQL della documentazione ufficiale.

Oltre a windows_events(), VQL mette a disposizione decine di plugin per categoria di indagine. La tabella seguente ne raccoglie alcuni tra i più usati nelle prime settimane di utilizzo, così da avere un punto di partenza pratico invece di dover leggere l'intero elenco della documentazione prima di scrivere la prima query.

Plugin VQL	Cosa restituisce	Caso d'uso tipico
glob()	File e cartelle che rispettano un pattern	Cercare file sospetti per nome o estensione su tutto il disco
pslist()	Elenco dei processi attivi	Individuare processi con nomi anomali o percorsi insoliti
windows_events()	Eventi dal Windows Event Log	Analisi di log di sicurezza, Sysmon e PowerShell
registry()	Chiavi e valori del registro di Windows	Verifica di chiavi di persistenza (Run, RunOnce, Services)
netstat()	Connessioni di rete attive	Individuare connessioni in uscita verso IP sospetti

Passo 9 - Raccogliere il primo artifact da un endpoint

Dalla GUI, apri la scheda di un client connesso, seleziona la sezione delle raccolte e poi il pulsante per una nuova collection. Cerca un artifact predefinito, ad esempio Linux.System.Processes o Windows.System.Services, e clicca Collect. Velociraptor invia la query al client, la esegue in locale e restituisce i risultati in pochi secondi, senza mai estrarre l'intero disco.

Lo stesso risultato si ottiene da riga di comando, utile quando vuoi automatizzare la raccolta in uno script di risposta agli incidenti:

velociraptor --config /etc/velociraptor/server.config.yaml query \
  "SELECT collect_client(client_id='C.1234567890abcdef', artifact='Windows.System.Services', parameters=dict(ServiceName='TermService')) AS CollectionId FROM scope()"

Esempio di output in formato JSON restituito dal comando:

[
  {
    "CollectionId": "F.CQNS9OG2V4K1A"
  }
]

Puoi poi interrogare quella raccolta con il suo ID per estrarre i risultati completi, oppure scaricarli come archivio zip direttamente dalla GUI per allegarli a un report di incident response.

Un dettaglio che sorprende chi arriva da altri strumenti forensi: Velociraptor non copia mai l'intero disco dell'endpoint per eseguire una raccolta. La query VQL gira localmente sul client e trasmette al server solo i dati richiesti dall'artifact, un approccio che riduce drasticamente il traffico di rete e il tempo necessario rispetto a un'immagine forense completa, pur restando complementare a quest'ultima quando serve un'analisi più approfondita su una singola macchina compromessa.

Passo 10 - Lanciare un hunt su decine di endpoint

Un hunt è semplicemente un contenitore che lancia la stessa raccolta su un gruppo di client, invece che su uno solo. È lo strumento che usi quando devi rispondere alla domanda "quante macchine della mia rete hanno questo indicatore di compromissione".

Dalla GUI: apri Hunt Manager, clicca New Hunt, scegli l'artifact da eseguire (ad esempio quello creato al Passo 8), definisci lo scope tramite etichette o client specifici, imposta una scadenza e avvia. Velociraptor crea automaticamente una raccolta per ogni endpoint che rientra nello scope e aggrega i risultati in un'unica vista.

Lo stesso hunt può essere avviato via VQL, comodo per integrarlo in una pipeline SOC:

SELECT hunt(
  artifact = "Windows.Sysmon.SuspiciousPowerShell",
  clients = all(),
  parameters = dict(
    Regex = "(EncodedCommand|Invoke-Expression|IEX)"
  ),
  expires = now() + 18000
) AS HuntId
FROM scope()

Il parametro expires, espresso in secondi da ora, evita che l'hunt resti aperto indefinitamente e continui a raccogliere dati anche dagli endpoint che si connettono giorni dopo il lancio, cosa che in ambienti con migliaia di macchine può generare volumi di dati difficili da gestire.

Durante un hunt in corso, la GUI mostra in tempo reale il numero di endpoint completati, in attesa e falliti. Un client che risulta "fallito" quasi sempre indica che era offline al momento del lancio: Velociraptor riprova automaticamente non appena torna online, purché l'hunt non sia ancora scaduto. È buona norma controllare questa vista prima di dichiarare chiusa un'indagine, perché un piccolo gruppo di endpoint mancanti può nascondere proprio la macchina compromessa che stavi cercando.

Passo 11 - Hardening: TLS, RBAC e permessi minimi

Un server Velociraptor mal configurato è un bersaglio interessante proprio perché ha accesso privilegiato a ogni endpoint della rete. Tre aree meritano attenzione prioritaria.

Sul fronte TLS, sostituisci il certificato autofirmato generato di default con uno emesso da una CA interna o pubblica prima di qualunque uso in produzione, e verifica che il campo CN/SAN corrisponda esattamente al public_url impostato al Passo 3: un disallineamento qui blocca la connessione dei client con errori di handshake difficili da diagnosticare.

Sul fronte permessi, Velociraptor usa un sistema di ruoli granulare. La tabella seguente riassume i quattro ruoli principali e cosa ciascuno può fare: assegna sempre il ruolo minimo necessario, evitando di dare Administrator ad analisti che devono solo consultare risultati già raccolti.

Ruolo	Può raccogliere artifact (COLLECT_CLIENT)	Può gestire utenti e server	Uso consigliato
Administrator	Sì	Sì	Solo per chi gestisce l'infrastruttura Velociraptor stessa
Investigator	Sì	No	Analisti DFIR che conducono hunt e raccolte attive
Analyst	Limitato ad artifact pre-approvati	No	Analisti junior o consulenti esterni temporanei
Reader	No	No	Auditor e stakeholder che devono solo visionare i report

Sul fronte least privilege del server, esegui sempre il servizio con un utente di sistema dedicato come fatto al Passo 4, non come root, e limita i permessi di lettura sui file server.config.yaml e sulle chiavi TLS solo a quell'utente. Monitora inoltre l'uso di artifact amministrativi ad alto rischio come Admin.Client.UpdateClientConfig, che dovrebbero essere eseguiti solo da account Administrator fidati.

Un'ultima misura, spesso trascurata, è l'autenticazione della GUI stessa. Oltre alla password locale generata da config generate, Velociraptor supporta l'integrazione con provider SSO tramite OpenID Connect: in un'organizzazione con più di due o tre analisti, collegare l'accesso al provider di identità aziendale (con relativo audit log centralizzato) riduce il rischio di credenziali condivise via chat o email, una cattiva abitudine che resta sorprendentemente diffusa anche in team di sicurezza maturi.

Passo 12 - Il caso CVE-2025-6264 e la campagna ToolShell/Warlock

Nell'ottobre 2025 diversi report di threat intelligence hanno descritto una catena d'attacco che parte dallo sfruttamento delle vulnerabilità SharePoint note come "ToolShell" per ottenere accesso remoto non autenticato ai server on-premise. Da lì, gli attaccanti hanno distribuito una versione datata di Velociraptor, la 0.73.4.0, sfruttandola come strumento di comando e controllo camuffato da software legittimo.

Il problema tecnico è documentato come CVE-2025-6264 nel database NVD: l'artifact amministrativo Admin.Client.UpdateClientConfig non applicava un controllo di permessi aggiuntivo rispetto al semplice ruolo COLLECT_CLIENT, permettendo a un utente con permessi di Investigator di aggiornare la configurazione di un client ed eseguire comandi arbitrari con privilegi elevati. Nella campagna osservata, questo ha permesso agli attaccanti di creare account con privilegi da domain admin, muoversi lateralmente nella rete e infine distribuire il ransomware Warlock, secondo quanto ricostruito anche dai bollettini pubblicati da Rapid7. La scheda ufficiale su CVE.org conferma che la falla è corretta a partire dalla versione 0.74.3.

L'aspetto che rende questo caso interessante per chi gestisce un ambiente Velociraptor legittimo è la sequenza degli eventi: l'accesso iniziale non è passato per Velociraptor stesso, ma per SharePoint on-premise, sfruttato tramite l'exploit chain nota come ToolShell. Solo dopo aver ottenuto esecuzione di codice sul server SharePoint, gli attaccanti hanno scelto di installare Velociraptor come strumento di comando e controllo, calcolando correttamente che un processo con quel nome avrebbe attirato meno sospetti di un malware generico agli occhi di chi monitora la rete senza sapere cosa cercare. È una scelta di tradecraft che ribadisce quanto sia importante, per un blue team, sapere riconoscere non solo un binario malevolo ma anche l'uso improprio di uno strumento legittimo.

La lezione operativa è diretta: aggiorna sempre a 0.77.2 o alla release più recente, non fidarti di un binario Velociraptor trovato o installato da terzi senza verificarne hash e provenienza, e patcha SharePoint on-premise se lo usi in produzione. Un DFIR toolkit obsoleto smette di essere una risorsa difensiva e diventa un'arma nelle mani di chi ha già violato il perimetro. Per tenere traccia sistematica di CVE come questa non appena vengono aggiunte ai cataloghi di vulnerabilità sfruttate attivamente, può tornare utile la nostra guida per monitorare il catalogo CISA KEV con Python e integrarlo in un SIEM esistente.

Errori comuni da evitare

La maggior parte dei problemi che i team incontrano con Velociraptor nelle prime settimane non riguarda VQL o gli hunt, ma configurazioni di base lasciate ai valori di default. Ecco gli errori più frequenti osservati in deployment reali, in ordine di impatto.

• Lasciare bind_address su 127.0.0.1: la GUI resta raggiungibile solo dal server stesso, un errore che genera decine di ticket "non riesco ad accedere" nei team che lo affrontano per la prima volta.
• Usare una versione precedente alla 0.74.3: espone il server alla falla CVE-2025-6264 descritta al Passo 12, sfruttata attivamente in campagne reali.
• Eseguire il server come root senza motivo: aumenta l'impatto di un'eventuale compromissione del processo stesso.
• Dare il ruolo Administrator a tutti gli analisti: viola il principio del privilegio minimo e rende impossibile capire chi ha lanciato una raccolta sospetta.
• Lasciare l'hunt senza scadenza (expires): continua a raccogliere dati da endpoint che si connettono giorni dopo, saturando lo storage del server.
• Non verificare hash e firma del binario scaricato: la pagina delle release pubblica checksum proprio per permettere questo controllo prima del deployment su larga scala.

Troubleshooting: problemi frequenti e soluzioni

Quando qualcosa non funziona, i log del servizio sono il primo posto dove guardare prima di rimettere mano alla configurazione. Su un'installazione systemd, journalctl -u velociraptor -f mostra l'output in tempo reale e nella maggior parte dei casi indica subito se il problema è di permessi, di rete o di sintassi nel file YAML. La tabella seguente raccoglie i problemi più segnalati dai team che installano Velociraptor per la prima volta, con la causa più probabile e la soluzione da provare per prima.

Problema	Causa probabile	Soluzione
La GUI non è raggiungibile da altri PC	bind_address ancora impostato su 127.0.0.1	Modifica in 0.0.0.0 e riavvia il servizio con systemctl restart velociraptor
Il browser mostra "connessione non sicura"	Certificato TLS autofirmato di default	Normale in laboratorio, in produzione sostituisci con un certificato firmato da CA
Il client Windows non compare mai nella GUI	Firewall blocca la porta TLS del frontend	Apri la porta configurata (default 8000) tra endpoint e server
Errore "handshake failed" sul client	public_url del server non combacia con l'host usato dal client	Rigenera client.config.yaml dopo aver corretto public_url sul server
systemctl status mostra "failed" all'avvio	Permessi errati su /etc/velociraptor o /var/lib/velociraptor	Esegui chown -R velociraptor:velociraptor sulle due cartelle
Una query VQL restituisce risultati vuoti	Nome del provider o del campo errato nella clausola WHERE	Verifica i nomi esatti dei campi nella documentazione dell'artifact di riferimento
L'hunt resta "in corso" per giorni	Mancava il parametro expires, oppure alcuni client sono offline	Imposta sempre una scadenza esplicita e controlla lo stato dei client nello scope
Il repack del client Windows fallisce	Percorso del client.config.yaml errato o file corrotto	Rigenera la configurazione con config generate e riprova il repack

Suggerimenti avanzati per un uso da SOC

Una volta preso confidenza con installazione e primi hunt, ci sono pratiche che separano un laboratorio da un deployment pronto per un SOC reale. La prima è l'uso dei Notebook della GUI per documentare un'indagine passo dopo passo, mescolando celle VQL e testo descrittivo: il risultato è un report che puoi esportare e allegare direttamente a un ticket di incident response, senza dover ricostruire a mano la cronologia delle query eseguite.

La seconda è l'etichettatura (labeling) dei client per gruppi logici, ad esempio per reparto o per criticità dell'asset: uno scope basato su etichette rende un hunt ripetibile e riduce il rischio di lanciarlo per errore su macchine fuori perimetro. La terza è l'integrazione con un SIEM esterno: Velociraptor può esportare i risultati delle raccolte verso sistemi come Wazuh o Splunk tramite VQL e connettori dedicati, così le raccolte forensi finiscono nello stesso pannello dove il team già monitora alert e log, invece di restare isolate nella console DFIR.

Infine, pianifica hunt ricorrenti su un piccolo set di artifact ad alta priorità (persistenza, task pianificati sospetti, servizi non firmati) invece di affidarti solo a raccolte manuali dopo un allarme: la caccia proattiva riduce il tempo medio di rilevamento rispetto all'attesa di un'analisi reattiva.

Un'ultima pratica utile riguarda la conservazione delle raccolte: imposta una policy di ritenzione esplicita per i dati che Velociraptor accumula sul disco del server, perché ogni hunt su un parco endpoint ampio genera archivi che, sommati nel tempo, possono saturare lo storage se nessuno li elimina o li archivia altrove. Molti team esportano periodicamente i risultati più vecchi verso uno storage a freddo, mantenendo sul server solo le raccolte relative alle indagini ancora aperte.

Progetto completo: playbook end-to-end pronto all'uso

Ecco uno script riassuntivo che mette insieme i passi 1, 2 e 4 per automatizzare l'installazione del server su una macchina Ubuntu pulita. Salvalo come install-velociraptor.sh e lancialo con sudo bash install-velociraptor.sh.

#!/bin/bash
set -e

VELOCIRAPTOR_VERSION="0.77.2"
INSTALL_DIR="/usr/local/bin"
CONFIG_DIR="/etc/velociraptor"
DATA_DIR="/var/lib/velociraptor"

echo "==> Scarico Velociraptor ${VELOCIRAPTOR_VERSION}"
wget -q "https://github.com/Velocidex/velociraptor/releases/download/v${VELOCIRAPTOR_VERSION}/velociraptor-v${VELOCIRAPTOR_VERSION}-linux-amd64" -O /tmp/velociraptor
mv /tmp/velociraptor "${INSTALL_DIR}/velociraptor"
chmod +x "${INSTALL_DIR}/velociraptor"

echo "==> Creo utente di sistema e cartelle"
useradd -r -s /bin/false velociraptor || true
mkdir -p "${CONFIG_DIR}" "${DATA_DIR}"

echo "==> Genero la configurazione (rispondi alle domande interattive)"
cd /tmp
velociraptor config generate -i
mv server.config.yaml "${CONFIG_DIR}/server.config.yaml"
mv client.config.yaml "${CONFIG_DIR}/client.config.yaml"
chown -R velociraptor:velociraptor "${CONFIG_DIR}" "${DATA_DIR}"

echo "==> Creo il servizio systemd"
tee /etc/systemd/system/velociraptor.service > /dev/null << EOF
[Unit]
Description=Velociraptor DFIR server
After=network.target

[Service]
Type=simple
User=velociraptor
Group=velociraptor
Restart=always
RestartSec=10
LimitNOFILE=20000
ExecStart=${INSTALL_DIR}/velociraptor --config ${CONFIG_DIR}/server.config.yaml frontend -v
WorkingDirectory=${DATA_DIR}

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable velociraptor
systemctl start velociraptor

echo "==> Fatto. Ricorda di correggere bind_address e public_url in ${CONFIG_DIR}/server.config.yaml prima di esporre la GUI."
systemctl status velociraptor --no-pager

Questo playbook copre solo il server: aggiungi i comandi dei Passi 6 e 7 per completare il deployment dei client, e ricordati di eseguire manualmente la correzione di bind_address e public_url descritta al Passo 3 prima di considerare l'ambiente pronto. Per un riferimento completo di tutte le opzioni di deployment disponibili, la documentazione ufficiale sul deployment copre anche scenari containerizzati e cluster multi-frontend che vanno oltre lo scopo di questa guida introduttiva.

Domande frequenti

Velociraptor è davvero gratuito?

Sì, è distribuito con licenza open source e può essere scaricato, modificato e usato in produzione senza costi di licenza. Il progetto è mantenuto dal team Velocidex con il supporto di Rapid7.

Qual è la differenza tra Velociraptor e un EDR commerciale?

Un EDR blocca minacce in tempo reale con motori di detection integrati. Velociraptor è pensato per la raccolta forense su richiesta e la caccia proattiva: risponde a domande specifiche su cosa è successo o sta succedendo su un endpoint, spesso in affiancamento a un EDR già installato.

Posso usare Velociraptor su un solo computer, senza un'infrastruttura client-server?

Sì, esiste una modalità standalone in cui il binario esegue raccolte forensi in locale senza bisogno di un server centrale, utile per analisi rapide di una singola macchina compromessa.

La vulnerabilità CVE-2025-6264 riguarda anche la versione che ho appena installato?

No, se segui questa guida installi la versione 0.77.2, successiva alla 0.74.3 in cui la falla è stata corretta. Il problema riguardava solo le installazioni rimaste su versioni precedenti alla 0.74.3, come la 0.73.4.0 sfruttata nella campagna ToolShell.

Quanti endpoint può gestire un singolo server Velociraptor?

Dipende dall'hardware e dal numero di hunt paralleli, ma un server con poche decine di GB di RAM può gestire tranquillamente migliaia di client. Per ambienti molto grandi si può scalare con più frontend dietro un load balancer, come descritto nella documentazione ufficiale.

VQL è difficile da imparare se conosco già SQL?

La sintassi di base (SELECT, FROM, WHERE) è familiare a chi ha già usato SQL. La curva di apprendimento riguarda soprattutto i plugin specifici per DFIR, come windows_events() o glob(), che richiedono di consultare la documentazione degli artifact.

Serve un database esterno per far funzionare il server?

No, Velociraptor salva i dati raccolti su disco locale in un formato proprietario, senza bisogno di installare PostgreSQL, MySQL o altri database esterni.

Posso scrivere artifact personalizzati oltre a quelli predefiniti?

Sì, un artifact è un semplice file YAML con una o più query VQL al suo interno. Puoi crearlo dalla GUI nella sezione dedicata oppure importarlo da repository di terze parti, purché ne verifichi sempre il contenuto prima di eseguirlo su endpoint di produzione.