Warda-DNSDocs Warda: from ward — to protect, guardian
v0.9.3
Menu

Network scan

Warda looks at the network of its default gateway only (a /23 at most), and nothing leaves it:

  • an empty UDP datagram to the discard port of each address, so that the kernel fills its neighbour table (ARP): no raw socket, no capability;
  • multicast DNS and SSDP queries, and their announcements heard all the time (ports 5353 and 1900; a machine that runs avahi-daemon shares the port); the UPnP description of a machine is read only from that machine, once a day, and only if it is in the neighbour table; a multicast DNS answer gives the name and model of the machine that sends it only when it carries its own address and no other (a router relaying the announcements of a printer does not become a printer);
  • reverse lookups at the box for the names;
  • the title of the home page of each machine (128 at most per scan, port 80, following a redirection to HTTPS on the same machine without checking its certificate: nothing is sent, only the title is kept), which gives the model of routers, firewalls and NAS.

The box is recognised from the title of its home page, its reverse name and the maker of its network card. Since 0.7.0 Warda knows 45 boxes of the providers of the European Union, the United Kingdom, Switzerland and Norway (internal/netscan/providers.go: Free, Orange, SFR, Bouygues Telecom, Proximus, VOO, Telenet, POST, KPN, Ziggo, Odido, Telekom, Vodafone, O2, 1&1, A1, Magenta, Swisscom, Sunrise, Salt, TIM, WINDTRE, Fastweb, Iliad, Movistar, Orange / Jazztel, MásMóvil, MEO, NOS, Digi, Orange Polska, Play, UPC, eir, Virgin Media, BT, Sky, Telia, Telenor, COSMOTE, Starlink…); when a mark is shared (a Livebox in France and in Spain, a Vodafone Station in several countries), the country of the installation decides, else the first one listed. It also knows 21 families of routers bought by the household, mesh systems included: TP-Link Deco and TP-Link (Archer), Netgear Orbi and Netgear (Nighthawk), ASUS ZenWiFi and ASUS (AiMesh), Linksys Velop and Linksys, Google Nest Wifi, Amazon eero, Ubiquiti AmpliFi and UniFi, MikroTik RouterOS, OpenWrt, pfSense, OPNsense, DD-WRT, Synology Router, AVM FRITZ!Box, Huawei and ZTE (4G/5G). Only marks seen on the equipment itself count (its page, its name, the maker of its card).

When the gateway is a router of the household, Warda looks for the router behind it on the way to the Internet (the second hop, when its address is private and it is in 192.168.0.0/16 or answers with a page of its own) and recognises it: the page shows "Behind it, on the way to internet: your box Livebox, at 192.168.1.1." and a note on the double NAT, as information: Warda works this way; Warda is given as DNS server in the router the devices connect to, not in the box. The page and the assistant say where that setting usually is for the family recognised. A router that answers the devices itself (eero, Google Nest Wifi, Netgear Orbi, AmpliFi: dns proxy) only lets the server it asks be chosen: the network is protected, but Warda sees every device as the router, unless Warda gives the addresses (its DHCP server); the page says so. For the boxes whose DNS cannot be changed (dns fixed: Livebox in France, SFR Box, Speedport, Vodafone Station in Germany, Ziggo, Virgin Media, BT, Sky, Starlink), the advice is to let Warda give the addresses.

GET /api/v1/network gives, in router: addr, mac, vendor, name, title, kind (box, router or mesh; absent when not recognised), isp, isp_name and box_name (the provider and its box), family and family_name (the router of the household), where (where its DNS setting usually is), dns (dhcp: the DNS server given to the devices can be set; fixed: it cannot; proxy: the router answers itself), admin_url, upstream (addr, title, isp, isp_name, box_name: the box behind a router of the household, absent without one) and self (the address of Warda to give). isp keeps its keys free, orange, sfr and bouygues; the new providers have keys of their own (proximus, kpn, vodafone-de, starlink…). The other routers and firewalls of the network are listed as before. Every 15 minutes Warda looks again which machines answer (ARP only, no name asked): a machine or a device seen once is never forgotten, and is shown as not available, with the last time it was seen, when it was not seen for 45 minutes (only the machines with a private, random hardware address given to no device are forgotten after 90 days: phones change it often). The machines are not in backups. Docker needs the host network for this, as for DNS.

