Skip to main content
Version: 0.10

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 namelinkshadow_assets
CreatesEndpoints
Runs onA sensor with HTTPS reach to the LinkShadow console
Fields writtennames, 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, localhost or printer, 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 to mac and 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.

Two machines can carry the same hostname, for example two laptops imaged with one name. When a grouped record's stable MACs identify at least two existing endpoints that answer to that name, each MAC held by that endpoint alone, the platform splits the record back into one per machine and matches each part on its own MACs, addresses and sightings. A MAC that several machines hold, such as a docking station's, identifies nothing and never splits a record.

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.

Directory data needs host details

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 match a machine with a generic hostname on its directory 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 of host is offline (180 days by default) measures.

OptionLast seen isA 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 sightingIs skipped
Network activity onlyWhat the sensors saw on the wireIs kept, with last seen empty
Active Directory onlyWhen the directory feed last read the computer objectIs kept, with last seen empty
Any sourceLinkShadow's own answer, the newest sighting from any feedIs 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.

Only Real activity says whether a machine is alive

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 trusts the endpoint plugin

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:

  1. Its Active Directory distinguished name, as the Active Directory integration writes it to distinguished_name.
  2. Its name, on an endpoint whose known MACs do not contradict it.
  3. Its name, on an endpoint whose IP addresses do not contradict it.
  4. A stable MAC already in ls_mac_addresses.
  5. Its name in ls_hostname, then in names with no address conflict, then its short name with no address conflict, then its name in names, then its short name against any of the endpoint's names.
  6. A stable MAC in any MAC field.
  7. Its addresses, on an endpoint whose name does not say it is another machine and whose OS is not another family.
  8. Its addresses alone, only for a record that brought no usable name, on an endpoint whose OS is not another family.
  9. 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.

"Its name" is LinkShadow's hostname, or, when that is missing or generic, the directory's DNS hostname from host details. A generic hostname itself is never matched on and never written to names.

An address match is a lease, and a lease outlives its holder, so the OS is what tells a new holder from the old one. Windows, Linux, macOS and iOS (including iPadOS) are families one machine cannot be two of: a Mac or an iPhone that took over a Windows laptop's address is not merged into that laptop. An OS unknown on either side, or one that names a vendor rather than a family, vetoes nothing.

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​

FieldHow it is written
names, fqdnAdded to. The directory's DNS hostname when known, otherwise LinkShadow's hostname if it is not generic
domainsAdded to. From the directory's DNS hostname, then the distinguished name's DC= parts, then the hostname
distinguished_name, mac, mac_vendors, tags, servicesAdded to
os, os_vendor, os_versionReplaced. 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
typeReplaced, except as below
private_ipReplaced, with the machine's own addresses. A record with no address of its own (every address it was seen on is shared or set aside) leaves the field alone
departmentReplaced
riskReplaced, only when LinkShadow's risk is a severity word (Critical, High, Medium, Low, None, Informational). A number stays in ls_risk_score
hw_vendorOnly when empty, from the MAC vendor
criticalitySet 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:

FieldsHold
ls_host_key, ls_hostname, ls_hostname_is_generic, ls_entity_ids, ls_entity_count, ls_entity_uids, ls_sensorsHow LinkShadow knows the machine, and which of its sensors saw it
ls_mac_addresses, ls_random_mac_addresses, ls_random_mac_count, ls_mac_vendorIts MACs
ls_host_addresses, ls_current_ip_address, ls_ip_addresses, ls_shared_ip_addresses, ls_subnets, ls_subnet_masksIts 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_servicesWhat it is
ls_sources, ls_sub_sources, ls_plugins, ls_in_active_directory, ls_seen_by_plugin, ls_seen_on_network, ls_endpoint_securityWhich feeds know it: the coverage view
ls_is_managed, ls_is_watched, ls_is_critical, ls_has_internet, ls_department, ls_tags, ls_commentFlags and notes set in LinkShadow
ls_risk_score, ls_score, ls_highest_score, ls_threat_score, ls_anomaly_count, ls_alert_count, ls_attack_stagesLinkShadow's scores and detections
ls_primary_user, ls_primary_user_display_name, ls_primary_user_department, ls_usersWho 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_detailsCustom 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​

FromToProtocolPort
The sensor running the integrationThe LinkShadow consoleHTTPS over TCP443

Access in LinkShadow​

NeedWhy
A console user able to sign in through the console's login formThe collection runs as that user's session
That user able to open Asset AutoDiscoveryThe entity list and the host detail records are read from it

In this deployment​

NeedWhy
A registered, healthy sensorThe integration runs on a sensor, on the platform's schedule. See Sensors
The Active Directory and endpoint agent integrations run firstThe distinguished-name and agent-MAC rules match to endpoints those integrations created

Configuration​

FieldRequiredNotes
NameYesLabel for this instance
URLYesThe LinkShadow console, e.g. https://linkshadow.example.com
UsernameYesConsole user the collection runs as
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 your estate hands out by default, e.g. localhost,new-host, added to the built-in list
Address max age (days)NoHow far back from a machine's last sighting its addresses still count as its own. 7 by default
SensorYesSensor that will run the integration

Password and Cookies are secrets: once saved, the console shows them as a locked box with Replace and Remove, never shows them back, and sends them only to the sensor.

TODO

Confirm the cookie-only sign-in. Username is required, and the sensor always signs in with the username and password when a username is set, so an empty password fails the sign-in even when the Cookies field carries a session. Only with no username does the sensor use a sessionid cookie from the Cookies field as the session.

Its scan template adds, beside the shared options described in Integrations:

OptionDefaultEffect
Last seen fromReal activityWhich sighting is last seen, and what the offline cutoff measures. See Last seen
Fetch host detailsOffReads each machine's detail record, one request per machine
Host detail workers4Detail requests in flight at once, 1 to 16
Host detail asset limit0Enrich at most this many machines, most recently seen first. 0 for all

See also​