Skip to main content
Version: 0.9

LinkShadow DHCP (WIP)

Reads the DHCP log LinkShadow's sensors write off the network and turns it into one record per client MAC: the name each device announces, the domain it registers under, the address it currently holds and when it last renewed.

A DHCP exchange is a device saying, in one packet, which network adapter it is on, what it calls itself and what address it was handed, whether or not any other tool manages it. So this integration mostly enriches endpoints the inventory already holds, and for the rest discovers what nothing else reports: IP phones, meeting-room units, building controllers.

Type namelinkshadow_dhcp
CreatesEndpoints
Runs onA sensor with HTTPS reach to the LinkShadow console
Fields writtenThe ls_dhcp_* fields, and names, fqdn, domains, mac, private_ip and last_seen where nothing contradicts them

How it reads LinkShadow​

The sensor reads the sensors' own DHCP log through LinkShadow's Shadow360 raw-log search. That log is written from mirrored traffic, so it holds every DHCP exchange a sensor saw whether or not a DHCP server sends its logs to the appliance. Nothing is changed in LinkShadow.

  • Each run reads the last Lookback hours, 24 by default, in half-hour slices. A slice that returns too many records to be complete is split until it is not.
  • Records are folded into one finding per client MAC, with every transaction for it: the names it announced, the addresses it was offered and acknowledged, the DHCP servers that answered and the message types seen.
  • A MAC leased under several device names (a USB network adapter or dock moved between laptops) is split into one finding per name and flagged as shared.
  • A device whose last DHCP transaction is older than Ignore if host is offline (7 days by default) is skipped.

Matching​

Correlation is the whole job of this integration. A finding is compared with the tenant's endpoints on its MAC, its announced name and, if it sent one, its registered FQDN (the name a domain member registers through DHCP). Names are compared on the short name; where both sides state a DNS domain, the domains must agree. The rules, strongest first; the first rule that names an endpoint wins:

  1. MAC and name agree. The endpoint holds the MAC and answers to the device's name.
  2. MAC, no contradicting name. The endpoint holds the MAC and is not known by some other name. This covers an endpoint whose record carries no name yet.
  3. Registered FQDN. The endpoint carries the device's FQDN, or its short name in the same domain. It identifies a domain member whichever adapter the lease came in on.
  4. Name, no contradicting MAC. The endpoint answers to the name and none of the network adapters it is known by says it is another device.

There is deliberately no rule that matches on the MAC alone once the names disagree, and none matches on the leased IP address.

When a rule names several endpoints (usually one machine imported twice), it keeps the one this integration already updates for that MAC, then the one LinkShadow assets recorded the MAC on, then the one with the exact FQDN, then the one that answers to the name. A step is taken only if it leaves exactly one endpoint; otherwise the finding is left for review and writes no shared field.

Docks and USB adapters

A dock or USB network adapter is leased by whichever laptop it is plugged into, so its MAC can sit on one laptop's record while another laptop leases it today. A MAC match is vetoed when the endpoint is known by a different name, and the lease is matched by the name it announces instead. A shared MAC is never written to mac.

Phones that announce the PC's name

Some desk phones announce the name of the PC plugged in behind them. That is why a MAC match (rule 2) ranks above a bare name match (rule 4), and why a name only matches an endpoint whose own adapters do not contradict it.

Leased addresses change hands

Short leases move between devices within hours, so the leased address often points at a different device than the MAC does. No rule uses it. Behind a DHCP relay, the source address of the packets is the relay's, and is recorded but never treated as the device's address.

Generic names identify nothing

Default names a whole class of device ships with, such as Mac, iPhone, android or localhost, and any name containing a space (a model name), are ignored on both sides: in the finding, and in the names an endpoint is known by. Add names your own devices announce by default under Additional generic hostnames.

Randomised MAC addresses​

Phones and laptops often use a randomised (privacy) MAC per network. A device on one that announces no name is handled by the Randomised MAC addresses option: by default its lease is put on an endpoint that already carries that address, and nothing new is created. Imported as a new device, it becomes an endpoint that is not recognised again once the address rotates. A device on a randomised MAC that announces a real name is always processed.

What it writes​

Every run's findings are decided together, against one snapshot of the endpoints, so that nothing is written that another endpoint contradicts.

