Documentation

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started (Developer)#

This guide explains how to set up your environment, build, and run bgscan locally for development.

Read first: Contributing — branching, commit conventions, and PR workflow.

Prerequisites#

Go 1.26.3+ (see go.mod for the exact version)
Git
For Android builds: Android NDK

1. Clone the repository#

git clone https://github.com/MohsenBg/bgscan.git
cd bgscan

2. Create a branch#

git checkout -b feature/my-change

See Contributing for branch naming conventions.

3. Install dependencies#

bgscan uses a companion tool called bgscan-builder to fetch and build the project’s dependencies. The install scripts download it for you, place it in the project root, and use it to fetch the correct dependency build for your OS/architecture.

Scan Source

Mon, 01 Jan 0001 00:00:00 +0000

Scan Source#

Before configuring a scan, bgscan asks you to choose where the target IPs come from. Navigate to Main Menu → Scan to open the source picker, which presents two options:

Key	Option	Description
`i`	IP List	Pick from your imported IP list files
`r`	Result List	Pick from a previous scan’s result file

IP List#

Choosing IP List opens your IP file browser. Select any file from the ips/ directory and bgscan will use its enabled entries as the scan targets.

Settings Overview

Mon, 01 Jan 0001 00:00:00 +0000

Settings Overview#

bgscan keeps all configuration in plain TOML files inside settings/. The app also exposes these same options through the in-app Settings inspector, which writes changes back to disk automatically.

Setting files#

File	Purpose
`settings/general_settings.toml`	Global scan control and pipeline mode
`settings/writer_settings.toml`	Result buffering and disk writes
`settings/icmp_settings.toml`	ICMP probe tuning
`settings/tcp_settings.toml`	TCP connect tuning
`settings/http_settings.toml`	HTTP/HTTPS/HTTP3 probe tuning
`settings/xray_settings.toml`	Xray test tuning
`settings/dns_settings.toml`	DNS resolver, DNSTT, and SlipStream tuning

Two ways to edit settings#

TOML files — open any settings/*.toml file in any text editor, change values, save, and restart bgscan. This is the most explicit approach and works well for version control.
In-app inspector — open bgscan, navigate to Settings in the main menu, pick a category, press Enter on any field to edit it. Changes are saved immediately to disk.

Some fields are dynamic. For example, TLS-related options only show when HTTPS is selected, and DNSTT/Slipstream fields only show when those probes are enabled.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Architecture#

bgscan is a layered application. A lightweight entry point boots startup health checks, then hands control to a BubbleTea TUI. The TUI drives a multi-stage scanner engine whose probes and I/O are pluggable.

Directory layout#

.
├── assets
│ └── xray
│ └── outbounds
├── cmd
│ └── bgscan
│ └── main.go
├── docs
├── go.mod
├── internal
│ ├── core
│ │ ├── config
│ │ ├── dns
│ │ ├── fileutil
│ │ ├── ip
│ │ ├── iplist
│ │ ├── process
│ │ ├── result
│ │ ├── scanner
│ │ └── xray
│ ├── logger
│ ├── startup
│ └── ui
│ ├── components
│ ├── main
│ ├── shared
│ └── theme
├── ips
├── scripts
└── settings

Layer overview#

┌─────────────────────────────────────────────┐
│ cmd/bgscan │
│ (entry point) │
├─────────────────────────────────────────────┤
│ internal/startup │
│ (health checks, config init) │
├─────────────────────────────────────────────┤
│ internal/ui │
│ ┌─────────────────────────────────────┐ │
│ │ main (root model, layout, dialogs) │ │
│ │ components (menus, tables, forms) │ │
│ │ shared (layout, env, dialog, ui) │ │
│ │ theme │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────────┤
│ internal/core │
│ ┌──────────────┐ ┌──────────┐ ┌─────────┐ │
│ │ scanner │ │ config │ │ result │ │
│ │ (engine, │ │ (TOML) │ │ (writer)│ │
│ │ probe, port) │ │ │ │ │ │
│ └──────────────┘ └──────────┘ └─────────┘ │
│ ┌──────────┐ ┌─────────┐ ┌──────────────┐ │
│ │ iplist │ │ dns │ │ xray/process │ │
│ └──────────┘ └─────────┘ └──────────────┘ │
├─────────────────────────────────────────────┤
│ internal/logger │
├─────────────────────────────────────────────┤
│ assets/ ips/ settings/ │
│ (data files) │
└─────────────────────────────────────────────┘

Directory reference#

Path	Description
`cmd/bgscan`	Application entry point (`main.go`). Creates the root TUI model and runs it.
`internal/core`	Core logic: config, DNS, file utilities, IP handling, process management, results, scanner, and Xray integration.
`internal/core/config`	TOML-based configuration singleton with thread-safe accessors.
`internal/core/scanner`	Scanner orchestrator, engine (pipeline), probe interface, port manager, and net utilities.
`internal/core/result`	Asynchronous result writer, CSV merge/sort, result file registry, and loader.
`internal/core/iplist`	IP list CSV loader, parser, registry, and shuffle.
`internal/core/dns`	DNS query, DNSTT, SlipStream, and SOCKS5 helpers.
`internal/core/xray`	Xray command runner, inbound/outbound management, and speed test.
`internal/core/process`	Cross-platform process lifecycle (spawn, kill, signal).
`internal/core/fileutil`	CSV, JSON, TOML, text, temp-file, and path helpers.
`internal/core/ip`	IP parsing and CIDR expansion.
`internal/logger`	Leveled logging with lumberjack rotation. Three streams: core, ui, debug.
`internal/startup`	Sequential startup health checks: logger, theme, config, Xray, DNSTT, Slipstream.
`internal/ui/main`	Root BubbleTea model — header/body/footer layout, overlay dialog manager.
`internal/ui/components`	Reusable UI: basic widgets, inspector forms, menus, tables, scanner view.
`internal/ui/shared`	Shared UI infrastructure: layout geometry, dialog system, env/keys, component interface, validation.
`internal/ui/theme`	Dark/light/auto color palettes (Catppuccin-based).
`assets/xray/outbounds`	Bundled Xray outbound config assets.
`assets/dnstt-client`, `assets/slipstream-client`	DNS tunneling binaries.
`ips`	Default IP range lists per provider (Cloudflare, AWS, Azure, etc.) as CSV.
`settings`	Default `.toml` settings files. `.default` copies are fallback templates.
`scripts`	Install, build, and release helper scripts.
`docs`	Hugo Book documentation site.

Application flow#

main()
 │
 ├─ startup.RunHealthChecks()
 │ ├─ logger init
 │ ├─ theme init
 │ ├─ config load + validate
 │ ├─ xray binary check
 │ ├─ dnstt binary check
 │ └─ slipstream binary check
 │
 ├─ tea.NewProgram(app.New()).Run()
 │ │
 │ ├─ header (title bar)
 │ ├─ body (component stack: main menu → scan/settings/logs/...)
 │ └─ footer (status bar, key hints)
 │
 └─ when user selects Run Scan:
 ├─ scanner.NewScanner(ctx, inputPath)
 ├─ scanner.AddStage(BuildICMPStage)
 ├─ scanner.AddStage(BuildTCPStage)
 ├─ ...
 ├─ scanner.Run()
 │ ├─ single stage → engine.RunScan
 │ └─ multi stage → engine.RunScanWithChain
 │ ├─ sequential
 │ ├─ streaming
 │ └─ batch
 │
 └─ results written via result.Writer → CSV merge → disk

Key design principles#

No external runtime deps for core scans. ICMP, TCP, and HTTP probes use Go stdlib. Xray, DNSTT, and Slipstream are optional binaries validated at startup.
Configuration is file-first. All settings live in settings/*.toml. The in-app inspector reads and writes the same files.
Probes are pluggable. The probe.Probe interface is the only contract. Adding a new scan type means implementing Init/Run/Close and registering a stage builder.
Engine is pipeline-agnostic. The engine does not know what the probes do — it just feeds IPs, collects results, and flushes to disk. The pipeline mode (sequential/streaming/batch) is a config choice.
UI is a component tree. Every screen is a ui.Component with Init/Update/View/OnClose/Mode. Overlays (dialogs, pickers) stack on top; the top overlay consumes all input.

Core — scanner engine, probe interface, config, and result pipeline in detail
UI — TUI architecture, component model, layout, and theming
Getting Started — build and run instructions

Scan Types

Mon, 01 Jan 0001 00:00:00 +0000

Scan Types#

bgscan supports five primary scan types, each accessible from the main menu via keyboard shortcuts:

Key	Scan Type	Description	Primary Use Case	Configuration File
`i`	ICMP Scan	Sends ICMP echo requests (ping) to check host availability	Host discovery, network mapping	`icmp_settings.toml`
`t`	TCP Scan	Attempts TCP connections to specified ports	Port scanning, service discovery	`tcp_settings.toml`
`h`	HTTP Scan	Sends HTTP/HTTPS requests to web servers	Web service testing, API endpoint discovery	`http_settings.toml`
`d`	DNS Scan	Queries DNS servers for resolution and tunneling capabilities	DNS resolver testing, tunneling detection	`dns_settings.toml`
`x`	Xray Scan	Tests outbound connectivity and bandwidth to remote servers	Network egress testing, bandwidth measurement	`xray_settings.toml`

💡 Note: The DNS Scan option (d) actually encompasses three sub-scan types when enabled in configuration:

Settings Inspector

Mon, 01 Jan 0001 00:00:00 +0000

Settings Inspector#

When you open any settings section from the in-app Settings menu, you see the inspector. It is a tabbed field list with labels, current values, and edit affordances.

select fields and press Enter to change them
press d to view the description/help text for the selected field
booleans show as toggles
some protocols expose extra fields only when the mode is selected

Changes are saved immediately to disk without restarting the scanner.

Core

Mon, 01 Jan 0001 00:00:00 +0000

Core#

The internal/core package contains all non-UI logic: configuration, the scanner engine, probe implementations, IP list handling, results, DNS, Xray integration, and process management.

Package map#

Package	Responsibility
`config`	Thread-safe singleton holding all TOML settings; load/save helpers; validation entry points.
`config/validate`	Per-protocol validators (ICMP, TCP, HTTP, DNS, Xray, writer, general).
`scanner`	`Scanner` orchestrator and stage builders.
`scanner/engine`	Pipeline execution: single scan, sequential chain, streaming pipeline, batch pipeline.
`scanner/probe`	`Probe` interface and all concrete probes (ICMP, TCP, HTTP, HTTP/3, DNS, DNSTT, SlipStream, Resolve, Xray).
`scanner/portmgr`	Ephemeral port pool for probes that need local bind ports (Xray, DNSTT, SlipStream).
`scanner/netutil`	Shared network utilities.
`result`	`Writer` (async batch+merge), CSV format, loader, registry, ordering.
`iplist`	CSV IP list loader, parser, registry, shuffle, streaming.
`ip`	IPv4 parsing and CIDR expansion.
`dns`	DNS query helpers, transport parsing, DNSTT/SlipStream SOCKS5 client.
`xray`	Xray binary runner, inbound/outbound config, link parsing, speed test.
`process`	Cross-platform process spawn/kill (Unix + Windows split).
`fileutil`	CSV, JSON, TOML, text, temp-file, and path helpers.
`logger`	Leveled logging (core, ui, debug) with lumberjack rotation.

Scanner#

internal/core/scanner/scanner.go defines the Scanner struct — the public API the UI calls to run a scan.

General Settings

Mon, 01 Jan 0001 00:00:00 +0000

General Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → General Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/general_settings.toml

This file controls the core behavior of the bgscan scanner, including scan limits, execution modes, and performance tuning.

Quick Reference#

Setting	Default	Description
`status_interval`	`1000`	UI refresh rate in milliseconds
`stop_after_found`	`0`	Stop after finding N successful targets
`max_ips_to_test`	`0`	Maximum number of IPs to scan
`shuffled`	`true`	Randomize target order
`pipeline_mode`	`"streaming"`	Execution mode for multi-stage scans
`max_ips_per_stage`	`100000`	Memory cap per pipeline stage
`batch_size`	`1000`	Batch size for batch mode

Scan Control#

Status Interval#

status_interval = 1000

Controls how often (in milliseconds) the UI refreshes with progress updates. Lower values give smoother real-time feedback but use more CPU. Higher values reduce overhead for very large scans.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

bgscan runs on Linux, macOS, Windows, and Android (Termux). Pick the method that fits your environment.

Quick Install#

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install.ps1 | iex

Android (Termux)

pkg update -y && pkg install bash curl unzip -y && curl -fsSL https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install.sh | bash

The installer downloads the latest release, extracts it to bgscan/, and makes the binary executable. If a previous installation exists, it prompts you to remove it or back it up as bgscan_old.

Scan Pipeline

Mon, 01 Jan 0001 00:00:00 +0000

Scan Pipeline#

bgscan supports multi-stage scanning where the output of one scan becomes the input for the next. This is configured via the General Settings under “Pipeline Execution Mode”.

Pipeline Modes#

bgscan offers three pipeline modes to balance performance, memory usage, and flexibility:

1. Streaming (Default)#

Stage 1 (IPs) → [ICMP Scan] → [TCP Scan] → [HTTP Scan] → Results
 │ │ │
 ▼ ▼ ▼
 (passed IPs) (passed IPs) (passed IPs)

How it works: All stages run simultaneously, with IPs flowing between stages via in-memory channels
Memory usage: Highest (holds multiple copies of IP lists in memory)
Speed: Fastest (no waiting for stages to complete)
Best for: High-performance scanning with sufficient memory
When to use: When you have enough memory and want maximum throughput

2. Sequential#

Stage 1 → [ICMP Scan] → (wait) → [TCP Scan] → (wait) → [HTTP Scan] → Results

How it works: Each stage waits for the previous to complete before starting
Memory usage: Lowest (only one stage’s data in memory at a time)
Speed: Slowest (total time is sum of all stage times)
Best for: Memory-constrained environments
When to use: When running on systems with limited RAM

3. Batch#

[Batch 1 of IPs] → [ICMP Scan] → [TCP Scan] → [HTTP Scan] → Results
[Batch 2 of IPs] → [ICMP Scan] → [TCP Scan] → [HTTP Scan] → Results
...

How it works: IPs are divided into batches; each batch goes through all stages before the next batch starts
Memory usage: Moderate (holds one batch’s data per stage)
Speed: Moderate (better than sequential, worse than streaming)
Best for: Balancing memory and performance
When to use: When you want to limit memory spikes while maintaining decent throughput

Configuring the Pipeline#

The pipeline mode is set in general_settings.toml:

IP Files

Mon, 01 Jan 0001 00:00:00 +0000

IP Files#

Scanners read target addresses from IP list files. Before a list can be used for scanning it must be imported through the TUI, which validates and converts it into bgscan’s internal format.

Preparing a File to Import#

The file you import must be a plain .txt file with one entry per line. Only IPv4 is supported — IPv6 addresses and prefixes are not accepted and will be skipped on import.

Logs

Mon, 01 Jan 0001 00:00:00 +0000

Logs#

bgscan maintains three separate log streams, each covering a different layer of the application. You can view any of them live from inside the TUI.

Navigate to Main Menu → Logs to open the log menu.

Log Categories#

Key	Category	Description
`c`	Core Logs	Scan engine activity — IP probing, file I/O, result writing, and internal errors from the scanner core
`u`	UI Logs	Interface-layer events — component lifecycle, file operations triggered from the TUI, and UI-level errors
`d`	Debug Logs	Low-level diagnostic output — detailed internal state, data dumps, and verbose error traces for troubleshooting

Press the corresponding key to open that log’s viewer.

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started with bgscan#

Welcome to bgscan! This guide gives you a quick overview of what you’ll see after installation and how to run your first scan.

Launching bgscan#

Navigate to the installation folder and run the application:

Windows: Double-click bgscan.exe or run .\bgscan.exe in PowerShell
Linux/macOS/Termux: Run ./bgscan in your terminal

When you launch bgscan, you’ll see the main menu with the following options:

Option	Description
Run Scan	Start a new network scan
IP Files	Manage and select IP list files for scanning
Result Files	View and manage saved scan results
Settings	Configure scan parameters and preferences
Xray Outbounds	Manage Xray proxy configurations
Logs	View application and scan logs

Use these keyboard shortcuts to navigate:

Result Writer Settings

Mon, 01 Jan 0001 00:00:00 +0000

Result Writer Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → General Settings tab 2 in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/writer_settings.toml

This file controls buffering and how often results are flushed to disk.

Quick Reference#

Setting	Default	Description
`merge_flush_interval`	`2000`	Interval (in milliseconds) for merging delta results into the main result file.
`chan_size`	`4096`	Capacity of the internal channel used by scanner workers to send IP scan results to the writer goroutine.
`batch_size`	`4096`	Initial capacity of the in-memory batch used to accumulate IP scan results before flushing them to disk.

Merge Flush Interval#

Controls how frequently (in milliseconds) partial scan results are committed to disk. Lower values increase disk I/O but reduce memory usage. Higher values reduce disk I/O but increase memory usage.

UI

Mon, 01 Jan 0001 00:00:00 +0000

UI#

bgscan’s terminal UI is built on BubbleTea (the Elvish v2 fork at charm.land/bubbletea/v2) and Lipgloss for styling. The architecture is a component tree with an overlay dialog system and a centralized layout manager.

Package map#

Package	Responsibility
`ui/main/app`	Root BubbleTea model. Manages layout, header/body/footer, and overlay dialog stack.
`ui/main/header`	Top bar — app title and branding.
`ui/main/body`	Central content area — holds a component stack (main menu → sub-screens).
`ui/main/footer`	Status bar — app version, current screen name, goroutine count, memory usage.
`ui/components/basic`	Reusable widgets: confirm, crud, input, inspector, logview, menu, notice, picker, progress, table, tabs.
`ui/components/inspector`	Per-protocol settings forms (DNS, general, HTTP, ICMP, TCP, Xray).
`ui/components/menus`	Screen-level menus: entry (main), logs, outbound, scantype, settings, targetsource.
`ui/components/tables`	Data tables: iplist, ipviewer, outbounds, resultlist.
`ui/components/scanner`	Live scan view — tabbed progress bars + result tables per stage.
`ui/shared`	Shared infrastructure: layout, dialog, env (keys/modes), component interface, validation.
`ui/theme`	Dark/light/auto color palettes + huh form theme adapter.

Component interface#

Every screen, widget, and dialog implements ui.shared.ui.Component:

ICMP Settings

Mon, 01 Jan 0001 00:00:00 +0000

ICMP Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → ICMP Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/icmp_settings.toml

This file controls the ICMP probe tuning.

Quick Reference#

Setting	Default	Description
`timeout`	`2000`	Maximum duration (in milliseconds) to wait for an ICMP echo reply. Targets failing to respond within this window are considered unreachable.
`tries`	`1`	The maximum number of retry attempts per target to mitigate packet loss. Higher values improve reliability but increase total scan duration.
`workers`	`400`	The number of concurrent workers sending ICMP echo requests. Higher values increase scan speed at the cost of greater CPU and network utilization.
`prefix_output`	`"icmp_"`	The filename prefix applied to all output files generated by this module. Useful for distinguishing results when running multiple scans simultaneously.

Timeout#

timeout = 2000

Maximum duration (in milliseconds) to wait for an ICMP echo reply. Targets failing to respond within this window are considered unreachable.

Result Files

Mon, 01 Jan 0001 00:00:00 +0000

Result Files#

After a scan completes, bgscan writes the discovered IPs and their measurements to result files. These files are organized by created time and can be browsed, viewed, renamed, or deleted from the TUI.

Viewing Result Files#

Navigate to Main Menu → Result Files to open the result file browser.

The table lists every result file across all scan types, sorted newest-first, and shows:

Column	Description
File Name	The result file name (without `.csv`)
Created Time	File creation or last modification timestamp
Type	The scan engine that produced the file (`icmp`, `tcp`, `http`, etc.)
Size	File size on disk

Two keyboard actions are available:

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

Contributing Guide#

Thank you for your interest in contributing to bgscan! Every contribution is appreciated, whether it’s fixing bugs, improving documentation, or implementing new features.

Before You Start#

Search existing Issues before opening a new one.
If you’re planning a large feature or major change, please open an Issue first to discuss it.
Keep pull requests focused on a single change.

Branch Strategy#

Please do not commit directly to the main branch.

TCP Settings

Mon, 01 Jan 0001 00:00:00 +0000

TCP Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → TCP Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/tcp_settings.toml

This file controls the TCP port scan configuration, including the target port, timeout, number of workers, retry attempts, and output prefix.

Port#

port = 80

The target TCP port to probe on each IP address. The scanner attempts to establish a TCP connection to this port. Common examples: 80 (HTTP), 443 (HTTPS), 22 (SSH).

Xray Outbounds

Mon, 01 Jan 0001 00:00:00 +0000

Xray Outbounds#

An outbound template tells bgscan how to route traffic through your proxy server during an Xray scan. Each template is a JSON file stored in assets/xray/outbounds/ that describes the protocol, transport, and security settings for one proxy configuration.

Before running an Xray scan you must have at least one outbound template configured.

Navigate to Main Menu → Xray → Outbounds to open the outbound manager.

The Outbound Table#

The table lists all configured outbound templates, sorted newest-first, and shows:

HTTP Settings

Mon, 01 Jan 0001 00:00:00 +0000

HTTP Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → HTTP Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/http_settings.toml

This file controls the HTTP/HTTPS/HTTP3 probe configuration, including target host, port, protocol, TLS settings, HTTP version, timeout, and accepted status codes.

Workers#

workers = 50

The number of concurrent workers performing HTTP requests. Higher values increase scan speed at the cost of greater CPU and network utilization.

DNS Settings

Mon, 01 Jan 0001 00:00:00 +0000

DNS Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → DNS Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/dns_settings.toml

This file controls the DNS resolver, DNSTT, and SlipStream scanning modules.

Quick Reference#

Setting	Default	Description
`workers` (resolver)	`500`	The number of concurrent workers sending DNS queries.
`protocol` (resolver)	`"udp"`	The transport protocol used for DNS queries.
`domain` (resolver)	`""`	The target domain name used as the primary query target for DNS resolution.
`port` (resolver)	`53`	The target port used for DNS queries (typically 53).
`check_types` (resolver)	`["txt"]`	The DNS record types to query (e.g., A, AAAA, TXT, MX).
`timeout` (resolver)	`2000`	Maximum duration in milliseconds to wait for a DNS response.
`tries` (resolver)	`2`	The maximum number of network retry attempts per target to mitigate packet loss.
`accepted_rcodes` (resolver)	`["noerror", "nxdomain"]`	The DNS response codes that are treated as successful ("alive") results.
`check_dpi` (resolver)	`false`	Enables the anti-hijacking pre-check.
`dpi_timeout` (resolver)	`500`	Maximum duration in milliseconds to wait for the DPI pre-check response.
`dpi_tries` (resolver)	`2`	The maximum number of network retry attempts for the DPI pre-check.
`random_subdomain` (resolver)	`true`	Generates a random subdomain for each query to bypass resolver caches.
`prefix_output` (resolver)	`"dns_"`	The filename prefix applied to all output files generated by this module.
`enabled` (dnstt)	`false`	Enables or disables the DNSTT probe phase.
`workers` (dnstt)	`20`	The number of concurrent workers performing DNSTT handshakes.
`domain` (dnstt)	`""`	The authoritative DNS zone delegated to your DNSTT server.
`timeout` (dnstt)	`10000`	Maximum duration in milliseconds to wait for a complete DNSTT handshake.
`prefix_output` (dnstt)	`"dnstt_"`	The filename prefix applied to all output files generated by the DNSTT module.
`enabled` (slip_stream)	`true`	Enables or disables the SlipStream probe phase.
`workers` (slip_stream)	`20`	The number of concurrent workers performing SlipStream probes.
`domain` (slip_stream)	`""`	The authoritative DNS zone used by the SlipStream server.
`timeout` (slip_stream)	`8000`	Maximum duration in milliseconds to wait for a complete SlipStream probe.
`prefix_output` (slip_stream)	`"slipstream_"`	The filename prefix applied to all output files generated by the SlipStream module.

Resolver Settings#

The resolver section configures the bulk DNS resolver scanner that tests public DNS resolvers.

Xray Settings

Mon, 01 Jan 0001 00:00:00 +0000

Xray Settings#

💡 Tip: You can change these settings directly in the bgscan application instead of editing the TOML file manually.

Navigate to Settings → Xray Settings in the main menu to configure these options interactively using the TUI inspector.

Configuration file: settings/xray_settings.toml

This file controls the Xray outbound validation module, which tests connectivity and bandwidth to remote servers.

Quick Reference#

Setting	Default	Description
`timeout`	`6000`	Maximum duration (in milliseconds) to wait for an Xray connectivity test to complete.
`workers`	`32`	Number of concurrent workers performing Xray connectivity tests.
`connectivity_test_type`	`3`	Type of connectivity test: 0 = connectivity only, 1 = download only, 2 = upload only, 3 = both download and upload.
`download_speed`	`100`	Target download data size (in KB) for the test (used when test type includes download).
`upload_speed`	`50`	Target upload data size (in KB) for the test (used when test type includes upload).
`prefix_output`	`"xray_"`	Filename prefix applied to all output files generated by this module.
`pre_scan_type`	`"tcp"`	Pre-scan connectivity test to perform before running Xray: `none`, `icmp`, `tcp`, or `http`.

Timeout#

timeout = 6000

Maximum duration (in milliseconds) to wait for an Xray connectivity test to complete. Tests failing to respond within this window are considered failed.

Documentation

Getting Started

Getting Started (Developer)#

Prerequisites#

1. Clone the repository#

2. Create a branch#

3. Install dependencies#

Scan Source

Scan Source#

IP List#

Settings Overview

Settings Overview#

Setting files#

Two ways to edit settings#

Architecture

Architecture#

Directory layout#

Layer overview#

Directory reference#

Application flow#

Key design principles#

Related pages#

Scan Types

Scan Types#

Settings Inspector

Settings Inspector#

Core

Core#

Package map#

Scanner#

General Settings

General Settings#

Quick Reference#

Scan Control#

Status Interval#

Installation

Installation#

Quick Install#

Scan Pipeline

Scan Pipeline#

Pipeline Modes#

1. Streaming (Default)#

2. Sequential#

3. Batch#

Configuring the Pipeline#

IP Files

IP Files#

Preparing a File to Import#

Logs

Logs#

Log Categories#

Overview

Getting Started with bgscan#

Launching bgscan#

Main Menu Overview#

Navigation Controls#

Result Writer Settings

Result Writer Settings#

Quick Reference#

Merge Flush Interval#

UI

UI#

Package map#

Component interface#

ICMP Settings

ICMP Settings#

Quick Reference#

Timeout#

Result Files

Result Files#

Viewing Result Files#

Contributing

Contributing Guide#

Before You Start#

Branch Strategy#

TCP Settings

TCP Settings#

Port#

Xray Outbounds

Xray Outbounds#