Appearance
Enforcement Mode
Enforcement mode allows the sensor to block or kill processes at the kernel level rather than only observing and recording them. Enforcement is deliberately staged through an approval path because the difference between a correctly-scoped rule and a disruptive one is often only visible after observation and limited rollout.
Enforcement is never active by default. Every node starts in observe mode and requires explicit operator advancement.
Prerequisites
operatorrole on the Console- Target sensor currently in
observemode with a policy pack assigned - Sensor trust state:
healthy(enforcement transitions block oncriticalorrevokedtrust state) - Sensor must have recorded events over an adequate observation window before you advance to
enforce_ready
Understand the two enforcement surfaces
The Telovix Console provides two independent enforcement surfaces:
| Surface | What it does |
|---|---|
| Pack enforcement state | Advances the entire assigned policy pack from observe to enforce_ready to enforced. Controls whether the pack's enforcement-capable rules are active. |
| Enforcement rules | Individual named rules based on built-in templates or custom YAML, targeted at a specific sensor, sensor group, or the whole fleet. These are separate from policy packs. |
Both are delivered to the sensor via the heartbeat response and applied within one heartbeat cycle (15 seconds).
Advance pack enforcement state
Policy packs with enforcement_capable: true support a three-state ladder. The state can only advance forward one step at a time and requires runtime_mode: live. Reverting to observe is always allowed.
observe - enforce_ready - enforced| State | Behavior |
|---|---|
observe | Events are recorded and alerts are generated. No blocking. Default for all assignments. |
enforce_ready | Pack loaded in enforcement mode; sensor ready to enforce but blocking not yet active. Used as a final review gate. |
enforced | Active blocking is enabled per the pack's enforcement rules. |
Advancing the enforcement state
In the Console, go to Sensors > [sensor] > Enforcement and use the state controls to advance from observe to enforce_ready and then to enforced.
Checking enforcement readiness before advancing
In the Console, go to Sensors > [sensor] > Enforcement and review the readiness panel before advancing. This panel shows the readiness class, any blocking conditions, and any caution conditions. Do not advance to enforce_ready or enforced until the readiness class is CandidateForEnforceReady. See Policy Packs for the full readiness criteria.
Enforcement rules (built-in templates)
Enforcement rules are individually managed, named rules based on built-in templates. They apply independently of the pack enforcement state. The following built-in templates are available:
| Template ID | What it does | Action type |
|---|---|---|
block-kmod-load | Blocks kernel module loading via sys_init_module | BPF LSM Override |
block-user-namespace | Blocks user namespace creation via sys_clone CLONE_NEWUSER | BPF LSM Override |
block-raw-sockets | Blocks raw socket creation | BPF LSM Override |
block-capset-sysadmin | Blocks SYS_ADMIN capability assignment | BPF LSM Override |
kill-ptrace-attach | Kills processes that attach via ptrace | Signal (SIGKILL) |
block-execve-tmp | Blocks execution from /tmp, /dev, /run/user, and /proc/self/fd paths | BPF LSM bprm_check_security Override |
block-memfd-create | Blocks anonymous memory file descriptor creation (memfd_create) | BPF LSM Override |
block-pivot-root | Blocks pivot_root system calls | BPF LSM Override |
block-mount-syscall | Blocks mount system calls | BPF LSM Override |
block-unshare | Blocks unshare system calls | BPF LSM Override |
block-bpf-load | Blocks BPF program loading via sys_bpf | BPF LSM Override |
block-socket-raw | Blocks raw socket creation (alternate coverage path) | BPF LSM Override |
block-chmod-suid | Blocks setuid bit setting via chmod | BPF LSM Override |
custom | Operator-supplied TracingPolicy YAML | Defined by the YAML |
::: note BPF LSM Override rules require CONFIG_BPF_LSM=y and lsm=...,bpf in the kernel configuration or boot parameters. Without BPF LSM, Override actions will not take effect. Verify BPF LSM is active before enabling any Override-based rule: cat /sys/kernel/security/lsm | grep bpf :::
Preview enforcement impact
Before creating an enforcement rule, use the impact preview in the Console to see how many events over the last 7 days would have been affected. In the Console, go to Policies > Enforcement > New Rule, select the template, and the impact preview panel shows total_events, has_data, and top_binaries (the binaries that would have been blocked most frequently). An empty result means no matching activity in the last 7 days, not that the rule is safe: it may simply not have been triggered yet.
Creating an enforcement rule
In the Console, go to Policies > Enforcement and click New Rule. Select a template, provide a name and optional description, and set the scope.
Scope: one of:
| Setting | Scope |
|---|---|
| Specific sensor | Single sensor |
| Sensor group | All sensors in the group |
| No scope selected | Fleet-wide (all sensors) |
Adding exceptions to a rule
Exceptions allow specific processes or process parents to bypass an enforcement rule. In the Console, go to Policies > Enforcement > [rule] > Exceptions and add entries with a process executable path pattern and/or parent executable path pattern and a reason for the audit trail.
Enabling and disabling a rule
In the Console, go to Policies > Enforcement, select the rule, and use the Enable or Disable toggle. The change takes effect on the next heartbeat cycle.
Deleting a rule
In the Console, go to Policies > Enforcement, select the rule, and click Delete.
Custom enforcement rules
Select the custom template when creating an enforcement rule and provide a TracingPolicy YAML body in the editor. The YAML must contain TracingPolicy as a field and follow the eBPF engine TracingPolicy schema. Custom rules have the same signature and delivery path as template-based rules.
How enforcement rules are applied to sensors
- The Console includes active enforcement rules for the sensor in the heartbeat response as
enforcement_policies[]. Each entry contains the policyname,content(TracingPolicy YAML),enabledflag, and an Ed25519signature. - The sensor verifies each signature against its
policy-signing.pubkey. The signature covers the messagetelovix-policy-v1:{policy_name}\n{yaml_content}. Policies with invalid signatures are rejected. - Valid policies are written to
compiled-policies/and applied to the embedded eBPF engine via gRPC. - Disabled rules are removed from the engine on the next heartbeat cycle.
Policy packs follow the same signature and application path. Pack YAML files are applied in all enforcement states. The enforcement state controls whether the blocking actions within the YAML take effect, not whether the YAML is loaded.
TracingPolicy action types
The embedded eBPF engine supports three action types in TracingPolicy YAML:
| Action | YAML | Effect |
|---|---|---|
| Observe | action: Post | Emit an event and continue. No blocking or killing. |
| Kill | action: Signal with argSig: 9 | Send SIGKILL to the process that triggered the match. The process starts but is killed before it can complete. |
| Block | action: Override with argError: -1 | Return an error from the kernel call, preventing the operation before the process begins (available on BPF LSM hooks only). |
Override (block) is only available on hooks that use BPF LSM, such as bprm_check_security (execution), kernel_read_file (module load), userns_create (namespace creation). Hooks on raw kprobes can only use Post or Signal.
Prefer Override for pre-execution denial. Use Signal when the hook fires after the operation has started and denial is no longer possible.
Recommended rollout sequence
- Observe first: verify the rule matches exactly what you intend by watching events in the Console for at least several heartbeat cycles before enabling any blocking action.
- Impact preview: review the impact preview panel when creating the rule to quantify the blast radius before saving.
- Single sensor canary: create the rule scoped to one non-critical sensor and monitor for unexpected blocks or false positives.
- Expand by group: if the canary is clean, expand scope to the target sensor group.
- Fleet rollout: only after the group is stable.
WARNING
Never combine a new match condition with an enforcement action in the same maintenance window on a critical network function. Observe the pattern first in the existing policy, then add the enforcement action as a separate change.
List enforcement rules
In the Console, go to Policies > Enforcement to see all enforcement rules. Each rule record shows rule_id, template, name, description, enabled state, scope (sensor or group if scoped), exceptions, and recent event counts from the last 7 days.
Troubleshooting
Enforcement rule created but sensor shows no blocks
BPF LSM is not active on this kernel. Run cat /sys/kernel/security/lsm | grep bpf on the sensor host. If bpf is absent from the output, enable BPF LSM by setting CONFIG_BPF_LSM=y in the kernel configuration and adding lsm=...,bpf to the boot parameters, then reboot.
Rule not appearing in sensor enforcement_policies in heartbeat
The rule is disabled or the sensor is not within the rule's scope. Verify the rule is enabled in the Console and that the sensor or group scope on the rule includes this sensor.
Policy signature rejected at sensor
The policy-signing.pub key on the sensor is missing or does not match the key used to sign the policy on the Console. Re-enroll the sensor to receive a fresh signing key from the Console.
enforce_ready transition rejected
The sensor is not in live runtime mode. Check the engine runtime state on the sensor's detail page in Sensors. Only the live adapter mode supports enforcement transitions.
Custom YAML rejected
The YAML is missing the required TracingPolicy type declaration. Validate the YAML syntax and ensure kind: TracingPolicy is present in the document.
Legitimate process blocked
The rule scope is too broad or the process needs an explicit exception. Add an exception for the process executable path or its parent executable path via Policies > Enforcement > [rule] > Exceptions.