Sensor Auto-Update

AttackLens sensors include a built-in self-update mechanism that keeps them current without manual intervention. When a new sensor version is published, sensors automatically download and apply the update during their next idle period.

How Auto-Update Works

The auto-update process is transparent and designed to minimize disruption to data collection.

Version Check (Every Request)

Every time a sensor communicates with the AttackLens backend, it includes version information in its HTTP request headers:

Header	Purpose
X-Tool-Type	Identifies the tool as sensor (vs. scanner).
X-Tool-Version	The sensor's current version number (CalVer format, e.g., 2026.04.0).

The backend inspects these headers on every request and responds with update metadata in the response headers:

Header	Purpose
X-Update-Available	true if a newer version exists, false otherwise.
X-Update-Version	The version number of the available update.
X-Update-Mandatory	true if the update is mandatory and must be applied before the sensor can continue operating.

This means the sensor learns about available updates passively, as a side effect of its normal communication with the backend. There is no separate polling mechanism for update checks.

Update Download

When the sensor detects that an update is available (via the X-Update-Available: true response header), it:

1. Waits for idle: The sensor finishes any in-progress data collection cycle before starting the update. This ensures no data is lost mid-collection.
2. Downloads the new binary: The sensor requests the new binary from the backend's update endpoint, downloading the correct binary for its OS and architecture.
3. Verifies integrity: The downloaded binary is verified against a checksum provided by the backend to ensure it has not been corrupted or tampered with during transfer.

Update Application

After downloading and verifying the new binary:

1. The sensor stops its current operation gracefully.
2. The new binary replaces the existing binary on disk.
3. The sensor process restarts with the new version.
4. On the next check-in, the backend sees the updated X-Tool-Version header and confirms the update was successful.

The entire process typically takes less than a minute and happens automatically.

INFO

The sensor service (systemd, Windows Service, or launchd) ensures the sensor restarts after the binary is replaced. If the restart fails for any reason, the service manager will retry based on its configured restart policy.

Mandatory Updates

In rare cases, an update may be marked as mandatory. This happens when:

• A critical security vulnerability has been patched in the sensor.
• A protocol change requires all sensors to be on the new version.
• A bug fix is essential for data integrity.

When a mandatory update is flagged:

1. The sensor receives X-Update-Mandatory: true in the response headers.
2. The sensor prioritizes the update immediately, even if a collection cycle is in progress.
3. The sensor will not send further data until the update is applied.

WARNING

Mandatory updates are rare and only used for critical fixes. Under normal circumstances, updates are applied during the sensor's next idle window.

Version Scheme

Sensor versions follow CalVer (Calendar Versioning) in the format YYYY.MM.PATCH:

• YYYY -- Four-digit year.
• MM -- Two-digit month (zero-padded).
• PATCH -- Incremental patch number within the month.

Example: 2026.04.0 is the first release in April 2026, 2026.04.1 is a patch release in the same month.

Monitoring Update Status

From the Sensor List

The Sensors page shows each sensor's current version. You can quickly identify sensors that are not running the latest version.

From Sensor Detail

The sensor detail view includes an Update Status section showing:

• Current Version: The version installed on the endpoint.
• Latest Available: The newest version available from the backend.
• Status: One of: Up to date, Update available, or Update in progress.

From Component Updates

Navigate to Settings > Feed and Updates to see the latest available sensor version and how many sensors are running each version.

Update Delivery Chain

The sensor update delivery follows this path:

1. AttackLens license server publishes a new sensor binary.
2. The UpdateWorker on your AttackLens backend checks for component updates every 6 hours.
3. The backend downloads the new sensor binary from the license server and stores it locally.
4. Sensors detect the update via response headers during their next check-in.
5. Each sensor downloads the new binary from your backend (not from the license server directly).

TIP

Since sensors download updates from your on-premises backend -- not from the internet -- the auto-update mechanism works even in air-gapped or restricted network environments. As long as your backend has been updated with the new binary (which can happen via the license server sync or manual upload), sensors will receive it.

Troubleshooting

Sensor is not updating

• Check the backend: Navigate to Settings > Feed and Updates and verify the latest sensor version is available on your backend. If the backend has not synced with the license server, sensors will not see the update.
• Check sensor connectivity: The sensor must be able to reach the backend to receive update headers. An Offline sensor cannot update.
• Check sensor logs: Look for update-related errors in the sensor logs on the endpoint. Common issues include insufficient disk space or file permission errors when replacing the binary.

Sensor updated to wrong version

This should not happen because the backend serves the correct binary based on the sensor's reported OS and architecture. If it does occur, check the backend logs for binary serving errors and verify the correct binaries are present in the update storage.

Rollback

There is no built-in rollback mechanism. If a new sensor version has issues, the recommended approach is to publish a corrected version. In an emergency, you can manually replace the binary on the endpoint with a known-good version.