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.
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
| Responsibility | What it means in practice |
|---|---|
| Running integrations | Every integration in the catalogue is assigned to a sensor, and the sensor is what calls the source system's API |
| Scanning the network | The 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 results | Raw findings are archived and posted back to the console, which does the interpretation |
| Reporting its own health | Version, how it is installed, hostname, addresses and a status message, reported when it starts and whenever its status changes |
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.
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.
| Property | Value |
|---|---|
| Direction | Sensor → console |
| Transport | HTTPS to the console's API |
| Authentication | A long-lived sensor API token, sent as an x-api-key header |
| Cadence | A polling loop; the default interval is 30 seconds (global.sleep_period) |
| Proxy | Supported, 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:
- Select platform. Docker is the only platform you can pick. Linux, Windows and macOS are listed as not supported yet.
- Select deployment token. Reveal or copy the tenant's token. Requires sensor management permission on the tenant; see Roles and permissions.
- 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.
- Enroll and start sensor. Run
docker compose up -dfrom 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).
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.
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.
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.
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 role | Dominated by |
|---|---|
| API integrations only | Almost nothing between polls; brief bursts while a sync runs and its result is compressed |
| Active scanning | CPU 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 |
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.
| From | To | Protocol | Port |
|---|---|---|---|
| Sensor | The Velum Edge console | HTTPS over TCP | Whatever the console URL names — 443 normally |
| Sensor | DNS resolver | DNS | 53 |
| Sensor | Your outbound proxy, where one is used | As the proxy requires | Carries the console traffic and integration calls |
| Sensor | Source systems it reads | Per integration — LDAPS, Kibana, a Nessus manager and so on | See 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.
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.
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:
| Method | Status | Install | Upgrade |
|---|---|---|---|
| Linux, Docker | Available today | Install | Upgrade |
| Linux, system service | Not available | Install | Upgrade |
| Windows service | Not available | Install | Upgrade |
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.
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.
| Situation | Sensors |
|---|---|
| One site, flat routing, SaaS integrations only | One |
| Several sites with firewalls between them | One per site |
| A segment you must scan but cannot route into | One inside it |
| A mirrored feed you want to listen to | One attached to that feed, once the sensor runs passive capture again |
| A DMZ or OT zone with strict egress | One inside it, with a proxy if required |
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:
| Shown | Meaning |
|---|---|
| Name, description | Yours to set: the only editable fields |
| Status | Health as the sensor last reported it, or Offline when it has stopped checking in |
| Mode | Whether the sensor is enabled for work |
| Version | The sensor build, useful when a fleet is mid-upgrade |
| Installation | How 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 |
| Type | The sensor's role |
| Hostname | As the host reports it |
| Private IP | The first IPv4 address of each of the host's network interfaces, loopback excluded |
| Public IP | The address the console saw it from |
| Sensor created, last seen | Enrolment time and the last check-in |
The detail view also shows the last self-test, and its actions are:
| Action | What it does |
|---|---|
| Run self-test | Asks the sensor to run its health checklist. See Running a self-test |
| Update agent | Compares 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, Enable | Changes the sensor's mode. See Status and mode are different things |
| Revoke token | Ends the sensor's API token at once, wherever a copy of it is |
| Delete | Removes the sensor from the tenant |
Status and mode are different things
| Values | Set by | |
|---|---|---|
| Status | Healthy, Maintenance, Fault | The sensor, when it starts and whenever its health changes |
| Offline | The console, when the sensor has not checked in for ten minutes | |
| Mode | Enabled, Disabled | You, 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.
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.
| Group | Checks |
|---|---|
| Agent | Agent version, uptime, and whether the configuration loaded without warnings |
| Host | CPU load, memory available, free disk space for results and for logs, and whether the results folder is writable |
| Backend | Name resolution of the console, an API round trip, TLS certificate verification, whether a proxy is set, and clock drift from the console |
| Network | IPv4 interfaces to scan from, the network scanner, and raw socket access for OS detection and SYN scans |
| Tasks | How 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:
- The sensor stops checking in.
- Its integrations stop running, so their assets stop being refreshed.
- Last-seen timestamps age.
- Coverage degrades, and nothing in the inventory looks broken.
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:
| Check | Where |
|---|---|
| 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
- Install a sensor on Linux (Docker) and Upgrade a sensor on Linux (Docker) — the supported deployment
- Linux (service) and Windows — packages that are not available yet
- Active scanner — probing from the sensor
- Passive scanner — listening from the sensor, not run by the current build
- Integrations — the catalogue and the shared configuration model
- Scanning — templates, schedules and run history
- Core concepts — where the sensor sits in the model