Net Engine v1.2.1

A modern desktop network toolkit with an embedded terminal, multi-session SSH client, file transfer, network adapter configurator, and a fully-local AI assistant. Built with Python + PyQt6 — pure Python, no native extensions. Runs natively on macOS, Windows, and Linux.

Download

Platform	Artifact	Built by
Windows	`NetEngine-<ver>-Windows.exe` (one-file)	`scripts\build_windows.bat`
macOS	`NetEngine-<ver>-macOS.dmg` (~41 MB)	`scripts/build_macos.sh`
Linux	`NetEngine-<ver>-Linux-x86_64.AppImage`	`scripts/build_linux.sh`
Linux	`netengine_<ver>_amd64.deb`	`scripts/build_linux.sh deb`

Each platform's installer must be built on that platform — PyInstaller is not a cross-compiler. See docs/RELEASE.md for full build instructions.

Or run from source — see Setup.

Changelog

v1.2.1 — 2026-06-26

Reliable LAN host/MAC discovery — the scanner now performs an active ARP sweep (a UDP probe per host that forces kernel ARP resolution) before reading the ARP table, so hosts that drop ICMP and every TCP probe — a Mac in firewall stealth mode is the classic case — are still discovered. A /24 that previously surfaced ~8 hosts now reliably finds every device on the subnet.
Fixed intermittent blank MAC columns — get_arp_cache() now uses arp -an (numeric); the old arp -a did a reverse-DNS lookup per entry that on a busy subnet ran ~5 s, hit the subprocess timeout, and returned an empty cache — blanking every MAC. Lookup is now ~5 ms.
Scanner host's own interface MAC is now filled in (the OS keeps no ARP entry for its own address).
Verified deterministic: 8 consecutive /24 scans found the identical host set with 100% MAC coverage.
Project cleanup — three PyInstaller specs merged into one platform-parametrized NetEngine.spec; .gitignore added (build artifacts no longer tracked); build/release docs moved to docs/; new STRUCTURE.md.

v1.2.0 — 2026-05-25

macOS and Linux packaging — .dmg for macOS, .AppImage and .deb for Linux, alongside the existing Windows .exe
Cross-platform core — primary development moved to macOS; Windows and Linux remain first-class targets
Platform-correct user data directories via new utils/paths.py:
- macOS: ~/Library/Application Support/Net Engine/
- Windows: %APPDATA%\NetEngine\
- Linux: $XDG_CONFIG_HOME/netengine/ (default ~/.config/netengine/)
- Legacy ~/.netscope/ data is auto-migrated on first launch (non-destructive copy)
Native font fallback chains (gui/platform_fonts.py) — SF Pro / SF Mono on macOS, Segoe UI / Cascadia on Windows, Inter / JetBrains Mono on Linux
Scanner MAC accuracy fix on macOS — short-form MACs from arp -a (e.g. c:e8:5c:68:c6:4) are now normalised, fixing vendor lookup for ~half of all hosts
TCP fallback ping is now ~7× faster on macOS
Assistant tab crash fixed on Windows

v1.1.0 — 2026-05-20

Portable single-file exe rebuilt — 42.7 MB (was 675 MB, 94% smaller)
Startup time down from 20–60 s to ~3 s
Lazy page initialization — only the Scanner loads at startup, all other pages init on first visit
DNS thread pool now created on first scan instead of at import time
Splash screen shown before main window construction for instant visual feedback
File Transfer page added (SCP workspace)
Tools tab removed from sidebar
About page redesigned as a 4-column feature card grid
Help page rewritten with clearer setup guides
AI assistant: improved intent parsing, safety policy, automation service

Features

Scanner

Concurrent ping sweep across any subnet — reverse-DNS, ARP/MAC vendor lookup, OS hint from TTL, configurable TCP port scan, sortable and filterable results table, CSV/JSON export, persistent scan history (last 20 scans).

Host details drawer — click any row to open a right-side panel with quick actions, host info, and an inline SSH connect form.

Terminal

Full in-app terminal with selectable shell backend (PowerShell, CMD, WSL on Windows; bash on Linux/macOS). Supports command history, built-in cd / clear / cls, Ctrl+C / Ctrl+L.

SSH Sessions

Multi-tab SSH client with collapsible connection form, saved-session manager (search + pin + last-connected), quick connect bar (user@host:port), per-tab status indicators, session duplication, and rename via double-click on the tab.

File Transfer

SCP-based file transfer workspace integrated with the SSH session manager. Browse remote directories and move files without leaving the app.

Network Adapter (Windows)

View current IPv4 settings, manage saved IP profiles, and switch between DHCP and static (address / mask / gateway / DNS) using netsh. Requires Administrator to apply changes.

Monitor

Live multi-target ping monitor and one-shot port tester with real-time latency graphs.

API Console

Built-in REST client with Basic / Bearer auth, custom headers, request body, save/load named requests, and cURL import/export.

Local AI Assistant

Optional, fully-local assistant powered by Ollama. Two modes:

