Dispositivi

Una persona, un telefono, un filtro — i dispositivi sono il modo in cui Warden sa a chi ha appena risposto.

Cos’è

Un dispositivo è un singolo endpoint sulla LAN — telefono, laptop, console, smart TV, lampadina IoT — fissato in Warden tramite il suo indirizzo IP, il suo MAC, o entrambi. Ogni dispositivo può avere il suo profilo, o appoggiarsi al default di un gruppo o della subnet.

Questa pagina copre quando aggiungere una voce dispositivo, ogni campo di identificazione e classificazione, e le superfici CLI / TUI / API che li leggono e li scrivono. Per il quadro d’insieme della risoluzione delle query, vedi processo di filtraggio.

Quando ti serve

Aggiungi una voce [[devices]] quando ti serve una di queste cose:

• Un profilo che segue una persona specifica anche quando il MAC viene randomizzato (telefoni dei bambini, laptop dei ragazzi).
• Un’eccezione per un singolo dispositivo — per esempio, il profilo “kids” blocca YouTube ma all’iPad della figlia maggiore serve per la scuola. Dai a quel dispositivo un profilo suo con una Custom List.
• Un nome leggibile nella TUI / nel query log al posto di 192.168.1.107.
• Un bersaglio per le scorciatoie block / quiet (“metti l’iPad in punizione fino alle 21:00”).

Non serve una voce per ogni host. Gli host non mappati ricadono sulla subnet ([[subnets]]) o sul default_profile globale, ed è esattamente il comportamento giusto per una VLAN ospiti o una serie di lampadine IoT identiche.

Schema

Una voce [[devices]] ha queste parti: identità (come Warden abbina il dispositivo), classificazione (come compare in TUI e CLI) e il profilo a cui punta. Un dispositivo non ha regole di filtro proprie.

Dimensioni di identità

Warden abbina un dispositivo confrontando l’IP sorgente di una query DNS con queste firme. L’IP sorgente identifica il dispositivo quando coincide con il suo ip, oppure quando lo snapshot della tabella ARP letto da Warden mostra quell’IP al mac del dispositivo o a uno dei suoi mac_aliases. Con [server].enforce_device_mac attivo (il default), il solo ip non identifica un dispositivo: Warden ha bisogno di un MAC da controllare (vedi il controllo del MAC). Un dispositivo con ip e senza mac mantiene il suo profilo solo finché la tabella ARP mostra a quell’indirizzo uno dei suoi mac_aliases; altrimenti le sue query ricadono sulla subnet o sul default_profile. Il solo IP funziona soltanto con enforce_device_mac = false. Configurare sia ip sia mac permette a Warden di ritrovare il dispositivo dopo un rinnovo DHCP, ma non subito: vedi quando viene riconosciuto un nuovo lease.

Ogni campo MAC accetta un solo MAC esatto: sei coppie di cifre esadecimali separate da due punti, come AA:BB:CC:DD:EE:FF. Wildcard, prefissi e intervalli (02:00:00:00:00:*, 02:00:00) non sono ammessi, e una configurazione che ne contiene uno viene rifiutata al caricamento. Per coprire molte macchine virtuali, vedi molte macchine virtuali o container.

Il controllo del MAC

Con [server].enforce_device_mac = true (il default, in passato enforce_client_mac), Warden non si fida di un indirizzo sorgente da solo. Quando l’IP sorgente di una query corrisponde a un dispositivo (il suo ip fissato, o un indirizzo visto per l’ultima volta a uno dei suoi MAC), Warden guarda il MAC che il suo snapshot ARP mostra a quell’indirizzo:

Prima della 0.44.5 il controllo confrontava solo mac: un dispositivo visto a uno dei suoi MAC alias veniva declassato, e così un dispositivo visto a un indirizzo fissato da un altro dispositivo. Ora entrambi mantengono o trovano il proprio profilo. Le righe di audit sono elencate nella pagina delle subnet.

