Configuration
The Runtime Sensor receives configuration through ENDURA_* environment variables. The endura CLI reads its current process environment and does not automatically load an environment file from disk.
| Deployment | How variables reach the Runtime Sensor |
|---|---|
| Native systemd service | systemd reads /opt/endura/sensor/environ |
| Direct native command | Export variables in the invoking process or explicitly load /opt/endura/sensor/environ |
| Docker or Podman | The container runtime reads an environment file passed to the container |
| Kubernetes | The Helm chart injects sensor.env values and the endura-sensor-secrets Secret |
For direct commands, load the root-only file in the privileged process:
sudo sh -c 'set -a; . /opt/endura/sensor/environ; exec endura license verify'Only source an environment file that is owned by root and writable only by root.
Required
| Variable | Description |
|---|---|
ENDURA_LICENSE_KEY | Runtime Sensor license key. Required in standalone and Team Server modes. |
For Team Server mode, also set:
| Variable | Description |
|---|---|
ENDURA_TEAM_SERVER | Fully qualified Team Server URL |
ENDURA_SENSOR_TOKEN | Enrollment token created for this Runtime Sensor in Team Server |
Team Server and the Runtime Sensor must share a major version. See Team Server Compatibility.
Container Requirement
| Variable | Value | Description |
|---|---|---|
ENDURA_PROC_PATH | /host/proc | Host procfs path inside a Docker or Podman Runtime Sensor container |
Docker and Podman require host PID mode and host /proc mounted at /host/proc. Missing/invalid paths fail startup; a valid container procfs or missing host PID visibility can instead cause job start to report workspace does not exist, even for root.
The Helm chart configures host procfs and PID visibility automatically.
Optional Variables
| Variable | Default | Description |
|---|---|---|
ENDURA_BATCHER_AUTOFLUSH | false | Submit violations immediately. Ephemeral runners using graceful Sensor shutdown do not need this; delivery is best effort. |
ENDURA_EXIT_ZERO | false | Report errors but exit 0. Keep disabled for normal CI integration. |
ENDURA_HTTP_TIMEOUT | 5 | HTTP timeout in seconds for Team Server and provider range feeds; maximum 86400 (24 hours). |
ENDURA_JOB_ABSOLUTE_TIMEOUT | disabled | Purge jobs after a duration such as 30m, 2h, or 1d. 0, a blank value, or an unset variable disables the limit. |
ENDURA_JOB_CANCELLATION_TIMEOUT | 15m | Grace period after CI/CD cancellation before retiring the protected build. Supports s, m, h, and d suffixes. 0 disables automatic retirement without disabling cancellation; a blank or unset value uses the default. |
ENDURA_LOG_FILE | /var/log/endura/sensor.log | Log file path. The packaged systemd service permits writes under /var/log/endura. |
ENDURA_LOG_FORMAT | text | File format: text or newline-delimited json. Standard output and submitted logs remain text. |
ENDURA_LOG_LEVEL | info | trace, debug, info, warn, or error. |
ENDURA_SENSOR_KILL_TASK | true | Terminate offending tasks on enforce-mode violations, on LSM and fallback paths. false leaves direct LSM denial active; fallback hooks then only report violations. |
ENDURA_SENSOR_MAX_CLIENTS | 16 | Maximum queued and active control-socket clients admitted to eight fixed workers. 0 disables the cap. |
ENDURA_SENSOR_POLICY_NOCACHE | false | Re-evaluate repeated events instead of caching policy outcomes. Diagnostic use increases CPU usage. |
ENDURA_SENSOR_TIMEOUT | 10 | Seconds allowed to deliver a complete control-socket request; maximum 86400 (24 hours). 0 disables the deadline. |
ENDURA_TLS_PIN | — | PEM file containing the only CA roots trusted for Team Server. |
ENDURA_TLS_VERIFY | true | Verify Team Server certificates. Set false only for temporary testing. |
ENDURA_VERSION_CHECK | true | Enforce same-major Team Server compatibility. Set false only as a temporary last resort. |
Configuration Validation
Every command first validates all Endura variables in its environment, including settings unused by that subcommand. Correct invalid values before retrying. Durations accept nonnegative whole seconds or lowercase s, m, h, d suffixes, up to 9223372036854775807 seconds after conversion.
Startup also requires /sys/fs/bpf, /sys/kernel/security, and the configured procfs root as directories. Errors identify missing or invalid paths. In containers, check mounts and ENDURA_PROC_PATH.
Control-Socket Limits
Eight workers process local control requests. At the default ENDURA_SENSOR_MAX_CLIENTS=16, queued and active connections together are capped at 16, each non-root UID can hold four, and two slots are reserved for root. Excess connections receive client limit reached; refusal logs are aggregated.
Per-UID and root shares scale with the cap. Increasing it permits more waiting connections and consumes more descriptors/memory, without adding workers. ENDURA_SENSOR_TIMEOUT limits each worker’s wait for a complete request. Keep both limits enabled; a zero client cap permits an unbounded queue.
TLS Pinning
ENDURA_TLS_PIN replaces Team Server trust roots with the supplied PEM bundle. A missing or empty file fails closed. It has no effect with ENDURA_TLS_VERIFY=false and does not affect provider feeds.
Provider Range Feeds
Every startup downloads AWS (ip-ranges.amazonaws.com), Azure (www.microsoft.com, then download.microsoft.com), GCP (www.gstatic.com), GitHub (api.github.com), and Linode (geoip.linode.com) feeds, even without provider selectors. Allow outbound HTTPS when using those selectors.
Downloads always use bundled public Web PKI roots. ENDURA_TLS_PIN cannot add an inspection CA and ENDURA_TLS_VERIFY=false cannot bypass verification. ENDURA_HTTP_TIMEOUT applies per request.
Providers load concurrently, with up to three attempts each and one-second retry delays, before eBPF loading and readiness. A failed feed delays startup but does not prevent it; its selectors remain empty until a successful download on restart. Look for provider ranges unavailable after retries and the loaded/failed summary initialized runtime provider ranges.
Restore network access or public certificate trust and restart. Use explicit CIDRs when protection must not depend on feed availability.
Log File Location
The packaged systemd service permits log writes under /var/log/endura. To use another ENDURA_LOG_FILE location, create its parent directory and add that directory to ReadWritePaths= in a systemd service override. The Sensor rejects a final log path that is a symbolic link or a file with multiple hard links.