Command — plain-English → one suggested shell command, with explanation and optional caution. Copy or Insert-into-Terminal. Never auto-executed.
Chat — streaming free-form help: ask about scan results, interpret terminal / SSH output, or explain a feature. History is bounded to the last ~10 exchanges.

Send with Ctrl+Enter. Stop cancels an in-flight response.

Nothing in this feature talks to the cloud — see Local AI (Ollama).

Theme System

Four built-in themes (Dark, Neon, Space, Glass) switchable from View → Theme or the Settings page. Choice is persisted automatically.

Setup

Requires Python 3.10+.

python -m pip install -r requirements.txt
python main.py

On Windows, double-click run.bat. For network-adapter changes launch with run-admin.bat (UAC prompt).

On macOS / Linux, run python main.py directly. Both platforms use the system's native shell (bash / zsh) for the embedded terminal.

Dependencies

Package	Why
PyQt6	Desktop UI
psutil	Network interface enumeration + live system metrics
paramiko	SSH / SCP transport
requests	Built-in API console
pyserial	Serial port utilities

Local AI (Ollama)

The Assistant page is fully optional. If Ollama is not installed or not running the rest of the app works normally — the page shows a banner explaining what to fix. No data leaves the machine. Every inference runs locally through an Ollama daemon on localhost:11434.

1. Install Ollama

Windows / macOS — install the Ollama Desktop app from https://ollama.com.
Linux — curl -fsSL https://ollama.com/install.sh | sh, then ollama serve.

2. Pull a model

ollama pull llama3.2:3b

llama3.2:3b is the default. Any instruct/chat model works — change the name in Settings after pulling it.

Model	Size	Notes
`llama3.2:1b`	~1.3 GB	Fastest, lowest quality
`llama3.2:3b`	~2.0 GB	Default — good balance on a laptop
`qwen2.5:3b`	~1.9 GB	Strong reasoning for the size
`phi3:mini`	~2.3 GB	Great at short factual answers

3. Open the Assistant tab

Launch Net Engine, open Assistant from the sidebar (or Ctrl+8), pick a mode, and start typing. Use Ctrl+Enter to send.

4. Configuration

Settings live in ~/.netscope/settings.json under the ai key:

{
  "ai": {
    "enabled": true,
    "base_url": "http://localhost:11434",
    "model": "llama3.2:3b",
    "command_model": "",
    "timeout": 60,
    "temperature": 0.3,
    "max_tokens": 512,
    "system_hint": ""
  }
}

model — main chat model.
command_model — optional separate model for command suggestions (leave empty to reuse model).
timeout — per-request timeout in seconds; increase for large models on first load.
system_hint — text appended to every system prompt (e.g. "I use WSL Ubuntu").

Privacy

The ai/ package only talks to localhost:11434.
No telemetry, no cloud API, no hosted endpoint.
Prompts and responses never leave your machine.

Keyboard shortcuts

Shortcut	Action
`F5`	Start scan
`Esc`	Stop scan
`Ctrl+E`	Export results
`Ctrl+B`	Toggle sidebar
`Ctrl+,`	Settings
`Ctrl+1`	Scanner
`Ctrl+2`	Terminal
`Ctrl+3`	SSH Sessions
`Ctrl+4`	File Transfer
`Ctrl+5`	Network Adapter
`Ctrl+6`	Monitor
`Ctrl+7`	API Console
`Ctrl+8`	AI Assistant
`Ctrl+9`	Settings
`F1`	Help
`Ctrl+Enter`	Send AI prompt (in Assistant)
`Ctrl+L`	Clear embedded terminal
`Ctrl+C`	Cancel running terminal command
`Ctrl+Q`	Quit

Project layout

