port killer - Moses Yebei

Abstract

A powerful cross-platform port management tool for developers. Monitor ports, manage Kubernetes port forwards, integrate Cloudflare Tunnels, and kill processes with one click.

The Problem

Developers frequently need to locate, inspect, and terminate stray network listeners—especially when juggling local services, Kubernetes port‑forwards, or Cloudflare tunnels. Manually hunting PIDs, handling cross‑platform quirks, and keeping UI feedback in sync is error‑prone and time‑consuming.

What This Does

Port‑Killer provides a native UI for macOS (Swift) and Windows (C#) plus a lightweight Linux CLI. The CLI entry point is platforms/linux/src/main.py; it loads configuration (config.py), discovers ports via scanner.py, and delegates actions to service modules (services/clipboard.py, services/cloudflare.py, services/k8s.py). On macOS the UI layer lives under platforms/macos/Sources/, with PortKillerApp.swift bootstrapping the app and wiring view models (e.g., PortForwardManager.swift) to the core Rust library (portkiller-core/src/lib.rs). The Windows solution is a WPF app anchored at platforms/windows/PortKiller/App.xaml.cs.

How It Is Wired

Linux CLI – Execution starts in platforms/linux/src/main.py. - Imports config, scanner, and UI helpers (ui/tray.py, ui/window.py). - main() calls scanner.scan_ports() (defined in scanner.py) which returns a list of PortInfo objects. - Selected actions invoke service functions: services/k8s.start_forward(), services/cloudflare.list_tunnels(), or services/clipboard.copy(). - UI updates are sent through the tray or window modules, which each import up to seven other UI helpers (e.g., ui/tray.py imports dialog, styles, and window).

macOS App – The binary entry point is PortKillerApp.swift. - Instantiates AppState (multiple extensions add auto‑refresh, favorites, etc.). - AppState holds references to manager classes (PortForwardManager, KubernetesDiscoveryManager, NamedTunnelManager). - Each manager calls into the Rust core via the portkiller-core crate (src/lib.rs). The Rust library exposes a C‑ABI bridge used by Swift through generated headers. - UI views (Views/*) observe manager publishers; the most connected view is Views/CloudflareTunnels/NamedTunnelDetailView.swift (57 levels of nesting reported).

Windows App – App.xaml.cs creates the main window, loads XAML resources, and calls into the same service layer (services/*.cs) that mirrors the Linux Python logic.

No circular import cycles were detected; the highest fan‑in module is platforms/linux/src/config.py (imports from four other modules, no outward imports).

How To Use It

# Clone the repo
git clone https://github.com/moses-y/port-killer
cd port-killer

# Linux – install Python deps (no lockfile, see health notes)
pip install -r requirements.txt   # requirements.txt not present; install manually if needed

# Run the CLI
python platforms/linux/src/main.py   # starts scanner and UI tray

# macOS – build the app
cd platforms/macos
swift build -c release            # uses Package.swift; produces a .app bundle

# Windows – open the solution
start platforms/windows/PortKiller.sln   # build in Visual Studio 2022

Configuration lives in platforms/linux/src/config.py (Python dict) and in the macOS Swift AppState extensions. No environment variables are required out of the box.

Real‑World Use

A backend engineer runs the CLI on a CI worker to ensure no stray ports remain after integration tests:

python platforms/linux/src/main.py --kill --filter "port==8080"

The command scans, matches the test server’s port, and issues a graceful then forced termination, preventing port‑collision failures in subsequent pipeline stages.

Code Health & Issues

Static analysis findings (30 high, 75 medium, 0 low):

Broad exception handling (2 files): platforms/linux/src/services/cloudflare.py, platforms/linux/src/ui/dialogs.py.
Deep nesting (57 occurrences): e.g., platforms/macos/Sources/Views/CloudflareTunnels/NamedTunnelDetailView.swift.
Duplicated code blocks (repeated 99 × 6‑line fragments across ~40 files).

Code‑health audit (9 findings):

HIGH – Pin GitHub Actions to commit SHA (.github/workflows/*).
HIGH – Release workflow pushes directly to main (.github/workflows/release.yml).
MEDIUM – No least‑privilege GITHUB_TOKEN permissions (.github/workflows/ci-linux.yml).
MEDIUM – No Dependabot/Renovate configuration.
MEDIUM – No dependency‑vulnerability gate in CI.
MEDIUM – Checkout step keeps credentials; should set persist-credentials: false.
MEDIUM – Test coverage low (5 tests vs. 195 source files).
LOW – No job timeouts in CI workflows.
LOW – Missing repo convention files (.editorconfig, formatter config, etc.).

Additional hygiene notes: CI present, licence MIT, no lockfile for package.json, no Dockerfile, no committed secrets.

The Bottom Line

Port‑Killer delivers a functional cross‑platform port‑management UI with a solid core written in Rust, but the codebase suffers from deep nesting, duplicated logic, and limited test coverage. The CI pipeline needs hardening (pinned actions, proper token scopes, dependency scanning). It is suitable for teams that can invest in refactoring and CI improvements while gaining immediate UI‑driven port control.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

235 files

Swift154
C#20
Python15
Rust6
YAML5
Markdown4

React

Module dependencies

The 10 most depended-upon modules of 15, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_platforms_linux_src_config["config"] n1_platforms_linux_src_scanner["scanner"] n2_linux_src_services_clipboard["clipboard"] n3_inux_src_services_cloudflare["cloudflare"] n4_forms_linux_src_services_k8s["k8s"] n5_platforms_linux_src_ui_tray["tray"] n6_latforms_linux_src_ui_window["window"] n7_atforms_linux_src_ui_dialogs["dialogs"] n8_platforms_linux_src_main["main"] n9_platforms_linux_port_killer["port-killer"] n8_platforms_linux_src_main --> n0_platforms_linux_src_config n8_platforms_linux_src_main --> n5_platforms_linux_src_ui_tray n7_atforms_linux_src_ui_dialogs --> n0_platforms_linux_src_config n5_platforms_linux_src_ui_tray --> n7_atforms_linux_src_ui_dialogs n5_platforms_linux_src_ui_tray --> n6_latforms_linux_src_ui_window n5_platforms_linux_src_ui_tray --> n1_platforms_linux_src_scanner n5_platforms_linux_src_ui_tray --> n3_inux_src_services_cloudflare n5_platforms_linux_src_ui_tray --> n4_forms_linux_src_services_k8s n5_platforms_linux_src_ui_tray --> n2_linux_src_services_clipboard n5_platforms_linux_src_ui_tray --> n0_platforms_linux_src_config n6_latforms_linux_src_ui_window --> n0_platforms_linux_src_config n6_latforms_linux_src_ui_window --> n1_platforms_linux_src_scanner n6_latforms_linux_src_ui_window --> n3_inux_src_services_cloudflare n6_latforms_linux_src_ui_window --> n4_forms_linux_src_services_k8s n6_latforms_linux_src_ui_window --> n2_linux_src_services_clipboard

Findings

LowDependencies declared without a lockfile - non-reproducible builds package.json

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium5

low2

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

dtolnay/rust-toolchain@stable, maxim-lobanov/setup-xcode@v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/release.yml

git push origin main

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/ci-linux.yml

2 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci-linux.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Expand the test suite; it cannot cover this codebasemedium5 occurrences

5 test files against 195 source files (ratio 0.026)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/ci-linux.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.