witr

Product Introduction

1. Definition: witr is a cross-platform process ancestry tracing tool, written in Go, that performs causal root-cause analysis on running system entities. Unlike conventional process inspection utilities that report state and metadata, witr operates as a process lineage resolver: it accepts a PID, process name, network port, container, or file path as input and reconstructs the full supervisory chain responsible for that entity's existence. It identifies the originating system—whether systemd, supervisor, shell, cron, or a container runtime—and augments the chain with contextual attributes including the initiating user, start timestamp, working directory, and operational warnings. witr compiles to a single static binary and runs natively on Linux, macOS, Windows, and FreeBSD, with an interactive TUI dashboard, a compact one-line CLI output mode, and a machine-readable JSON mode with real exit codes for scripting.

2. Core Value Proposition: witr exists to answer the fundamental operational question: "Why is this running?" Traditional system utilities like ps, top, lsof, ss, systemctl, and docker ps expose what is running—process metadata, resource usage, open ports, and container state—but place the cognitive burden on the user to manually correlate outputs across multiple tools to infer why a process exists. witr makes causality explicit by tracing the exact chain of supervisors, schedulers, and parent processes that led to the current state of any running entity. For DevOps engineers, SREs, and system administrators, witr collapses what would typically require cross-referencing pstree, systemctl status, crontab -l, docker inspect, and lsof output into a single deterministic command. It answers the "process ancestry" or "process origin" question directly—critical for incident investigation, security audits, infrastructure onboarding, and the ongoing battle against unexplained CPU, memory, or port usage in production environments.

Main Features

1. Interactive TUI Dashboard (Processes, Ports, Containers, Locks Tabs): Running witr with no arguments launches a full-screen interactive terminal dashboard organized into four dedicated tabs. The Processes tab provides a navigable list of running processes; selecting any entry reveals its complete causation chain. The Ports tab enumerates listening sockets and bound endpoints, allowing an operator to select a suspicious port and immediately identify which process owns it and, critically, why that process was spawned. The Containers tab lists active containers (via container runtime integration) and traces each back to its launching mechanism—container runtime, orchestrator, or manual invocation. The Locks tab surfaces file locks held by processes, with the same causal trace applied: which process holds the lock, what chain of supervision created that process, and what conflict warnings are relevant. The TUI is optimized for keyboard-driven investigation, making it a practical tool for incident triage on headless servers where a terminal is the only interface available.

2. Scriptable CLI with --short and --json Modes: For automation and operational use, witr exposes a deterministic command-line interface. The --short flag collapses the entire supervision chain into a single-line output, formatted as a readable ancestry chain (e.g., systemd → pm2 → node), suitable for shell pipes, notification messages, or quick contextual output. The --json flag emits structured JSON containing the full causal graph, process metadata, environmental context, and warnings; critically, JSON mode implements real exit codes—allowing CI/CD pipelines, monitoring hooks, and incident-response scripts to programmatically branch on whether a process was successfully traced, whether the target was not found, or whether the trace was incomplete due to permission restrictions or os-specific limitations. This distinguishes witr from tools that merely dump text, making it a first-class citizen in automated observability workflows.

3. Multi-Source Supervision Chain Reconstruction (systemd, supervisor, shell, cron, container runtime): witr's core tracing engine recursively walks the parent-process hierarchy and correlates each node against known supervision and scheduling systems. When it encounters a systemd unit, it resolves the unit file name, the unit type (service, socket, timer, path), and the activation mechanism (e.g., socket activation, timer-triggered, D-Bus-activated). When it detects a supervisor-managed process (e.g., PM2, supervisord, runit, daemontools), it traces back through the supervisor's configuration to identify the managed service definition. For cron-launched jobs, witr identifies the crontab entry, the owning user, and the schedule. For shell-spawned processes, it traces through the shell parent chain to the originating command, invoking user, working directory, and environment. The tool also identifies container boundaries, mapping processes to their container ID, image, and runtime. The output is a unified chain, not merely a PID tree—it explains the causal relationship between each layer.

4. Cross-Platform Static Go Binary with Broad Distribution: witr is distributed as a single static binary with no runtime dependencies, covering linux (amd64, arm64), macOS (darwin amd64/arm64), windows (amd64/arm64), and freebsd. It is packaged across an unusually broad ecosystem: official Debian and Ubuntu APT repositories (Ubuntu 26.04+, Debian sid), Homebrew, MacPorts, conda-forge (via conda/mamba/pixi), Arch Linux AUR (witr-bin), Winget, Chocolatey, Scoop, npm (@pranshuparmar/witr), FreeBSD FreshPorts (pkg install witr), GNU Guix, AOSC OS (oma install witr), uniget, aqua, brioche, and mise. For organizations avoiding package managers, a Unix install script (install.sh) detects OS and CPU architecture and installs the binary plus a man page; a Windows PowerShell script (install.ps1) downloads, verifies checksum, and manages user PATH. The Go toolchain also supports direct installation via go install github.com/pranshuparmar/witr/cmd/witr@latest, and a Nix flake supports nix run github:pranshuparmar/witr for ephemeral execution without installation. A web-based browser simulation of a Linux environment (hosted at pranshuparmar.github.io/witr/) enables hands-on evaluation before installation.

