multi-protocol IP scanner with modular chain architecture
bgscan is a terminal-based, multi-protocol network scanner written in Go. It probes IP addresses across ICMP, TCP, HTTP, DNS, Xray, and DNS tunneling (DNSTT, VayDNS, Slipstream, MasterDNS, StormDNS, TheFeed), and chains scan stages into pipelines, all through a keyboard-driven TUI.
Use it for host discovery, web service testing, DNS resolver analysis, tunneling detection, and Xray proxy validation. Results land on disk and can feed the next scan, so you can run a broad ICMP sweep, then drill into survivors with TCP or HTTP.
It is built for developers and researchers who want speed and a modern terminal experience without leaving the keyboard.
bgscan-demo.mp4
Scanning engine
- Multi-protocol probes: ICMP, TCP, HTTP/1.1, HTTP/2, HTTP/3 (QUIC), DNS, DNSTT, VayDNS, Slipstream, MasterDNS, StormDNS, TheFeed, and Xray
- Pipeline chaining between stages (for example ICMP → TCP → HTTP) in Streaming or Batch mode
- Per-probe worker pools for concurrent scanning
- Shuffle and sample: randomize target order and cap the number of IPs to scan
- Dual-stack aware: IPv4 and IPv6 targets and lists are supported end to end
Terminal UI
- BubbleTea TUI, fully keyboard-driven; scan, monitor, and manage results without a browser
- Live scan dashboard with tabbed progress bars and per-stage result tables
- In-app settings inspector that edits every config field interactively and saves to disk immediately
- Theme support: dark, light, and auto palettes built on Catppuccin
Data and I/O
- Results written to CSV and reusable as input for new scans
- Bundled IP lists for Cloudflare (IPv4 and IPv6), AWS, Azure, Google, Akamai, Fastly, Bunny, G-Core, Iran, and public DNS servers
- Xray outbound manager: add outbounds from share links or JSON files, then validate and speed-test them
Reliability
- Crash-safe result writer with atomic merge,
fsync, temp-file rename, and constant memory - Log rotation across three streams (core, UI, debug) with 50 MB rotation, 3 backups, and 7-day retention
- Startup health checks validate config and locate optional binaries, warning instead of crashing when something is missing
- Most scanners do one protocol well. bgscan chains them: ping a range, connect to survivors, HTTP-probe the open ports, in a single run.
- The engine is pipeline-agnostic. It feeds IPs, collects results, and flushes to disk. Adding a new scan type means implementing a four-method
Probeinterface (Init, Run, Schema, Close) and registering a stage builder. - No runtime clutter. ICMP, TCP, HTTP, and DNS probes use the Go standard library. Slipstream is the only external binary, validated at startup; when it is missing a warning is logged and only that scan type is disabled. Xray and the DNS tunnels (DNSTT, VayDNS, MasterDNS, StormDNS, TheFeed) run in-process through vendored libraries.
- All settings live in plain TOML. The in-app inspector reads and writes the same files, so what you see in the TUI is what is on disk.
- Built for the terminal: keyboard navigation, overlay dialogs, live progress, streaming logs. No browser, no Electron, no web server.
| Protocol | Layer | Description |
|---|---|---|
| ICMP | 3 | Host discovery and reachability via Ping (IPv4 and IPv6) |
| TCP | 4 | Connection scanning and TCP handshake validation |
| HTTP | 7 | HTTP/1.1, HTTP/2, and HTTP/3 over QUIC via ALPN |
| DNS | 7 | Advanced DNS queries (UDP, TCP, DNS-over-TLS) with fallback and anti-hijacking checks |
| DNSTT | 7 | DNS tunnel validation with SOCKS and SSH base connections |
| VayDNS | 7 | DNS tunnel validation with SOCKS and SSH base connections |
| Slipstream | 7 | DNS tunnel validation with SOCKS and SSH base connections |
| MasterDNS | 7 | DNS tunnel validation with configurable encryption and MTU discovery |
| StormDNS | 7 | DNS tunnel validation with configurable encryption and MTU discovery |
| TheFeed | 7 | Encrypted DNS feed tunnel validation over UDP, TCP, or DNS-over-TLS |
| Xray | 7 | Xray outbound validation and bandwidth speed testing |
Linux / macOS / Termux:
curl -fsSL https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install.ps1 | iexAndroid (Termux):
{ command -v curl >/dev/null 2>&1 || pkg install -y curl; } && curl -fsSL https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install.sh | shThe installer downloads the bgscan-installer tool (a small standalone Rust binary from the separate bgscan-installer project), which resolves the latest release asset for your platform, verifies its SHA-256 checksum, and installs bgscan into bgscan/. On re-run it detects an existing install and offers to update in place (keeps your ips, assets, and settings, replaces the binary and adds missing files), do a clean install, or back up the old installation to a timestamped bgscan_<timestamp> directory.
To install a specific version instead of the latest:
curl -fsSL https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install.sh | sh -s -- --version v2.11.0- Download the ZIP for your platform from the Releases page.
- Extract the archive.
- Run the binary:
- Linux / macOS / Termux:
./bgscan - Windows:
bgscan.exe
- Linux / macOS / Termux:
The first run creates a settings/ directory with default TOML config and an ips/ directory with bundled IP lists.
bgscan uses a companion build tool (bgscan-builder) to fetch the platform-specific Slipstream sidecar binary and bundled IP lists, and to build the project. bgscan-builder is build-only; installing and updating releases is handled by the separate bgscan-installer tool described above. Xray needs no binary: it runs in-process through a vendored library.
git clone https://github.com/MohsenBg/bgscan.git
cd bgscan
# Install the builder tool
# Linux / macOS:
curl -fsSL https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install-builder.sh | bash
# Windows (PowerShell):
irm https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install-builder.ps1 | iex
# Fetch dependencies for your platform
# Linux / macOS:
./scripts/install-deps.sh
# Windows:
./scripts/install-deps.ps1
# Build and run
go run ./cmd/bgscan/For release builds targeting a specific platform (see bgscan-builder release -h for all flags):
./bgscan-builder release -os linux -arch amd64
./bgscan-builder release -os windows -arch amd64
./bgscan-builder release -os macos -arch arm64
./bgscan-builder release -os android -arch arm64 -ndk-dir /opt/android-ndkbgscan cannot be installed via
go installbecause it needs the platform-specific Slipstream sidecar binary. Use the builder tool or the quick install script.
- Launch bgscan from your installation folder (
./bgscanon Unix,bgscan.exeon Windows). - Select Run Scan and press
Enter. - Choose a target source: IP List (from your imported files) or Result List (from a previous scan).
- Pick a scan type: ICMP, TCP, HTTP, DNS Resolve, DNS Tunneling, or Xray.
- Press
Enterto start. Progress and results stream live in the dashboard. - Open Result Files from the main menu to review, rename, or delete saved results.
| Key | Navigation |
|---|---|
↑ ↓ |
Move between items |
Enter |
Select / start |
b or Esc |
Go back |
q |
Quit |
Full documentation is available at:
- Homepage: https://mohsenbg.github.io/bgscan
- Full docs: https://mohsenbg.github.io/bgscan/docs
The documentation covers:
- Quick Start: installation, launch, and first scan
- Scanner: scan types, scan sources, IP lists, result files, scan pipeline, Xray outbounds
- DNS Tunneling: per-protocol configuration guides (DNSTT, VayDNS, Slipstream, MasterDNS, StormDNS, TheFeed), scan flow, and platform defaults
- Settings: every TOML config file explained (general, writer, ICMP, TCP, HTTP, DNS, Xray) and the in-app inspector
- Logs: three log streams, the log viewer, and rotation policy
- Developer: architecture, core (engine, probes, config, results), UI (component model, layout, theming), contributing guide, and build instructions
All configuration lives in plain TOML files in the settings/ directory next to the binary:
| File | Purpose |
|---|---|
general_settings.toml |
Pipeline mode, batch size, max IPs per stage, max successful IPs, shuffle, status interval |
writer_settings.toml |
Result buffering, flush interval, channel and batch size, result directory |
icmp_settings.toml |
ICMP timeout, retries, workers |
tcp_settings.toml |
TCP port, timeout, retries, workers |
http_settings.toml |
HTTP/HTTPS/HTTP3 version, TLS range, uTLS fingerprint, accepted status codes |
dns_settings.toml |
DNS resolver tuning and DNS tunnel scan orchestration |
xray_settings.toml |
Xray connectivity test type, speed test timeout, concurrent dial limits, pre-scan |
Edit files manually or use the in-app inspector. Both write to the same files, and the inspector saves changes immediately without restarting. See the Settings documentation for every field.
Scan a bundled IP list: after launching, select Run Scan → IP List → cloudflare_IPv4 (or cloudflare_IPv6 for an IPv6 sweep), then choose a scan type such as t for TCP. bgscan scans the list with the configured workers and writes results to result/tcp/ (or a custom result_directory if you set one).
Chain ICMP → TCP → HTTP: in general_settings.toml, set pipeline_mode = "streaming". If multiple scan types are enabled, their stages chain automatically, and only IPs that pass each stage's success criteria proceed to the next.
Re-scan a previous result: select Run Scan → Result List and pick a saved result file. bgscan re-scans only the IPs in that file, useful for deeper analysis on hosts that already passed an earlier stage.
Xray outbound validation: from the main menu, open Xray Outbounds, press a to add a template from a share link (vless://, vmess://, trojan://, ss://, hysteria2://, wireguard://) or a JSON file. Then run an Xray scan to test connectivity and bandwidth.
DNS tunneling: from the main menu, open DNS Tunneling to create DNSTT, VayDNS, Slipstream, MasterDNS, StormDNS, or TheFeed configurations, then run the DNS Tunneling scan type to test which resolvers can carry the tunnel.
| Platform | Architectures |
|---|---|
| Linux | amd64, arm64, arm32, 386 |
| Windows | amd64, arm64 (10+) |
| macOS | amd64, arm64 |
| Android (Termux) | arm64, arm32, x86_64, x86 |
Termux: install from F-Droid. The Play Store version is outdated.
bgscan/
├── cmd/bgscan/ # Application entry point
├── internal/
│ ├── core/
│ │ ├── config/ # TOML configuration, defaults, and validation
│ │ │ └── validate/ # Per-section and aggregate validators
│ │ ├── scanner/ # Scanner orchestrator and stage builders
│ │ │ ├── engine/ # Streaming and batch pipeline execution
│ │ │ ├── portmgr/ # Local port leasing for tunnel and Xray probes
│ │ │ └── probe/ # Probe interface and per-protocol implementations
│ │ ├── result/ # Result interface, schema, async writer, CSV merge, loader
│ │ ├── iplist/ # IP list loader, parser, registry, shuffle
│ │ ├── netutil/ # netip.Addr helpers and CIDR utilities (IPv4/IPv6)
│ │ ├── dns/ # DNS queries, tunnel config services (DNSTT, VayDNS, Slipstream, MasterDNS, StormDNS, TheFeed), SOCKS5, SSH
│ │ ├── speedtest/ # Xray bandwidth, latency, and transport tests
│ │ ├── xray/ # In-process Xray service (vendored core), outbound/link parsing
│ │ ├── process/ # Cross-platform process lifecycle (Slipstream sidecar)
│ │ └── fileutil/ # CSV, JSON, TOML, text, temp-file helpers
│ ├── logger/ # Leveled logging with lumberjack rotation
│ └── ui/ # BubbleTea TUI (splash, startup, workspace, components, theme)
├── assets/ # Slipstream sidecar binary, Xray configs and data, DNS tunnel configs + outbound templates
├── ips/ # Bundled and imported IP lists (CSV)
├── settings/ # Default TOML configuration files
├── result/ # Scan output (CSV, per scan type)
├── logs/ # core.log, ui.log, debug.log
├── scripts/ # Install, build, dependency, publish, and release scripts
├── docs/ # Hugo Book documentation site
└── go.mod
Contributions are welcome, whether bug fixes, documentation improvements, or new features.
- Branch from
mainand use a descriptive branch name (feature/,fix/,docs/,refactor/). - Follow existing conventions: keep code simple and readable, and prefer small focused commits.
- Use commit prefixes:
feat:,fix:,docs:,refactor:,test:. - Before opening a PR, ensure the project builds and existing tests pass, and update documentation for new features.
- For large changes, open an Issue first to discuss the approach.
See the full Contributing Guide in the documentation.
By submitting a contribution to bgscan, you grant permission for your contribution to be distributed as part of the project under the project's license. You confirm that you have the right to submit this contribution and that it does not violate any third-party rights.
GPL-3.0 — Copyright (c) 2026 Mohsen Bagheri
If bgscan has been useful to you, consider supporting its development:
| Network | Currency | Address |
|---|---|---|
| Bitcoin | BTC |
bc1qdwh57dm97nmx5jzdr7lrc9cxe5xh3zc59er7z9 |
| Ethereum | ETH |
0x40Fd22Fff4E059e906A10747Fd0a45A1DB39c985 |
| BNB Smart Chain | BNB / BEP20 |
0x40Fd22Fff4E059e906A10747Fd0a45A1DB39c985 |
| TRON | TRX / TRC20 |
TNW6pbfY8zZVZezZWyYXo7h12MycRsVJK7 |
Built with Go · GPL-3.0 License