Netfence

Come Envoy xDS, ma per filtri eBPF.

Netfence funge da demone sui tuoi host VM/container e inietta automaticamente programmi di filtro eBPF nei cgroups e nelle interfacce di rete, con un server DNS integrato che risolve i domini consentiti e popola la lista di IP consentiti.

I demoni di Netfence possono essere gestiti tramite la loro API locale su socket Unix, oppure connettersi a un piano di controllo centrale che implementi tramite gRPC per sincronizzare liste consentite/bloccate con il tuo backend.

Il tuo piano di controllo invia regole di rete come ALLOW *.pypi.org o ALLOW 10.0.0.0/16 alle interfacce/cgroups collegati. Quando una VM/container interroga il DNS, Netfence lo risolve, aggiunge gli IP al filtro eBPF e blocca il traffico verso IP sconosciuti prima che lasci l'host, con un overhead di percorso riscaldato che è praticamente indistinguibile da una normale connessione socket nei benchmark attuali.

Features

• Collega filtri eBPF a interfacce di rete (TC) o cgroups
• Modalità policy: disabilitata, lista consentiti, lista bloccati, blocca-tutto
• Supporto IPv4 e IPv6 CIDR con TTL opzionali
• Server DNS UDP/TCP per allegato con lista di domini consentiti/bloccati e override upstream ordinati
• Le regole per domini supportano sottodomini con corrispondenza basata sulla specificità (le regole più specifiche vincono)
• I domini risolti popolano automaticamente il filtro IP
• Metadati su demoni e allegati per associazione con ID VM, tenant, ecc.
• Supporto per l'inoltro di query DNS al piano di controllo per prendere decisioni DNS per allegato

Nota di sicurezza: esclusioni predefinite

Nella modalità lista consentiti, il link-local IPv4 (169.254.0.0/16) non è più automaticamente consentito per impostazione predefinita — quindi il servizio metadata cloud (169.254.169.254) è bloccato a meno che non sia esplicitamente inserito nella lista consentiti. Questa è una scelta deliberata: il servizio metadata è un bersaglio per il furto di credenziali, e i carichi di lavoro sandboxed non devono poterlo raggiungere implicitamente. Localhost (127.0.0.0/8, ::1) e la scoperta di vicini IPv6 (fe80::/10, ff02::/16) rimangono consentiti per impostazione predefinita in modo che la connettività di base e NDP continuino a funzionare. Per consentire il servizio metadata per un carico di lavoro, inserisci 169.254.169.254/32 nella lista consentiti (un override di esclusione per allegato tramite il piano di controllo è un follow-up pianificato).

Il broadcast IPv4 (255.255.255.255) e il multicast (224.0.0.0/4) non hanno esclusioni e sono soggetti alla policy, quindi in modalità lista consentiti TC il traffico come i broadcast di rinnovo DHCP è bloccato a meno che non sia esplicitamente consentito. I controlli di esclusione vengono eseguiti prima della lista bloccati, quindi un intervallo escluso può essere bloccato solo disattivando la sua esclusione — e poiché il link-local IPv4 è ora disattivato per impostazione predefinita, la modalità lista bloccati può bloccare anche il servizio metadata.

Differenze rispetto ad altre opzioni