5. Contextual Warning and Metadata Augmentation: Beyond the causal chain, witr surfaces operational warnings that are relevant to process health and troubleshooting. These include: stale lock files, orphaned processes whose parent has exited, discrepancies between expected and actual command paths, environment variables that deviate from the defining container or service configuration, processes running as unexpected users, and conflicts between port bindings and declared service configurations. In JSON mode, each warning is a structured entry with severity and message, allowing monitoring systems to ingest and alert on them. For each hop in the chain, witr reports: the process ID, parent PID, process name, executable path, working directory, start time (via process creation timestamp), the invoking user, the controlling terminal (if any), and the full command-line invocation. This metadata payload makes witr valuable not just as a causality tool but as a forensic process-profiling platform.

Problems Solved

1. Pain Point: Manual Cross-Tool Correlation Is Slow and Error-Prone. The daily reality of diagnosing an unfamiliar Linux, macOS, or Windows system requires an operator to run ps aux | grep <term>, identify a suspect PID, run pstree -p to map hierarchy, cross-reference systemctl status <pid> or cat /proc/<pid>/cgroup to locate the systemd unit, invoke crontab -l to check for scheduled jobs, run lsof -i :<port> to determine port ownership, and then still manually stitch those fragmented observations into an explanation. On modern systems with containers layered on top of supervisors layered on top of systemd, that "chain synthesis" is a hidden tax on every incident. witr eliminates this entire workflow: a single invocation against a PID, process name, port, container, or file returns the answer, not the raw data to assemble into an answer. This directly addresses the "why is a process running" problem, "port already in use" origin detection, and "unknown process consuming resources" investigation.

2. Target Audience: The primary personas are: DevOps Engineers and SREs who manage large fleets of Linux servers and need to rapidly attribute processes to their originating automation, systemd unit, cron job, or deployment pipeline; Platform Engineers who maintain internal PaaS environments and need to trace how tenant workloads were scheduled and spawned; System Administrators responsible for "mystery process" tickets, port conflicts, and identifying whether a process is legitimate, orphaned, or malicious; Support Engineers who triage support escalations on systems they did not configure; Security Analysts and incident responders who need forensic process ancestry to establish how an unknown binary was launched on a compromised host; Container Infrastructure Operators who need to map processes inside containers back to the container creation mechanism, and verify that container runtimes (Docker, containerd, Podman) were the initiating chain; and Technical Onboarding Specialists who use witr in documentation and training to explain how a system's process tree was formed.

3. Use Cases: Specific, high-value scenarios include: (a) A server's CPU is pegged; top shows a node process; witr <pid> reveals the chain systemd → pm2 → node and identifies the pm2-managed application name, the deployment timestamp, and the user who launched the PM2 daemon—immediately distinguishing an expected workload from a rogue process. (b) A production service fails to bind because port 8080 is already in use; running witr 8080 (or witr --port 8080) identifies the process holding the port, the systemd service definition that spawned it, and the socket-activation policy—resolving a deployment conflict in seconds instead of minutes. (c) A cron-based data-processing job produces unexpected output; witr <job pid> reveals the crontab entry, the schedule expression, and the environment under which cron invoked it—permitting direct verification of the cron configuration without parsing /var/log/cron. (d) A filesystem lock prevents a database from starting; witr <lock file path> traces the file lock to the owning process and then back through its full supervision chain, identifying the stale or conflicting process holding the lock. (e) During a security incident, an operator points witr at a suspicious binary's PID and instantly obtains the complete causal chain—who launched it, from which shell or scheduler, when, and with what warnings—streamlining the initial containment and attribution phase. (f) An engineer is handed a legacy server with no documentation; running witr bare in TUI mode and stepping through the Processes tab reconstructs an architectural map of why every significant service is running, effectively reverse-engineering the server's intended configuration.

Unique Advantages

1. Differentiation: The existing process-management ecosystem is fragmented across three categories: state inspectors (like ps and top, which report CPU, memory, and process existence but only show direct parent-child relationships), hierarchy visualizers (like pstree, which render the process tree but provide no semantic explanation of what each supervisor, scheduler, or container boundary means), and runtime-specific tools (like systemctl status, docker inspect, and pm2 list, which explain a process only if you already know which runtime owns it). None of these tools establish the causal chain across heterogeneous layers: a systemd-managed process that is itself a container, that contains a supervisor, that spawned a worker, is invisible to any single conventional utility. witr is the only tool in its category that integrates hierarchy resolution with cross-runtime semantic tracing—it understands the meaning of systemd units, cron tabs, supervisor configs, and container boundaries, and expresses the cause as a coherent chain rather than a raw PID nesting. Compared to tools like htop (which shows the tree but no causality), lsof (which shows port-to-process mapping but no ancestor semantics), and systemd-analyze (which explains boot-time units but not runtime-spawned processes), witr is the only one that answers the "why" question directly, at a higher semantic level, and across the entire layering stack.

2. Key Innovation: witr's innovation lies in its causal chain reconstruction engine—a recursive resolver that walks each ancestor in the process tree and classifies it against a knowledge base of supervision systems (systemd, cron, at, PM2, supervisord, runit, daemontools, Docker/Podman/containerd, shell interpreters including bash, zsh, and PowerShell, and OS-specific launchers like launchd on macOS and Service Control Manager on Windows). Instead of emitting a linear list of parent PIDs (which is what pstree does), witr interprets each hop semantically: it identifies the specific systemd unit file, the specific crontab entry, the specific supervisor service definition, or the specific container runtime operation that is responsible for spawning the child. This means the output is an answer, not a tree. A second innovation is the real exit-code contract in JSON mode, enabling witr to participate in automation pipelines as a conditionally-failing probe (trace found, trace not found, permission denied, platform unsupported) rather than as a text generator. A third is the browser-based simulation sandbox, which allows an operator to practice tracing a fully simulated Linux system without installing the binary—an unusually deep documentation mechanism for a system tool. The combination of semantic classification, scriptable contracts, cross-runtime integration, and an interactive browser tutorial is unique in the process-analysis tooling space, which has not seen sustained innovation since the introduction of htop and pstree.

Frequently Asked Questions (FAQ)

1. What exactly does witr do that tools like ps and pstree do not? ps reports the current state of processes (PID, PPID, CPU, memory, command). pstree visualizes the parent-child hierarchy. Neither explains why an ancestor exists or what system is responsible for it. witr traces the full causal chain—detecting that a process is managed by a specific systemd unit, or was launched by a specific cron entry, or is running under a supervisor like PM2, or is executing inside a container—and combines that with contextual metadata (who started it, when, from which directory, with which warnings). For example, pstree might show systemd → pm2 → node, but witr tells you that the path is the myapp.service systemd unit which spawned the PM2 daemon, which runs the application named worker, which was started by user deploy at 09:14 UTC from /opt/myapp—with a warning that the PM2 config specifies 4 instances but only 1 is running.

2. Can I use witr in production scripts, CI/CD pipelines, or monitoring automation? Yes. witr is built for scripting. The --short flag produces a single line (e.g., systemd → pm2 → node), ideal for command substitution, log lines, or notifications. The --json flag emits structured JSON with the complete causal graph, process metadata, environmental context, and warning entries—and, critically, enforces meaningful exit codes: 0 for a successful trace, and non-zero codes for trace-not-found, permissions-denied, or platform-limitation conditions. This enables a monitoring hook to fail a deployment if a process is not traceable to an expected systemd unit, or to page an on-call engineer if a port is bound by an unexpected process chain.

3. Which platforms and operating systems are supported by witr, and how can it be installed? witr is a static Go binary supporting Linux, macOS (darwin), Windows, and FreeBSD, on both amd64 and arm64 architectures. Installation methods include: APT (sudo apt install witr on Debian sid, Ubuntu 26.04+ and derivatives), Homebrew (brew install witr), MacPorts (sudo port install witr), conda-forge (conda install -c conda-forge witr or via mamba/pixi), Arch AUR (witr-bin), Winget (winget install -e --id PranshuParmar.witr), Chocolatey (choco install witr), Scoop (scoop install main/witr), npm (npm install -g @pranshuparmar/witr), FreeBSD pkg (pkg install witr), GNU Guix, AOSC OS, uniget, aqua, brioche, mise, the official curl install script for Unix, a PowerShell installer for Windows, go install github.com/pranshuparmar/witr/cmd/witr@latest for source-level installation, and a Nix flake for ephemeral evaluation via nix run github:pranshuparmar/witr. A full, up-to-date packaging matrix is maintained on Repology.

4. How does witr trace processes inside containers, and is there a browser demo I can try? For containers, witr detects the container boundary by examining process cgroups and namespace metadata, identifies the container ID and image, and traces the causality chain through the container runtime—showing, for example, systemd → containerd → dockerd → container (nginx:latest) → nginx worker. It then continues the trace outside the container if the runtime was itself spawned by a supervisory chain. Yes—a full browser-based demo is available at https://pranshuparmar.github.io/witr/, which simulates a realistic Linux box with a guided tutorial and a free-play sandbox. Visitors can practice tracing processes, ports, and containers before installing anything. Virtual "try witr in your browser" onboarding is a documented feature of the project.

5. Is witr a security or malicious-process detection tool? How does it help during incident response? witr is primarily a diagnostic and causality-analysis tool, but it is highly useful in security workflows. During incident response, an operator can point witr at any unknown or suspicious PID, port, container, or file lock and immediately receive: the complete ancestral chain of how the process came to be, the user account that initiated the chain, the precise start time, the working directory, and any warnings such as unusual environment variables, a parent process that exited and orphaned the child, or a mismatch between a declared service command and the actual running command. This forensics-grade ancestry helps distinguish a legitimate systemd-managed service from a reverse shell, a cryptominer, or a tampered binary. It is not a signature-based antivirus, but it is a powerful attribution layer that accelerates the triage of compromised or misconfigured hosts.