Il controllo è ergonomico, non crittografico: un attaccante deciso con accesso fisico può falsificare qualsiasi MAC, ma basta a impedire a un adolescente curioso di cambiarsi l’IP statico per sfuggire al profilo “kids”.

Quando viene riconosciuto un nuovo lease

Dopo un rinnovo DHCP il nuovo indirizzo del dispositivo non corrisponde a nessun ip configurato. Warden cerca allora l’indirizzo in uno snapshot della tabella ARP di sistema e ritrova il dispositivo dal suo mac. Lo snapshot non è in tempo reale: Warden rilegge la tabella ARP soltanto:

• all’avvio del daemon;
• quando la configurazione viene caricata o ricaricata (vale anche per ogni modifica con warden device, warden group o warden subnet, che ricarica il daemon a caldo);
• quando un client chiede l’elenco dei dispositivi: la TUI mentre mostra la tab Dashboard, Dispositivi o Subnet (ogni 2-5 s), oppure warden device list --live;
• ogni 60 s se la configurazione ha almeno uno schedule: il controllo degli schedule ricostruisce l’indice dei dispositivi da una nuova lettura ARP, quindi di solito un dispositivo con mac viene ritrovato entro circa un minuto.

Senza schedule, nessun timer lo aggiorna. Finché non accade una di queste cose, le query dal nuovo indirizzo non vengono associate al dispositivo e ricadono sulla subnet o sul default_profile. Un dispositivo con mac e senza ip viene trovato solo in questo modo.

Riferimento dei campi

Lo schema 5 non ha allow_rules, deny_rules né override_profile_deny su un dispositivo, e una configurazione che li contiene viene rifiutata. Su un host aggiornato dalla 0.41 le regole dei dispositivi vengono spostate in una Custom List e in una copia del profilo; vedi regole personalizzate (in inglese).

Esempi

Voce minima — fissa un host, puntalo a un profilo:

[[devices]]
id = "kids-tablet"
display_name = "iPad dei bambini"
ip = "192.168.1.50"
mac = "11:22:33:44:55:66"
profile = "kids"

Un dispositivo con alias MAC per un telefono che randomizza, classificato per la TUI. Il telefono mantiene il suo profilo con uno qualsiasi dei tre MAC:

[[devices]]
id = "alice-iphone"
display_name = "iPhone di Alice"
ip = "192.168.1.107"
mac = "AA:BB:CC:DD:EE:FF"
mac_aliases = [
  "22:33:44:55:66:77",
  "33:44:55:66:77:88",
]
profile = "kids"
owner = "Alice"
device_type = "iPhone"
department = "family"

Un dispositivo senza profilo diretto — il profilo arriva dal gruppo a priorità più alta a cui appartiene:

[[devices]]
id = "kitchen-bulb"
display_name = "Lampadina cucina"
mac = "FF:EE:DD:CC:BB:AA"
groups = ["iot-lite"]
device_type = "Smart bulb"
department = "iot"

CLI

Ogni sottocomando di scrittura attiva un hot reload del daemon (swap atomico della config, niente restart). I sottocomandi di sola lettura (list, show) funzionano anche senza il daemon.

warden device allow, warden device deny e warden device rules prune sono ritirati nella 0.44.0. Falliscono senza scrivere nulla. Vedi regole personalizzate (in inglese).

Pattern comuni:

# fissa un nuovo tablet
sudo warden device add kids-tablet \
  --ip 192.168.1.50 --mac 11:22:33:44:55:66 \
  --profile kids --owner Alice --device-type iPad

# coprifuoco
sudo warden device quiet kids-tablet --for 12h

# attività live
warden device list --live

Fonte: src/cli/commands/devices.rs, src/cli/mod.rs → DeviceAction.

TUI

Premi 3 (o g v) nella TUI per saltare alla tab Dispositivi. La vista è master/detail: dispositivi configurati e host non mappati osservati live in un’unica lista, con una scheda di dettaglio sulla destra che mostra vendor, statistiche di cache, alias MAC, e profilo effettivo.

