proc-connector

Linux Process Event Connector (NETLINK_CONNECTOR + CN_IDX_PROC) — safe, zero-overhead, full-coverage parser for all 10+ PROC_EVENT_* types.

Installation

cargo add proc-connector

Minimum supported Rust version: 1.85 (edition 2024).

Requirements

• Linux kernel with CONFIG_CONNECTOR and CONFIG_PROC_EVENTS enabled
• CAP_NET_ADMIN capability (run as root or with cap_net_admin+ep)

The crate compiles on any platform, but all runtime operations require a Linux kernel with proc connector support. Non-Linux platforms will fail at runtime with Error::Os(ENOSYS).

Testing

Unit tests (no privileges needed)

cargo test

67 unit tests covering all protocol parsing (every event variant, truncation edge cases, malformed headers, kernel boundary conditions, multi-message iteration), error formatting, alignment helpers, and alignment math.

Integration tests (require root)

2 additional tests verify end-to-end behavior against a real Linux kernel. Build as normal user, run under sudo:

cargo test --test integration_test --no-run
sudo -E ~/.cargo/bin/cargo test --test integration_test -- --ignored

Test	What it checks
test_receive_exec_event	Create connector → spawn /bin/true → receive Exec event within 5s
test_subscribe_unsubscribe	Subscribe → unsubscribe → re-subscribe, no errors

---

About this crate

The Linux kernel exposes process lifecycle events (exec, fork, exit, uid/gid change, ptrace, etc.) through the Proc Connector — a netlink protocol multiplexed over NETLINK_CONNECTOR with CN_IDX_PROC.

Event coverage

Event	Kernel constant	Fields
Exec	PROC_EVENT_EXEC	pid, tgid
Fork	PROC_EVENT_FORK	parent_pid, parent_tgid, child_pid, child_tgid
Exit	PROC_EVENT_EXIT	pid, tgid, exit_code, exit_signal
Uid	PROC_EVENT_UID	pid, tgid, ruid, euid
Gid	PROC_EVENT_GID	pid, tgid, rgid, egid
Sid	PROC_EVENT_SID	pid, tgid
Ptrace	PROC_EVENT_PTRACE	pid, tgid, tracer_pid, tracer_tgid
Comm	PROC_EVENT_COMM	pid, tgid, comm: [u8; 16]
Coredump	PROC_EVENT_COREDUMP	pid, tgid

Quick example

use proc_connector::ProcConnector;
use std::time::Duration;

// Requires CAP_NET_ADMIN
let conn = ProcConnector::new().expect("create connector");
let mut buf = [0u8; 4096];

loop {
    match conn.recv_timeout(&mut buf, Duration::from_secs(1)) {
        Ok(Some(event)) => println!("{event}"),
        Ok(None) => eprintln!("timeout"),
        Err(e) => { eprintln!("{e}"); break; }
    }
}

Async integration

use proc_connector::ProcConnector;

let conn = ProcConnector::new().unwrap();
let raw_fd = conn.as_raw_fd();

// With tokio:
// let async_fd = tokio::io::unix::AsyncFd::new(conn).unwrap();

---

Modules

src/
├── consts.rs   # All kernel constants (PROC_EVENT_*, CN_IDX_PROC, NLMSG_*, layout offsets)
├── error.rs    # Error enum (Os, Truncated, BufferTooSmall, Interrupted, ConnectionClosed, Overrun)
├── socket.rs   # ProcConnector (new, subscribe, unsubscribe, recv_raw, as_raw_fd)
├── event.rs    # ProcEvent enum + netlink/cn_msg/proc_event three-layer parser
└── lib.rs      # Re-exports, prelude

---

Error handling

All fallible operations return Result<T, Error>. The Error enum covers both system-level and protocol-level failures:

Variant	Meaning
Os(io::Error)	System call failed (socket, bind, sendmsg, recv)
Truncated	Message shorter than minimum protocol header
BufferTooSmall { needed }	Provided buffer too small
Interrupted	recv interrupted by signal (retry)
ConnectionClosed	recv returned 0
Overrun	Kernel reporting dropped events (increase buffer / consume faster)

use proc_connector::Error;

fn handle(e: Error) {
    match &e {
        Error::Os(e) => eprintln!("os error: {e}"),
        Error::BufferTooSmall { needed } => eprintln!("need buffer of {needed} bytes"),
        Error::Overrun => eprintln!("events dropped!"),
        _ => eprintln!("{e}"),
    }
}

License

MIT License