NetEngine/
├── main.py                        Entry point
├── run.bat                        Launcher (Windows)
├── run-admin.bat                  Launcher with elevation (UAC)
├── requirements.txt
├── NetEngine.spec                 Unified PyInstaller spec (Win/macOS/Linux)
├── create_icon.py                 Generates .ico / .png / .icns
├── STRUCTURE.md                   Directory-by-directory map of the repo
├── docs/
│   ├── BUILD.md                   Build notes
│   └── RELEASE.md                 Cross-platform build / release guide
├── scripts/
│   ├── build_windows.bat          → Windows .exe
│   ├── build_macos.sh             → macOS .dmg
│   └── build_linux.sh             → Linux .AppImage / .deb
├── packaging/
│   └── linux/                     AppRun, .desktop, debian/control template
├── gui/
│   ├── themes.py                  Theme palette + ThemeManager + QSS builder
│   ├── main_window.py             Sidebar + stacked pages (lazy init)
│   ├── dialogs.py                 PortScan, Export, About dialogs
│   ├── motion.py                  Global animation / interaction system
│   └── components/
│       ├── sidebar.py
│       ├── loading_screen.py      Boot-sequence splash
│       ├── scanner_view.py
│       ├── scan_toolbar.py
│       ├── host_table.py
│       ├── detail_panel.py        Host details drawer
│       ├── terminal_view.py
│       ├── terminal_widget.py     Embedded terminal control
│       ├── collapsible.py         Collapsible section helper
│       ├── ssh_view.py            Multi-session SSH workspace
│       ├── ssh_session_tab.py     One SSH session = one tab
│       ├── file_transfer_view.py  SCP file transfer workspace
│       ├── monitor_view.py        Multi-ping monitor + port tester
│       ├── api_console_view.py    Built-in REST client
│       ├── network_config_view.py Windows netsh adapter config
│       ├── assistant_view.py      Local AI assistant (Ollama)
│       ├── settings_view.py       App settings UI
│       ├── help_view.py           Help page
│       ├── about_view.py          About / credits
│       └── app_status_bar.py      Live CPU/MEM status bar
├── ai/
│   ├── ollama_client.py           HTTP client, no Qt imports
│   ├── model_config.py            AI config (~/.netscope/settings.json)
│   ├── prompts.py                 Centralized system prompts
│   ├── command_assistant.py       One-shot command suggestion + parser
│   ├── chat_assistant.py          Bounded-history chat
│   └── ai_service.py              Facade + AIStatus + QThread workers
├── scanner/
│   ├── network.py                 Interface enumeration, ARP, IP range
│   ├── host_scanner.py            Ping/DNS/MAC pipeline + ScanController
│   ├── live_ping.py               Continuous ping worker (Monitor page)
│   ├── port_scanner.py            TCP connect scanner
│   ├── service_mapper.py          Port to service name + presets
│   ├── fingerprint.py             OUI vendor table + OS hint from TTL
│   ├── ssh_client.py              paramiko-based SSH session
│   ├── scp_transfer.py            SCP file transfer helpers
│   └── net_config.py              Windows netsh adapter helper
└── utils/
    ├── paths.py                   Platform-correct user data directory
    ├── export.py                  CSV / JSON export
    ├── history.py                 Scan history persistence
    └── settings.py                Theme + saved sessions + IP profiles

OS-specific notes

macOS is the primary development platform. Scanner, terminal, SSH, file transfer, monitor, API console, and AI assistant all work natively. Pings use ping -c 1, ARP cache via arp -a (with short-form MAC normalisation).
Windows remains a fully supported release target — pings use ping -n 1, ARP cache via arp -a, adapter configuration via netsh interface ipv4. Terminal supports PowerShell, CMD, and WSL backends.
Linux — scanner, terminal, SSH, and file transfer all work. The Network Adapter page shows a "Windows only" notice.
Admin privileges are only required for the Apply action on the Adapter page. Every other feature runs as a regular user.

Persistent state

Net Engine writes to the platform's standard user-data location:

OS	Settings + history
macOS	`~/Library/Application Support/Net Engine/`
Windows	`%APPDATA%\NetEngine\`
Linux	`$XDG_CONFIG_HOME/netengine/` (default `~/.config/netengine/`)

Inside that directory:

settings.json — active theme, saved SSH sessions (passwords not persisted unless opted in per session), saved IP profiles, saved API requests, terminal-shell preference, AI config.
history/scan_*.json — last 20 completed scans.

Legacy data in ~/.netscope/ (from v1.1.0 and earlier) is auto-migrated on first launch via a non-destructive copy; the original directory is left in place as a user-controlled backup.

Limitations

Embedded terminal is line-buffered. Not a full PTY — programs that expect a TTY (vim, top) should be launched via SSH instead.
The OUI vendor table is a hand-curated subset (~150 prefixes).
IPv6 is not in scope; the scanner is IPv4-only.
Network-adapter configuration is Windows only.
Local AI assistant requires a locally-running Ollama instance. No cloud fallback.

Name		Name	Last commit message	Last commit date
Latest commit History 44 Commits
.claude		.claude
ai		ai
assets		assets
docs		docs
gui		gui
landing		landing
packaging/linux		packaging/linux
scanner		scanner
scripts		scripts
tests		tests
utils		utils
.gitignore		.gitignore
NetEngine.spec		NetEngine.spec
README.md		README.md
STRUCTURE.md		STRUCTURE.md
create_icon.py		create_icon.py
main.py		main.py
requirements.txt		requirements.txt
run-admin.bat		run-admin.bat
run.bat		run.bat

Folders and files

Latest commit

History

Repository files navigation

Net Engine v1.2.1

Download

Changelog

v1.2.1 — 2026-06-26

v1.2.0 — 2026-05-25

v1.1.0 — 2026-05-20

Features

Scanner

Terminal

SSH Sessions

File Transfer

Network Adapter (Windows)

Monitor

API Console

Local AI Assistant

Theme System

Setup

Dependencies

Local AI (Ollama)

1. Install Ollama

2. Pull a model

3. Open the Assistant tab

4. Configuration

Privacy

Keyboard shortcuts

Project layout

OS-specific notes

Persistent state

Limitations

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages