witr --version

witr v0.3.4 (commit 7e46fa68151fd7c59fb7a0cf4247a9a0ac0fbb6e, built 2026-10-04T17:31:44Z)

witr explains why a process or port is running by tracing its ancestry.

Usage:
  witr [process name...] [flags]

Examples:

  # Inspect a running process by name
  witr nginx

  # Look up a process by PID
  witr --pid 1234

  # Find the process listening on a specific port
  witr --port 5432

  # Find the process holding a file open
  witr --file /var/lib/dpkg/lock

  # Inspect a container by name
  witr --container redis

  # Inspect a process by name with exact matching (no fuzzy search)
  witr bun --exact

  # Show the full process ancestry (who started whom)
  witr postgres --tree

  # Show only warnings (suspicious env, arguments, parents)
  witr docker --warnings

  # Display only environment variables of the process
  witr node --env

  # Short, single-line output (useful for scripts)
  witr sshd --short

  # Disable colorized output (CI or piping)
  witr redis --no-color

  # Output machine-readable JSON
  witr chrome --json

  # Show extended process information (memory, I/O, file descriptors)
  witr mysql --verbose

  # Combine flags: inspect port, show environment variables, output JSON
  witr --port 8080 --env --json

  # Multiple inputs
  witr nginx node
  witr --port 8080 --port 3000
  witr --pid 1234 --pid 5678

  # Mixed inputs
  witr nginx --pid 1234 --port 8080


Flags:
  -c, --container strings   container(s) to look up (repeatable)
      --env                 show environment variables for the process
  -x, --exact               use exact name matching (no substring search)
  -f, --file strings        file(s) held open by a process (repeatable)
  -h, --help                help for witr
  -i, --interactive         interactive mode (TUI)
      --json                show result as JSON
      --no-color            disable colorized output
  -p, --pid strings         pid(s) to look up (repeatable)
  -o, --port strings        port(s) to look up (repeatable)
  -s, --short               show only ancestry
  -t, --tree                show only ancestry as a tree
      --verbose             show extended process information
  -v, --version             version for witr
      --warnings            show only warnings

WITR(1)                                                                WITR(1)

NAME
       witr - Why is this running?

SYNOPSIS
       witr [process name...] [flags]

DESCRIPTION
       witr explains why a process or port is running by tracing its ancestry.

OPTIONS
       -c, --container=[]      container(s) to look up (repeatable)
       ...

Multiple matching processes found:

[1] sshd (pid 7194)
    sshd: /usr/sbin/sshd -D [listener] 0 of 10-100 startups
[2] sshd (pid 25397)
    sshd: root@notty
[3] sshd (pid 88186)
    sshd: root@notty
[4] sshd (pid 214186)
    sshd: root@pts/2
[5] sshd (pid 214891)
    sshd: root@notty

Re-run with:
  witr --pid <pid>

witr python -x

Target      : python

Process     : python (pid 849108) {forked}
User        : root
Security    : AppArmor docker-default (enforce)
Container   : docker: witr-v034-py
Image       : python:3.12-alpine
Command     : python -m http.server 8142 --bind 0.0.0.0
Started     : just now (Sun 2026-10-25 09:41:45 +08:00)

Why It Exists :
  systemd (pid 1) → ? (original parent exited) → containerd-shim-runc-v2 (pid 849084) → python (pid 849108)

Source      : docker (container)

Working Dir : /

Warnings    :
  • Process is running as root
  • Container has no healthcheck configured

witr --pid 7194 --short

systemd (pid 1) → sshd (pid 7194)

witr --pid 4194305 ; echo "exit=$?"

no running process with pid 4194305

No matching process or service found. Please check your query or try a different name/port/PID.
For usage and options, run: witr --help
exit=2

python3 -m http.server 8141 --bind 0.0.0.0 &
witr --port 8141

Target      : python3

