# karol-broda/snitch: a friendlier ss and netstat with a TUI and styled tables

> snitch is a Go network connection inspector that wraps the usual ss/netstat output in a Bubble Tea TUI, styled tables, JSON and CSV. It reads /proc/net/*, installs from Homebrew, Go, nixpkgs, AUR or a shell script, and is licensed MIT.

**karol-broda/snitch** — a prettier way to inspect network connections

- Repository: https://github.com/karol-broda/snitch
- Stars: 3,488 · Forks: 56
- Language: Go
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/karol-broda-snitch

## What snitch replaces, and who is actually reaching for it

The README opens with a one-line positioning statement: a friendlier ss / netstat for humans. That is the whole problem statement. On Linux and macOS, the stock tools print wide, unaligned columns that are hard to scan, and ss in particular is not the same on every distribution. snitch targets the person who types ss -tulpn several times an hour and then has to squint at the result.

The audience is narrower than "everyone who runs a server". snitch reads /proc/net/* on Linux, which the README notes does not require CAP_NET_ADMIN or CAP_NET_RAW. That makes it usable by an unprivileged user who wants to see sockets, and it also means process attribution is a separate concern: the Docker example only gets PID, process name and user when the container is given --pid=host and --cap-add=SYS_PTRACE. If you are a network engineer looking for flow analysis, this is not the tool. If you are a developer or SRE who wants to see what is listening on your laptop or a box you just SSH'd into, the fit is closer.

## How snitch gets its data, and what the TUI layer adds

There is no daemon and no eBPF program here. The go.mod lists Bubble Tea for the terminal UI, Lip Gloss for styling, Cobra for the command tree and Viper for configuration. The README says snitch reads from /proc/net/*, so the data path is: parse the kernel's procfs socket tables, optionally resolve IP addresses to hostnames and port numbers to service names, then render either as a live-updating Bubble Tea model or as a one-shot table.

That choice has consequences. Because the source is procfs rather than a packet socket, snitch sees the state of sockets, not traffic. It cannot tell you how many bytes moved. It also inherits the limits of /proc/net/*: on Linux that is fine, but the README's install matrix only lists linux and darwin artifacts, and the macOS path cannot use procfs, so the README does not document what it reads there instead. The resolution layer is configurable: --resolve-addrs defaults to true, --resolve-ports is opt-in, and --no-cache forces fresh lookups. DNS caching exists, which matters if you run snitch in a loop and do not want a lookup per row.

The TUI is the part that distinguishes it from a shell alias. Keybindings include j/k navigation, t/u to toggle TCP and UDP, l/e/o to toggle listening, established and other, s/S to cycle sort and reverse, and K to kill a process with confirmation. There is also w to watch or highlight a process and W to clear watched processes, which is a filter that persists as the list refreshes rather than a one-time grep.

## Installing snitch and running a first query

The README lists several install paths. Homebrew is the shortest, and the README credits @bevanjkay for adding snitch to homebrew-core:

```bash
brew install snitch
```

If you have a Go toolchain, go install pulls the module path directly:

```bash
go install github.com/karol-broda/snitch@latest
```

There is also a shell script that installs to ~/.local/bin when available and /usr/local/bin otherwise. The README notes that on macOS the script strips the com.apple.quarantine attribute unless KEEP_QUARANTINE=1 is set, and that INSTALL_DIR overrides the destination:

```bash
curl -sSL https://raw.githubusercontent.com/karol-broda/snitch/master/install.sh | INSTALL_DIR=~/bin sh
```

Once installed, the quick start section gives the first commands to try. Running snitch with no arguments launches the interactive TUI; snitch ls prints a styled table and exits:

```bash
snitch              # launch interactive tui
snitch -l           # tui showing only listening sockets
snitch ls -t -e     # tcp established connections
snitch ls -p        # plain output (parsable)
```

What you should see for snitch ls is a table, paged automatically if it exceeds the terminal height. For scripts, snitch ls -o json and snitch ls -o csv are the structured forms, and snitch json is a dedicated subcommand for the same purpose. There is also snitch watch, which streams JSON frames at an interval, so a pipeline like snitch watch -i 1s | jq '.count' is documented in the README as a supported use.

## The Docker path, and why the capability flags matter

Running snitch in a container is documented, and the README is unusually explicit about what each flag buys you. The image tags are published to GitHub Container Registry in alpine, scratch, debian and ubuntu variants, with version-pinned tags like 0.2.0-alpine alongside latest.

```bash
docker run --rm --net=host snitch:latest ls
docker run --rm --net=host --pid=host --cap-add=SYS_PTRACE snitch:latest ls
```

The first form sees host sockets but not process names. The second adds PID, process name and user. The README states plainly that CAP_NET_ADMIN and CAP_NET_RAW are not required because snitch reads /proc/net/*. That is a meaningful security property: you are not handing the container broad network capabilities to get a connection listing. The trade-off is that process attribution needs SYS_PTRACE plus a shared PID namespace, which is a larger concession than the network capabilities you avoided. If you only want to know which ports are open on the host, the first command is enough and the second is unnecessary exposure.

## Where snitch stops being the right tool

snitch reports socket state. It does not capture packets, does not count bytes, and does not keep history. If a connection opened and closed between two refreshes of the TUI, the README gives no indication that snitch records it. For that class of question you want tcpdump, Wireshark or a flow collector, not a prettier ss.

The platform story is also incomplete in the README. The release artifacts cover linux and darwin, and the Docker images are Linux-only. The README does not document a Windows build. On macOS, the procfs mechanism described for Linux cannot apply, and the README does not explain the alternative source, so how complete the macOS view is cannot be confirmed from the documentation.

There is a second, quieter limitation: the kill binding. K kills a process with confirmation, which means snitch is not read-only in the TUI. On a shared or production machine that is a footgun unless you are deliberate about it. The one-shot snitch ls path has no such binding, so if you want a strictly observational tool, stay out of the TUI on machines where a stray keystroke is expensive.

## Compared with the tools it wraps

The honest alternative is ss itself, and the difference is not capability but presentation and configuration. ss is already installed, is scriptable, and has a stable flag vocabulary that every Linux admin knows. snitch adds a live TUI with toggles and a watched-process highlight, a set of named themes (catppuccin, gruvbox, dracula, nord, tokyo-night, solarized, one-dark and mono among them), and structured output in JSON and CSV behind its own flags.

If your workflow is already ss -tulpn piped into grep, snitch's advantage is mostly ergonomic: the -t, -u, -l, -e, -4 and -6 shortcut flags map onto the same filters, and the TUI lets you change them interactively instead of retyping. If your workflow is a monitoring agent that parses ss output, snitch json is a cleaner contract than column scraping, but it is a second dependency to install and keep current. That is the real trade: you gain a schema and lose the guarantee that the tool is already on the box.

## Maintenance, upgrade path and licence

The repository is not archived, and the last push was on 2026-06-11. The most recent release listed is v0.2.2 from 2025-12-29, preceded by v0.2.1 and v0.2.0 in the same week. So the release cadence visible in the repository is a burst in late December 2025 followed by commits into mid-2026 with no tagged release after that. That is not abandonment, but it is also not a project with a steady release train, and anyone pinning a version should plan around that.

Upgrades are handled in-band. The README documents snitch upgrade to check for updates, snitch upgrade --yes to apply automatically, and snitch upgrade -v 0.1.7 to install a specific version. That is convenient, and it also means the binary can replace itself, which is worth knowing before you run it on a host where you control binaries by package manager. If you installed via Homebrew, nixpkgs or the AUR, upgrading through snitch itself would bypass the package manager's record of what is installed, so pick one channel and stay on it.

The licence is MIT. That permits commercial and closed-source use, modification and redistribution provided the copyright notice and permission notice are preserved. This is a description of the licence text, not legal advice; if you are redistributing snitch inside a product, have your own counsel read the LICENSE file. Note that the dependency tree is larger than the MIT label alone suggests: go.mod pulls in Bubble Tea, Lip Gloss, Cobra, Viper and others, each with its own licence, so a redistribution audit should cover go.sum too.

## Conclusion

snitch fits engineers who read connection tables often and want a live TUI plus parsable output from one binary. Skip it if you need packet capture, historical flow data, or Windows support, none of which the README claims. Before adopting, check the releases page for a build matching your platform and confirm the last push date, 2026-06-11, against your own tolerance for a project that is not archived but has not been pushed to in months.

## FAQ

### What is karol-broda/snitch?

It is a Go command-line tool that the README describes as a friendlier ss / netstat for humans, offering a live terminal UI plus styled tables and JSON or CSV output for inspecting network connections.

### How do I install snitch?

The README lists Homebrew (brew install snitch), go install github.com/karol-broda/snitch@latest, nixpkgs, the AUR package snitch-bin, a shell install script, prebuilt release archives and OCI images on ghcr.io.

### Does snitch need root or special network capabilities?

The README states that CAP_NET_ADMIN and CAP_NET_RAW are not required because snitch reads from /proc/net/*. Process names and PIDs in a container do require --pid=host and --cap-add=SYS_PTRACE.

### Can snitch output be parsed by scripts?

Yes. The README documents snitch ls -p for plain output, snitch ls -o json and snitch ls -o csv, a dedicated snitch json subcommand, and snitch watch, which streams JSON frames at an interval.

### How do I upgrade snitch?

The README documents snitch upgrade to check for updates, snitch upgrade --yes to upgrade automatically, and snitch upgrade -v 0.1.7 to install a specific version.

## Sources

- [Issues](https://github.com/karol-broda/snitch/issues)
- [karol-broda/snitch on GitHub](https://github.com/karol-broda/snitch)
- [License: MIT](https://github.com/karol-broda/snitch/blob/master/LICENSE)
- [README](https://github.com/karol-broda/snitch/blob/master/README.md)
- [Releases](https://github.com/karol-broda/snitch/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/karol-broda-snitch