NetOrbit

Real-time global packet visualization in your terminal.

Scapy packet capture · Textual/Rich terminal aesthetic · Braille world map · live GeoIP telemetry

---

English • Русский

English

Why NetOrbit?

NetOrbit turns raw outbound IPv4 traffic into visual intelligence. Every external packet becomes a signal on a terminal-native world map: where your machine is talking, how fast destinations appear, and what routes light up while you work.

It is built for people who want network awareness without leaving the shell. No browser dashboard. No heavy desktop UI. Just a cyberpunk command center running directly in your terminal.

• Visual intelligence: watch outbound connections land on a global map instead of reading dead packet logs.
• Real-time tracking: Scapy captures traffic asynchronously while the TUI keeps rendering.
• Pure terminal aesthetics: high-density Braille pixels, neon-style traces, and Rich-powered panels.
• Low CPU footprint: static map caching keeps warm renders fast, measured at 0.0044s.

[!IMPORTANT] Root is required because NetOrbit captures packets through Scapy. On Linux, NetOrbit can also re-run itself through sudo when capture privileges are missing.

Quick Start

# Install
pipx install git+https://github.com/ZXCurban/NetOrbit.git

# Run live capture
sudo netorbit

---

[!NOTE] Note for Nix users: Due to internal privilege management and Scapy's need for raw socket access, please run the application using this command (works on any Linux distro with Nix installed):

sudo nix --extra-experimental-features "nix-command flakes" run github:ZXCurban/NetOrbit

---

Need to inspect available network interfaces first?

netorbit --list-interfaces

Want the visual experience without root or real traffic?

netorbit --demo
netorbit --demo --green

Force a specific interface or a VPN + default-route pair:

sudo netorbit -i tun0,wlo1

Run with a different color theme:

sudo netorbit --green
sudo netorbit --red
sudo netorbit --violet

Key Features

• Braille-rendered world map with dense terminal pixels and a coordinate grid.
• Sub-pixel accuracy through a virtual 2x4 Braille dot layer.
• Async Scapy sniffing for live outbound IPv4 capture without blocking the UI.
• GeoIP resolution via MaxMind-compatible workflows and IP-API fallback.
• Live destination traces from your home point to remote IP locations.
• Recent connection panel with IP, country, protocol, size, and interface data.
• Smart filtering for local, private, multicast, and broadcast addresses.
• Low CPU footprint with cached static map layers and 0.0044s warm render.

Tech Stack

Layer	Technology
Runtime	Python 3.10+
Terminal UI	Textual/Rich terminal aesthetic, implemented with Rich rendering
Packet capture	Scapy AsyncSniffer
Geolocation	MaxMind-ready architecture / IP-API
Rendering	Braille canvas, cached world mask, sub-pixel trajectories

Commands

netorbit --help
netorbit --list-interfaces
netorbit --demo
netorbit --demo --green
sudo netorbit
sudo netorbit --red
sudo netorbit --violet
sudo netorbit -i eth0
sudo netorbit -i tun0,wlo1

How It Works

1. NetOrbit detects one or more capture interfaces from your routing table.
2. Scapy streams outbound IPv4 packets into an async pipeline.
3. Local and non-routable destinations are filtered out.
4. GeoIP lookup resolves remote IPs to latitude, longitude, country, and city.
5. The renderer projects coordinates onto a cached Braille world map.
6. Rich updates the terminal with active traces and recent connection telemetry.

Requirements

• Linux recommended, Fedora supported.
• Python 3.10+.
• pipx for clean CLI installation.
• Root privileges for real packet capture.

Contributors

Special thanks to these people for making NetOrbit better:

• DiVan2000 - Added Nix/NixOS support and Flake packaging.

---

Русский

Почему NetOrbit?

NetOrbit превращает исходящий IPv4-трафик в визуальную разведку. Каждый внешний пакет становится сигналом на терминальной карте мира: куда говорит ваша машина, какие направления вспыхивают в реальном времени и как выглядит сеть прямо из shell.

