Neo23x0/process-watcher

A narrow, root-required eBPF agent that watches one service's process tree and reports what it starts. It fits incident-response or hardening work on a known Linux host, not a general EDR.

The problem

Suppose an attacker finds a way to make your public-facing nginx, php-fpm or Java service run a command. The service looks normal; only an unexpected child process — a shell, useradd, a downloader — reveals the intrusion. Inspecting /proc after the fact misses processes that already exited, and detection based on the service's own logs may never trigger. process-watcher attaches eBPF programs and emits an event when a watched tree spawns a child, so you see the short-lived command plus its parent chain instead of reconstructing it later.

What's different

The mechanism is the point: the agent matches on the file name of the program actually executed, not comm or argv[0], and tracks descendants across exec, reparenting, double forks and the death of the root, so a command that re-parents to PID 1 is still attributed. Events go to JSONL, TCP/UDP or a webhook, and argument capture is opt-in because command lines can contain secrets. Optional kill rules can signal matching children by image, argv or regex — a blunt, explicit lever.

The trade-off is strictness. If a requirement is missing, the agent exits with code 3 and never falls back to polling /proc, which the README says would miss short-lived processes. Coverage is binary: either the host qualifies or you get no data. check-config and print-config run without root, but observation cannot.

Who should try it

Good fit: a security or platform team running a specific Linux service on a known amd64/arm64 host with a modern kernel, wanting a lightweight, auditable record of what that service spawns — for example during the PHP critical-release window the README calls out. It also suits an IR team watching a suspect service rather than the whole machine.

Poor fit: older kernels, container-only environments, or a host where the service tree cannot be pinned to an image name. It is not a general host intrusion-detection system; it watches the trees you name.

Requirements and limitations

Linux amd64/arm64, kernel 5.15+ with BTF (/sys/kernel/btf/vmlinux); the README notes the version alone is no guarantee because the agent checks the exact functions and fields it needs at start. Root (or CAP_BPF + CAP_PERFMON, plus CAP_SYS_PTRACE for other users' executables and CAP_KILL for kill rules) is required, and the initial host PID namespace is mandatory: it refuses to run in a container, and kernel lockdown confidentiality blocks it. sudo ./process-watcher doctor checks these; tested kernels are in docs/compatibility.md.

Ongoing upkeep matters: maintain the watch list and exclusions, take care with argument capture, and stage-test kill rules. Deployment is a single static binary or a systemd unit via packaging/INSTALL.md, with checksums and build attestation for releases.

HotRepo's take

HotRepo first tracked this on 2026-10-24; on the 2026-10-25 NEW-REPOSITORY board (新项目榜, not the overall Trending board) it showed 109 total stars at #25 — a snapshot, not a daily growth figure. With only two recorded dates, persistence cannot be judged. Before adopting, confirm your kernel passes doctor and that your service's real executable name matches what you watch.