Process     : python3 (pid 744395)
User        : root
Command     : python3 -m http.server 8141 --bind 0.0.0.0
Started     : just now (Sun 2026-10-25 09:26:12 +08:00)

Why It Exists :
  systemd (pid 1) → ? (original parent exited) → python3 (pid 744395)

Source      : session-17.scope (systemd)
Description : Session 17 of User root
Unit File   : /run/systemd/transient/session-17.scope

Working Dir : /opt/data/quzuo/tmp/witr
Git Repo    : quzuo (master)
Sockets     : 0.0.0.0:8141 (TCP | LISTENING)

Warnings    :
  • Process is listening on a public interface
  • Process is running as root
  • Process sets LD_PRELOAD (potential library injection)
  • Process sets DYLD_* variables (potential library injection): DYLD_LIBRARY_PATH

witr --file /opt/data/quzuo/tmp/witr/http.log

Target      : python3

Process     : python3 (pid 744395)
User        : root
Command     : python3 -m http.server 8141 --bind 0.0.0.0
Started     : just now (Sun 2026-10-25 09:26:12 +08:00)

Why It Exists :
  systemd (pid 1) → ? (original parent exited) → python3 (pid 744395)

Source      : session-17.scope (systemd)
Description : Session 17 of User root
Unit File   : /run/systemd/transient/session-17.scope

Working Dir : /opt/data/quzuo/tmp/witr
Git Repo    : quzuo (master)
Sockets     : 0.0.0.0:8141 (TCP | LISTENING)

Warnings    :
  • Process is listening on a public interface
  • Process is running as root
  • Process sets LD_PRELOAD (potential library injection)
  • Process sets DYLD_* variables (potential library injection): DYLD_LIBRARY_PATH

witr --container witr-v034-demo

Target      : sleep

Process     : sleep (pid 754786) {forked}
User        : root
Security    : AppArmor docker-default (enforce)
Container   : docker: witr-v034-demo (id 85fcf40bcf7e)
Image       : busybox
Command     : sleep 3600
Started     : just now (Sun 2026-10-25 09:27:41 +08:00)

Why It Exists :
  systemd (pid 1) → ? (original parent exited) → containerd-shim-runc-v2 (pid 754761) → sleep (pid 754786)

Source      : docker (container)

Working Dir : /

Warnings    :
  • Process is running as root
  • Container has no healthcheck configured

witr --pid 7194 --port 8141

----- [pid: 7194] -----
Process     : sshd (pid 7194)
Source      : ssh.service (systemd)
----- [port: 8141] -----
Process     : python3 (pid 744395)
Source      : session-17.scope (systemd)

witr --port 8141 --short

systemd (pid 1) → ? (original parent exited) → python3 (pid 744395)

witr --pid 7194 --tree

systemd (pid 1)
  └─ sshd (pid 7194)
    ├─ sshd (pid 25397)
    ├─ sshd (pid 88186)
    ├─ sshd (pid 214186)
    └─ sshd (pid 214891)

{
  "Target": {
    "Type": "port",
    "Value": "8141"
  },
  "ResolvedTarget": "python3",
  "Process": {
    "PID": 744395,
    "PPID": 1,
    "Command": "python3",
    "Cmdline": "python3 -m http.server 8141 --bind 0.0.0.0",
    "StartedAt": "2026-10-25T09:26:12.92+08:00",
    "User": "root",
    "WorkingDir": "/opt/data/quzuo/tmp/witr",
    "GitRepo": "quzuo",
    "GitBranch": "master",
    "Sockets": [
      {
        "Inode": "2467781",
        "Port": 8141,
        "Address": "0.0.0.0",
        "State": "LISTEN",
        "Protocol": "TCP"
      }
    ],
    ...
  },
  "RestartCount": 0,
  "Ancestry": [...],
  "Source": {
    "Type": "systemd",
    "Name": "session-17.scope",
    "Description": "Session 17 of User root",
    "UnitFile": "/run/systemd/transient/session-17.scope",
    "Details": {}
  },
  "Warnings": [
    "Process is listening on a public interface",
    "Process is running as root",
    "Process sets LD_PRELOAD (potential library injection)",
    "Process sets DYLD_* variables (potential library injection): DYLD_LIBRARY_PATH"
  ],
  "SocketInfo": {
    "Port": 8141,
    "State": "LISTEN",
    "LocalAddr": "0.0.0.0",
    "Explanation": "The process is actively waiting for incoming connections."
  },
  ...
}

