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, sovrascrivere una singola regola sopra il profilo del gruppo, o appoggiarsi al default 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. Per i vincoli per campo, vedi il riferimento TOML.

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 sopra un profilo — per esempio, il profilo “kids” blocca YouTube ma l’iPad della figlia maggiore lo usa per la scuola.
• 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 tre strati: identità (come Warden abbina il dispositivo), classificazione (come compare in TUI e CLI), e overlay (eccezioni per dispositivo sopra il profilo risolto).

Dimensioni di identità

Warden abbina un dispositivo confrontando l’IP sorgente di una query DNS con queste firme. Una sola firma è sufficiente — IP e MAC si combinano in OR, non in AND, quindi configurarli entrambi permette di raggiungere il dispositivo anche dopo un rinnovo DHCP o una randomizzazione del MAC.

Se [server].enforce_client_mac = true (il default) e la tabella ARP mostra un MAC che non corrisponde né a mac né a un mac_aliases, il dispositivo viene declassato fuori dal suo profilo diretto e trattato come non mappato — si applica la subnet o il default_profile. Il declassamento è 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”.

Riferimento dei campi

Il tetto combinato allow_rules + deny_rules è di 64 voci (soft, warning del validator) / 128 (hard, rifiutato). Fonte: src/config/schema/device.rs.

Esempi

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

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

Un dispositivo che segue una ragazzina anche con MAC randomizzato, classificato per la TUI, con un’unica regola di allow sopra il profilo “kids” per la scuola:

[[devices]]
id = "anna-iphone"
display_name = "iPhone di Anna"
ip = "10.10.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 = "Anna"
device_type = "iPhone"
department = "famiglia"
tags = ["mobile", "scuola"]

allow_rules = ["anna-allow-classroom"]
override_profile_deny = false

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.

Pattern comuni:

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

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

# eccezione per un singolo dispositivo
sudo warden device allow anna-iphone classroom.example.com

# attività live
warden device list --live

Fonte: src/cli/commands/devices.rs, src/cli/mod.rs:474.

TUI

Premi 3 (o g d) 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.

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 se uno schedule lo referenzia ancora.
• 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.
• ↑/↓ (o j/k) — naviga; le righe header dei gruppi vengono saltate.

La lista interroga il daemon ogni 5 s tramite il comando IPC DeviceStats. 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 array JSON, una voce per ogni dispositivo che ha colpito il daemon dall’ultimo snapshot:

[
  {
    "name": "kids-tablet",
    "ip": "10.10.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. Sola lettura, nessun token richiesto. 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. Profilo diretto del dispositivo. L’IP sorgente corrisponde a ip (o il MAC corrisponde via ARP), e il dispositivo imposta profile = "...".
2. Schedule attivo. Una voce [[schedules]] con una finestra temporale che copre adesso riguarda questo dispositivo o uno dei suoi gruppi.
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. L’IP sorgente non è in [[devices]] ma 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.

override_profile_deny, allow_rules e deny_rules agiscono dentro il profilo risolto — sono un overlay, non un livello a parte.

Se enforce_client_mac = true e ARP mostra un MAC diverso, il dispositivo viene declassato al livello 4 (subnet) per quella query. Schedule, gruppo e profilo diretto vengono saltati. Fonte: src/profiles/resolver.rs.

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, overlay allow/deny — con uid del chiamante, azione, target id, e se è stato usato override_profile_deny. 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 modello delle minacce.
• Le note (notes = "...") restano locali. Non vengono mai serializzate via IPC o REST.

Risoluzione problemi

Viene applicato il profilo sbagliato. Chiedi direttamente al resolver:

warden resolve 10.10.1.50
# Level 1: device 'kids-tablet' → profile 'kids'

Se il livello mostrato non è quello che ti aspettavi, risali la catena — il MAC è stato randomizzato? il lease si è spostato? enforce_client_mac sta declassando il 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. Promuovila (Enter) o aggiungila a mac_aliases:

sudo warden device set anna-iphone mac_aliases "[AA:BB:CC:DD:EE:FF,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.

warden device allow è rifiutato con RULE_REFUSED_OVERRIDE. Il profilo del dispositivo nega già quel dominio e override_profile_deny è false. Alza il flag e riprova, oppure aggiungi la regola di allow a livello di profilo:

sudo warden device set anna-iphone override_profile_deny true
sudo warden device allow anna-iphone classroom.example.com

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, oppure affidati al mac (che funziona indipendentemente dalla famiglia di indirizzi, finché il dispositivo è sullo stesso segmento L2 di Warden).

Per altro, vedi risoluzione problemi.

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 admin — le regole referenziate da allow_rules / deny_rules.
• Riferimento TOML — ogni campo, ogni vincolo.
• Riferimento CLI — la superficie completa di warden device ….