LinkShadow assets (WIP)
Reads LinkShadow's asset inventory and creates or enriches an endpoint for every machine in it. Beside the usual identity and OS fields, it records which of LinkShadow's own feeds know each machine (Active Directory, an endpoint plugin, network traffic), so a domain member that no endpoint agent reports, or a device only the network has ever seen, is visible as a coverage gap.
| Type name | linkshadow_assets |
| Creates | Endpoints |
| Runs on | A sensor with HTTPS reach to the LinkShadow console |
| Fields written | names, fqdn, domains, os, os_vendor, os_version, type, mac, mac_vendors, hw_vendor, private_ip, department, tags, services, risk, criticality, distinguished_name, first_seen, last_seen, and the ls_* fields (presence flag ls_exists) |
How it reads LinkShadow
Each run reads the whole entity list from the console's Asset AutoDiscovery view. Nothing is changed in LinkShadow.
LinkShadow keeps one entity per MAC address, not one per machine: a laptop rotating private Wi-Fi addresses appears as many entities, and a server with two NICs as two. The sensor folds them back into one record per machine before anything reaches the platform:
- Grouping. Entities with the same hostname are one machine. A generic name that every
unnamed device of its kind reports, such as
Mac,iPhone,localhostorprinter, is not grouped on: each such entity stays a record of its own, keyed on its MAC. Add names your estate hands out by default in Additional generic hostnames. - MAC addresses. Randomised (locally administered) MACs are set aside in
ls_random_mac_addresses. Only the stable ones are written tomacand used for matching. - Addresses. A machine's own addresses are those it was seen on within
Address max age (days) of its own last sighting (7 by default). Link-local, broadcast
and other non-host addresses are dropped. An address claimed by more than three machines
is treated as a gateway or NAT address and belongs to none of them; an address two or
three machines were seen on belongs to the one seen on it most recently. Addresses set
aside this way are kept in
ls_shared_ip_addresses.
Host details
Fetch host details in the scan template adds LinkShadow's per-machine detail record: OS
version, logged-in users, Active Directory computer attributes, threat score, anomaly and
alert counts, attack stages and hosted services. It costs one request per machine, so it is
off by default. Machines are enriched most recently seen first, so a limit spends its budget
on machines that are still around. ls_details_fetched shows which records got one. The
primary user is the most recent user to log on who is not a service account.
The Active Directory attributes, including the distinguished name and the directory's DNS
hostname and operating system, come only from the detail record. With Fetch host details
off, the integration cannot match on the distinguished name, cannot recognise failover
cluster names, and the ls_ad_* fields stay empty.
Last seen
LinkShadow's own "last seen" for a machine is the newest sighting from any of its feeds, and its directory feed re-reads every computer object on each collection. A machine decommissioned months ago therefore reads as seen today for as long as its computer object stays in Active Directory. The Last seen from option chooses which sighting is used, and so what Ignore if host is offline (180 days by default) measures.
| Option | Last seen is | A machine with no such sighting |
|---|---|---|
| Real activity (default) | The newest evidence the machine itself was running: traffic a sensor saw, the endpoint plugin checking in, a DHCP lease. For a device the directory does not know (a phone, a printer, a device known only by its MAC), LinkShadow's own sighting | Is skipped |
| Network activity only | What the sensors saw on the wire | Is kept, with last seen empty |
| Active Directory only | When the directory feed last read the computer object | Is kept, with last seen empty |
| Any source | LinkShadow's own answer, the newest sighting from any feed | Is kept, with last seen empty |
Whichever is chosen, the per-feed sightings are written alongside: ls_last_seen_network,
ls_last_seen_plugin, ls_last_seen_ad and ls_last_seen_reported (any source).
ls_last_seen holds the selected one and ls_last_seen_source names the option.
Active Directory only and Any source both read fresh for every computer object still in the directory. Network activity only marks every machine on a segment no sensor sees as unseen. Under Real activity, Active Directory never counts, not even the computer account logging on.
Real activity counts LinkShadow's plugin feed as evidence the machine was running, which
holds when the plugin is a per-device endpoint agent. A directory or inventory plugin would
be dated by its own poll and make machines read as alive. ls_sub_sources names the
plugins behind a machine's evidence.
The shared last_seen field takes LinkShadow's sighting when it is newer than what the
asset holds, or when the date the asset holds was written by this same instance. A machine
skipped as offline is not imported, but if it matches exactly one asset on which this
instance had written a different last_seen, that date is corrected or withdrawn. Nothing
else on the asset is touched.
Failover cluster names. A computer account that is a failover cluster's network name,
recognised by its cluster service principal names or by the description Windows writes on
it, logs on through the cluster's nodes. Its logon and password dates are the cluster's
activity, so they are not written to ls_ad_last_logon and ls_ad_pwd_last_set, and are
removed if an earlier run wrote them. The raw values stay in ls_ad_attributes.
Matching
A record is matched to an existing endpoint by the first of these that finds one, strongest first:
- Its Active Directory distinguished name, as the Active Directory
integration writes it to
distinguished_name. - Its name, on an endpoint whose known MACs do not contradict it.
- Its name, on an endpoint whose IP addresses do not contradict it.
- A stable MAC already in
ls_mac_addresses. - Its name in
ls_hostname, then innameswith no address conflict, then its short name with no address conflict, then its name innames, then its short name against any of the endpoint's names. - A stable MAC in any MAC field.
- Its addresses, on an endpoint whose name does not say it is another machine.
- Its addresses alone, only for a record that brought no usable name.
- A randomised MAC that an endpoint agent (CrowdStrike, Azure) reports as its own, on exactly one endpoint, with no real name on either side disagreeing.
A generic hostname is never matched on and never written to names. When a rule finds
several endpoints, a stable MAC settles it if it leaves exactly one; otherwise the ambiguity
is left for a person to settle. A record with no stable MAC, no usable name and no address
of its own is imported as an endpoint of its own.
What it writes
| Field | How it is written |
|---|---|
names, fqdn | Added to. The directory's DNS hostname when known, otherwise LinkShadow's hostname if it is not generic |
domains | Added to. From the directory's DNS hostname, then the distinguished name's DC= parts, then the hostname |
distinguished_name, mac, mac_vendors, tags, services | Added to |
os, os_vendor, os_version | Replaced. The directory's operating system is preferred; when it only says a build triplet such as pc-linux-gnu, LinkShadow's own OS is used |
type | Replaced, except as below |
private_ip | Replaced, with the machine's own addresses |
department | Replaced |
risk | Replaced, only when LinkShadow's risk is a severity word (Critical, High, Medium, Low, None, Informational). A number stays in ls_risk_score |
hw_vendor | Only when empty, from the MAC vendor |
criticality | Set to Critical only when empty and LinkShadow flags the machine critical |
Device type. LinkShadow's own classification is preferred, as it names kinds an OS string cannot (a printer, a camera, a switch): the console category an operator set first, then the classifications from its feeds, then the entity type. A general-purpose computer is the exception: there the OS decides between Endpoint and Server, and when the OS does not say, Endpoint is written only if the asset has no type yet.
The ls_* fields keep LinkShadow's own view, in these groups:
| Fields | Hold |
|---|---|
ls_host_key, ls_hostname, ls_hostname_is_generic, ls_entity_ids, ls_entity_count, ls_entity_uids, ls_sensors | How LinkShadow knows the machine, and which of its sensors saw it |
ls_mac_addresses, ls_random_mac_addresses, ls_random_mac_count, ls_mac_vendor | Its MACs |
ls_host_addresses, ls_current_ip_address, ls_ip_addresses, ls_shared_ip_addresses, ls_subnets, ls_subnet_masks | Its addresses: its own, the current one, every one seen, and those set aside |
ls_os, ls_os_version, ls_operating_systems, ls_entity_type, ls_asset_category, ls_classifications, ls_hardware_status, ls_hosted_services | What it is |
ls_sources, ls_sub_sources, ls_plugins, ls_in_active_directory, ls_seen_by_plugin, ls_seen_on_network, ls_endpoint_security | Which feeds know it: the coverage view |
ls_is_managed, ls_is_watched, ls_is_critical, ls_has_internet, ls_department, ls_tags, ls_comment | Flags and notes set in LinkShadow |
ls_risk_score, ls_score, ls_highest_score, ls_threat_score, ls_anomaly_count, ls_alert_count, ls_attack_stages | LinkShadow's scores and detections |
ls_primary_user, ls_primary_user_display_name, ls_primary_user_department, ls_users | Who uses it |
ls_ad_* | The Active Directory computer object, from host details |
ls_first_seen, ls_last_seen, ls_last_seen_* | Its sightings, as described in Last seen |
ls_custom_attributes, ls_entity_details | Custom attributes and the raw entity records |
ls_last_seen_network, ls_last_seen_plugin, ls_ad_last_logon and ls_ad_pwd_last_set
are decommissioning evidence.
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 able to sign in through the console's login form | The collection runs as that user's session |
| That user able to open Asset AutoDiscovery | The entity list and the host detail records are read from it |
In this deployment
| Need | Why |
|---|---|
| A registered, healthy sensor | The integration runs on a sensor, on the platform's schedule. See Sensors |
| The Active Directory and endpoint agent integrations run first | The distinguished-name and agent-MAC rules match to endpoints those integrations created |
Configuration
| Field | Required | Notes |
|---|---|---|
| Name | Yes | Label for this instance |
| URL | Yes | The LinkShadow console, e.g. https://linkshadow.example.com |
| Username | Yes | Console user the collection runs as |
| 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 your estate hands out by default, e.g. localhost,new-host, added to the built-in list |
| Address max age (days) | No | How far back from a machine's last sighting its addresses still count as its own. 7 by default |
| Sensor | Yes | Sensor that will run the integration |
Its scan template adds, beside the shared options described in Integrations:
| Option | Default | Effect |
|---|---|---|
| Last seen from | Real activity | Which sighting is last seen, and what the offline cutoff measures. See Last seen |
| Fetch host details | Off | Reads each machine's detail record, one request per machine |
| Host detail workers | 4 | Detail requests in flight at once, 1 to 16 |
| Host detail asset limit | 0 | Enrich at most this many machines, most recently seen first. 0 for all |
See also
- LinkShadow users: the user accounts LinkShadow knows
- LinkShadow DHCP: the DHCP view of the same network
- LinkShadow applications: applications seen on the network
- Integrations overview: the shared configuration model
- Sensors: where the integration runs
- Assets: how endpoints are shown and compared