• Interruzione immediata delle connessioni esistenti quando le regole cambiano per non consentire un IP (solo collegamento interfaccia)
• Supporta tutti i protocolli di rete e la connettività diretta tramite IP. Ad esempio, il fantastico httpjail non consente di connettersi direttamente agli IP, o connessioni TCP/UDP dirette come la connessione ai database.
• Risoluzione dinamica del DNS e filtraggio pre-risoluzione (quindi non c'è esfiltrazione di secretdata.someattacker.com)

A mia conoscenza, nessun'altra soluzione offre tutte queste funzionalità insieme.

Limitazione nota: gli allegati cgroup filtrano a livello di socket (hook connect/sendmsg), quindi un processo con CAP_NET_RAW può creare pacchetti raw che li bypassano. Usa un allegato TC (interfaccia), che filtra a livello di dispositivo, per carichi di lavoro che potrebbero avere CAP_NET_RAW.

Tuttavia, questo ha un po' più di overhead rispetto a qualcosa come httpjail.

Panoramica delle prestazioni

Questi numeri sono stati misurati nel gate Docker Linux privilegiato su linux/arm64 usando make bench-docker. I valori sono mediane di cinque campioni.

Percorso socket riscaldato

Il benchmark del socket riscaldato utilizza socket UDP connessi per isolare il costo dell'hook eBPF cgroup/connect4 dalla latenza della stretta di mano TCP. In questo percorso, il DNS ha già risolto il dominio, l'IP è ancora entro il TTL e l'IP/CIDR è già presente nella mappa eBPF.

La differenza misurata tra i percorsi di connessione normale, LPM protetto e host esatto DNS è all'interno del rumore del campione.

Non esiste oggi un percorso "kernel miss chiede al processo padre". Una mancata nella lista consentiti cgroup è decisa localmente da eBPF e viene bloccata immediatamente.

Percorso query DNS

Questi numeri misurano il percorso del server DNS, non il percorso di connessione socket riscaldato.

Le righe a freddo si sincronizzano attraverso la reale barriera di mutazione degli allegati e cancellano il grafico di proprietà del benchmark e lo snapshot falso della mappa esatta tra le query. Il timer viene eseguito continuamente per preservare la località dello scheduler UDP, mentre ns/op sottrae il tempo reale fixture-reset-ns/op riportato separatamente (inclusa qualsiasi coda del gestore precedente dopo che il client ha ricevuto il suo pacchetto) e quindi misura lo scambio corrente del client. raw-total-ns/op riporta entrambi insieme. Il reset preserva i domini policy configurati e l'archiviazione di supporto, e il benchmark asserisce un'aggiunta fisica alla mappa esatta per query. Le righe a caldo inizializzano la proprietà una volta e asseriscono un'aggiunta fisica durante l'esecuzione.

I microbenchmark di proprietà interna di seguito sono diagnostici di scalabilità, non righe di accettazione del percorso di query DNS end-to-end. L'helper nella cache viene mantenuto solo per test e benchmark; avvolge un record alla volta e ripete la convalida del dominio. Sia esso che il traffico del resolver normale attraversano la barriera di mutazione degli allegati, mentre il traffico del resolver normale ammette ogni risposta completa come una transazione.

Design

Architecture```

+------------------+ +-------------------------+ | Your Control |<------->| Daemon (per host) | | Plane (gRPC) | stream | | +------------------+ | +-------------------+ | | | DNS Server | | | | (per-attachment) | | | +-------------------+ | +-------------------------+ | +------+------+ | | TC Filter Cgroup Filter (veth, eth) (containers)

Ogni attachment riceve un indirizzo DNS unico (porta) fornito dal demone. I container/VM devono essere configurati per utilizzare il proprio indirizzo DNS assegnato; filtrare il traffico DNS normale del carico di lavoro non lo reindirizza in modo trasparente.

### Topologia e comportamento del resolver DNS

`dns.listen_addr` deve identificare un indirizzo IPv4 o IPv6 concreto che ogni carico di lavoro connesso possa raggiungere. Gli indirizzi wildcard vengono rifiutati perché non possono essere annunciati come endpoint del resolver. Un hostname configurato viene risolto una volta all'avvio del demone e l'IP concreto risultante viene utilizzato per binding, annuncio, persistenza e bootstrap del filtro. Il valore predefinito `127.0.0.1` è appropriato solo quando il carico di lavoro condivide il namespace di rete del demone; un container o VM in un altro namespace necessita normalmente di un indirizzo host/bridge raggiungibile.```yaml
dns:
  listen_addr: 10.0.0.1
  port_min: 11000
  port_max: 11500
  # Daemon-global fallback when DnsConfig.upstream_servers is empty.
  upstream: 1.1.1.1:53
  # Hard daemon ceilings for each attachment's bounded DNS exact ownership.
  # Zero/unset uses these defaults (max_ips_per_family instead derives from
  # filter.max_dns_rule_entries).
  max_ips_per_family: 4096
  max_ips_per_response: 64
  max_ips_per_policy_domain: 1024
  max_tracked_domains: 1024
  max_ownership_edges: 8192
  # Rolling physical-admission/LRU mutation budget and slow-planning work
  # allowance. The window is daemon-global and immutable until restart;
  # DnsConfig.max_churn_units may only lower the daemon ceiling.
  max_churn_units: 8192
  churn_window: 1m

Attach restituisce il concreto dns_address; configura quell'indirizzo esatto come resolver del carico di lavoro. Netfence installa una voce allow protetta, non scadente, /32 o /128 per l'IP del listener, così la modalità allowlist può avviarsi senza una regola DNS-IP del piano di controllo. I filtri correnti applicano prefissi IP, non porte di destinazione, quindi quella voce protetta permette ogni porta all'IP del listener (non solo la sua porta DNS); questo è particolarmente importante per modelli di minaccia di allegato cgroup. Usa un IP listener dedicato quando quella raggiungibilità più ampia non è accettabile.

L'endpoint assegnato serve sia UDP che TCP. Le risposte UDP sono troncate al limite di 512 byte di un client legacy o alla sua dimensione EDNS pubblicizzata e portano il flag TC quando necessario, consentendo al carico di lavoro di riprovare lo stesso endpoint su TCP. Per la risoluzione upstream, una risposta UDP troncata viene ritentata su TCP contro lo stesso upstream per primo. Un fallimento di trasporto, SERVFAIL, o REFUSED passano quindi al successivo upstream configurato in ordine.

DnsConfig.upstream_servers sovrascrive il dns.upstream globale del demone per un singolo allegato. Le voci usano la sintassi host:port (letterali IPv6 tra parentesi), sono canonizzate e deduplicate nell'ordine di primo avvistamento, e sono limitate a otto server unici. Una lista vuota seleziona il fallback globale.

Nelle modalità di filtraggio, Netfence rimuove i parametri ipv4hint e ipv6hint dalle risposte HTTPS/SVCB, incluse le loro corrispondenti referenze mandatory, perché gli indirizzi suggeriti non hanno superato indipendentemente l'ammissione del filtro. La modalità disabilitata preserva le risposte upstream invariate.

I contatori delle query DNS sono mutuamente esclusivi: dns_queries_allowed conta le query consentite dalla policy e risposte con successo (incluso NXDOMAIN), dns_queries_blocked conta le risposte REFUSED della policy, e dns_queries_errors conta i percorsi di errore del resolver, proxy, ammissione filtro, scrittura risposta e altri. Una query incrementa esattamente un bucket.

Ogni risposta contenente indirizzi in una modalità DNS di filtraggio viene ammessa al tier HASH IPv4/IPv6 esatto dell'allegato come una transazione prima che qualsiasi indirizzo A/AAAA dalla sezione risposta, autorità o aggiuntiva venga restituito. Se la risposta completa non può essere rappresentata, il resolver restituisce SERVFAIL senza indirizzo e preserva il set di lavoro precedentemente ammesso. Le decisioni PROXY che restituiscono indirizzi devono impostare add_to_filter; altrimenti falliscono anch'esse chiuse come SERVFAIL. La modalità DNS disabilitata è l'esplicita eccezione di passaggio diretto.

Le voci esatte portano archi TTL dalla query normalizzata al proprietario della policy abbinata. Rimuovere o negare un dominio rimuove prontamente i suoi ultimi indirizzi esatti solo DNS, mentre un indirizzo condiviso sopravvive a un altro proprietario di query attivo e un CIDR sovrapposto del piano di controllo continua indipendentemente nel tier LPM protetto. Le risposte DNS DENYLIST default-allow e explicit-allow sono tracciate anch'esse, anche mentre il packet DENYLIST ignora gli allow esatti, così un successivo passaggio in modalità pacchetto a ALLOWLIST può utilizzare indirizzi già restituiti in cache senza una nuova query.

Tutto lo stato di proprietà normale/attivo dello spazio utente è limitato dalle cinque impostazioni di proprietà sopra. I bordi provvisori sintetici ripristinati sono esenti da quei limiti logici in modo che non possano essere dimenticati prima della riconciliazione, ma rimangono limitati dalle mappe esatte fisiche IPv4/IPv6. I domini di policy configurati e i domini di query attive condividono max_tracked_domains, e ogni record TTL (query, proprietario abbinato, IP) consuma uno slot max_ownership_edges.

Sotto pressione, l'ammissione proietta prima via i bordi TTL scaduti. Poi recupera i bordi logici completi query/proprietario con il minor collaterale fisico prima della recency, seguiti da LRU deterministico osservato dal resolver (l'IP canonico rompe i pareggi). Una rimozione fisica cancella l'intera chiave DNS esatta e tutti i suoi proprietari DNS. L'IP fisico in arrivo e il bordo esatto (IP, query, proprietario) in arrivo sono protetti per la transazione di risposta. La proprietà provvisoria ripristinata protegge la sua chiave fisica fino alla riconciliazione autorevole, ma i metadati DNS normali non correlati che condividono quella chiave possono ancora essere recuperati. Gli allow autorevoli del piano di controllo/sistema e ogni deny rimangono in tier LPM separati e non sono mai candidati per il recupero DNS.

Il budget di churn rotante per allegato addebita un'unità per una nuova chiave fisica esatta e una per ogni chiave fisica DNS attiva rimossa; una sostituzione completa vecchio-nuovo costa quindi due. Aggiornamenti, recupero solo logico, scadenza e rimozione di policy costano zero. Gli eventi rimangono attivi mentre la loro età è inferiore a dns.churn_window e scadono al confine esatto. DnsConfig.max_churn_units può solo abbassare il tetto del demone; zero lo eredita. La finestra non può essere modificata dal piano di controllo, e modificare il tetto/finestra del demone richiede un riavvio. Abbassare e poi alzare un limite di allegato non dimentica la storia ancora attiva.

Un registro di lavoro rotante separato limita la costosa pianificazione del grafo di proprietà. Aggiornamenti rapidi e ammissioni ordinarie non lo toccano mai. Prima che un percorso di pressione cloni o analizzi il grafo, Netfence addebita unità di lavoro stabili derivate dalle chiavi fisiche correnti, bordi di proprietà, domini tracciati e dimensione della risposta rispetto ai loro tetti immutabili del demone/mappa. Quel costo del tentativo è mantenuto anche quando il piano si dimostra impossibile o una successiva transazione sulla mappa esatta fallisce, chiudendo il percorso di riprova a zero mutazioni per pressione CPU/allocation senza cambiare la contabilità di churn fisico transazionale sopra. Ai tetti predefiniti, l'indennità ammette otto passaggi di grafo equivalenti al massimo per finestra; abbassare DnsConfig.max_churn_units ne mantiene almeno uno. Abbassare e poi alzare il limite non ridimensiona né dimentica la storia di lavoro attiva.

Quando nessuno stato DNS idoneo può soddisfare un limite, o una delle due indennità rotanti è esaurita, Netfence preserva il set di lavoro ammesso e restituisce SERVFAIL senza restituire l'indirizzo non ammesso. I fallimenti di capacità incrementano map_full_drops; i throttling di churn fisico e lavoro di pianificazione no. I battiti cardiaci espongono i valori correnti della mappa esatta, capacità, e high-water della generazione del processo, più le rimozioni LRU DNS cumulative, tutti i fallimenti di ammissione, e un conteggio aggregato di throttle del budget che copre entrambe le guardie rotanti. I log di pressione/recupero di capacità, budget fisico e budget di lavoro sono limitati in frequenza indipendentemente. Gli operatori possono attendere il recupero TTL/finestra, ridurre il churn di risposta/dominio o tentativi ripetuti di pressione di cap, o alzare DnsConfig.max_churn_units fino al tetto del demone dns.max_churn_units. Alzare il tetto del demone richiede un riavvio; aumentare filter.max_dns_rule_entries richiede anche la ricreazione dell'allegato perché le mappe pinnate non possono essere ridimensionate in loco.

Capacità CIDR protetta e recupero fail-closed

I CIDR autorevoli del piano di controllo e le regole del sistema demone usano quattro mappe LPM indipendenti e non rimovibili: allow/deny × IPv4/IPv6. Ogni mappa ha slot filter.max_rule_entries. Il bootstrap /32 o /128 del listener DNS è un allow di sistema e conta contro la corrispondente mappa allow protetta. Le voci DNS esatte per host rimangono nelle loro mappe separate e non possono consumare questi slot. Nessuna regola protetta viene mai rimossa LRU: gli allow espliciti, le regole di sistema e ogni deny rimangono fino a una rimozione autorizzata o una sostituzione completa.

Un SubscribedAck o BulkUpdate completo viene canonizzato e la sua occupazione finale viene verificata per tutte e quattro le mappe prima della mutazione. La capacità è basata sullo stato finale, quindi sostituire chiavi in una mappa piena è valido; uno stato sovradimensionato viene rifiutato senza rimuovere o accettare parzialmente regole. I sopravvissuti non vengono rimossi e riaggiunti. Se una successiva syscall di mappa fallisce, Netfence ripristina e verifica l'esatto inventario delle quattro mappe pre-chiamata. La modalità provata dopo il rollback è la vecchia modalità o BLOCK_ALL (normalmente BLOCK_ALL), quindi il demone mantiene ancora l'allegato in fallimento chiuso fino a quando un completo tentativo autorevole non riesce.

