probe

Reference for linuxguard-agent probe — host capability check covering kernel, BPF, fanotify, netlink, audit, and Linux capabilities.

Synopsis

Check whether the host kernel and runtime environment support the building blocks the LinuxGuard agent depends on: kernel version, BTF availability, BPF ringbuf support, bpffs writability, fanotify, netlink sock_diag, auditd reachability, and the relevant Linux capabilities (CAP_BPF, CAP_PERFMON, CAP_DAC_READ_SEARCH, CAP_SYS_ADMIN, CAP_SYS_PTRACE, CAP_NET_ADMIN). Designed for pre-flight checks before enrolling an agent and for CI-host validation in container images.

The probe is bounded by a 3-second outer context timeout and a per-check 200ms budget. Per-check failures are recorded as false on the result and logged via slog.Warn.

linuxguard-agent probe [flags]

Important: probe always exits 0 — including when capability checks fail. The command is non-fatal by design: the exit code reports CLI success, not host suitability. Always inspect the JSON output to determine the actual outcome. CI and Ansible callers should parse the JSON and fail their own pipeline based on the boolean fields, not on the agent's exit code.

Flags

Flag	Type	Default	Description
--json	bool	true	Emit machine-readable JSON to stdout. Accepted for forward compatibility — JSON is the only supported output format today.
--pretty	bool	false	Indent the JSON output for human reading. When true, output is produced via json.MarshalIndent with two-space indentation.

Environment

probe reads no environment variables. It does not respect any of the LINUXGUARD_* variables that influence the start command. The probe is intentionally self-contained so it can run inside a freshly-pulled image with no prior configuration.

Signals

probe is a one-shot CLI invocation — it does not install signal handlers via signal.Notify. The 3-second outer context timeout is the only interrupt path. Ctrl-C aborts the process via Go's default SIGINT handler (no graceful unwind, no JSON output).

Exit codes

Code	Meaning
0	Always. probe is non-fatal by design. The exit code does NOT reflect probe outcome — inspect the JSON output's boolean fields to determine actual capability availability.

The non-fatal behavior is intentional — even when json.Marshal fails (which should not happen for a struct of basic types), the agent logs the error via slog.Warn, emits {} to stdout, and returns nil. This guarantees that callers parsing the output do not block on a missing newline or a non-zero status.

Output schema

probe emits a single JSON object matching the capability.Capabilities struct:

Field	Type	Meaning
kernel_version	string	Full uname-style kernel version (e.g. 5.15.0-amd64).
kernel_major	int	Parsed major component of the kernel version.
kernel_minor	int	Parsed minor component of the kernel version.
architecture	string	runtime.GOARCH value: amd64, arm64, arm (armv7), riscv64, etc.
btf_available	bool	Whether the kernel's BTF type information is available for CO-RE.
ringbuf_supported	bool	Whether the BPF ringbuf map type is supported by the kernel.
bpffs_writable	bool	Whether the bpf filesystem can be written by the agent.
fanotify_available	bool	Whether fanotify_init returns a usable fd.
netlink_sock_diag	bool	Whether the agent can open a NETLINK_SOCK_DIAG socket.
auditd_reachable	bool	Whether the audit netlink socket is reachable.
caps	object	Effective Linux capabilities — see below.
caps.bpf	bool	CAP_BPF (kernel 5.8+).
caps.perfmon	bool	CAP_PERFMON (kernel 5.8+).
caps.dac_read_search	bool	CAP_DAC_READ_SEARCH.
caps.sys_admin	bool	CAP_SYS_ADMIN.
caps.sys_ptrace	bool	CAP_SYS_PTRACE.
caps.net_admin	bool	CAP_NET_ADMIN.
probed_at	timestamp	RFC3339 timestamp when the probe ran.
probe_duration_ms	int	Total wall-clock duration of the probe in milliseconds.

All boolean fields default to false on per-check failure (the probe never returns an error; failures are recorded as flags on the result, per capability package documentation).

Examples

Pretty-print a probe to stdout

linuxguard-agent probe --pretty

Sample stdout on a typical Ubuntu 22.04 host with sufficient privileges:

{
  "kernel_version": "5.15.0-78-generic",
  "kernel_major": 5,
  "kernel_minor": 15,
  "architecture": "amd64",
  "btf_available": true,
  "ringbuf_supported": true,
  "bpffs_writable": true,
  "fanotify_available": true,
  "netlink_sock_diag": true,
  "auditd_reachable": true,
  "caps": {
    "bpf": true,
    "perfmon": true,
    "dac_read_search": true,
    "sys_admin": true,
    "sys_ptrace": true,
    "net_admin": true
  },
  "probed_at": "2026-05-31T12:00:00Z",
  "probe_duration_ms": 142
}

JSON probe for CI parsing

linuxguard-agent probe | jq '.btf_available, .caps.bpf, .caps.perfmon'

Fail a CI step when any required capability is missing

probe always exits 0, so the CI step must parse the JSON and decide:

output=$(linuxguard-agent probe)
required_keys='.btf_available, .ringbuf_supported, .bpffs_writable, .fanotify_available, .caps.bpf, .caps.perfmon'
missing=$(echo "$output" | jq -r "[$required_keys] | map(select(. == false)) | length")
if [ "$missing" != "0" ]; then
  echo "Pre-flight FAILED: $missing required capability check(s) returned false."
  echo "$output" | jq .
  exit 1
fi
echo "Pre-flight OK."

Probe inside a container image

docker run --rm \
  --cap-add=SYS_ADMIN --cap-add=BPF --cap-add=PERFMON \
  ghcr.io/linuxguardx/linuxguard-agent:vX.Y.Z \
  linuxguard-agent probe --pretty

A reduced-capability container will show caps.sys_admin = false etc. while the kernel-level booleans remain accurate.

Probe via Ansible pre-flight

- name: LinuxGuard host capability check
  ansible.builtin.command: linuxguard-agent probe
  register: linuxguard_probe
  changed_when: false

- name: Parse probe result
  ansible.builtin.set_fact:
    probe_data: "{{ linuxguard_probe.stdout | from_json }}"

- name: Fail when BTF is unavailable
  ansible.builtin.fail:
    msg: |
      Host {{ inventory_hostname }} reports btf_available=false.
      eBPF probes will not load. Install a kernel with BTF or switch to
      the agent's degraded mode.
  when: not probe_data.btf_available

The changed_when: false is important because probe is read-only — Ansible should not record a change.

---

Related: start | config | CLI Reference | Reference