anegio.com

ipchorus: See Who Your Computer Is Talking To from Your Terminal

· 822 words · 4 min read
tools
pythonnetworkingterminaltuiwhoisgeoiptcpdumppcaplinuxobservabilityipchorusprojects
On this page Table of Contents

Every so often I get curious about what my machine is actually talking to.

I’d open tcpdump, watch a wall of packets scroll past, and end up asking the same question:

“OK… but who is this IP?”

I’ve tried plenty of tools for this over the years. They all showed me how much, but never the picture I had in my head.

What I wanted was something that answered a different question:

Who is my computer actually talking to?

So I built ipchorus.

Open it, give it sudo, and in one screen you’ll immediately see every remote IP your machine is talking to, how much traffic is flowing in each direction, what kind of peer it is (public Internet, your LAN, multicast, loopback, and more), and who it belongs to.

It’s a small terminal network monitor for Linux. No daemon. No web UI. No database. Just one terminal window.

Install

The project uses uv for dependency management. If you don’t already have uv, install it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone the repository:

git clone https://github.com/aganet/ipchorus.git
cd ipchorus

Install the dependencies:

uv sync

Run it:

sudo .venv/bin/ipchorus

That’s it.

If you’d rather avoid running with sudo every time, grant the required capabilities once:

sudo setcap cap_net_raw,cap_net_admin=eip "$(realpath .venv/bin/python3)"

Then simply run:

uv run ipchorus

What you’ll see

Every row represents one remote IP, refreshed live.

For each connection you’ll see:

  • IP address
  • Hostname (or organization name if reverse DNS isn’t available)
  • Country (optional, via GeoLite2)
  • Connection type (Public, LAN, Multicast, Broadcast, Loopback, Link-local, etc.)
  • Incoming and outgoing bandwidth
  • Running traffic totals
  • Packet counts

Press Enter (or w) on any row to display detailed WHOIS/RDAP information, including:

  • ASN
  • Organization
  • Network name
  • CIDR
  • Registry
  • Country

Everything happens without leaving your terminal.

Why I built it

Tools like iftop, bandwhich, and nethogs already answer one question very well:

How much traffic is flowing?

I wanted something that answered a different one:

Who am I talking to?

Specifically, I wanted a tool that could:

  • Show every remote IP, sorted by traffic.
  • Resolve hostnames automatically.
  • Fall back to WHOIS organization names when reverse DNS isn’t available.
  • Clearly distinguish Internet traffic from LAN, multicast, broadcast, loopback, and link-local traffic.
  • Display country information.
  • Stay entirely inside the terminal.

So I made the simplest tool I could that does exactly those things.

Nothing more.

Things I’m quietly proud of

A few details make the interface feel calm instead of busy.

Intelligent hostname resolution

Whenever possible, ipchorus displays the reverse DNS hostname.

If a PTR record doesn’t exist, it quietly performs an RDAP lookup in the background and replaces the placeholder with the organization’s name.

That means anonymous cloud addresses suddenly become much easier to recognize.

Automatic network classification

Every connection is classified as one of:

  • Public
  • LAN
  • Link-local
  • Carrier-grade NAT
  • Multicast
  • Broadcast
  • Loopback
  • Reserved

Each category has its own colour, making local network chatter immediately distinguishable from Internet traffic.

Broadcast detection

At startup, ipchorus calculates the broadcast address for every interface.

Instead of treating subnet broadcasts as ordinary LAN hosts, traffic sent to those addresses is correctly identified and highlighted.

Optional GeoIP

If you download the free MaxMind GeoLite2 database, ipchorus displays country codes next to every public IP.

If you don’t, everything else works exactly the same.

No telemetry.

No online API requests.

Keyboard shortcuts

Key Action
↑ / ↓ Move between rows
Enter / w Show WHOIS/RDAP information
s Change sort column
r Reverse sort order
c Clear collected statistics
q Quit

Under the hood

The project is intentionally small.

The entire application currently fits in a single Python file of roughly 700 lines.

  • Scapy captures packets in a background thread.
  • Textual renders the terminal UI.
  • ipwhois performs RDAP lookups.
  • geoip2 reads the optional MaxMind database.
  • Reverse DNS is handled through a small cached thread pool.

That’s the entire architecture.

Give it a try

If you’ve ever looked at a packet capture and wondered:

“Who is this machine?”

give ipchorus a try.

It does one thing.

It shows you who’s on the other end of every connection your machine has open right now.

I tried very hard to make it do that one thing well, while keeping the code small, the interface simple, and the information easy to scan.

The project is open source under the MIT license. If you’d like to report an issue, suggest an improvement, or send a pull request, I’d be happy to hear from you.

Comments