Per la tab vera e propria (ogni colonna, gli assi di raggruppamento e cosa dice la scheda di dettaglio) vedi la tab Dispositivi. Quello che segue è la versione breve.

Combinazioni di tasti nella tab Dispositivi:

• a — apre il modal Aggiungi (i campi rispecchiano warden device add).
• e — Modifica il dispositivo configurato selezionato.
• d — Cancella con conferma s/n. Rifiutato finché un gruppo elenca il dispositivo o uno schedule lo prende come bersaglio.
• Enter su una riga non mappata — promuovi la riga: il modal Aggiungi si apre già pre-compilato con IP + MAC osservati; tu fornisci id e display_name.
• G — cicla l’asse di raggruppamento: nessuno → owner → department → profile.
• ↑/↓ — naviga; le righe header dei gruppi vengono saltate. Anche Home/End/PgUp/PgDn spostano la selezione.
• i — apre i dettagli; Esc li chiude.
• f — mette il focus sul filtro Subnet. / filtra la lista per subnet (CIDR); R toglie il filtro.

La lista interroga il daemon ogni 5 s tramite il comando IPC GetAllDevices. Fonte: src/tui/tabs/devices.rs.

API REST

Le statistiche live dei dispositivi sono esposte dalle API locali.

GET /api/devices — autenticato con Bearer token. Restituisce un oggetto JSON il cui array devices contiene una voce per ogni dispositivo che ha colpito il daemon dall’ultimo snapshot:

{
  "devices": [
    {
      "name": "kids-tablet",
      "ip": "192.168.1.50",
      "queries": 4321,
      "blocked": 187,
      "blocked_pct": 4.3,
      "cache_hits": 2890,
      "profile": "kids",
      "last_seen": 1714820400
    }
  ]
}

Il path legacy /api/clients è deprecato; le risposte trasportano gli header Deprecation e Sunset che puntano a /api/devices.

IPC

Sul socket Unix: IpcCommand::DeviceStats { token: None } restituisce IpcResponse::DeviceList { clients: Vec<DeviceStatEntry> }. Stessi campi della REST. Richiede il token di amministrazione. Fonte: src/api/handlers.rs, src/ipc/protocol.rs.

Ordine di precedenza

Quando arriva una query, Warden percorre cinque livelli in quest’ordine. Vince la prima corrispondenza.

1. Schedule attivo. Una voce [[schedules]] con una finestra temporale che copre adesso riguarda questo dispositivo o uno dei suoi gruppi.
2. Profilo diretto del dispositivo. L’IP sorgente corrisponde a ip (o il MAC corrisponde via ARP), e il dispositivo imposta profile = "...".
3. Profilo di gruppo. Il dispositivo non ha profile diretto ma appartiene a uno o più [[groups]]. Vince il gruppo a priorità più alta; i conflitti a parità di priorità sono errori del validator.
4. Subnet, longest-prefix match. Nessun livello precedente ha trovato una corrispondenza — nessuna riga dispositivo, un dispositivo senza profilo, gruppo o schedule, o un dispositivo escluso dal controllo del MAC — e l’IP sorgente cade in un CIDR di [[subnets]]. Vince il prefisso più lungo.
5. Fallback globale. [server].default_profile. Se non impostato, le query non mappate ricevono REFUSED.

Uno schedule attivo viene controllato prima del profilo del dispositivo, quindi vince dentro la sua finestra. Senza quest’ordine, uno schedule su un dispositivo che ha già un profilo non farebbe nulla. Uno schedule che prende come bersaglio il dispositivo vince su uno che prende come bersaglio uno dei suoi gruppi.

Un dispositivo non ha regole proprie. Una volta scelto il profilo, decidono la query solo le liste e le Custom List di quel profilo.

Se enforce_device_mac = true e ARP mostra all’indirizzo sorgente un MAC che non è né il mac del dispositivo né uno dei suoi mac_aliases, il dispositivo viene declassato al livello subnet per quella query. Schedule, profilo diretto e gruppo vengono saltati. Lo stesso accade, mentre enforce_device_mac è attivo (lo è di default), a un dispositivo che ha un ip e nessun mac, a meno che la tabella ARP non mostri al suo indirizzo uno dei suoi mac_aliases. Se il MAC appartiene a un altro dispositivo configurato, la query viene risolta come quel dispositivo, attraverso tutti e cinque i livelli. Vedi il controllo del MAC. Fonte: src/profiles/resolver.rs → ProfileResolver::resolve() (il controllo del MAC, poi schedule, profilo diretto e gruppo), build_resolver_map() (i MAC e gli indirizzi che identificano ogni dispositivo), compute_active_schedules() (lo schedule del dispositivo prima di quello del gruppo).

Note di sicurezza

• Gli indirizzi MAC sono in chiaro in config.toml e devices.d/*.toml. Non vengono hashati.
• Il query log registra client_ip e client_name (l’id del dispositivo). Non registra il MAC.
• L’audit log registra le operazioni CRUD sui dispositivi — add, remove, modifica di campi — con uid del chiamante, azione e target id. Non registra i MAC.
• L’enforcement del MAC è ergonomico, non crittografico. Ferma il cambio IP casuale, non un attaccante deciso con accesso fisico. Per la garanzia precisa, vedi il threat model (in inglese).
• Le note (notes = "...") restano sull’host. L’API REST non le restituisce. Il socket IPC locale le porta alla TUI.

Risoluzione problemi

Viene applicato il profilo sbagliato. Chiedi direttamente al resolver:

warden resolve 192.168.1.50
# Source IP:      192.168.1.50
# Matched device: kids-tablet (iPad dei bambini)
# Match level:    1 (direct device profile)
# Active profile: kids

Se il livello mostrato non è quello che ti aspettavi, risali la catena — il MAC è stato randomizzato? il lease si è spostato? enforce_device_mac sta declassando il dispositivo? a quell’indirizzo risponde ora il MAC di un altro dispositivo?

Un telefono che ieri funzionava oggi finisce sulla subnet. Quasi sempre randomizzazione del MAC. Controlla nella tab Dispositivi della TUI la riga non mappata che condivide lo stesso IP — mostra il nuovo MAC. Aggiungi quel MAC ai mac_aliases del dispositivo, nel modulo Modifica della TUI (e) o nel TOML, poi esegui sudo warden reload. Un alias identifica il telefono e supera il controllo del MAC, quindi anche il vecchio MAC continua a funzionare. warden device set non può modificare mac_aliases; può solo sostituire il mac primario:

sudo warden device set alice-iphone mac 22:33:44:55:66:77

Un dispositivo fissato solo per IP perde il profilo dopo un riavvio del router. Il DHCP ha riassegnato il lease. Fissa il lease sul router, oppure aggiungi un mac alla voce così l’identità segue l’hardware. Il mac non ha effetto nell’istante in cui cambia il lease: Warden ritrova il dispositivo solo dopo la lettura successiva della tabella ARP (vedi quando viene riconosciuto un nuovo lease). Un warden reload, o l’apertura della tab Dispositivi della TUI, forza quella lettura.

Il journal dice observed MAC belongs to another device. Il router ha assegnato al dispositivo B un indirizzo ancora fissato con ip al dispositivo A, e Warden conosce B dal suo mac o da un alias. Warden vede nella tabella ARP il MAC di B a quell’indirizzo e, con enforce_device_mac attivo, risolve la query come B, con il profilo di B, quindi B non viene declassato. L’avviso ti dice che il pin di A è superato. Con enforce_device_mac = false non c’è alcun controllo del MAC, e B riceve il profilo di A finché il pin punta a quell’indirizzo. Quando sposti un dispositivo su un altro indirizzo nel router, aggiorna subito il suo pin: sudo warden device set <id> ip <nuovo-indirizzo>.

warden device allow o deny fallisce con “Legacy allow/deny rules and device overlays are retired”. È previsto dalla 0.44.0. Per un’eccezione su un solo dispositivo, dai al dispositivo un profilo suo e monta su quel profilo una Custom List:

sudo warden profile add alice --display-name "Alice"
sudo warden custom-list create alice-allow --display-name "Alice allow"
sudo warden custom-list add alice-allow classroom.example.com --allow
sudo warden profile mount alice --custom-list alice-allow
sudo warden device set alice-iphone profile alice

Una configurazione che ha ancora allow_rules, deny_rules o override_profile_deny su un dispositivo viene rifiutata al caricamento.

Un host dual-stack riceve il profilo sbagliato su IPv6. Lo schema attuale memorizza un solo ip per dispositivo. Se l’host ha indirizzi v4 e v6 separati, fissa l’IPv6 con una voce [[subnets]] che copra il suo CIDR IPv6. Il mac qui non aiuta: Warden legge solo la tabella ARP IPv4, quindi un MAC non identifica mai una sorgente IPv6.

Molte macchine virtuali o container con lo stesso profilo

Warden non ha un pattern per i MAC: mac e mac_aliases accettano un solo MAC esatto ciascuno, quindi 02:00:00:00:00:* viene rifiutato. Oggi ci sono due strade.

Opzione A: un dispositivo per ogni VM, riconosciuto dal MAC, tutti in un gruppo. Assegna a ogni VM un MAC proprio (va bene uno amministrato localmente, come 02:00:00:00:00:01), dichiaralo solo con --mac e lascia che sia il gruppo a portare il profilo. Non impostare un profilo sui dispositivi: un profilo diretto vincerebbe sul gruppo. Crea prima il gruppo (il profilo lab deve già esistere):

sudo warden group add vms --display-name "Macchine virtuali" --profile lab
sudo warden device add vm-01 --mac 02:00:00:00:00:01 --groups vms
sudo warden device add vm-02 --mac 02:00:00:00:00:02 --groups vms

Oppure in TOML:

[[groups]]
id = "vms"
display_name = "Macchine virtuali"
profile = "lab"

[[devices]]
id = "vm-01"
display_name = "vm-01"
mac = "02:00:00:00:00:01"
groups = ["vms"]

L’appartenenza si può scrivere da entrambi i lati: groups sul dispositivo o devices sul gruppo. Warden unisce i due elenchi. warden device add --groups scrive il lato del dispositivo. Ogni nuova VM richiede comunque una sua voce, e una VM viene trovata solo dopo la lettura successiva della tabella ARP (vedi quando viene riconosciuto un nuovo lease). Non fissare una VM con il solo ip: con enforce_device_mac attivo (il default) quel dispositivo viene ignorato.

Opzione B: dai alle VM un intervallo di indirizzi dedicato e aggiungi una subnet. Riserva un blocco di indirizzi per le VM sul server DHCP, per esempio 192.168.1.192/26, poi:

sudo warden subnet add vm-range --display-name "Intervallo VM" --profile lab --cidrs 192.168.1.192/26

Una subnet corrisponde solo all’IP sorgente. Non guarda i MAC e non richiede una lettura ARP, quindi un nuovo lease nell’intervallo è coperto subito. Il prezzo: qualsiasi host che prende un indirizzo di quell’intervallo riceve il profilo, e --profile non dovrebbe essere meno restrittivo del tuo default_profile. Vince il prefisso più lungo, quindi una /26 batte una subnet /24 che la contiene. Una voce dispositivo per lo stesso indirizzo ha comunque la precedenza. Vedi subnet.

Per altro, vedi risoluzione problemi (in inglese).

Vedi anche

• Profili — cosa contiene un profilo (liste di blocco, regole, risposta di blocco).
• Gruppi — assegna un solo profilo a molti dispositivi.
• Subnet — fallback per host non mappati.
• Pianificazioni — scambi di profilo basati sull’orario.
• Regole personalizzate (in inglese) — dove stanno ora le regole; un dispositivo non ne ha di proprie.
• Riferimento CLI — la superficie completa di warden device ….