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 name | linkshadow_dhcp |
| Creates | Endpoints |
| Runs on | A sensor with HTTPS reach to the LinkShadow console |
| Fields written | The 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:
- MAC and name agree. The endpoint holds the MAC and answers to the device's name.
- 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.
- 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.
- 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.
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.
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.
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.
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.
| Field | Written when |
|---|---|
ls_dhcp_* | Always, on the matched or created endpoint |
names, fqdn, domains | Added 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 |
mac | Only on a new endpoint, and only for a MAC that is not randomised, not shared and not held by any endpoint |
private_ip | Only 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_seen | Except 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.
| Field | Holds |
|---|---|
ls_dhcp_exists | Set on every endpoint this integration matched or created |
ls_dhcp_mac_address, ls_dhcp_mac_is_random | The client MAC, and whether it is randomised |
ls_dhcp_hostname, ls_dhcp_hostname_is_generic, ls_dhcp_hostnames | The name the device announced, whether it is generic, and every name it used |
ls_dhcp_client_fqdn, ls_dhcp_domain | The FQDN it registered, and its domain |
ls_dhcp_ip_address, ls_dhcp_ip_addresses | The address of the latest acknowledged lease, and every acknowledged address |
ls_dhcp_requested_addresses | Addresses the device asked for |
ls_dhcp_server_addresses, ls_dhcp_source_addresses | DHCP servers that answered, and where the client's packets came from (a relay, if there is one) |
ls_dhcp_lease_time, ls_dhcp_acked | Lease length in seconds, and whether a lease was acknowledged |
ls_dhcp_message_types, ls_dhcp_transaction_count | Counts by DHCP message type, and the number of transactions |
ls_dhcp_sensors | The LinkShadow sensors that saw it |
ls_dhcp_first_seen, ls_dhcp_last_seen, ls_dhcp_last_ack | First 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
| From | To | Protocol | Port |
|---|---|---|---|
| The sensor running the integration | The LinkShadow console | HTTPS over TCP | 443 |
Access in LinkShadow
| Need | Why |
|---|---|
| A console user with access to Shadow360 | The DHCP log is read through the raw-log search |
| Sensors writing the DHCP log | This 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
| Need | Why |
|---|---|
| A registered, healthy sensor | The integration runs on a sensor, on the platform's schedule. See Sensors |
| Endpoints already discovered by other integrations | Most leases enrich an endpoint that is already registered. Schedule this after the endpoint integrations, including LinkShadow assets |
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
| Field | Required | Notes |
|---|---|---|
| Name | Yes | Label for this instance |
| URL | Yes | The LinkShadow console, e.g. https://linkshadow.contoso.com |
| Username | Yes | Console user the collection runs as. Needs access to Shadow360 |
| Password | No | Leave empty when the session is carried by the Cookies field |
| Cookies | No | For a console behind an access gateway or SSO: name=value; name2=value2 |
| Proxy settings | No | http://host:port |
| Ignore SSL | No | Skips certificate validation. On by default |
| Additional generic hostnames | No | Comma-separated names devices on this network announce by default, e.g. kiosk,new-host, never used to recognise a machine |
| Sensor | Yes | Sensor that will run the integration |
Its scan template adds, beside the shared settings in the Integrations overview:
| Option | Default | Effect |
|---|---|---|
| Lookback (hours) | 24 | How 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 addresses | Update known devices only | For nameless devices on a randomised MAC: Update known devices only, Import as new devices or Ignore |
| Ignore if host is offline | 7 days | Skips a device whose last DHCP transaction is older than this |
See also
- LinkShadow assets: the devices LinkShadow itself inventories, whose records this integration often enriches
- LinkShadow applications: applications from the same appliance's logs
- Integrations overview: the shared configuration model
- Sensors: where the integration runs
- Assets: how endpoints and their fields are shown