Это инструмент для тех, кому нужна сетевая осведомленность без браузерных панелей и тяжелого UI. Только терминал, живая карта и киберпанковский командный центр в одну команду.

• Визуальная разведка: внешние соединения видны на карте, а не теряются в сухих логах.
• Отслеживание в реальном времени: Scapy асинхронно ловит пакеты, пока TUI продолжает рендеринг.
• Чистая терминальная эстетика: плотные Braille-пиксели, неоновые трассы и панели на Rich.
• Низкая нагрузка на CPU: кэш статической карты дает быстрый теплый рендер, измерено 0.0044s.

[!IMPORTANT] Root нужен потому, что NetOrbit захватывает пакеты через Scapy. На Linux приложение также может автоматически перезапуститься через sudo, если прав для захвата не хватает.

Быстрый старт

# Установка
pipx install git+https://github.com/ZXCurban/NetOrbit.git

# Запуск live-захвата
sudo netorbit

---

[!NOTE] Заметка для пользователей Nix: Из-за особенностей управления правами доступа и необходимости Scapy в доступе к сырым сокетам (raw sockets), пожалуйста, запускайте приложение с помощью этой команды (работает на любом Linux-дистрибутиве с установленным Nix):

sudo nix --extra-experimental-features "nix-command flakes" run github:ZXCurban/NetOrbit

---

Посмотреть доступные сетевые интерфейсы:

netorbit --list-interfaces

Запустить визуальный режим без root и реального трафика:

netorbit --demo
netorbit --demo --green

Принудительно выбрать интерфейс или пару VPN + default-route:

sudo netorbit -i tun0,wlo1

Запустить с другой цветовой темой:

sudo netorbit --green
sudo netorbit --red
sudo netorbit --violet

Ключевые возможности

• Карта мира на Braille с плотной терминальной графикой и координатной сеткой.
• Sub-pixel accuracy через виртуальный слой Braille 2x4 точек.
• Асинхронный Scapy-sniffing для live-захвата исходящих IPv4-пакетов без блокировки UI.
• GeoIP-резолвинг с архитектурой под MaxMind и fallback через IP-API.
• Живые трассы назначений от вашей home-точки к удаленным IP.
• Панель последних соединений с IP, страной, протоколом, размером и интерфейсом.
• Умная фильтрация локальных, приватных, multicast и broadcast-адресов.
• Низкая нагрузка на CPU благодаря кэшу статических слоев карты и 0.0044s warm render.

Технологический стек

Слой	Технология
Runtime	Python 3.10+
Terminal UI	Textual/Rich terminal aesthetic, implemented with Rich rendering
Захват пакетов	Scapy AsyncSniffer
Геолокация	MaxMind-ready architecture / IP-API
Рендеринг	Braille canvas, cached world mask, sub-pixel trajectories

Команды

netorbit --help
netorbit --list-interfaces
netorbit --demo
netorbit --demo --green
sudo netorbit
sudo netorbit --red
sudo netorbit --violet
sudo netorbit -i eth0
sudo netorbit -i tun0,wlo1

Как это работает

1. NetOrbit определяет один или несколько интерфейсов захвата по таблице маршрутизации.
2. Scapy передает исходящие IPv4-пакеты в асинхронный pipeline.
3. Локальные и неротируемые адреса отфильтровываются.
4. GeoIP lookup превращает удаленный IP в широту, долготу, страну и город.
5. Рендерер проецирует координаты на кэшированную Braille-карту мира.
6. Rich обновляет терминал активными трассами и телеметрией последних соединений.

Требования

• Рекомендуется Linux, Fedora поддерживается.
• Python 3.10+.
• pipx для чистой CLI-установки.
• Root-доступ для реального захвата пакетов.

Контрибьюторы

Особая благодарность тем, кто помогает развивать проект:

• DiVan2000 - добавил поддержку Nix/NixOS и упаковку в Flake.