A client whose hardware address Warda cannot find (a router that forwards every query, another network) is a device known only by its IP address. Such new devices are created 32 at once at most, then one every 2 minutes (the addresses of the box itself are not counted): past that, their queries are recorded without a device, and a warning is logged at most every 10 minutes.

Network → Network analysis says for each machine whether it uses Warda (Yes, or Not yet: no name asked within 24 hours). Since 0.6.8 a machine is also recognised by its IP address: a machine that asks Warda while its hardware address was not in the neighbour tables has a device known by its address only, and that device counts for it; so do the other network cards of a machine whose devices were merged (below). The machines that use Warda no longer stay at Not yet.

One device per machine#

A machine must be one device, whatever told Warda about it. Two things made one machine two devices up to 0.6.7: the routers give the devices a name in the domain of the local network (zeu.tips-of-mine.local, tv.fritz.box, pc.home) while the same machine announces itself with its bare name (zeu); and a new IPv6 address (a temporary one, a network the neighbour tables never showed) made a device known by its address only. Since 0.6.8:

  • the names given by the network lose the domain of the local network: the customary suffixes (local, lan, home, localdomain, internal, intranet, private, corp, box, localnet, home.arpa), the local domain of Warda and the zones of the conditional forwarding rules (the domain of the router); the names already kept are cleaned by the task below;
  • the task One device per machine (devices.merge, a minute after the start, then every 5 minutes) merges a device known by its address only into the device of the hardware address the neighbour tables now give to that address (seen in the last 10 minutes; reason neighbour), or into the only device with a hardware address that has the same name (reason name: only when the device known by its address appeared in the last 24 hours and both were seen in the last 24 hours, and never for a name systems give themselves out of the box, whatever its case: localhost, raspberrypi, ubuntu, debian, iphone, ipad, android, laptop, desktop, pc, and the names starting with android-, galaxy, macbook, desktop-, laptop- — several machines of a network may carry them; those are merged by hand); a merge made when a query arrives is address. Each merge is written in the administration log (device.merge, by warda, "old → kept (reason)");
  • Devices → Merge… on the row of a device (administrators, area devices) chooses in Same machine as the other device, and asks to confirm ("… keeps its name, its place and its rules, and gets the history of … with the rules and unblocked names it does not have. … leaves the list. This cannot be undone."). The devices with the same name are listed first, marked "(same name)". POST /api/v1/devices/{id}/merge {"device_id": <the other>}: the other goes into {id}; 400 for a device into itself or the box of Warda, 409 for two devices placed differently; audit device.merge.

The device kept keeps its name, its place and its rules, and gets what it lacks from the other: its whole history (the counts of the same period added up), the rules, unblocked names, services and channels blocked it does not have, a name, a place, and its hardware address, kept beside its own (device_macs, in the backups: the network analysis and the next merges know the machine by both cards). The quarantine and what is kept in memory follow; a query recorded a moment after the merge is moved too. Two devices placed differently (given to two people, put in two groups by hand; a group guessed is only a guess) are never merged, automatically or by hand ("These two devices are placed differently (two people or two groups): place them the same way first."). The box of Warda itself is never merged.

Managed switches#

Warda listens, on every Ethernet interface of the box, to the announcements of the equipment it is plugged into: LLDP (IEEE 802.1AB, 01:80:c2:00:00:0e, type 0x88cc) and CDP (Cisco, 01:00:0c:cc:cc:cc). A managed switch (or a router, an access point) sends them on each of its ports every 30 to 60 seconds; an unmanaged switch says nothing, and these frames do not cross a switch. Network → Network analysis shows the equipment heard: its name, model and version, its capabilities (switch, router, Wi-Fi access point…), the port the box is plugged into, its VLAN and its address of administration; with none after a few minutes, the box is plugged into an unmanaged switch, straight into the router, or the announcements are turned off. Warda sends nothing: two raw packet sockets (AF_PACKET, CAP_NET_RAW, allowed by warda.service) receive the LLDP frames and the 802.2 (LLC) frames, of which only CDP is read; their texts are cut to 200 characters and 32 equipments at most are kept, in memory, a day after their last announcement (internal/lldp, Linux only). Docker needs the host network and NET_RAW.

Map of the network#