Lo stato di sicurezza della policy protetta è persistito con l'allegato ed esportato nei battiti cardiaci. BLOCK_ALL di per sé è una modalità configurata normale e sana: policy_degraded è falso quando policy_degraded_reason è vuoto. Una mutazione protetta rischiosa che inizia mentre BLOCK_ALL è sano scrive prima nel journal protected_policy_mutation_in_progress. Questo è un journal di crash transitorio, non una diagnosi di fallimento stabile: l'operazione live può pubblicare la sua modalità intesa prima del salvataggio finale di cancellazione del journal, e il completamento con successo cancella il journal stesso. Se l'avvio lo trova dopo un crash, l'avvio forza e prova prima BLOCK_ALL, poi persiste protected_policy_mutation_interrupted. I codici di ragione di degrado stabile sono:

• protected_policy_mutation_interrupted
• authoritative_protected_policy_failed
• incremental_deny_install_failed
• incremental_allow_removal_failed
• incremental_mode_change_failed

Queste sono classificazioni stabili, mai testo grezzo di syscall/store. Il journal in corso è un confine di crash interno persistito; le statistiche del battito cardiaco si serializzano con la mutazione proprietaria e quindi osservano o la sua cancellazione riuscita o una conversione di fallimento stabile, non il journal intermedio live. Le ragioni di degrado/interruzione stabili mantengono l'enforcement dei pacchetti in BLOCK_ALL provato e rifiutano comandi CIDR incrementali e di modalità pacchetto. Cambiamenti indipendenti di configurazione DNS e scadenza TTL DNS possono continuare sotto quella presa provata, ma non possono cancellare la ragione stabile o riattivare la policy dei pacchetti. Il recupero da una ragione stabile richiede uno stato desiderato LPM completo e DNS: applica BulkUpdate tramite il piano di controllo o API locale (o rispondi a un nuovo Subscribed di un allegato ripristinato con SubscribedAck). Netfence mette in scena lo stato protetto completo, applica lo stato DNS autorevole, attiva la modalità richiesta, e cancella la ragione durevole solo dopo che ogni passo ha successo. Preferisci un command_id unico su un BulkUpdate di recupero del piano di controllo e richiedi un CommandResult riuscito; l'API locale rifiuta command_id perché il suo risultato RPC unario riporta già successo o fallimento.

I battiti cardiaci espongono le voci fisiche correnti, la capacità dura, e l'high-water della generazione del demone indipendentemente per tutte e quattro le mappe protette. Il bootstrap è incluso; le voci pinnate adottate inizializzano l'high-water della nuova generazione. map_full_drops è cumulativo e include i rifiuti di capacità protetta. Se una lettura dell'occupazione fallisce, il demone conserva l'ultimo snapshot provato ed emette un avviso al massimo una volta ogni 30 secondi invece di inventare nuovi conteggi. Per recuperare dalla pressione, riduci le regole desiderate complete al di sotto di ciascuna capacità per mappa e riprova l'aggiornamento completo. Alzare filter.max_rule_entries è solo al momento del caricamento e richiede la ricreazione di un allegato pinnato esistente. Se il demone non può provare BLOCK_ALL o registrare durevolmente il suo marcatore di sicurezza, ferma l'ammissione di mutazione; ripara il guasto della mappa/store e riavvia piuttosto che assumere che l'enforcement sia stato riaperto.

Per host

Esegui il demone, che:

• Espone un'API gRPC locale (DaemonService) per allegati, policy e ispezione
• Opzionalmente si connette al tuo piano di controllo tramite stream bidirezionale (ControlPlane.Connect)
• Carica e gestisce programmi eBPF

Avvia il demone:```bash

Start with default config

netfenced start

Start with custom config file

netfenced start --config /etc/netfence/config.yaml

**Controlla lo stato del daemon:**```bash
netfenced status

Con nessun control_plane.url, un nuovo attachment viene creato in modalità pacchetto/DNS disabilitata e può essere configurato immediatamente tramite l'API locale o la CLI. Nessun processo del control-plane è richiesto per il flusso di lavoro standalone documentato in “Per attachment”.

Confine di fiducia del socket Unix locale

L'API gRPC locale non ha autenticazione per-RPC. L'accesso al filesystem al suo socket Unix è il confine di autorizzazione, e ogni processo che può connettersi è un amministratore di rete host completamente fidato: può allegare o scollegare programmi eBPF host, sostituire la politica pacchetto e DNS, e aprire o chiudere il traffico del carico di lavoro. Mantenere ristretta l'appartenenza al gruppo del socket e proteggere la directory padre del socket.```yaml

Defaults to /var/run/netfence.sock.

socket: /run/netfence/netfence.sock

Unix group name or numeric GID. Empty/unset uses the daemon's effective GID.

socket_group: netfence-admin

`NETFENCE_SOCKET` e `NETFENCE_SOCKET_GROUP` sono le variabili d'ambiente
equivalenti. All'avvio, il demone associa il socket a una directory di staging
privata, imposta il suo gruppo e la modalità `0660` mentre è irraggiungibile, e
poi lo pubblica atomicamente. Il demone rimuove qualsiasi socket Unix preesistente
nella destinazione configurata—non distingue un socket obsoleto da uno posseduto
da un altro demone attivo—quindi esattamente un demone deve possedere un percorso
di socket. Rifiuta di rimuovere una destinazione che non è un socket. Su Linux,
la ridenominazione senza sostituzione impedisce la sovrascrittura di un nuovo
percorso creato dopo tale rimozione; lo spegnimento rimuove il percorso pubblicato
solo quando identifica ancora l'inode del socket del demone stesso. Un gruppo
non valido, un errore di proprietà/modalità o una destinazione non-socket causa
un errore di avvio senza pubblicare un endpoint permissivo.

### Control-plane transport security (TLS / mTLS / bearer token)

Il canale del piano di controllo è la superficie d'attacco di maggior valore
nel sistema (chiunque lo controlla può inviare regole `ALLOW` a ogni carico di
lavoro), quindi il demone **fallisce in chiusura**: se `control_plane.url` è
impostato, la configurazione deve scegliere esplicitamente un trasporto — o un
blocco `control_plane.tls` o `control_plane.insecure: true`. Un URL senza
nessuno dei due viene rifiutato all'avvio; non esiste un default implicito in
chiaro. (Questo è un cambio di comportamento deliberato: le versioni precedenti
chiamavano silenziosamente il piano di controllo senza crittografia.)```yaml
control_plane:
  url: cp.internal:443
  tls:
    # CA bundle used to verify the control-plane server certificate.
    # Path to a PEM file or inline PEM; omit to use the system root pool.
    ca: /etc/netfence/cp-ca.pem
    # Client certificate + key (path or inline PEM). Setting BOTH enables
    # mTLS: the daemon presents this cert to the control plane. Setting only
    # one is a config error.
    cert: /etc/netfence/daemon.pem
    key: /etc/netfence/daemon.key
    # Optional hostname override for server certificate verification (SNI),
    # e.g. when dialing by IP.
    server_name: cp.internal
  # Optional bearer token, sent as `authorization: Bearer <token>` metadata
  # on every control-plane RPC. Refused on a plaintext channel unless
  # `insecure: true` was explicitly set (so a misconfiguration can't leak it).
  auth_token: "..."

TLS con solo root di sistema (certificato server emesso da CA pubblica, nessun mTLS) è solo un blocco vuoto:```yaml control_plane: url: cp.example.com:443 tls: {}

Il testo in chiaro per lo sviluppo locale è un opt-in esplicito (mutuamente esclusivo con `tls`):```yaml
control_plane:
  url: localhost:9000
  insecure: true

I certificati e le chiavi vengono caricati una volta all'avvio, quindi un percorso/PEM errato causa un errore all'avvio con un messaggio chiaro invece di apparire a ogni riconnessione.

Liveness del piano di controllo (keepalive) e backoff di riconnessione

Il demone invia ping keepalive HTTP/2 sulla connessione del piano di controllo in modo che un percorso silenziosamente morto (cavo estratto, mapping NAT scaduto, route blackholed) venga rilevato e chiuso in circa keepalive_time + keepalive_timeout — invece di rimanere CONNECTED per minuti fino al timeout di ritrasmissione TCP del kernel mentre ogni query DNS proxy consuma il suo timeout completo.
Le riconnessioni sono gestite da un backoff esponenziale con jitter (inizia a 1s, raddoppia, jitter ±20%, limitato a reconnect_backoff_max); il backoff si azzera al valore minimo solo dopo che una connessione è rimasta sana per 30s, quindi un piano di controllo che accetta connessioni e le chiude immediatamente continua a fare backoff invece di essere colpito al valore minimo.```yaml control_plane:

Send a keepalive ping after this much inactivity… (default 30s; gRPC

clamps the effective interval to a 10s minimum client-side)

keepalive_time: 30s

…and declare the peer dead if no ack arrives within this (default 10s).

keepalive_timeout: 10s

Cap on the jittered exponential reconnect backoff (default 30s).

reconnect_backoff_max: 30s

I valori zero/non impostati indicano i valori predefiniti — **non** disabilitano il keepalive o il backoff. Il tuo control plane deve consentire questa cadenza di ping nella sua politica di enforcement del keepalive gRPC (vedi sotto), altrimenti rifiuterà il demone con `ENHANCE_YOUR_CALM (too_many_pings)`.

### Riavvii, crash e aggiornamenti del demone (stato BPF pinned)

Il demone blocca (pins) i collegamenti BPF e le mappe delle regole di ogni attachment su bpffs (`filter.bpf_pin_dir`, di default `/sys/fs/bpf/netfence`, una directory per ID di attachment). Poiché lo stato pinned è mantenuto dal kernel — non dal processo demone — **l'applicazione continua mentre il demone è giù**: un crash (`kill -9`), un arresto controllato o un aggiornamento lascia l'ultima policy conosciuta (modalità + tutte le regole) in esecuzione, e il successivo avvio del demone riadotta lo stato pinned così com'è. Il ripristino non riattacca né riscrive mai le mappe live, quindi non c'è alcuna finestra in cui un carico di lavoro consentito viene bloccato o una destinazione bloccata viene permessa, e nessun attachment duplicato.

