Scanner on Documentation

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.

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:

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.

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:

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: