Fabric → Sensors

Sensors are remote intrusion-detection probes that passively watch network traffic on the interfaces you choose. They run in detect mode — they raise alerts using a ruleset but never block or drop traffic. Operating sensors requires the IDS Sensors add-on; anyone with the read permission can always see the sensors that exist. Without the add-on, Create, Edit, and Regenerate Token are locked with a padlock explaining what is missing.

Sensors are viewed and managed on the Fabric page’s Estate tab, alongside your Workers and Proxies. Filter the Estate to Sensors to focus on them. The detection ruleset that sensors apply is authored separately, on the Rulesets view of Govern → IDS Policy.

What you can do

• See every registered sensor and its live status.
• Register a new sensor and obtain its deployment token.
• Edit a sensor’s interfaces, home network, and detection variables.
• Regenerate a sensor’s authentication token.
• Delete a sensor.

Table columns

On the Estate tab, sensor rows show:

Column	Notes
Name	Sensor display name.
Type	Sensor.
Status	pending (awaiting connection admission), online (connected and alerting), offline (unreachable), or error.
Location	The location the sensor monitors.
Version	The sensor agent version the sensor reports. (The detection engine’s own version is shown separately in View details.)
Activity	Kernel packet-loss rate (drop %). A high rate means the sensor is overloaded and missing traffic.
Extra	The ruleset version the sensor currently applies, with a drift warning when the sensor is still behind the active ruleset.
Last Heartbeat	Timestamp of the most recent check-in, or Never until the sensor first connects.
Actions	View details / Edit / Regenerate Token / Delete.

Open View details to see a sensor’s traffic and engine stats, its applied-versus-active ruleset, and its recently stored alerts. A Live badge above the table indicates that status, drop rate, and heartbeats refresh as sensors check in.

Fields

These are the inputs on the create/edit form, in the order they appear.

Field	Meaning
Name	A descriptive label for the sensor. Required.
Description	Free-form notes about the sensor. Optional.
Location	The location this sensor monitors. Required.
Capture Interfaces	One or more interface names to listen on, such as eth0. Required.
Home Network	One or more CIDR blocks or IPs the sensor protects. Prefix an entry with ! to negate it. Required.
Checksum Checks	Auto, Yes, or No. Leave on Auto unless you capture from a SPAN/mirror port, where checksum offload can cause false drops.
Alert Rate Limit	Most alerts per minute the sensor sends (default 600). Alerts beyond it are dropped and counted; 0 sends none.
EVE Alert Export	Optional. Stream alerts to your own Redis: host, port, mode, key, and which event types to export.
Rule Variables	Optional. Override address groups (such as HTTP_SERVERS) and port groups (such as SSH_PORTS) used by the ruleset.
Enabled	Whether the sensor is active. Edit only.

Licensing

Sensors are gated by the IDS Sensors add-on, whose capacity sets the maximum number of sensors you may register. The Licensing page shows a Sensors usage card (for example, 2 / 5). Creating a sensor beyond your licensed capacity is rejected — existing sensors keep reporting, and you can always delete one to get back under the limit.

Common tasks

Register a new sensor

1. On the Fabric Estate tab, click Create and choose Sensor.
2. Fill the form:
   • Name — a descriptive label (for example, Sensor — DMZ edge).
   • Location — the location this sensor monitors.
   • Capture Interfaces — the interface(s) to listen on, such as eth0.
   • Home Network — the CIDR block(s) or IP(s) the sensor protects.
   • Checksum Checks — leave on Auto unless you use a SPAN/mirror port.
   • Optionally configure EVE Alert Export and Rule Variables.
3. Click Create.
4. A dialog shows the deployment token. Copy it — the full token is only shown once.

Deploy the sensor agent

The sensor agent is the mistershell/sensor container, run on a Linux host that can see the traffic you want to monitor. MisterShell does not install it for you.

1. Set the core’s public URL as MISTERSHELL_URL (your load balancer / GSLB hostname) — the sensor connects out to it.
2. Set the deployment token from the previous step as SENSOR_TOKEN.
3. Run the container with host networking and packet-capture capabilities (NET_RAW, NET_ADMIN, SYS_NICE) so it can see the interfaces. The capture interfaces and home network you set on the form are delivered by the core on connect — you do not pass them as configuration, but the host must actually have those interfaces.
4. Start the container. It authenticates with MisterShell, pulls the active ruleset, and moves from pending to online.

Both MISTERSHELL_URL and SENSOR_TOKEN are required — the agent exits immediately if either is missing. See Deployment → Docker Compose examples for a complete run example.

Regenerate a sensor’s token

Use this when a token has been exposed or on a rotation schedule.

1. Click the Regenerate Token action on the row.
2. Confirm in the dialog.
3. A dialog shows the new token. Update SENSOR_TOKEN on the host — the old token stops working immediately.

Edit a sensor

1. Click the Edit action on the row.
2. Update interfaces, home network, checksum mode, export settings, rule variables, or enabled state.
3. Click Update.

Delete a sensor

1. Click the Delete action on the row.
2. Confirm.

The sensor’s entry is removed; if the agent is still running on its host, it can no longer authenticate. Stop and uninstall the agent process on the host to complete decommissioning.

Manage the detection ruleset

Choosing rule sources, authoring custom rules, overriding individual rules, and building & publishing the ruleset your sensors apply all live on the Rulesets view of Govern → IDS Policy. After a new ruleset is published, sensors pull and apply it on their next check-in; until a sensor catches up, a drift warning appears next to it on the Estate.

Permissions

• View sensor registration and runtime status: app.fabric.read.
• Register / edit / regenerate token: app.fabric.write.
• Delete a sensor registration: app.fabric.delete.
• View detection policy: app.sensors.read.
• View retained IDS alerts: app.sensors.execute.
• Change or delete IDS policy objects: app.sensors.write / app.sensors.delete.

Alert counters and ruleset health

The sensor detail view shows how many alerts the sensor emitted, how many it dropped because they exceeded its Alert Rate Limit, and how many it dropped because they could not be sent (no connection to MisterShell, or an alert too large to send). Dropped alerts are counted, never queued: detection continues at full speed while a limit applies. If the rate-limited count keeps growing, tune the ruleset or raise the sensor’s limit.

A sensor does not resend alerts. MisterShell retries storing an alert for a few minutes while its database is briefly unavailable, and stores each alert once even when it arrives twice.

An unknown applied ruleset means the detection engine has not confirmed activation. Downloaded rules alone are not reported as applied. A failed activation restores the previous complete rules where possible.

Keep each sensor’s data volume across restarts. Upgrade sensors together with MisterShell: both must run the same version.