witr --pid 744395 --env

Process     : python3 (pid 744395)
Command     : python3 -m http.server 8141 --bind 0.0.0.0
Environment :
  SHELL=/bin/bash
  COLORTERM=truecolor
  LANG=en_US.UTF-8
  PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
  ...

witr --pid 7194 --warnings

Process     : sshd (pid 7194)
Command     : sshd: /usr/sbin/sshd -D [listener] 0 of 10-100 startups
Warnings    :
  • Process is listening on a public interface
  • Process is running as root
  • Process is running from a suspicious working directory: /

witr --pid 7194 --verbose

CPU (avg)   : 0.0%

Memory:
  Virtual  : 11.8 MB
  Resident : 8.2 MB
  Shared   : 7.1 MB

I/O Statistics:
  Read  : 3.4 MB (413178 ops)
  Write : 72.0 KB (5382 ops)

Open Files  : 5 of 1024 (0%)

File Descriptors: 5/1024
  0 -> /dev/null
  1 -> socket:[51663]
  2 -> socket:[51663]
  3 -> socket:[23346]
  4 -> socket:[26701]

Children of sshd (pid 7194):
  ├─ sshd (pid 25397)
  ├─ sshd (pid 88186)
  ├─ sshd (pid 214186)
  └─ sshd (pid 214891)

witr --pid 7194 --short > /dev/null 2>&1; rc=$?
case $rc in
  0) echo "All clear" ;;
  1) echo "Warnings detected" ;;
  2) echo "Process not running" ;;
  3) echo "Need elevated privileges" ;;
  4) echo "Invalid input or ambiguous match" ;;
  5) echo "Internal error" ;;
  6) echo "Cannot tell what started it" ;;
esac

Warnings detected

Process not running

witr -i < /dev/null ; echo "exit=$?"

Error: interactive mode needs a terminal; give a target to explain: a process name, --pid, --port, --file or --container
exit=4

Error: must specify --pid, --port, --file, --container, or a process name
exit=4

# bash
echo 'eval "$(witr completion bash)"' >> ~/.bashrc
source ~/.bashrc

# zsh
echo 'eval "$(witr completion zsh)"' >> ~/.zshrc
source ~/.zshrc

# fish（即时生效 + 永久化）
witr completion fish | source
witr completion fish > ~/.config/fish/completions/witr.fish

# powershell
witr completion powershell | Out-String | Invoke-Expression

# bash completion V2 for witr                                 -*- shell-script -*-

__witr_debug()
{
    if [[ -n ${BASH_COMP_DEBUG_FILE-} ]]; then
        echo "$*" >> "${BASH_COMP_DEBUG_FILE}"
    fi
}

#!/bin/bash
# deploy-guard.sh —— 上线前确认业务端口未被占用
PORT=8141
witr --port $PORT --short > /dev/null 2>&1
rc=$?
case $rc in
  2) echo "Port $PORT free, go" ;;
  0|1) echo "Port $PORT occupied:"; witr --port $PORT --short ;;
  3) echo "Need sudo to inspect port $PORT" ;;
  *) echo "witr exit=$rc, check manually" ;;
esac

Port 8141 occupied:
systemd (pid 1) → ? (original parent exited) → python3 (pid 744395)

witr --pid 7194 --json | jq -r '"\(.ResolvedTarget) | source=\(.Source.Name) | warnings=\(.Warnings | length)"'

sshd | source=ssh.service | warnings=3