From ce1402b5f38c1945c310843adb167e6fcd04eb1d Mon Sep 17 00:00:00 2001 From: Olivier Date: Mon, 18 May 2026 12:00:58 +0200 Subject: [PATCH] docs: add Apple to brand tables and troubleshooting section (proxy-ARP) - Add Apple ecosystem row in all three README brand tables - Add Troubleshooting section explaining proxy-ARP false positives and the TCP check fix (fr/en/es) Co-Authored-By: Claude Sonnet 4.6 --- README.es.md | 18 ++++++++++++++++++ README.fr.md | 18 ++++++++++++++++++ README.md | 18 ++++++++++++++++++ 3 files changed, 54 insertions(+) diff --git a/README.es.md b/README.es.md index 40283ba..dad093f 100644 --- a/README.es.md +++ b/README.es.md @@ -318,6 +318,7 @@ Pueden aparecer varios logos simultáneamente si coinciden varias palabras clave | Correo | Servidor de correo | `mail`, `smtp`, `imap`, `postfix`, `dovecot`, `mailcow`, `mailu`, `roundcube` | | Base de datos | MariaDB | `mariadb`, `maria db` | | Orquestación | Kubernetes | `kubernetes`, `k8s`, `kubectl`, `k3s` | +| Ecosistema Apple | Apple | `apple`, `iphone`, `ipad`, `ipados`, `macbook`, `imac`, `mac mini`, `mac pro`, `mac studio`, `macos`, `mac os`, `ios`, `icloud`, `airpods`, `airdrop` | | OS | Debian | `debian` | | OS | Ubuntu | `ubuntu` | | Automatización | Ansible | `ansible` | @@ -393,6 +394,23 @@ npm run dev # Servidor dev Vite en :5173, proxifica /api/ hacia :8000 --- +## 🔧 Solución de problemas + +### El escaneo devuelve cientos de falsos positivos (proxy-ARP / UniFi) + +**Síntoma** — El descubrimiento automático reporta tantos hosts como direcciones hay en la subred (por ejemplo 254 para un `/24`), cuando en realidad solo hay unas pocas máquinas presentes. + +**Causa** — Algunos equipos de red (especialmente UniFi Security Gateway, Dream Machine y equipos similares) activan el proxy-ARP y responden a los pings ICMP para **todas** las IPs de la subred, suplantando la IP de origen de la respuesta. La verificación de IP de origen integrada en el escáner no puede filtrar estos falsos positivos. + +**Solución** — Activar la opción **"Verificación TCP (anti proxy-ARP)"** en la pantalla de configuración del escaneo. Esta opción sondea cada host en los puertos TCP 22, 80, 443, 8080 y 8443 tras el ping ICMP: + +- Un **host real** responde con RST (puerto cerrado) o acepta la conexión → considerado activo. +- Una **IP fantasma**: el gateway descarta silenciosamente el SYN sin responder → timeout → eliminada. + +> **Nota**: un equipo cuyo firewall descarte silenciosamente (*DROP*, sin RST) **todos** los puertos sondeados no será descubierto automáticamente y deberá añadirse manualmente. + +--- + ## 🏗️ Arquitectura Ver [`docs/architecture.md`](docs/architecture.md) para el flujo de solicitudes detallado, la configuración Docker y el modelo de autenticación. diff --git a/README.fr.md b/README.fr.md index 7c64451..0de4ed4 100644 --- a/README.fr.md +++ b/README.fr.md @@ -318,6 +318,7 @@ Plusieurs logos peuvent s'afficher simultanément si plusieurs mots-clés corres | Messagerie | Serveur mail | `mail`, `smtp`, `imap`, `postfix`, `dovecot`, `mailcow`, `mailu`, `roundcube` | | Base de données | MariaDB | `mariadb`, `maria db` | | Orchestration | Kubernetes | `kubernetes`, `k8s`, `kubectl`, `k3s` | +| Écosystème Apple | Apple | `apple`, `iphone`, `ipad`, `ipados`, `macbook`, `imac`, `mac mini`, `mac pro`, `mac studio`, `macos`, `mac os`, `ios`, `icloud`, `airpods`, `airdrop` | | OS | Debian | `debian` | | OS | Ubuntu | `ubuntu` | | Automatisation | Ansible | `ansible` | @@ -393,6 +394,23 @@ npm run dev # Serveur dev Vite sur :5173, proxifie /api/ vers :8000 --- +## 🔧 Dépannage + +### Le scan remonte des centaines de faux positifs (proxy-ARP / UniFi) + +**Symptôme** — La découverte automatique retourne autant d'hôtes qu'il y a d'adresses dans le sous-réseau (par exemple 254 pour un `/24`), alors que seules quelques machines sont réellement présentes. + +**Cause** — Certains équipements réseau (notamment UniFi Security Gateway, Dream Machine et équipements similaires) activent le proxy-ARP et répondent aux pings ICMP pour **toutes** les IP du sous-réseau, en usurpant l'IP source de la réponse. La vérification de l'IP source intégrée au scan ne peut donc pas filtrer ces faux positifs. + +**Solution** — Cocher l'option **"Vérification TCP (anti proxy-ARP)"** dans l'écran de configuration du scan. Cette option sonde chaque hôte sur les ports TCP 22, 80, 443, 8080 et 8443 après le ping ICMP : + +- Un **vrai hôte** répond avec RST (port fermé) ou accepte la connexion → considéré vivant. +- Une **IP fantôme** : le gateway droppe silencieusement le SYN sans répondre → timeout → éliminée. + +> **Note** : un équipement dont le pare-feu bloque silencieusement (*DROP*, sans RST) **tous** les ports sondés ne sera pas découvert automatiquement et devra être ajouté manuellement. + +--- + ## 🏗️ Architecture Voir [`docs/architecture.md`](docs/architecture.md) pour le flux de requêtes détaillé, la configuration Docker et le modèle d'authentification. diff --git a/README.md b/README.md index 2a1cd57..2a45c5e 100644 --- a/README.md +++ b/README.md @@ -318,6 +318,7 @@ Multiple logos can appear simultaneously if several keywords match. | Mail | Mail server | `mail`, `smtp`, `imap`, `postfix`, `dovecot`, `mailcow`, `mailu`, `roundcube` | | Database | MariaDB | `mariadb`, `maria db` | | Orchestration | Kubernetes | `kubernetes`, `k8s`, `kubectl`, `k3s` | +| Apple ecosystem | Apple | `apple`, `iphone`, `ipad`, `ipados`, `macbook`, `imac`, `mac mini`, `mac pro`, `mac studio`, `macos`, `mac os`, `ios`, `icloud`, `airpods`, `airdrop` | | OS | Debian | `debian` | | OS | Ubuntu | `ubuntu` | | Automation | Ansible | `ansible` | @@ -393,6 +394,23 @@ npm run dev # Vite dev server on :5173, proxies /api/ to :8000 --- +## 🔧 Troubleshooting + +### Scan returns hundreds of false positives (proxy-ARP / UniFi) + +**Symptom** — Auto-discovery reports as many hosts as there are addresses in the subnet (e.g. 254 for a `/24`), while only a few machines are actually present. + +**Cause** — Some network equipment (notably UniFi Security Gateway, Dream Machine, and similar devices) enables proxy-ARP and responds to ICMP pings for **every** IP in the subnet, spoofing the source IP of the reply. The built-in source-IP check in the scanner cannot filter these false positives. + +**Fix** — Enable the **"TCP check (anti proxy-ARP)"** option in the scan configuration screen. This option probes each host on TCP ports 22, 80, 443, 8080, and 8443 after the ICMP ping: + +- A **real host** replies with RST (port closed) or accepts the connection → marked alive. +- A **ghost IP**: the gateway silently drops the SYN without replying → timeout → discarded. + +> **Note**: a device whose firewall silently drops (*DROP*, without RST) **all** probed ports will not be discovered automatically and must be added manually. + +--- + ## 🏗️ Architecture See [`docs/architecture.md`](docs/architecture.md) for the detailed request flow, Docker setup, and authentication model.