netprobe

How it works

All three actions are native in-process socket work — no shell-out, no subprocess (netprobe_plugin.cpp:1-65). icmp opens one ICMP session for the whole run, resolves each target to its first IPv4 address only (netprobe_plugin.cpp:340), and sends count echo requests spaced 200 ms apart (netprobe_plugin.cpp:79, :346-348); on Windows via IcmpSendEcho, on macOS/Linux via an unprivileged SOCK_DGRAM ICMP ping socket, which Linux additionally gates on net.ipv4.ping_group_range (netprobe_plugin.cpp:6-11, matrix.md). tcp resolves each target to any address family (AF_UNSPEC, netprobe_plugin.cpp:381) and times a non-blocking connect() per sample on the chosen port (default 443). dns times one getaddrinfo call per name and reports the resolved address count and status. Every action validates and caps the targets CSV first (max 4 — netprobe_plugin.cpp:75, netprobe_stats.hpp:118-136) and rejects each invalid entry individually rather than failing the whole call (netprobe_plugin.cpp:308-313).

The plugin deliberately does not schedule its own recurrence or keep history — that is the server scheduler’s job against the response store (content/definitions/netprobe.yaml:1-4); nor does it shell out to the OS ping binary the way the sibling device.network_actions.ping does (content/definitions/network_actions.yaml:74-82).

flowchart LR
  OP[Operator / workflow<br/>dispatches definition] --> SRV[Server<br/>authz: Infrastructure.Read]
  SRV -- gRPC mTLS --> HOST[Agent plugin host]
  HOST --> EX[netprobe.execute]
  EX --> WIN[Windows leg<br/>IcmpSendEcho icmp<br/>non-blocking connect tcp<br/>getaddrinfo dns]
  EX --> MAC[macOS leg<br/>SOCK_DGRAM ICMP ping socket icmp<br/>non-blocking connect tcp<br/>getaddrinfo dns]
  EX --> LIN[Linux leg<br/>SOCK_DGRAM ICMP ping socket icmp — constrained<br/>non-blocking connect tcp<br/>getaddrinfo dns]
  WIN & MAC & LIN --> ROWS[rtt / dns rows<br/>UNDECLARED result status] --> RS[(ResponseStore)] --> API[REST /api/responses]

OS capability

Declared limits per leg (descriptor fallback text, verbatim):

• icmp / Linux — requires net.ipv4.ping_group_range to admit the process group; reports not-permitted otherwise

Privileges and prerequisites

No netprobe-specific row exists in docs/agent-privilege-model.md (per privilege.md); the identities above are the agent’s general per-OS account model, cited at the lines shown.

No external binaries or subprocesses (the whole plugin is native socket calls — ::socket/::connect/::sendto/::recv at netprobe_plugin.cpp:126,157,228,256,271; IcmpSendEcho/IcmpCreateFile on Windows). Network access: outbound ICMP echo, outbound TCP connect, and DNS resolution to the operator-supplied targets only.

Data contract

Inputs

Outputs

Pipe-delimited rows. icmp and tcp share one row shape with a literal rtt discriminator (the proto field, not the row prefix, tells them apart); dns uses its own dns-prefixed row. An invalid target still emits one row (never dropped silently) with the sanitized target string, zeroed timing fields, and a status naming why (netprobe_plugin.cpp:294-306).

network.probe.dns — name|resolve_ms|status|addresses

network.probe.icmp — target|proto|sent|ok|min_ms|avg_ms|max_ms|jitter_ms|loss_pct|status

network.probe.tcp — target|proto|sent|ok|min_ms|avg_ms|max_ms|jitter_ms|loss_pct|status

Result status

This plugin does not set a typed result status; the agent records UNDECLARED and every sample shows UNDECLARED / UNKNOWN / for every action on every OS (see Sample output).

Where the data goes

• Instruction result only. Rows travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore, queryable at /api/responses/{id}.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX, or metrics (no reference to netprobe or network.probe.* anywhere under server/ outside the plugin catalogue and descriptor summary map, server/core/src/agent_registry.cpp:830-833). Recurrence/trending is the server scheduler’s job, not this plugin’s (content/definitions/netprobe.yaml:1-4).
• Sensitivity. Rows carry only the operator-supplied target (a hostname or IP literal the caller chose, not read from the probing host) plus timing/loss statistics; no field names the probing device, a person, or installed software.
• Siblings: device.network_actions.ping — a one-shot ICMP reachability check that shells out to the OS ping binary and streams its raw text output (content/definitions/network_actions.yaml:74-82), unlike netprobe’s native, structured, no-shell-out RTT/jitter/loss rows. Both ship in the same #2204 network/security plugin declaration group alongside netstat, discovery, wifi, wol, http_client, certificates, firewall, and quarantine (changelog.d/2204-declarations-group-c.added.md).
• MCP / REST. Discover: discover_plugins (summary) → yuzu://plugin-docs (this page as data) → discover_instructions / get_definition("network.probe.icmp"). Run: execute_instruction {definition_id, parameters}. Read: /api/responses/{id}.