Il comportamento di arresto è configurato esplicitamente (`filter.detach_on_stop`):```yaml
filter:
  # false (default): stopping the daemon KEEPS ENFORCING — filters stay
  # attached via their bpffs pins and are re-adopted on the next start
  # (fail-closed across restarts/upgrades).
  # true: stopping the daemon detaches filters and removes their pins —
  # traffic is unfiltered while the daemon is down (explicit fail-open).
  detach_on_stop: false
  # bpffs directory for pinned state. Must be on a bpffs mount; the daemon
  # mounts bpffs at /sys/fs/bpf if needed (privileged). An explicit "" turns
  # pinning off entirely (BPF state then dies with the process).
  bpf_pin_dir: /sys/fs/bpf/netfence
  # Capacity of each authoritative/system LPM map (allowed/denied per family).
  # Protected entries are non-evictable; the DNS listener bootstrap consumes
  # one slot in its address family. Changing pinned-map capacity requires
  # recreating the attachment.
  max_rule_entries: 4096
  # Independent capacity of each DNS-derived exact-host HASH map (IPv4/IPv6).
  # These entries can never consume or evict authoritative/deny capacity.
  max_dns_rule_entries: 4096

Un Detach esplicito (RPC/CLI), o la rimozione di un target posseduto coerentemente vivo, distrugge lo stato pinnato insieme all'attaccamento. Al riavvio, l'assenza del target non autorizza tentativi di indovinare: i pin persistiti futuri, non impegnati, misti, o altrimenti non verificabili vengono preservati e l'avvio viene interrotto per ispezione.

Le directory dei pin sono un formato di persistenza versionato. Il marcatore dello schema viene bloccato per ultimo, solo dopo che ogni mappa e collegamento richiesto esiste. L'aggiornamento di un attaccamento a un livello pre-esatto impegna le due nuove mappe esatte vuote con un marcatore in corso, sostituisce atomicamente il programma di ogni collegamento riutilizzando le mappe autoritative vive, verifica l'identità programma/mappa e impegna il marcatore per ultimo. Un arresto anomalo o un aggiornamento ambiguo lascia il marcatore non impegnato; il successivo avvio ri-aggiorna ogni collegamento utilizzando le stesse mappe. Le generazioni di programma vecchie e nuove impongono la stessa politica LPM autoritativa durante quello stato misto limitato, quindi la migrazione non rimuove mai il pin né ricrea un filtro valido. Set di pin sconosciuti, incompleti o non verificabili vengono preservati e l'avvio viene interrotto per ispezione invece di essere indovinati.

Note sullo stato riadottato:

• Ogni attaccamento ripristinato con successo viene contrassegnato per la riconciliazione autoritativa. A ogni connessione del piano di controllo, il daemon invia prima il SyncRequest, poi una dichiarazione Subscribed completa per ogni attaccamento ripristinato che necessita ancora di riconciliazione. Rispondere con un nuovo SubscribedAck: la sua modalità, CIDR, TTL e configurazione DNS costituiscono lo stato desiderato completo. Il daemon applica un delta (i CIDR invariati non vengono mai rimossi) e cancella il marcatore di ripristino solo dopo che l'intero ack è stato applicato. Un timeout, una disconnessione o un fallimento di validazione lasciano l'applicazione invariata. Un fallimento di applicazione di filtro/mappa/DNS/store può lasciare un delta parziale, ma la riconciliazione non utilizza una cancellazione completa della mappa o una rimozione/ri-aggiunta dei sopravvissuti invariati; il marcatore di ripristino rimane impostato e il daemon riprova dopo una connessione successiva.
• Le scadenze TTL delle regole stesse non vengono persistite. Le regole riadottate vengono trattate provvisoriamente come permanenti fino all'arrivo del nuovo SubscribedAck; quell'ack autoritativo sostituisce esattamente la loro durata, inclusa la riduzione di una scadenza o la trasformazione di una regola provvisoriamente permanente in una regola con TTL finito. Le chiavi DNS esatte ripristinate vengono inventariate e rappresentate da proprietari provvisori vincolati (le capacità effettive delle mappe pinnate sono il limite); la prima configurazione DNS autoritativa scarta ogni rivendicazione sintetica, rimuove le chiavi lasciate senza proprietario e preserva una chiave solo quando ha separatamente un normale proprietario vivo. Un inventario non canonico/in conflitto interrompe il ripristino senza indovinare o pubblicare parzialmente i metadati di proprietà.
• Non esiste un documento di stato desiderato locale persistito. Se nessun piano di controllo è configurato o raggiungibile, non si verificano modifiche automatiche alle regole: una mappa pinnata adottata continua ad applicare i suoi CIDR protetti ultimi noti, rappresentati nel registro dello spazio utente come provvisori fino a un aggiornamento completo. Un ripristino che non può adottare pin validi ricrea l'attaccamento nella sua modalità persistita con mappe vuote (fail-closed per allowlist/block-all). Un orchestratore autonomo deve rieseguire dopo ogni riavvio del daemon per sostituire lo stato dei pacchetti provvisorio e ripristinare il suo stato desiderato completo e i TTL.

Per attaccamento

Il tuo sistema di orchestrazione chiama l'API locale del daemon.

RPC:``` DaemonService.Attach(interface_name: "veth123", tc_direction: TC_DIRECTION_INGRESS, metadata: {vm_id: "abc"}) // or DaemonService.Attach(cgroup_path: "/sys/fs/cgroup/...", metadata: {container_id: "xyz"})

