ayaFlow

ayaFlow è un analizzatore di traffico di rete basato su Rust + eBPF, costruito con Aya. Esegue un agente per nodo Linux, attacca un classificatore TC in ingresso e uscita, espone dati di traffico in tempo reale, cronologia basata su SQLite e metriche Prometheus.

Cosa Fa

• Cattura il traffico IPv4, IPv6, TCP e UDP con un classificatore TC eBPF.
• Mantiene statistiche sulle connessioni in tempo reale in memoria e registri storici in SQLite.
• Arricchisce opzionalmente il traffico con DNS inverso, domini di query DNS e SNI TLS.
• Espone API REST, flusso WebSocket e endpoint Prometheus /metrics.
• Include esempi per Docker, Kubernetes, Prometheus e Grafana.

Flusso di sviluppo supportato

Il runtime di cattura pacchetti di ayaFlow è solo Linux. I flussi di lavoro per i contributori sono divisi appositamente:

• Controlli sicuri su host su macOS o Linux:
  • cargo test -p ayaflow-common
  • cargo test -p ayaflow
  • cargo xtask build-user
  • cargo xtask check-host
• Build e runtime solo Linux:
  • cargo xtask build-ebpf
  • cargo xtask build
  • cargo xtask run -- --deep-inspect

Se sei su macOS, usa Docker o una VM Linux per l'intero flusso di lavoro eBPF. Vedi HOW_TO_USE_LOCAL.md per entrambi i percorsi.

Avvio rapido

1. Verifica il supporto dell'host

cargo xtask check-host

2. Compila su Linux

cargo xtask build

3. Esegui su Linux

sudo ./target/debug/ayaflow --db-path /tmp/traffic.db

Se --interface viene omesso, ayaFlow rileva automaticamente l'interfaccia predefinita da /proc/net/route e ricade su eth0 solo se il rilevamento fallisce.

4. Verifica

curl http://localhost:3000/api/health
curl http://localhost:3000/api/stats
curl "http://localhost:3000/api/history?limit=5&row_type=raw"
curl http://localhost:3000/metrics

Opzioni CLI

Flag	Descrizione	Predefinito
-i, --interface	Interfaccia da monitorare. Ometti per rilevare automaticamente l'interfaccia di default su Linux.	auto-rilevamento, fallback eth0
-p, --port	Porta del server API	3000
--db-path	Percorso del database SQLite	traffic.db
--connection-timeout	Pulizia connessioni inattive in secondi	60
--data-retention	Eliminazione automatica cronologia più vecchia di N secondi	disabilitato
--aggregation-window	Memorizza finestre di cronologia aggregate invece di righe di pacchetti grezzi	0 (modalità grezza)
--allowed-ips	CIDR autorizzati ad accedere all'API	senza restrizioni
-c, --config	Percorso del file di configurazione YAML	nessuno
-q, --quiet	Sopprime i log non di errore	false
--deep-inspect	Abilita estrazione query DNS + SNI TLS	false
--enable-ipv6	Abilita cattura pacchetti IPv6	false
--resolve-dns	Abilita reverse DNS lookup	false

Riferimento API

Endpoint	Metodo	Descrizione
/api/health	GET	Stato di salute, contatori pacchetti e configurazione runtime attiva
/api/stats	GET	Uptime, throughput, conteggi e configurazione runtime attiva
/api/live	GET	Top 50 connessioni attive per conteggio pacchetti
/api/history	GET	Traffico storico filtrabile con metadati di paginazione
/api/stream	WS	Statistiche in tempo reale ogni secondo
/metrics	GET	Formato testo Prometheus

/api/history supporta:

• limit, offset
• start_time, end_time
• protocol
• ip, src_ip, dst_ip
• port, src_port, dst_port
• direction
• domain
• row_type=raw|aggregated

Esempio:

curl "http://localhost:3000/api/history?limit=20&protocol=TCP&dst_port=443&row_type=raw"

Struttura del progetto

ayaflow/           Userspace runtime, API, storage, and host-safe tests
ayaflow-common/    Shared packet/event types used by userspace and eBPF
ayaflow-ebpf/      TC classifier and payload capture program
xtask/             Build and workflow helpers
k8s/               Kubernetes manifests
monitoring/        Prometheus and Grafana assets

L'albero src/ duplicato a livello di root è legacy e non fa parte del percorso di build supportato. Usa il crate ayaflow/ e i comandi cargo xtask sopra.

Guide di distribuzione

• Flussi di lavoro Linux locale e macOS+VM: HOW_TO_USE_LOCAL.md
• Docker: HOW_TO_USE_DOCKER.md
• Kubernetes: HOW_TO_USE_K8S.md

Documentazione tecnica

• Architettura: ARCHITECTURE.md
• Note su impronta e prestazioni: PERFORMANCE.md

Testato qui

Il flusso di lavoro sicuro su host ora passa su questa macchina di sviluppo macOS con:

• cargo test -p ayaflow-common
• cargo test -p ayaflow
• cargo xtask check-host

La validazione del runtime solo Linux deve ancora avvenire su un host Linux o su un runner CI con la toolchain eBPF installata.

Licenza

Questo progetto utilizza tre licenze diverse a seconda del componente:

Componenti userspace

L'agente userspace e le librerie comuni (ayaflow e ayaflow-common) sono dual-licensed sotto una delle seguenti:

• Apache License, Version 2.0
• MIT License

a tua scelta.

Componenti Kernel

I componenti kernel eBPF (ayaflow-ebpf) sono concessi in licenza strettamente sotto la GNU General Public License v2.0 (GPL) per garantire la compatibilità con il verificatore del kernel Linux.