DEV Community

QuantumCat
QuantumCat

Posted on

The Polish Pass — I Rewrote My Three Beginner Scripts to Match the App They Became

#python #cybersecurity #beginners #opensource

A few weeks ago I wrote about turning three beginner Python scripts — a connection monitor, a port scanner, and a snapshot reporter — into the QuantumCat SOC Toolkit, a desktop app with a real installer and a local AI analyst.

There was a loose end, and it itched.

The app had moved on. The GitHub repos hadn't. Anyone who clicked through from the toolkit to the original scripts still landed on the May 2026 versions: the monitor that didn't run, the scanner that couldn't say "closed," the process check that flagged "sync" for containing "nc." The repos are the front door to the whole project — they should show what the code learned, not just where it started.

So: a polish pass. All three scripts, upgraded to the same standard as the shipped toolkit. Same repos, same honesty rules.

The monitor: 57 lines → 373

The original net_watch.py polled ss -tun every 3 seconds and diffed the output. It also had a syntax error on line 19, tagged the local endpoint instead of the peer, and decided "private" by string prefix — which silently misses the entire 172.16.0.0/12 private range.

The rewrite:

  • Events are keyed on the peer endpoint — the address your machine is actually talking to, which is the only one a watcher cares about.
  • Real IP classification via the ipaddress module: full RFC1918 (10/8, 172.16/12, 192.168/16), loopback, link-local, IPv6 ULA, and CGNAT space (100.64/10) — the range that taught me a failing test is a gift.
  • Cross-platform collection with psutil, because Windows has no ss and the toolkit's users are mostly on Windows now.
  • A silent baseline on the first poll, so startup doesn't dump every existing connection on you as if it were news.
  • Proper structure: a ConnectionTracker that owns the diffing, a top-talkers count, and clean process name (pid) labels on events.

It went from "script I run in a terminal" to the actual engine the Monitor tab runs. Same job, done properly.

The port scanner: ~21 lines → 253

The original prompted for an IP and walked 11 ports one at a time with a 1-second timeout, printing only the open ones. A full sweep could take eleven seconds of pure waiting, and silence meant… something. Closed and filtered are different answers; the original couldn't give either.

The rewrite:

  • Threaded — 32 workers, so a sweep is a sweep, not a coffee break.
  • 25 well-known ports with service names, because "443" means less to a learner than "443 — HTTPS."
  • Three distinct states: open, closed, filtered. All three get reported.
  • Optional --banner grab — reads what a service volunteers when you connect, nothing more. Passive, and labelled as such.
  • Input validation that explains itself instead of tracebacking at you.

Still standard library only. That was a rule from the start and it survived the rewrite.

The snapshot report: ~81 lines → 440

The original shelled out through os.popen and wrote a timestamped triage report. The soul was right — one file you can hand to a human — but the flagged-process check was a substring search, which is how "sync" ended up on a watchlist for containing the letters "nc."

The rewrite:

  • psutil-based sections throughout, with a computed connection summary instead of raw dumps.
  • The flagged-process check now compares exact process names against a short list of known dual-use tools (nc, ncat, socat, nmap, masscan, hydra, tcpdump, and friends). Exact match only. And it's still labelled in plain sight as the basic heuristic it is — a hint to go look, never a detection claim.
  • Every section degrades gracefully: if a data source isn't available, the report says "(unavailable)" and keeps going instead of dying halfway down the page.
  • Reports still land as timestamped files, same as the original — that part never needed fixing.

What I deliberately did not change

The git history.

The broken first commits are still there — the missing parenthesis, the misindented if, all of it. The new code sits on top as new commits, and the READMEs now tell both stories: what the script was in May 2026, and what the polish pass changed and why. Rewriting history to look like I knew what I was doing from day one would be a lie, and it would delete the most useful part for anyone learning behind me: the evidence that the embarrassing version is a normal place to start.

The READMEs got the same treatment as the code — rewritten to match what the scripts actually do now, bugs described in the past tense, "Updated" sections that say plainly what changed.

And yes, everything got tested before it got committed: the monitor catching a live loopback connection, the scanner against localhost with a real banner grab, the snapshot flagging an nc-named process on purpose. Lesson zero from the first article still runs the shop: run the thing you ship.

Why bother polishing free scripts?

Because the repos are where people decide whether the toolkit is worth twelve dollars. A front door that says "this code is broken and I never fixed it" argues against the app behind it. Now the free scripts and the paid app are the same standard of work — the app just adds the GUI, the analyst, and the installer.

If you're learning this stuff the way I did: keep your first versions. Commit the broken ones. Then, when you know more, go back and do the polish pass in public. The diff between who you were and who you're becoming is the best documentation you'll ever write.

Links

Top comments (0)