**CLI:**```bash
# Attach to a host-side veth peer or VM tap (TC) - use ingress direction
netfenced attach --interface veth123 --direction ingress --metadata vm_id=abc

# Attach to a cgroup
netfenced attach --cgroup /sys/fs/cgroup/... --metadata container_id=xyz

# Attach to an uplink inside the workload's own netns (TC) - egress is the default
netfenced attach --interface eth0 --metadata tenant=acme,env=prod

Direzione TC: il campo tc_direction (CLI --direction) seleziona a quale hook TCX il filtro si attacca, e scegliere quello corretto dipende da quale lato del collegamento si trova l'interfaccia:

La direzione si applica solo agli attacchi a interfaccia (TC); viene ignorata per gli attacchi cgroup.

• Il demone attacca un filtro eBPF al target.
• Quando control_plane.url è configurato, il demone invia Subscribed{id, target, type, metadata} e attende SubscribedAck con la configurazione iniziale (mode, CIDRs, regole DNS). Se il control plane non risponde entro il timeout (default 5s, configurabile tramite control_plane.subscribe_ack_timeout), l'attacco viene annullato e la chiamata attach fallisce. I fallimenti di validazione e altri pre-commit seguono la stessa regola di rollback ordinario.
• Senza control plane configurato, attach viene eseguito immediatamente in modalità disabilitata; utilizzare i comandi di policy locali qui sotto per configurarlo.
• Un policy iniziale valido che incontra un fallimento di protected-map/store è l'eccezione deliberata di errore commesso: il demone mantiene l'attacco in BLOCK_ALL durevole invece di annullarlo in modo distruttivo. Con un timeout limitato, Attach restituisce un errore contenente l'ID dell'attacco mantenuto; il chiamante può scoprire quell'ID abbinando il target in List, e il control plane deve recuperarlo con un BulkUpdate completo.
• Con subscribe_ack_timeout: 0, un nuovo Attach viene restituito dopo aver accodato ; un ack successivo viene comunque validato e applicato. Questo valore zero non disabilita la riconciliazione degli attacchi ripristinati: i tentativi di ripristino attendono fino a 5s in background e riprovano su una connessione successiva se necessario. Se quell'ack successivo incontra una pressione protetta, l'attacco già restituito viene mantenuto in ; non emette né né errore , e il demone non riavvia automaticamente la dichiarazione prima del riavvio. Rilevare più la sua ragione, occupancy/capacity, e in , quindi inviare un completo con per ottenere un risultato di recupero esplicito.

RPC:``` DaemonService.Detach(id)

**CLI:**```bash
netfenced detach --id <attachment-id>

Elenco allegati:```bash netfenced list netfenced list --all # fetch all pages

### Politica locale e ispezione

Ogni mutazione locale è una sottile codifica CLI della singola
RPC `DaemonService.ApplyCommand(ControlCommand)`. Fornisci l'ID dell'allegato
restituito da `attach`:```bash
# Packet policy and protected CIDRs.
netfenced set-mode <id> allowlist
netfenced allow-cidr <id> 10.0.0.0/8
netfenced allow-cidr <id> 192.0.2.10/32 --ttl 5m
netfenced deny-cidr <id> 10.20.0.0/16
netfenced remove-cidr <id> 10.20.0.0/16 --list deny
# --list accepts allow, deny, or both (the default).

# DNS policy.
netfenced set-dns-mode <id> denylist
netfenced allow-domain <id> example.com --subdomains
netfenced deny-domain <id> blocked.example.com
netfenced remove-domain <id> blocked.example.com

# Deterministic current-policy inspection as protobuf JSON.
netfenced rules <id>

Le modalità dei pacchetti sono disabled, allowlist, denylist e block-all; le modalità DNS sono disabled, allowlist, denylist e proxy. Il DNS in modalità proxy richiede un piano di controllo configurato e raggiungibile. Il matching dei domini utilizza il suffisso di corrispondenza più specifico; quando regole di allow e deny ugualmente specifiche corrispondono entrambe, vince deny. CIDR e domini vengono canonicalizzati. TTL, enum, CIDR, domini, selettori e messaggi annidati negativi, malformati o altrimenti non validi vengono rifiutati prima della mutazione, quindi un comando non valido è un no-op per la policy.

Per una sostituzione completa, apply-rules legge la forma JSON protobuf BulkUpdate esistente da un file o da stdin:```bash cat >rules.json <<'JSON' { "mode": "POLICY_MODE_ALLOWLIST", "allowCidrs": [{"cidr": "10.0.0.0/8"}], "dns": { "mode": "DNS_MODE_DENYLIST", "denyDomains": [{"domain": "blocked.example.com", "includeSubdomains": true}] } } JSON netfenced apply-rules --file rules.json

Equivalent stdin form:

netfenced apply-rules --file - < rules.json

`ApplyCommand` accetta solo `SetMode`, `AllowCIDR`, `DenyCIDR`, `RemoveCIDR`,
`BulkUpdate`, `SetDnsMode`, `AllowDomain`, `DenyDomain` e `RemoveDomain`.
Le varianti stream-only sync/ack, comandi sconosciuti o vuoti, e valori locali
di `command_id` vengono respinti. `BulkUpdate` è anche l'unica operazione locale
in grado di recuperare una politica di pacchetti stabile degradata; deve contenere lo
stato desiderato completo di LPM e DNS.

Il selettore opzionale `ControlCommand.remove_cidr_list` può avere come target la lista
allow, la lista deny, o entrambe quando la variante del comando è `RemoveCIDR`. Il suo
valore legacy non specificato e l'esplicito `BOTH` rimuovono entrambi da entrambe le liste,
preservando il comportamento originale del protocollo.

Le mutazioni locali e del control-plane condividono un parser, una barriera di mutazione,
un registro TTL, un percorso di recupero fail-closed e un proprietario di policy.
Non esiste deliberatamente alcun arbitrato di proprietà tra locale e control-plane:
le operazioni in conflitto su una singola lista di policy hanno effetto nell'ordine in cui
vengono committate, indipendentemente dalla sorgente. In particolare, un successivo `BulkUpdate`
completo del control-plane o `SubscribedAck` può sostituire lo stato locale.

`GetRules`/`netfenced rules` restituisce un'istantanea del registro userspace coerente e
deterministica. Ogni CIDR riporta la lista allow/deny, `policyOwned` (locale o control-plane),
`systemOwned` del demone, `expiresAt` assoluto, `provisional` ripristinato e lo stato
`installed` dell'ultimo kernel committato. Una voce installata senza alcun proprietario è un
tentativo di rimozione fallito, non una policy desiderata. L'output DNS è il `DnsConfig`
effettivo live e normalizzato. L'ispezione intenzionalmente non enumera le mappe del kernel
protette né espone le voci della cache DNS risolte dinamicamente per host esatti; utilizzare
la telemetria heartbeat per l'occupazione delle mappe protette.

## Sul control-plane (lo implementi tu)

Implementa il RPC `ControlPlane.Connect` - uno stream bidirezionale:

Configura la politica di enforcement del keepalive del tuo server gRPC per consentire la
cadenza di ping del demone (`control_plane.keepalive_time`, default 30s): imposta
`MinTime` a o al di sotto di quell'intervallo e `PermitWithoutStream: true`. La politica
predefinita di gRPC (5 minuti) tratta i ping del demone come abusivi e chiude
la connessione con `ENHANCE_YOUR_CALM (too_many_pings)`. In Go:```go
grpc.NewServer(grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
    MinTime:             10 * time.Second,
    PermitWithoutStream: true,
}))

Ricevere dal demone:

• SyncRequest su connessione/riconnessione (elenca gli attachment correnti)
• Subscribed quando vengono aggiunti nuovi attachment, e dopo SyncRequest per attachment ripristinati che necessitano ancora di uno stato autorevole fresco
• Unsubscribed quando gli attachment vengono rimossi
• Heartbeat con statistiche
• CommandResult{command_id, id, success, error} — esito di qualsiasi comando inviato con un command_id non vuoto (nonce di correlazione opzionale su ControlCommand; i comandi senza nonce non producono risultato). success è vero solo se il comando è stato applicato completamente — un BulkUpdate parzialmente applicato segnala fallimento con l'errore aggregato. I risultati sono a miglior sforzo: tratta un risultato mancante come sconosciuto, non come fallito.

Inviare al demone:

• SyncAck dopo aver ricevuto SyncRequest
• SubscribedAck{mode, cidrs, dns_config} dopo aver ricevuto Subscribed (richiesto - il demone attende questo)
• SetMode{mode} - cambia la modalità della policy di filtro IP
• AllowCIDR{cidr, ttl} / DenyCIDR / RemoveCIDR (opzionalmente seleziona allow, deny, o entrambi; se non specificato mantiene il comportamento legacy "both")
• SetDnsMode{mode} - cambia la modalità di filtro DNS
• AllowDomain{domain} / DenyDomain / RemoveDomain (la corrispondenza più specifica vince; deny vince in caso di parità di specificità)
• BulkUpdate{mode, cidrs, dns_config} - sincronizzazione dello stato completo

Quando il control plane riceve Subscribed, deve rispondere con un SubscribedAck completo. Per un nuovo attachment il demone normalmente attende quell'ack prima di restituire successo al chiamante locale. Per un attachment ripristinato, l'handshake viene eseguito in background mentre la policy pinned dell'ultima conoscenza continua ad essere applicata. Utilizza i metadati per identificare la VM/tenant/container e restituisci la modalità desiderata completa, i CIDR (inclusi i TTL) e lo stato DNS; una configurazione DNS omessa significa disabilitato con liste di domini vuote.

Riconnessioni e idempotenza (richiesto)

SyncRequest è il punto di riconciliazione autorevole: ad ogni (ri)connessione è il primo evento sul flusso e elenca il set completo di attachment correnti del demone. Reconcilia la tua vista contro di esso — aggiungi attachment che non conoscevi, rimuovi quelli assenti dalla lista. Alla riconnessione, il demone elimina gli eventi che erano in coda rispetto alla connessione precedente (la sincronizzazione li sostituisce), quindi non vedrai Heartbeat obsoleti, Unsubscribed per attachment già assenti dalla sincronizzazione, o CommandResult dalla connessione morta riprodotti dopo di essa. Due casi limite rimangono per progettazione, e il tuo control plane DEVE gestirli in modo idempotente:

• Un Subscribed può seguire un SyncRequest che elenca già lo stesso id. Questo accade quando un ack di un nuovo attachment era in sospeso durante la riconnessione, e deliberatamente per ogni attachment ripristinato fino a quando un ack autorevole non viene applicato completamente. Trattalo come un aggiornamento, rispondi con un SubscribedAck completo fresco, e non scartarlo mai come duplicato. SyncRequest riconcilia l'inventario degli attachment; SubscribedAck riconcilia la policy desiderata.
• Un evento generato contemporaneamente alla (ri)connessione può competere con l'istantanea di sincronizzazione in entrambe le direzioni. Tratta un Unsubscribed per un id di attachment sconosciuto o già rimosso come un no-op.

Durata delle regole (TTL)

• Le voci CIDR (comandi AllowCIDR/DenyCIDR e le liste CIDR in SubscribedAck/BulkUpdate) hanno un TTL opzionale. Le regole con TTL vengono rimosse da un addetto alla manutenzione del demone (janitor) una volta scadute (intervallo di scansione ttl_janitor_interval, predefinito 1s); le regole senza TTL sono permanenti.
• Le riaggiunte incrementali di AllowCIDR/DenyCIDR estendono un CIDR alla scadenza successiva — non la accorciano mai — e una riaggiunta incrementale senza TTL la rende permanente. Al contrario, lo stato completo in SubscribedAck/BulkUpdate sostituisce esattamente ogni durata del control plane, quindi la riconciliazione autorevole può accorciare un TTL o cambiare da permanente a finita senza rimuovere/riaggiungere la voce della mappa attiva. Usa RemoveCIDR per eliminare una regola incrementale in anticipo.
• Gli IP risolti da DNS entrano solo nel livello esatto con il TTL del record limitato al minimo da dns.min_filter_ttl (predefinito 60s; zero/non impostato significa il predefinito, non "nessun minimo"). Un TTL upstream pari a zero vive quindi per il minimo; un TTL PROXY omesso è esplicitamente predefinito a 300s prima che venga applicato il minimo. Una regola CIDR permanente o di durata maggiore che copre lo stesso indirizzo rimane installata indipendentemente nel livello LPM protetto quando la proprietà esatta del DNS scade.