Skip to main content
Version: 0.10

Sensors

A sensor is the Velum Edge collector you run inside your own network. It is the platform's only foothold on your side of the boundary, and everything that touches your systems happens there: every integration run, every API call to a source system, every packet a scan sends.

The console holds the inventory and decides what work needs doing. The sensor does the work.

You can deploy as many sensors as your network needs — most organizations run several, one per site or segment.

A sensor is not an endpoint agent

There is no need to install anything on your endpoints. A sensor is a collector, not an agent: one of them covers thousands of assets, because the information comes from the integrations it runs — your EDR, your directory, your cloud subscriptions — and from what it can probe or observe on the network. You deploy sensors for reach, so that every source system and every segment has one that can get to it, never for coverage of individual machines.

What a sensor is responsible for​

ResponsibilityWhat it means in practice
Running integrationsEvery integration in the catalogue is assigned to a sensor, and the sensor is what calls the source system's API
Scanning the networkThe active scanner probes from the sensor. The passive scanner is designed to listen on the sensor's feed, but the current sensor build does not run it: see below
Uploading resultsRaw findings are archived and posted back to the console, which does the interpretation
Reporting its own healthVersion, how it is installed, hostname, addresses and a status message, reported when it starts and whenever its status changes
The current sensor build does not run passive capture

The sensor image ships without the capture engine the passive scanner relies on, and the sensor does not start passive capture. Until that returns, a passive scanner instance assigned to a sensor collects nothing; plan coverage on active scanning and integrations.

Nothing runs "in the cloud, separately"

It is worth stressing, because it is the single most common misunderstanding: integrations are not console-side jobs that reach into your network. They are tasks the sensor runs. If a sensor cannot reach a source system — no route, no proxy, an expired credential — that integration cannot run, and the console has no other path to the data.

How the sensor talks to the console​

The connection is outbound only, and initiated by the sensor. Nothing connects to a sensor, and no inbound firewall rule is ever needed for one.

PropertyValue
DirectionSensor → console
TransportHTTPS to the console's API
AuthenticationA long-lived sensor API token, sent as an x-api-key header
CadenceA polling loop; the default interval is 30 seconds (global.sleep_period)
ProxySupported, through the sensor's proxy setting (LE_PROXY). See Proxy

Each cycle, the sensor asks for its queued tasks, starts any it has been given, and reports progress. That same request is what refreshes the sensor's last seen time in the console, so a sensor with nothing to do still checks in, and a stale last-seen means the sensor is not running, cannot reach the console, or is being refused by it.

How a sensor picks up work​

The sensor periodically pulls updates from the console, checking whether there is anything new for it — a configuration change, or a task to execute.

When you create a new integration instance you always specify the sensor that will run it. So by the time a scanning task starts, which sensor is going to run it is already well defined: the task goes to that sensor, it does the work, and it uploads the result back to the console.

Tasks run in parallel threads on the sensor, so one slow integration does not block the others. A sensor runs at most global.max_concurrent_tasks scans at once (4 by default); further scans wait as Queued in the console until a slot frees. Connection tests have one extra slot of their own, so they never wait behind a long scan. See Concurrency. A sensor that restarts requeues whatever it had in flight rather than losing the schedule; those tasks start again from the beginning.

The stages a task passes through, and which of them run on the sensor rather than in the console, are set out in Scanning.

Enrolling a sensor​

Enrolment is a two-token exchange. A short-lived deployment token identifies the tenant a new sensor may join; the sensor trades it once for its own long-lived API token and never uses the deployment token again.

In the console​

Settings → Sensors → Add sensor walks through it:

  1. Select platform. Docker is the only platform you can pick. Linux, Windows and macOS are listed as not supported yet.
  2. Select deployment token. Reveal or copy the tenant's token. Requires sensor management permission on the tenant; see Roles and permissions.
  3. Create the docker-compose file. The dialog shows a compose file that already points at your console and, once you have revealed or copied the token, carries it. Copy it or download it, and save it on the host.
  4. Enroll and start sensor. Run docker compose up -d from the folder with the compose file. On its first start the sensor enrols with the token.

While the dialog is open it watches for the new sensor, says when it has enrolled, and offers to connect an integration through it. The full procedure, and every setting the compose file can carry, is in Install a sensor on Linux (Docker).

One active deployment token per tenant

Revealing or copying the token shows the tenant's active token, and mints a new one only when there is none. While it is valid, the same token can enrol as many hosts as you need. Revoke token in the dialog invalidates it immediately, and the next reveal mints a fresh one. Sensors that have already enrolled are unaffected, because they no longer depend on it.

A deployment token is short-lived

The dialog states that the token is valid for 60 minutes. If it lapses before you have enrolled the host, reveal a new one and start again. Expiry affects only enrolment, never a sensor that has already enrolled.

TODO

The console says 60 minutes, but the backend currently issues deployment tokens that expire after 24 hours (sensorEnrollmentTokenDuration). Align the two, then state one figure here.

A new sensor names itself

Registration creates the sensor as Sensor-<hostname> and it appears in maintenance status until it has settled. Rename it from the sensor detail view to something that says where it sits, such as dc-core-span or branch-rome, because that is the question you will be asking when you assign integrations to it. Registration is refused once the tenant has reached its sensor limit.

System requirements​

The sensor is a lightweight collector. Typically it needs no more than 2 vCPU and 2 GB of RAM, on an x86-64 Linux host with Docker Engine and the Compose plugin; see Deployment options. Beyond that it wants modest local disk, because results are staged and archived on the host before they are uploaded, and an NTP-synchronised clock, because tokens carry expiry times and every finding it produces is timestamped.

What it costs to run still depends on the work you give it:

Sensor roleDominated by
API integrations onlyAlmost nothing between polls; brief bursts while a sync runs and its result is compressed
Active scanningCPU and network during a run, and disk proportional to the number of addresses scanned and pages probed
Passive capture (not run by the current build)Sustained CPU and memory proportional to the throughput of the mirrored feed, whatever the size of the estate
TODO

Publish disk sizing per scanned address count, and the maximum feed throughput a single passive sensor sustains.

Network requirements​

Everything is outbound and sensor-initiated. No inbound rule to a sensor is ever required, and nothing in the platform connects to one.

FromToProtocolPort
SensorThe Velum Edge consoleHTTPS over TCPWhatever the console URL names — 443 normally
SensorDNS resolverDNS53
SensorYour outbound proxy, where one is usedAs the proxy requiresCarries the console traffic and integration calls
SensorSource systems it readsPer integration — LDAPS, Kibana, a Nessus manager and so onSee each integration's page

The console traffic is the only rule every sensor needs. The rest follow from the integrations you assign to it, which is another argument for deciding placement first — see Where to place sensors, and how many.

TLS-inspecting proxies need their CA trusted by the sensor

Where outbound traffic is intercepted, the sensor sees the proxy's certificate rather than the console's, and refuses it. The sensor checks certificates against the CA bundle in its own image, so installing the proxy's CA on the host is not enough. Do not fall back to turning verification off (secure: false): the sensor would then trust anything that answers in the console's place, including whoever is intercepting the connection that carries its API token.

TODO

Document the supported way to add a TLS-inspecting proxy's CA to the sensor.

Deployment options​

The sensor is meant to be installable the way your platform team already installs things. Not all of those paths exist yet, and each has a page for installing and a page for upgrading:

MethodStatusInstallUpgrade
Linux, DockerAvailable todayInstallUpgrade
Linux, system serviceNot availableInstallUpgrade
Windows serviceNot availableInstallUpgrade

Whichever path you take, enrolment is the same exchange described above: the deployment token goes in, an API token comes back, and the sensor starts polling. Only the packaging differs.

The Add sensor dialog lists platforms ahead of their availability

Its platform selector lists Linux, Windows and macOS alongside Docker, marked not supported yet, and only Docker can be picked. Deploy with Docker.

Where to place sensors, and how many​

A sensor's usefulness is decided almost entirely by where it sits — which is why the count follows from your network, not from the size of your estate. A single sensor with internet egress can inventory the whole company if every source is a SaaS API; a segmented network with several sites needs one per island. Two questions settle it:

What does it need to reach? An integration runs on one sensor, so that sensor needs a route to that source system — a domain controller, an internal Nessus manager, a Kibana instance. SaaS sources only need general internet egress, so one sensor with outbound access covers all of them.

What does it need to see? An active scan can only probe what its sensor can route to, and a passive scan can only observe what its feed carries. Both are per-segment concerns.

SituationSensors
One site, flat routing, SaaS integrations onlyOne
Several sites with firewalls between themOne per site
A segment you must scan but cannot route intoOne inside it
A mirrored feed you want to listen toOne attached to that feed, once the sensor runs passive capture again
A DMZ or OT zone with strict egressOne inside it, with a proxy if required
Prefer a second sensor to a firewall exception

Opening inter-segment ACLs so one sensor can scan everything makes that sensor a high-value target and a lasting hole in your segmentation. A second sensor with outbound HTTPS only is cheaper to justify and easier to defend.

Managing a sensor​

The sensor list shows every sensor in the tenant with its status, mode, version and last check-in. Opening one shows what it has reported about itself and what you can change:

ShownMeaning
Name, descriptionYours to set: the only editable fields
StatusHealth as the sensor last reported it, or Offline when it has stopped checking in
ModeWhether the sensor is enabled for work
VersionThe sensor build, useful when a fleet is mid-upgrade
InstallationHow the sensor is installed, as it reports it: Docker for the container. Sensors older than 0.9.1 do not report it and show Unknown
TypeThe sensor's role
HostnameAs the host reports it
Private IPThe first IPv4 address of each of the host's network interfaces, loopback excluded
Public IPThe address the console saw it from
Sensor created, last seenEnrolment time and the last check-in

The detail view also shows the last self-test, and its actions are:

ActionWhat it does
Run self-testAsks the sensor to run its health checklist. See Running a self-test
Update agentCompares the sensor's version with the platform's and, for a Docker sensor, shows the image to set and the command to run. See Upgrade a sensor on Linux (Docker)
Disable, EnableChanges the sensor's mode. See Status and mode are different things
Revoke tokenEnds the sensor's API token at once, wherever a copy of it is
DeleteRemoves the sensor from the tenant

Status and mode are different things​

ValuesSet by
StatusHealthy, Maintenance, FaultThe sensor, when it starts and whenever its health changes
OfflineThe console, when the sensor has not checked in for ten minutes
ModeEnabled, DisabledYou, in the console

The sensor reports Maintenance while it starts, Healthy once it has reached the console, and Fault when enrolment, its startup or a polling cycle fails, with the reason as its status message.

Status is a report. Mode is an instruction: the console refuses every request from a disabled sensor, so it takes no scans or connection tests, its results are not accepted, and its schedules skip it, while it stays enrolled. Scans already queued wait until you enable it again, and the agent is let back in with the same token. That is what you want during host maintenance, a network change, or while investigating whether a scan is causing trouble. Because a disabled sensor cannot check in, it shows as Offline after ten minutes.

Offline is inferred from the check-in, not announced

A sensor that dies cannot report that it has died. What you have is last seen, refreshed every polling cycle; the console marks a sensor Offline once it is ten minutes old. Sensor offline and sensor fault are also notification types, so the platform can tell you rather than waiting for you to look.

Disabling, revoking and deleting​

Disabling stops the work and keeps everything else: the enrolment, the token, the sensor's history, and every asset it has discovered.

Revoking the token cuts off the agent, and anyone holding a copy of its token, at once. The sensor, its integrations and its history stay. To use the host again, enrol it with a new deployment token: it joins as a new sensor, so move the old sensor's integrations to it. Use this when a token may have leaked.

Deleting removes the sensor from the tenant. Its scan tasks and the integration instances running through it are not reassigned, so move those first. The agent on the host keeps running until you remove it, and is refused by the console.

In every case the assets it discovered stay in the inventory; they simply stop being refreshed.

Running a self-test​

Run self-test queues a health checklist for the sensor, which picks it up on its next poll, runs it beside its tasks and reports back. The console shows each check as passed, warning, failed or skipped, with what it measured and what it expected. It needs a sensor that is enabled and runs agent 0.9.1 or later. A self-test that makes no progress for ten minutes, because the sensor was stopped or restarted, is shown as not finished; run it again.

GroupChecks
AgentAgent version, uptime, and whether the configuration loaded without warnings
HostCPU load, memory available, free disk space for results and for logs, and whether the results folder is writable
BackendName resolution of the console, an API round trip, TLS certificate verification, whether a proxy is set, and clock drift from the console
NetworkIPv4 interfaces to scan from, the network scanner, and raw socket access for OS detection and SYN scans
TasksHow many scan slots are in use

The thresholds behind the graded checks can be changed, and any check switched off, in the sensor's config file; see Self-test thresholds.

When a sensor stops reporting​

The failure is quiet, which is what makes it dangerous:

  1. The sensor stops checking in.
  2. Its integrations stop running, so their assets stop being refreshed.
  3. Last-seen timestamps age.
  4. Coverage degrades, and nothing in the inventory looks broken.
Stale is not absent

An asset last seen weeks ago has not necessarily been decommissioned — its sensor may be the thing that is down. Check sensor health before acting on a last-seen date, and think twice before setting Asset missing to Delete asset on any integration. See Integrations.

A checklist when a sensor goes quiet:

CheckWhere
Is it still checking in?Last seen, in the sensor list
What did it last say?The sensor's status message
Is it disabled?Mode, on the sensor detail view
Is the host running?The container, on the host
Can it reach the console?Outbound HTTPS, and the proxy setting if there is one
Is its token still valid?Revoking the token or deleting the sensor in the console cuts it off
What does the sensor say about itself?Run a self-test, and read the container's output on the host
Are its tasks stuck?Scan history, filtered to that sensor's integrations

See also​