Network → Network map (administrators; free, beta) draws the network of the home simply: the box of the Internet (the gateway), under it the switches and the Wi-Fi access points, and under each the machines plugged in by cable or connected by Wi-Fi (the devices of Warda and the machines found by the scan, seen within 30 days; the absent ones faded). Nothing is asked of the equipment: Warda uses only what it already knows.

  • Equipment: what announces itself (LLDP, CDP: its capabilities say switch or access point; matched to a machine of the network by its address of administration, its hardware address or its name), and the machines of the group Wi-Fi and network equipment or that look like it: a name such as sw-…, switch, SG350 says a switch, ap, borne, mesh, deco, repeater an access point, otherwise "network equipment". The box of the Internet itself is left out of the machines.
  • Wi-Fi or cable: a private, random hardware address is Wi-Fi (only the Wi-Fi of phones, tablets and computers uses them); a machine of a person, a connected object or a camera is taken for Wi-Fi, and so is a machine of a maker of objects with Wi-Fi only (Nest, Google, Amazon, Espressif, Tuya, Shelly, Xiaomi, TP-Link, AzureWave, Murata…: admin.wifiMakers); a NAS, a server and this box for a cable, the others for a cable.
  • The access points by their maker: network equipment of a maker of access points and mesh points (Synology, Ubiquiti, eero, Ruckus, Aruba, Zyxel…: admin.apMakers) is taken for an access point when its name says nothing.
  • The tables of the managed switches (SNMP v2c, read only): given the community of a switch (Correct on the switch; kept in the settings, never shown nor written in the log), Warda reads the hardware addresses it learnt on each port (Q-BRIDGE-MIB dot1qTpFdbPort, else BRIDGE-MIB dot1dTpFdbPort) and the names of the ports (ifName), at most 16 switches, 6 seconds in all, kept 2 minutes (internal/snmp; an answer that does not match the question asked, or an unusual identifier in a table, is skipped without spoiling the rest). A machine alone on a port is plugged into that switch by cable, on that port; the machines behind the port of an access point are its Wi-Fi (the trick to know which access point a phone uses, when the access points are plugged into the switch); several machines on one port are behind a simple switch; a port where the box of the Internet or several equipment are seen leads further up and tells nothing. What an administrator said wins. snmp of the node: ok (with ports), no answer, or the error.
  • The box of the Internet takes its name from its model; a router that shares a printer on its USB port announces the model of the printer, which is left out.
  • Where: the cables on the equipment this box is plugged into when it announces itself, else on the only switch, else on the box of the Internet; the Wi-Fi on the only access point, on the box of the Internet when it is a router with no access point known, else on Wi-Fi (access point to say); the equipment on the box of the Internet.

Two views: Plan (the default, remembered in the browser): a zone by equipment with its machines inside and the equipment plugged into it below, icons by kind of machine (computer, phone, NAS, TV, printer, camera, connected object), cables in full lines, Wi-Fi in green dotted lines, a dot green when present, the whole plan scaled to fit its frame (no scrolling, on a phone as on a computer); and List. Since 0.6.8 the plan is in colour: each machine takes the colour and the icon of its kind (this Warda box, the devices of people, TVs and consoles, NAS, printers, cameras, connected objects, network equipment, other machines), the kind being the default group its device is in, else what its name says (kind of the machine in GET /api/v1/network/map); the box of the Internet and this box stand out; the links are coloured by type (cable, Wi-Fi, between two equipments) and grey when the machine was not seen lately; a Legend under the plan gives the colours of the machines and of the links. What is guessed is drawn dashed. Correct (on an equipment) or a click on a machine says what it is (a machine, a switch, an access point, network equipment, or as guessed), how it is connected and to what; it is kept (network_map in the settings, one entry per machine), and a loop said by mistake is cut at the box. An equipment that announces itself stays network equipment (its role can be changed, not removed); without a hardware address it is known by a hash of its identifier (lldp:…). GET /api/v1/network/map gives nodes (the box of the Internet first: key, label, role router, switch, ap or equipment, parent, source gateway, lldp, admin or guess, role_guessed, parent_guessed, snmp, ports) and machines (key: the hardware address, or self for this box; link ethernet or wifi, link_guessed, parent, parent_guessed, person, kind, port); PUT /api/v1/network/map {"key": "aa:bb:cc:dd:ee:ff", "role": "ap", "link": "wifi", "parent": "<key of an equipment>", "snmp": "<community>"} (each field optional, auto back to the guess, "snmp": "" stops reading the switch; this box is never network equipment; audit network.map, snmp without the community).