Probe Deployment

Low-resource, temp processes to enable endpoint testing

A probe is an endpoint process that knows how to run security tests.

Probes require no special privileges and do not require installation. Probes are designed to be lightweight - measuring between 1-2 kilobytes - and can run anywhere you have code. As such, probes can be deployed on devices ranging from laptops to servers to cloud environments and OT infrastructure.

Because you should know what is running on your endpoints, all Prelude probes are open-source.


Probes require an environment variable, PRELUDE_TOKEN, to be set before they can start. This variable is the unique identifier for the endpoint it's running on and allows the Prelude Service to identify your ownership.

This token is not a secret: it is used for identification purposes only. If someone were to steal this token, they would be capable of running the security tests you schedule for it but nothing else.


Probes can be deployed one of two ways:

  • Ephemeral: export the PRELUDE_TOKEN environment variable and start the probe as a script.
  • Installed: run one of the provided installers to install the probe as a service.


Probes can be dynamically configured through the following environment variables. Set these anytime, even if a probe is actively running.

  • PRELUDE_DIR: This variable specifies the directory (.vst) where the VSTs will be downloaded, executed, and cleaned up. This is important because it ensures that the VSTs are stored in a safe location that cannot be tampered with or accessed by unauthorized users.

  • PRELUDE_SLEEP: This variable specifies how long the probe should sleep before attempting to download and execute the VST again. This is important because it ensures that the probe will not execute anything while not tasked. The default is 14400 seconds (4 hours).

  • PRELUDE_CA: This variable specifies the expected S3 location for downloading VSTs. This is important because it ensures the VSTs are downloaded from a trusted and secure source.

  • PRELUDE_TOKEN: This variable specifies the endpoint token and serves as the authentication mechanism for the probe. The token is a unique identifier used to authenticate the probe with the Prelude API.

Registering Probes

You will need to generate credentials to deploy probes.


Ephemeral probes are lightweight processes with the smallest footprint possible. They are designed to run without dependencies on any modern version of Windows, Linux or MacOS.


Use the CLI to generate a new endpoint token:

Serial is intended to be a serial number but can be any unique string associated with the target machine

prelude detect create-endpoint -h <HOST> -s <SERIAL>


Installed probes run as a service to survive machine reboots, restart if stopped and upgrade automatically. Probes write all stdout/stderr to a common log file, in accordance of the operating system they are running on. The log file will be named prelude.log.

Instructions in this doc are for headless installs. Download and double-click to install via GUI.

To reinstall, run the uninstall and install steps for your platform.


To install a probe, you first need to create a user in your account with SERVICE privileges:

prelude iam create-user registration --permission SERVICE

This will generate a low-privilege authentication token. Use this, along with an account ID, to install probes.