Manuale Utente

Introduzione

Cos'è FireDog

FireDog è una piattaforma di gestione centralizzata del firewall per flotte di host Linux. Invece di configurare iptables a mano su ogni server, un unico pannello web (il master) permette di definire e distribuire regole a tutti gli host gestiti (i target), monitorarne il traffico bloccato e le minacce rilevate, e reagire da un solo posto.

Il prodotto è organizzato in tre componenti, ciascuno con un ruolo preciso:

A chi si rivolge questo manuale

• Chi installa e amministra FireDog (un amministratore di sistema) — capitoli 1–2.
• Chi lo usa ogni giorno per gestire target, regole e configurazione — capitoli 3 in poi.

Cosa fa FireDog

• Gestione centralizzata delle regole — CRUD standard su /api/rules/, con dispatch in tempo reale all'agent via WebSocket; se l'agent non è connesso la regola resta persistita in attesa della prossima riconciliazione.
• Supporto host multi-NIC — un target può avere più interfacce di rete; le regole possono essere scoped su un'interfaccia specifica, con contatori rx/tx per NIC.
• Policy di default DROP con protezioni integrate contro SYN-flood, port-scan e brute-force SSH (soglia, finestra e tipo di ban configurabili).
• Cattura e analisi del traffico — il traffico bloccato viene loggato in PCAP (ulogd2) e analizzato dal traffic-analyzer, che assegna un punteggio di minaccia.
• Dashboard e monitoraggio — stato dei target, statistiche di traffico, minacce rilevate, tutto in tempo reale via WebSocket.
• Audit log — ogni operazione di scrittura (regole, IP bloccati, configurazione) viene registrata con utente, azione e valori.
• Server MCP — un'interfaccia programmatica (Model Context Protocol) che permette ad agenti AI autorizzati di consultare — e, con una chiave di scrittura, agire su — regole, minacce, traffico e stato dei target.

Cosa NON fa (per evitare aspettative sbagliate)

• Non installa il firewall via push SSH dal master: il provisioning di un target avviene sempre in autonomia sul target stesso, tramite lo script di bootstrap (capitolo 1) — nessuna credenziale SSH è mai condivisa tra target e master.
• Non ha un terminale SSH integrato nella UI: la gestione del target avviene tramite la CLI firewall-manager in locale o tramite le regole distribuite dal master.
• Non è multi-tenant: un'installazione master serve un'unica organizzazione/flotta.
• Non sostituisce un IDS/IPS completo: il threat scoring del traffic-analyzer è un'euristica su traffico bloccato, non un'analisi approfondita dei pacchetti.

1. Installazione

L'installazione di FireDog è divisa in tre passi indipendenti, nell'ordine in cui vanno normalmente eseguiti: prima il master, poi gli strumenti firewall su ogni target, infine il pairing di dog-agent.

Master (server web)

Il master si installa clonando il repository e seguendo la guida INSTALL.md, testata passo-passo.

Requisiti

Passi

git clone --branch stabile https://github.com/Dognet-Technologies/firedog.git
cd firedog
cat INSTALL.md

La guida copre configurazione di PostgreSQL e Redis, virtualenv Python, build del frontend React, unit systemd per Daphne (ASGI) e Celery (già pronte in deploy/), e configurazione di nginx come reverse proxy.

Target (strumenti firewall)

Su ogni host da gestire, esegui lo script di bootstrap: scarica il pacchetto degli strumenti firewall e li installa in autonomia — nessun accesso dal master è necessario.

# scarica, ispeziona ed esegui (consigliato)
curl -fsSL https://raw.githubusercontent.com/Dognet-Technologies/firedog/stabile/firedog-package/get-firedog.sh -o get-firedog.sh
less get-firedog.sh
sudo bash get-firedog.sh            # oppure: sudo bash get-firedog.sh --skip-init

# in alternativa, one-liner diretto
curl -fsSL https://raw.githubusercontent.com/Dognet-Technologies/firedog/stabile/firedog-package/get-firedog.sh | sudo bash

Distribuzioni supportate:

