porthole

module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 14, 2026 License: MIT

README

porthole

A port kill switch and service viewer for your terminal.

See what is listening, know which project owns it, kill it in one keystroke — from an animated TUI or a scriptable CLI, backed by the same engine.

porthole                 # launch the interactive TUI
porthole list             # table to stdout
porthole kill 3000        # SIGTERM, escalate after 2s

Install

go install github.com/subh05sus/porthole/cmd/porthole@latest

Prebuilt binaries, a Homebrew tap, and a Scoop bucket are planned (see .goreleaser.yaml and install.sh) but not published yet — go install is the only way to get porthole today.

Status: pre-release, under active development.

Directories

Path Synopsis
cmd
porthole command
Command porthole is a port kill switch and service viewer for your terminal.
Command porthole is a port kill switch and service viewer for your terminal.
internal
cli
Package cli implements the porthole command tree.
Package cli implements the porthole command tree.
config
Package config loads porthole's optional ~/.porthole.yaml — protected ports (FUTURE_PLANS.md v1.3) plus a few display/behavior settings.
Package config loads porthole's optional ~/.porthole.yaml — protected ports (FUTURE_PLANS.md v1.3) plus a few display/behavior settings.
container
Package container talks to a local Docker-Engine-API-compatible daemon (Docker, Podman, OrbStack, Colima) to enrich scan results with container names/images and route kills through `docker stop` instead of signaling the docker-proxy PID directly.
Package container talks to a local Docker-Engine-API-compatible daemon (Docker, Podman, OrbStack, Colima) to enrich scan results with container names/images and route kills through `docker stop` instead of signaling the docker-proxy PID directly.
daemon
Package daemon implements `porthole daemon` — an auto-kill daemon that watches for services matching a user-authored allow-list and kills them.
Package daemon implements `porthole daemon` — an auto-kill daemon that watches for services matching a user-authored allow-list and kills them.
firewall
Package firewall manages a small, isolated set of firewall rules scoped to exactly what porthole already discovered in a scan — never arbitrary rules, CIDRs, or ports the user didn't already see.
Package firewall manages a small, isolated set of firewall rules scoped to exactly what porthole already discovered in a scan — never arbitrary rules, CIDRs, or ports the user didn't already see.
firewall/firewallfmt
Package firewallfmt parses `netsh advfirewall firewall show rule` output.
Package firewallfmt parses `netsh advfirewall firewall show rule` output.
firewall/firewalltest
Package firewalltest provides a scriptable firewall.Manager test double, mirroring scan/scantest, kill/killtest, and proc/proctest.
Package firewalltest provides a scriptable firewall.Manager test double, mirroring scan/scantest, kill/killtest, and proc/proctest.
history
Package history implements FUTURE_PLANS.md's "history" idea: a JSONL log of what porthole killed and when, so "wait, did I kill that" has an answer.
Package history implements FUTURE_PLANS.md's "history" idea: a JSONL log of what porthole killed and when, so "wait, did I kill that" has an answer.
kill
Package kill implements the OS-agnostic kill ladder: verify the target is still the process we scanned, signal it, wait, and escalate.
Package kill implements the OS-agnostic kill ladder: verify the target is still the process we scanned, signal it, wait, and escalate.
kill/killtest
Package killtest provides a scriptable kill.Killer test double so CLI and TUI code can be tested without a real operating system.
Package killtest provides a scriptable kill.Killer test double so CLI and TUI code can be tested without a real operating system.
notify
Package notify sends best-effort desktop notifications for watch mode's --notify flag, by shelling out to whatever native notifier tool the OS already ships rather than adding a notification library dependency.
Package notify sends best-effort desktop notifications for watch mode's --notify flag, by shelling out to whatever native notifier tool the OS already ships rather than adding a notification library dependency.
output
Package output renders []scan.Service for the CLI: a plain table for humans and JSON for scripts.
Package output renders []scan.Service for the CLI: a plain table for humans and JSON for scripts.
proc
Package proc resolves per-process metadata (name, cmdline, cwd, user, start time) for a PID discovered by internal/scan.
Package proc resolves per-process metadata (name, cmdline, cwd, user, start time) for a PID discovered by internal/scan.
proc/proctest
Package proctest provides a scriptable proc.Lookup test double, mirroring scan/scantest and kill/killtest.
Package proctest provides a scriptable proc.Lookup test double, mirroring scan/scantest and kill/killtest.
project
Package project resolves a project name from a process's working directory — the thing PRD.md calls out as porthole's actual differentiator: "node on port 3000" is useless, "zapmail-web on port 3000" is the answer you wanted.
Package project resolves a project name from a process's working directory — the thing PRD.md calls out as porthole's actual differentiator: "node on port 3000" is useless, "zapmail-web on port 3000" is the answer you wanted.
restart
Package restart implements PRD's v1.2 feature (FUTURE_PLANS.md): kill a process and immediately respawn it with the same command line, working directory, and environment.
Package restart implements PRD's v1.2 feature (FUTURE_PLANS.md): kill a process and immediately respawn it with the same command line, working directory, and environment.
restart/restarttest
Package restarttest provides a scriptable restart.Spawner test double, mirroring scan/scantest and kill/killtest — necessary because the real Spawner actually launches a new OS process.
Package restarttest provides a scriptable restart.Spawner test double, mirroring scan/scantest and kill/killtest — necessary because the real Spawner actually launches a new OS process.
scan
Package scan discovers listening network sockets and the processes behind them.
Package scan discovers listening network sockets and the processes behind them.
scan/lsoffmt
Package lsoffmt parses macOS lsof/ps text formats.
Package lsoffmt parses macOS lsof/ps text formats.
scan/procfmt
Package procfmt parses Linux /proc text formats.
Package procfmt parses Linux /proc text formats.
scan/scantest
Package scantest provides a scriptable scan.Lister test double so that every layer above the OS boundary (CLI, TUI, watch engine) can be tested without a real operating system.
Package scantest provides a scriptable scan.Lister test double so that every layer above the OS boundary (CLI, TUI, watch engine) can be tested without a real operating system.
tui
Package tui implements porthole's interactive Bubble Tea interface.
Package tui implements porthole's interactive Bubble Tea interface.
tui/anim
Package anim holds pure animation math for the TUI: no bubbletea dependency, no wall-clock reads of its own — every function takes elapsed time as a parameter, so it's fully deterministic and testable.
Package anim holds pure animation math for the TUI: no bubbletea dependency, no wall-clock reads of its own — every function takes elapsed time as a parameter, so it's fully deterministic and testable.
tui/theme
Package theme centralizes every lipgloss style the TUI uses, resolved once at startup so the rest of the TUI never has to think about color degradation itself.
Package theme centralizes every lipgloss style the TUI uses, resolved once at startup so the rest of the TUI never has to think about color degradation itself.
webui
Package webui implements `porthole serve`'s optional local web dashboard: a small stdlib net/http server exposing the scan/kill loop as a JSON API plus one embedded HTML/JS page.
Package webui implements `porthole serve`'s optional local web dashboard: a small stdlib net/http server exposing the scan/kill loop as a JSON API plus one embedded HTML/JS page.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL