Skip to main content
Version: 0.10

Active scanner

Probes the subnets you name, enumerates what answers, and turns the result into assets. It is the only source in the catalogue that discovers a host nothing else knows about — no agent, no directory record, no cloud API — which is precisely what it is for.

Type nameactive_scanner
CreatesEndpoints
Runs onA sensor with routed access to the target subnets
Presence flagactive_scanner_exits
Field prefixactive_scanner_
Active scanning is intrusive by nature

This integration sends traffic to every address in scope. It can trip IDS rules, and on fragile devices — industrial controllers, older printers, embedded appliances — a port scan can cause instability. Agree the target scope and the window with the network owners before enabling it, and start with one small subnet.

What it contributes​

  • Reachability — which addresses answered, and nmap's view of their state
  • Open ports and services — what is actually listening, versus what is documented
  • Hostnames — from reverse DNS, traceroute, NetBIOS, SMB, RDP and TLS certificates
  • OS identity — from nmap's fingerprinting and from protocol-specific probes
  • Hardware identity — vendor and model, where an HTTP probe recognises the device
  • SSH host key fingerprints — a stable identifier that survives address changes
  • Host detail from an authenticated SSH probe, if you enable it and supply credentials

Alongside its own active_scanner_* fields it writes the shared asset fields, so what it finds correlates against every other source. Nearly all of them are written in do-not-override mode — see Exported fields.

How a run works​

Half the work happens on the sensor and half in the console. The split matters when you are debugging: a scan that "found nothing" failed on the sensor, a scan that found hosts but created no assets failed in identification.

Subnets are processed sequentially, and each one reports progress back to the console as it completes — a long run is visible in Scan history while it is still going.

Requirements​

Network access​

FromToProtocolPort
The sensor running the scanEvery address in the configured SubnetsTCP (and ICMP where the network permits)The ports nmap selects — see What the scan actually sends
The sensorOpen HTTP/HTTPS ports on discovered hostsHTTPS/HTTP over TCPThe ports listed in Ports for HTTP Probe
The sensorOpen SSH ports on discovered hostsSSH over TCPThe ports listed in Ports for SSH Probe, if the SSH probe is enabled

This is the one integration whose traffic is inbound to your own estate, so the firewall work is internal: the sensor's segment needs a route to each target segment, and inter-VLAN ACLs have to permit it. A sensor that cannot route to a subnet reports a clean, empty scan rather than an error.

On the sensor host​

NeedWhy
nmap installedThe sensor shells out to it; the container image ships it
Raw socket privilegesOS fingerprinting and SYN scanning need them. The sensor container runs with host networking and keeps only the raw-socket and network-administration capabilities for this reason; the sensor self-test reports whether raw socket access is allowed
Local disk for the runRaw XML plus every probed HTTP page is written to the sensor's task scratch space, archived, then uploaded
CPU and time proportional to scopeThe sensor scans one subnet at a time, so wall-clock grows with the address count

In this deployment​

NeedWhy
A registered, healthy sensor placed inside the networkSee Sensors
One sensor per routing islandA sensor only scans what it can reach; segments behind a firewall need their own

Configuration​

Two layers, as with every integration. The instance holds almost nothing — the scan template holds everything that decides what a run does.

Instance​

FieldRequiredNotes
NameYesLabel for this instance
SensorYesThe sensor that will do the scanning — and therefore what the scan can reach

Scan template — basic​

FieldRequiredDefaultWhat it does
Template name, Template DescriptionYes—Labels the template
Subnets to scanYes—IPv4 addresses, IPv4 CIDR ranges or host names, separated by commas, semicolons or spaces, e.g. 192.168.10.0/24,10.10.0.0/16. Scanned one at a time, in order. Checked when the template is saved, see Which targets are accepted
Allow public rangesNoOffAllows entries outside the private address ranges. Leave off unless you mean to scan public addresses you own
Ports to discoverYes21, 22, 23, 25, 53, 67, 68, 80, 135, 139, 161, 443, 445, 3389, 8443, 8834Ports used for discovery — see the warning below
Use ICMPYesOnUse ICMP for host discovery — see the warning below
Detect OSYesOnAttempt OS identification — see the warning below
Probe HTTP PortsYesOnFetch web pages from open HTTP(S) ports and identify the device from the response
Ports for HTTP ProbeYes80,443Which open ports the HTTP probe visits. 443 is treated as TLS; everything else as plain HTTP
Minimum scan rateYes0Lower bound on packet rate — see the warning below
Maximum scan rateYes1000Upper bound on packet rate — see the warning below
Exclude default gatewaysYesOffDrops any finding whose address ends in .1
Probe SSH ports and pull host informationYesOffLog in over SSH and run a fixed set of read-only commands — see SSH probe
Ports for SSH ProbeNo22Which open ports the SSH probe tries
Credentials for SSH PRobeNo—The credentials to try, stored as a secret: once saved, the console shows a locked box with Replace and Remove, never the value, and sends it only to the sensor

Scan template — advanced and actions​

GroupSettingWhat it does
AdvancedInternal domainsComma-separated list of your own domains. Used to discard useless certificate names — see How a name is chosen
AdvancedIgnore of host is offlinePresent on the form; carries no meaning for this type, since every record in a scan result is by definition current
AdvancedScan TimeoutUpper bound on a single run
ActionsOn new asset discovered / Existing asset updated / Asset missing / On scan complete / On scan failedThe shared action model — see Integrations overview
Several scan settings are not yet passed to the scanner

Ports to discover, Use ICMP, Detect OS, Minimum scan rate and Maximum scan rate are stored on the template but the sensor's current nmap invocation does not apply them. Every run uses the same fixed command described below, which means the port list you enter does not narrow the scan and the rate limits do not slow it down. Scope a run with Subnets, and control its impact with the schedule window, until these are wired through.

TODO

Wire discoveryPorts, useICMP, detectOS, minRate and maxRate through to the sensor's nmap arguments, then replace the warning above with the real mapping from each field to its flag.

Which targets are accepted​

Every entry in Subnets to scan must be a scan target and nothing else. The console checks the list when the template is saved, and the sensor checks it again before it scans. One bad entry refuses the whole list, with a message naming the entry; nothing is scanned from a partly valid list.

EntryAccepted
An IPv4 address or CIDR range inside 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 or 100.64.0.0/10Yes
An IPv4 address or range outside thoseOnly with Allow public ranges on
A host nameYes. The sensor resolves it on your network and applies the same rules to every address it resolves to; a name that does not resolve fails the run
Anything touching 0.0.0.0/8, loopback 127.0.0.0/8, link-local 169.254.0.0/16 (which includes cloud metadata services), multicast 224.0.0.0/4 or reserved 240.0.0.0/4Never
localhost, or a name ending in .localhostNever
An IPv6 addressNo: only IPv4 is scanned
An entry starting with -No: it would be read as a scanner option

What the scan actually sends​

Per subnet, the sensor runs one nmap process:

nmap --stats-every 10 -Pn -A -- <subnet> -oX <result>.xml

What that means in practice:

FlagEffect
-PnSkip host discovery — treat every address in the range as online and scan it regardless of whether it answers a ping
-AEnable OS detection, service and version detection, the default NSE script set, and traceroute
-oXWrite structured XML, which is what the console parses
--stats-every 10Emit progress every ten seconds
--Everything after it is a target, never an option

With no explicit -p, nmap scans its own default selection of the most common 1000 TCP ports per address.

-Pn makes scope expensive, and noisy in the inventory

Because host discovery is skipped, a /16 is a thousand-port scan against 65,536 addresses rather than against the handful that answer — and every address is reported as "up", so records can arrive for addresses where nothing exists. Scan the ranges you actually use, sized in /24s, rather than the whole supernet. Watch the first run of a new subnet with On new asset discovered set to To approve before letting it create anything.

TODO

Confirm how records for non-responding addresses behave end to end on a live deployment, and document the recommended filter for suppressing them.

HTTP probe​

Where a discovered host has one of the Ports for HTTP Probe open, the sensor fetches / and, if the response looks like a device it recognises, follows up with that device's specific pages — a printer's network configuration page, an appliance's about page. The pages are uploaded with the scan result, and the console matches them against a library of device fingerprints.

A match can supply the hostname, MAC, OS, device type, hardware vendor and model — identity a port scan alone cannot produce. The recognised families are:

CategoryRecognised
Printers and MFPsHP LaserJet, Ricoh, Zebra, HID
NetworkCisco routers, Cisco switches, Cisco IP phones, Juniper NetScreen (ScreenOS), FortiGate, Alcatel-Lucent OmniSwitch, Ruijie Easy Smart, Ubiquiti, Proxim wireless
Serial and device serversLantronix XPort, Moxa NPort
Power and environmentSchneider Electric APC, Knürr PDU, Knürr RMS Compact, Emerson NXS UPS, NTI Enviromux
CamerasHikvision, Hanwha Vision
Storage and otherExaGrid, CMI Genus
The first match wins

Fingerprints are evaluated in a fixed order and evaluation stops at the first module that claims the response. A device that two modules would match is identified by whichever comes first, so a wrong hw_vendor on an otherwise correct asset is usually an over-eager fingerprint rather than a bad scan.

Certificate validation is off for probes

Probe requests are made without verifying TLS certificates, because the devices this is aimed at almost universally present a self-signed one. The probe reads pages only; it never submits credentials to a web interface.

SSH probe​

Optional, off by default, and the only part of the scanner that authenticates. When enabled, the sensor connects to each open SSH port and tries the configured credentials in order until one works, then runs a fixed set of read-only commands:

hostnamectl · ip addr show · ip link · ip route · uptime · lscpu · free · df -h · lsblk

The console parses two of them today — hostnamectl for hostname, operating system, hardware vendor and model, and ip addr show for addresses and MAC addresses. The rest are collected and stored with the raw result.

Credentials are tried against every host that answers

The credential list is attempted host by host across the whole scanned range. Against a domain-joined estate with lockout policies, a scan can lock the account out; against monitored hosts it produces a wave of failed-logon events that looks exactly like credential spraying. Use a dedicated, unprivileged, non-lockout account, tell your SOC before the first run, and keep the SSH probe scoped to subnets where you know it is welcome.

Host keys are accepted automatically

The probe accepts unknown SSH host keys rather than refusing to connect, so a host that has been re-keyed or spoofed is still logged into. The fingerprint is recorded in active_scanner_ssh_fingerprint, which is what you compare against when that matters.

How a name is chosen​

Hostname is the field correlation leans on hardest, so it is worth knowing where it comes from. The scan itself proposes a name from the first of:

  1. The name nmap resolved for the address
  2. A traceroute hop's name, ignoring _gateway
  3. An NSE script result — rdp-ntlm-info, ms-sql-ntlm-info, smb-os-discovery, nbstat, or ssl-cert on ports 443 and 3389

That name is trimmed to its first label, so dc-01.corp.example.com becomes dc-01, unless the value is an IPv4 address, which is kept whole.

The probes then take precedence over the scan, strongest last:

  1. A hostname asserted by an HTTP device fingerprint replaces it
  2. hostnamectl output from the SSH probe replaces both

A name from a probe is used as reported. When it is fully qualified, its short form goes to names and the full name and its domain to fqdn and domains.

Internal domains feeds step 3: certificate names that match one of your own domains, or a wildcard for one, are discarded rather than used as a hostname. Without it, every host behind a wildcard certificate ends up sharing one name — and correlation then happily merges them.

Set internal domains before the first run

It costs one field and it prevents the single most common way an active scan corrupts an inventory. List every domain your internal certificates use.

How the OS is chosen​

From the scan, protocol evidence is preferred over fingerprinting, and the first of these that answers is used:

  1. fingerprint-strings on port 32775 — IBM FileNet Content Platform Engine
  2. smb-os-discovery
  3. rdp-ntlm-info and smtp-ntlm-info — an NTLM product version, mapped to a release name
  4. vmware-version
  5. nmap's own osmatch / osclass guess

The probes then take precedence over the scan, strongest last:

  1. An HTTP device fingerprint replaces it
  2. hostnamectl from the SSH probe replaces both

The NTLM mapping is exact where the build is known:

Reported buildBecomes
10.0.10240Windows 10
10.0.14393Windows Server 2016
10.0.17763Windows Server 2019
10.0.20348Windows Server 2022
10.0.22621Windows 11
10.0.26100Windows 11 if port 5357 or 2701 is open, otherwise Windows Server 2025
5.1 / 5.2 / 6.0 / 6.1 / 6.2 / 6.3Windows XP / Server 2003 / Server 2008 / Server 2008 R2 / Server 2012 / Server 2012 R2
Any other 10.0 buildWindows Server 2016
Client-or-server is inferred from open ports

Windows client and server builds share a version number in recent releases, so the run decides between them by looking for ports 5357 (WSD) and 2701, which are typical of a workstation. A server with those ports open is labelled as a workstation, and vice versa. Where the distinction matters for reporting, check type against an EDR-sourced value.

Exported fields​

Each <host> element in the nmap output becomes one asset record. Two rules drop records before anything is written:

  • Exclude default gateways, if enabled, discards any finding whose address ends in .1
  • A record whose fingerprint — instance, hostname, address and SSH host key — already appeared in this run is skipped as a duplicate rather than written twice

Identity​

FieldTypeHolds
active_scanner_exitsBooleanAlways true — the presence flag marking this asset as scanner-covered
active_scanner_statusTextnmap's host state. With -Pn in force this reads up for every address scanned
active_scanner_hostnamesTextThe name chosen by the ladder in How a name is chosen

Network​

FieldTypeHolds
active_scanner_addressIPThe host's IPv4 address, as reported by nmap
active_scanner_address_typeTextAddress family — ipv4
active_scanner_portsTextThe open ports found on this host
active_scanner_ssh_fingerprintTextSSH host keys as type=fingerprint lines, one per key. Stable across address changes, and the value to compare when a host key matters

Platform​

FieldTypeHolds
active_scanner_os_full_nameTextOS as chosen in How the OS is chosen, normalised to a canonical name
active_scanner_os_vendorTextNormalised vendor — Windows, Linux, MacOS, OpenBSD, VMware
active_scanner_os_familyTextOS family as the evidence reported it, before normalisation

Timing and raw result​

FieldTypeHolds
active_scanner_last_onlineDate/timeWhen the finding was processed — see the note below
_meta_active_scanner_scan_resultText blockThe complete nmap record for this host, kept verbatim so any value on the asset can be traced back to the evidence for it
active_scanner_last_online is the processing time, not the probe time

The field is stamped when the console identifies the record, not when the packet came back. For a long scan those differ by the length of the run, and for a requeued task by longer. Use it to answer "was this host seen by the most recent scan", not to time an event.

Shared fields it writes​

Shared fieldDerived fromMode
namesThe chosen hostname, short formDo-not-override
fqdn / domainsThe chosen hostname, when a probe reported it fully qualifiedDo-not-override
private_ipThe host address, plus any addresses the SSH probe reportedMerge
macnmap's MAC (else nbstat's, replaced by an HTTP fingerprint's), plus every MAC the SSH probe reported. Placeholder MACs that many machines share are never writtenMerge
osThe chosen OS, normalisedDo-not-override
os_vendorThe chosen OS, normalised to a vendorDo-not-override
os_versionThe OS family stringDo-not-override
typeAn HTTP fingerprint's device type, else the device class nmap's OS detection reported (switch, firewall, printer and similar), else inferred from osDo-not-override
hw_vendorAn HTTP fingerprint, or hostnamectlDo-not-override
hw_productAn HTTP fingerprint, or hostnamectlDo-not-override
opened_portsThe open port listOverwrite
first_seen / last_seenactive_scanner_last_online. first_seen is set when the asset is created; last_seen only moves forward, so a newer sighting by another source is kept—
updated_atTime of the run that produced the recordOverwrite
Nearly everything here is do-not-override — deliberately

A network scan is an outside view. It infers where an agent knows, so it fills fields that are empty and steps aside where a stronger source has already spoken. The two exceptions are private_ip and mac, which merge: a host with two NICs accumulates both addresses rather than flapping between them, and the MACs other sources reported for the host are kept beside the scanner's.

os_version receives an OS family, not a version

The field is populated from the family string — Windows, Linux — rather than from a release number. When the SSH probe supplied the OS, it holds the same text as os. Read os for the release, and treat os_version from this source as a coarse label.

How results match existing assets​

Identification tries a ladder of rules and stops at the first that matches. The rule that fired is recorded on the change entry, so the console can always tell you why a record landed on a given asset:

OrderMatches when the candidate agrees on
1active_scanner_hostnames and active_scanner_address
2names and active_scanner_address
3names and private_ip
4active_scanner_hostnames and private_ip
5active_scanner_hostnames
6active_scanner_ssh_fingerprint
7names
8mac, against the MAC the scan or an HTTP fingerprint reported (not those from the SSH probe)
9active_scanner_address, with no conflicting name
10private_ip, with no conflicting name
TODO

Rule 6 compares active_scanner_ssh_fingerprint, but the field is not among those the matching step loads for existing assets, so the rule appears never to fire today. Confirm, and either fix the matching or drop rule 6 from this table.

Where more than one existing asset matches, the change entry is marked as needing manual input instead of being applied — it lands in the approval queue rather than merging two assets on a guess.

Address-only rules and DHCP do not mix

Rules 9 and 10 match on address alone, guarded only by the absence of a conflicting name. In a DHCP range, yesterday's laptop and today's laptop share an address, so an unnamed record can attach to the wrong asset. The name guard is what prevents most of it — which is another reason to get Internal domains right, and to prefer scanning static ranges where you can.

Operating it​

  • Start narrow. One /24 you know well, On new asset discovered set to To approve, and read what it proposes before widening.
  • Schedule against the window, not the calendar. Because the port list and rate limits are not yet applied, run duration is driven by address count; a scope that grows will eventually outgrow its window.
  • Tell the people who watch the network. The first run of an active scan is indistinguishable from reconnaissance, because it is reconnaissance.
  • Keep one instance per network island, each bound to the sensor that can reach it, rather than one instance listing every subnet in the company.

See also​

  • Passive scanner — discovery without sending anything
  • Sensors — the component that runs the scan, and where to place it
  • Integrations overview — the shared configuration model
  • Scanning — templates, schedules and run history
  • Assets — inspecting which source asserted an attribute