Attenzione: l'attivazione del firewall applica una policy DROP su INPUT/OUTPUT. Assicurati di avere accesso console/seriale prima di confermare, oppure usa --skip-init e attiva in un secondo momento con sudo firewall-init.sh && sudo systemctl enable --now firewall-fm.

Lo script è idempotente: si può rilanciare per aggiornare gli strumenti su un target già installato.

dog-agent

Il pairing tra target e master avviene tramite dog-agent, l'agent condiviso da tutta la suite Dognet. Vedi il capitolo 8 per i dettagli del pairing.

2. Primo accesso

Apri il browser all'indirizzo del master (es. http://<indirizzo-master>) e accedi con le credenziali admin create durante l'installazione (python manage.py createsuperuser, vedi INSTALL.md). La configurazione di nginx fornita in deploy/ serve il sito in HTTP semplice: per esporlo in HTTPS va aggiunta a mano una terminazione TLS (es. certbot/Let's Encrypt) davanti al reverse proxy.

Dopo il primo accesso troverai:

• Targets — elenco degli host gestiti, stato online/offline, versione firedog installata, interfacce di rete;
• Firewall — vista unificata delle regole, IP bloccati e whitelist su tutti i target;
• Threats — minacce rilevate dal traffic-analyzer, con punteggio e possibilità di risoluzione;
• Dashboard — panoramica aggregata di traffico e stato della flotta;
• Settings — API key per l'agent, API key MCP, notifiche, gestione utenti.

3. Ruoli e permessi

FireDog usa i gruppi standard di Django per due ruoli.

Admin

Permessi completi:

• visualizzare tutti i dati (target, regole, statistiche, minacce);
• creare/modificare/eliminare target;
• aggiungere/rimuovere regole firewall e bloccare/sbloccare IP;
• modificare configurazioni di sistema;
• accesso a Django Admin.

Reporter

Permessi in sola lettura:

• visualizzare target e loro stato, regole firewall, minacce rilevate, statistiche e dashboard, audit log;
• non può creare, modificare o eliminare alcuna risorsa.

Autenticazione

FireDog usa JWT (JSON Web Token): un token di accesso (60 minuti) e uno di refresh (24 ore), ottenuti da POST /api/token/ e usati come header Authorization: Bearer <token> su tutte le chiamate API.

4. Target e multi-NIC

Censire un target

Un target si crea da Targets → Add indicando IP, hostname e MAC address esatti della macchina: il master ne calcola l'identity_hash = SHA512(ip+hostname+mac), usato in fase di pairing dell'agent (capitolo 8) per verificare che sia davvero quella macchina a connettersi.

Interfacce multiple

Se un host espone più interfacce di rete, FireDog le rileva tutte automaticamente tramite l'export periodico dell'agent e le elenca nella vista di dettaglio del target, con:

• nome interfaccia, indirizzo IP, indirizzo MAC;
• indicatore di interfaccia primaria;
• contatori di traffico ricevuto/inviato (rx/tx bytes e packets), aggiornati a ogni heartbeat;
• un selettore NIC per filtrare statistiche e regole per interfaccia specifica.

Per default vengono riportate tutte le interfacce rilevate; è possibile restringere l'elenco (es. per escludere interfacce virtuali come docker0 o veth*) tramite MONITORED_INTERFACES nel file di configurazione del target — vedi capitolo 6.

5. Regole firewall

Le regole sono un CRUD standard su /api/rules/: lettura per tutti gli utenti autenticati, scrittura riservata al ruolo Admin.

Creare una regola

POST /api/rules/
Authorization: Bearer <token>
Content-Type: application/json

{
    "target": 1,
    "chain": "INPUT",
    "port": 80,
    "protocol": "tcp",
    "action": "ACCEPT",
    "source_ip": "192.168.1.0/24",  // opzionale
    "interface": "eth0",             // opzionale, NIC specifica su host multi-NIC
    "comment": "HTTP traffic"        // opzionale
}

Alla creazione, il master tenta subito di inviare il comando al target via WebSocket. Se l'agent è connesso, la regola viene applicata immediatamente e marcata is_synced: true; se il target è offline, resta comunque salvata nel database (is_synced: false) e verrà applicata alla prossima riconnessione dell'agent.

Il campo interface

Su un target con più NIC, valorizzare interface applica la regola come -i <interfaccia> (chain INPUT) o -o <interfaccia> (chain OUTPUT) invece che su tutte le interfacce. Non è supportato sulla chain FORWARD.

Rimuovere una regola

DELETE /api/rules/{id}/
Authorization: Bearer <token>

IP bloccati e whitelist

Oltre alle regole generiche, FireDog gestisce due liste dedicate — Blocked IPs (IP bloccati manualmente o dal threat-scoring) e Whitelist (IP sempre permessi, mai bloccati automaticamente) — entrambe distribuite ai target con lo stesso meccanismo di dispatch via WebSocket.

6. Configurazione del target

/etc/firewall/firedog.conf è il file di configurazione locale del target, seedato al primo install (come custom_rules.conf: non viene mai sovrascritto agli aggiornamenti). Formato KEY="value", leggibile sia da bash (firewall-init.sh) sia da firewall-manager.py.

# Interfacce da monitorare/riportare al master (separate da virgola).
# Vuoto = tutte le interfacce rilevate (default).
MONITORED_INTERFACES="eth0,eth1"

# Porte da tenere sempre aperte in INPUT, prima della policy DROP finale.
# La porta SSH è già protetta a parte, non va elencata qui.
ALWAYS_OPEN_PORTS="80/tcp,443/tcp"

# Protezione SSH brute-force — vedi capitolo 7.
SSH_PROTECT_MAX_ATTEMPTS="4"
SSH_PROTECT_WINDOW_SECONDS="60"
SSH_PROTECT_BAN_DURATION="0"

Importante: ALWAYS_OPEN_PORTS va valorizzato prima di lanciare firewall-init.sh la prima volta — senza, qualunque servizio in ascolto su quelle porte diventerebbe irraggiungibile non appena la policy DROP entra in vigore. Dopo una modifica, applica con sudo firewall-init.sh (idempotente: va rilanciato per raccogliere le modifiche).

7. Protezione SSH brute-force

Oltre alla soglia di tentativi/finestra temporale (SSH_PROTECT_MAX_ATTEMPTS/SSH_PROTECT_WINDOW_SECONDS), FireDog può reagire al superamento della soglia con un ban vero e proprio, non solo il drop nella finestra:

Il ban richiede il pacchetto ipset (installato di default dallo script target) ed è persistente: sopravvive a un rilancio di firewall-init.sh e, tramite salvataggio periodico da cron, anche a un riavvio della macchina.

Gestire i ban attivi

firewall-manager --list-bans        # IP bannati e tempo alla scadenza (o "permanente")
firewall-manager --unban 203.0.113.5  # rimuove un ban, incluso uno permanente

8. dog-agent e pairing

L'agent si autentica al master con un pairing a 2 fasi sul WebSocket ws(s)://<master>/ws/agent/:

dog-agent                              master
    │  {"api_key", ip, hostname, mac}    │
    ├────────────────────────────────────▶
    │        FASE 1: verifica API key    │  API key attiva (hash SHA-512)
    │        FASE 2: verifica identità   │  SHA512(ip+hostname+mac) ==
    │                                    │  target.identity_hash
    ◀────────────────────────────────────┤
    │  pairing OK → heartbeat/stats/     │
    │  threats push + comandi regole     │

1. Sul master — Settings → API Keys Agent → genera una nuova API key (globale per la flotta, hashata SHA-512).
2. Sul master — censisci il target (capitolo 4) con IP, hostname e MAC esatti.
3. Sul target — installa dog-agent (vedi la pagina dedicata) e configura /etc/dog-agent/agent.conf:

   [[targets]]
   system_type = "firedog"
   url         = "http://<master>"         # https:// solo se hai aggiunto TLS davanti al master
   api_key     = "<chiave generata al passo 1>"
   ip          = "<ip del target>"        # identici al Target censito
   hostname    = "<hostname>"
   mac         = "aa:bb:cc:dd:ee:ff"

4. Sul target — sudo systemctl enable --now dog-agent e verifica con journalctl -u dog-agent -f (cerca "pairing success").

Se il pairing fallisce: API key errata/disattivata (fase 1) oppure ip/hostname/mac che non coincidono col Target sul master (fase 2) — l'errore è visibile sia nei log dell'agent sia nella UI del master.

9. Server MCP

FireDog espone un server MCP (Model Context Protocol) su POST /api/mcp (JSON-RPC 2.0, autenticazione Bearer con API key dedicata) che permette ad agenti AI autorizzati di consultare — e, se la chiave lo consente, agire su — la piattaforma in modo programmatico: elenco target, regole firewall, minacce, statistiche di traffico e network flow.

Le chiavi si generano da Settings, con lo stesso principio di scope in lettura/scrittura usato per le altre integrazioni della suite: una chiave in sola lettura può solo consultare dati, una chiave di scrittura può anche creare/eliminare regole e bloccare IP. Le operazioni di scrittura via MCP sono registrate nell'audit log come qualsiasi altra modifica.

10. Aggiornamenti

Master

Aggiorna il repository alla release desiderata, applica le migration del database e riavvia i servizi:

git fetch
git checkout stabile
git pull
# segui la sezione "Aggiornamenti" di INSTALL.md per migration e restart dei servizi

Strumenti target

Rilancia lo script di bootstrap — è idempotente, aggiorna gli strumenti già installati senza toccare custom_rules.conf o firedog.conf:

curl -fsSL https://raw.githubusercontent.com/Dognet-Technologies/firedog/stabile/firedog-package/get-firedog.sh -o get-firedog.sh
sudo bash get-firedog.sh

dog-agent

Scarica il nuovo pacchetto dalla release più recente e reinstalla (upgrade in place, la configurazione esistente non viene toccata):

sudo dpkg -i dog-agent_<versione>-1_amd64.deb   # Debian/Ubuntu
sudo zypper install ./dog-agent-<versione>-1.x86_64.rpm  # openSUSE/SLES

11. Domande frequenti

Perché un target appare offline anche se l'agent è attivo?

Controlla che dog-agent sia effettivamente in esecuzione e correttamente configurato (journalctl -u dog-agent -f). Se il pairing è andato a buon fine ma il master mostra comunque "offline" più a lungo di un paio di minuti dopo un riavvio del backend, verifica di essere su FireDog v1.0.0 o successivo: le versioni precedenti potevano restare bloccate su "offline" dopo un'interruzione temporanea dell'heartbeat.

Posso installare gli strumenti firewall senza attivare subito la policy DROP?

Sì: usa sudo bash get-firedog.sh --skip-init. Attiverai il firewall in un secondo momento con sudo firewall-init.sh && sudo systemctl enable --now firewall-fm, quando avrai verificato ALWAYS_OPEN_PORTS in firedog.conf.

Come aggiungo una porta sempre aperta su un target già in produzione?

Modifica ALWAYS_OPEN_PORTS in /etc/firewall/firedog.conf e rilancia sudo firewall-init.sh: lo script ricrea l'intero ruleset, quindi pianifica una finestra di manutenzione — non basta modificare il file, serve il rilancio per applicare la modifica.

È possibile installare FireDog e CyberSheppard/SentinelCore sullo stesso host?

Sì: dog-agent è unico per tutta la suite. Basta aggiungere un blocco [[targets]] per ciascun prodotto nello stesso agent.conf.

Perché SSH (o altre connessioni legittime) vengono bloccate dopo pochi tentativi ravvicinati?

Nelle versioni precedenti la v1.0.1 le soglie di SSH_PROTECT e SYN_FLOOD erano troppo basse (4 tentativi/60s, 10 pacchetti SYN/s) e scattavano anche con un uso normale (tool di amministrazione, riconnessioni rapide), droppando la sorgente con "Connection reset by peer" o timeout. Dalla v1.0.1 i default sono SSH_PROTECT_MAX_ATTEMPTS=20 e SYN_FLOOD_LIMIT_PER_SEC=50/SYN_FLOOD_BURST=100 (quest'ultimo ora configurabile in firedog.conf come già era per SSH_PROTECT). Su un target già installato, aggiorna gli strumenti (sezione Aggiornamenti) o imposta i valori direttamente in /etc/firewall/firedog.conf e rilancia firewall-init.sh.