Sample output

Windows — captured: windows Microsoft Windows NT 10.0.26200.0 x64 · bare-metal · 2026-09-07 · SYSTEM · leg-hash e635d1fd4823

== action=icmp targets=127.0.0.1
rtt|127.0.0.1|icmp|5|5|0.0|0.0|0.0|0.0|0.0|ok
[result_status] UNDECLARED / UNKNOWN

== action=tcp targets=127.0.0.1 port=22
rtt|127.0.0.1|tcp:22|5|5|0.3|0.3|0.4|0.0|0.0|ok
[result_status] UNDECLARED / UNKNOWN

== action=dns targets=localhost
dns|localhost|2.8|ok|2
[result_status] UNDECLARED / UNKNOWN

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-09-07 · euid 501 (jsmith) · leg-hash e635d1fd4823

== action=icmp targets=127.0.0.1
rtt|127.0.0.1|icmp|5|5|0.0|0.1|0.1|0.0|0.0|ok
[result_status] UNDECLARED / UNKNOWN

== action=tcp targets=127.0.0.1 port=22
rtt|127.0.0.1|tcp:22|5|5|0.0|0.1|0.1|0.0|0.0|ok
[result_status] UNDECLARED / UNKNOWN

== action=dns targets=localhost
dns|localhost|0.9|ok|2
[result_status] UNDECLARED / UNKNOWN

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-09-07 · euid 0 · leg-hash e635d1fd4823

== action=icmp targets=127.0.0.1
rtt|127.0.0.1|icmp|5|5|0.0|0.1|0.2|0.0|0.0|ok
[result_status] UNDECLARED / UNKNOWN

== action=tcp targets=127.0.0.1 port=22
rtt|127.0.0.1|tcp:22|5|0|0.0|0.0|0.0|0.0|100.0|ok
[result_status] UNDECLARED / UNKNOWN

== action=dns targets=localhost
dns|localhost|0.4|ok|2
[result_status] UNDECLARED / UNKNOWN

Caveats and known gaps

1. status: ok means the probe ran to completion, not that every sample connected — read it together with loss_pct. tcp (and icmp) write status: ok unconditionally once a session opened and the target resolved (netprobe_plugin.cpp:359, :394), regardless of how many samples actually succeeded. The Linux tcp capture against 127.0.0.1 port=22 (no sshd in the capture container) shows this directly: rtt|127.0.0.1|tcp:22|5|0|0.0|0.0|0.0|0.0|100.0|ok — all 5 connect attempts failed fast (ok: 0, loss_pct: 100.0), yet status still reads ok. Windows and macOS, which do have something listening on 22, show ok: 5/loss_pct: 0.0 for the same capture (rtt|127.0.0.1|tcp:22|5|5|0.3|0.3|0.4|0.0|0.0|ok and …|0.0|0.1|0.1|0.0|0.0|ok). The targets grammar itself is comma-separated hostnames/IPv4 literals only — no embedded port (valid_probe_target, netprobe_stats.hpp:83-93, rejects :); the port is the separate port parameter (default 443), as all three samples now correctly demonstrate.
2. The Linux icmp leg is honestly gated, never fakes loss. When the kernel refuses the unprivileged SOCK_DGRAM ICMP socket (net.ipv4.ping_group_range doesn’t admit the process group), the row reports status: not-permitted with sent: 0/loss_pct: 100.0 rather than a fabricated 100% loss figure (netprobe_plugin.cpp:9-11, :229-230, :332-337). The Linux sample was captured as root (euid 0) and so did not exercise this path.
3. icmp is IPv4-only; tcp/dns resolve any family. icmp forces AF_INET (netprobe_plugin.cpp:340, comment “IPv4 only this slice”); tcp resolves AF_UNSPEC (netprobe_plugin.cpp:381). A target with only an IPv6 address succeeds on tcp/dns but fails icmp with resolve-failed. IPv6 for icmp is a tracked follow-up (netprobe_plugin.cpp:11).
4. Windows ICMP RTT is whole-millisecond only. IcmpSendEcho’s RoundTripTime is a whole-ms value by API design (netprobe_plugin.cpp:184-186) — a sub-millisecond LAN hop reads 0.0; use tcp for sub-ms fidelity on Windows.
5. No action-level deadline, only per-sample. Each sample is bounded by timeout_ms (100-3000 ms) plus a fixed 200 ms inter-sample gap, run strictly sequentially (netprobe_plugin.cpp:79, :346-348, :388-390); worst case is about 2 minutes at maximum targets/samples/timeout (netprobe_plugin.cpp:16-18), but nothing bounds the sum beyond that arithmetic.

Source and tests

• Plugin: agents/plugins/netprobe/src/netprobe_plugin.cpp · agents/plugins/netprobe/src/netprobe_stats.hpp
• Definitions: content/definitions/netprobe.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_c.hpp
• Tests: tests/unit/test_netprobe_stats.cpp
• Privilege row: docs/agent-privilege-model.md (no row yet)