FieldWritten when
ls_dhcp_*Always, on the matched or created endpoint
names, fqdn, domainsAdded only when no endpoint, the matched one included, already carries the short name. domains is the domain from the device's FQDN, not the network's search domain
macOnly on a new endpoint, and only for a MAC that is not randomised, not shared and not held by any endpoint
private_ipOnly from an acknowledged lease, only into an empty field, and only when no other endpoint holds that address. Of several leases on one address in a run, the newest fills it
last_seenExcept when a nameless lease matched a named endpoint on its MAC alone (rule 2), which is not corroborated. The lease time is still kept in ls_dhcp_last_seen

Further guards on the run as a whole:

  • No new endpoint under a taken name. A device that matches nothing but whose name another endpoint carries is skipped.
  • One machine, one new endpoint. A machine that leased on two MACs in one run (its own adapter and a dock) is created once. The next run finds it by name.
  • One endpoint, one lease. When several leases match one endpoint, only the best one writes: a MAC an agent on the machine reports, then an acknowledged lease, then a named one, then a MAC no other endpoint holds, then the newest.
FieldHolds
ls_dhcp_existsSet on every endpoint this integration matched or created
ls_dhcp_mac_address, ls_dhcp_mac_is_randomThe client MAC, and whether it is randomised
ls_dhcp_hostname, ls_dhcp_hostname_is_generic, ls_dhcp_hostnamesThe name the device announced, whether it is generic, and every name it used
ls_dhcp_client_fqdn, ls_dhcp_domainThe FQDN it registered, and its domain
ls_dhcp_ip_address, ls_dhcp_ip_addressesThe address of the latest acknowledged lease, and every acknowledged address
ls_dhcp_requested_addressesAddresses the device asked for
ls_dhcp_server_addresses, ls_dhcp_source_addressesDHCP servers that answered, and where the client's packets came from (a relay, if there is one)
ls_dhcp_lease_time, ls_dhcp_ackedLease length in seconds, and whether a lease was acknowledged
ls_dhcp_message_types, ls_dhcp_transaction_countCounts by DHCP message type, and the number of transactions
ls_dhcp_sensorsThe LinkShadow sensors that saw it
ls_dhcp_first_seen, ls_dhcp_last_seen, ls_dhcp_last_ackFirst and last transaction, and the last acknowledged lease

ls_dhcp_last_seen and ls_dhcp_last_ack are decommissioning evidence: a device that renews its lease is on the network.

Requirements​

Network access​

FromToProtocolPort
The sensor running the integrationThe LinkShadow consoleHTTPS over TCP443

Access in LinkShadow​

NeedWhy
A console user with access to Shadow360The DHCP log is read through the raw-log search
Sensors writing the DHCP logThis is the log searched. The connection test checks the log source exists, and reports when it holds nothing from the last hour

In this deployment​

NeedWhy
A registered, healthy sensorThe integration runs on a sensor, on the platform's schedule. See Sensors
Endpoints already discovered by other integrationsMost leases enrich an endpoint that is already registered. Schedule this after the endpoint integrations, including LinkShadow assets
A sensor sees only its own segments

LinkShadow sees the traffic its sensors are attached to. A device on a segment no sensor sees, or whose DHCP requests are not mirrored to one, never shows here. On some segments a sensor may see only the server's replies, which carry no client name.

Configuration​

FieldRequiredNotes
NameYesLabel for this instance
URLYesThe LinkShadow console, e.g. https://linkshadow.contoso.com
UsernameYesConsole user the collection runs as. Needs access to Shadow360
PasswordNoLeave empty when the session is carried by the Cookies field
CookiesNoFor a console behind an access gateway or SSO: name=value; name2=value2
Proxy settingsNohttp://host:port
Ignore SSLNoSkips certificate validation. On by default
Additional generic hostnamesNoComma-separated names devices on this network announce by default, e.g. kiosk,new-host, never used to recognise a machine
SensorYesSensor that will run the integration

Its scan template adds, beside the shared settings in the Integrations overview:

OptionDefaultEffect
Lookback (hours)24How many hours of DHCP logs each run reads, 1 to 168. A day sees every client on a weekly lease renew at least once
Randomised MAC addressesUpdate known devices onlyFor nameless devices on a randomised MAC: Update known devices only, Import as new devices or Ignore
Ignore if host is offline7 daysSkips a device whose last DHCP transaction is older than this

See also​