Scripts are run through `sh -c`, so when the program a `call_format`
starts with is missing, the only feedback is whatever the shell prints
once the scan has already finished:
Open 127.0.0.1:18080
[~] Starting Script(s)
[!] Error No such file or directory (os error 2)
which neither names the program nor arrives before a long scan has been
wasted.
Check the first word of every selected script format against PATH while
the scripts are initialised, and fail there with the program named. Name
resolution follows what the shell would do: PATH entries in order, plus
PATHEXT on Windows.
Formats that do not start with a bare program name are left alone, since
their first word is not something PATH can answer for:
- `FOO=bar cmd ...` (leading assignment)
- `/opt/custom/nmap ...` (explicit path)
- `{{script}} ...` (placeholder filled in at run time)
With nmap absent, on the same scan:
before: scans, then "[!] Error No such file or directory (os error 2)"
after: "[!] Initiating scripts failed!
The script `default` runs `nmap`, which is not installed or
not in PATH. Install it, or skip scripts with `--scripts none`."
With nmap present the scan and the script phase run as before.
Implemented with std/target-specific helpers rather than a new
dependency: `which` pulls in a newer windows-sys and rewrites ~110 lines
of Cargo.lock for a 15-line check.
Refs #691
Co-authored-by: QianEric <[email protected]>
A subnet sweep for one port printed the batch-size hint for every host without that port. When any host answered with an open port, or a closed one under --closed, replies got through at this batch size and timeout, so batch size and timeout are unlikely to be the cause and the hint is skipped. When nothing was found it is printed once for all targets.
Fixes#795
`Opts::merge` copied every value present in the config file over the
parsed command line, so e.g. `-r 8600-8650` was silently replaced by the
config's `range` and the requested ports were never scanned (`-p` only
survived because `PortStrategy::pick` prefers `ports` over `range`).
The same happened to `-a`, `-b`, `-t`, `--tries`, `-g`, `--scripts`,
`--scan-order`, the trailing nmap command and every other merged option.
This contradicts the documented behaviour: "Any arguments passed
directly to the binary will override the default provided in this
config file".
`Opts::parse()` cannot tell a value typed by the user from a clap
default, so `Opts::read()` now parses through `ArgMatches` and records
the ids of the arguments whose `value_source` is `CommandLine` in a new
skipped `cli_args` field. `merge_required`/`merge_optional` leave those
fields alone; options not given on the command line are still filled in
from the config file. `--top` and `--no-config` behave as before.
Add pure parsing tests (no sockets) covering both directions.
Fixes#722
* Initialize the fallback DNS resolver only when needed
* Record lazy DNS startup benchmark results
* docs(perf): remeasure lazy DNS against merged Tokio master
* docs(perf): verify lazy DNS on current master
* test(scanner): preserve port filtering order and boundaries
* perf(scanner): reuse port lists and index large exclusions
* perf(scanner): use bitmap for dense exclusions
* bench(scanner): document production port preparation speedups
* ci(bench): diagnose repeated macOS listener misses
* ci(bench): capture socket errors immediately after listener misses
* perf(scanner): keep bitmap storage out of repeated async polls
* ci(bench): provision macOS TCP memory for repeated scans
* refactor(scanner): run the scanner on tokio instead of async-std
async-std is discontinued upstream (RUSTSEC-2025-0052). tokio is already in
the dependency tree through hickory-resolver, so switching adds no crate and
removes 28 from Cargo.lock (async-std, async-io, polling,
async-global-executor, blocking, futures-executor, ...).
This is a like-for-like port. The scanner keeps its architecture and the
library API keeps its signatures:
- a single `FuturesUnordered` keeps at most `batch_size` sockets in flight
from one future; nothing is spawned per socket;
- connect and UDP receive timeouts use `tokio::time::timeout` and report the
same `TimedOut` error that async-std's `io::timeout` did;
- open TCP sockets are still shut down in both directions before they are
closed (through `into_std()`, because tokio only has a write-side shutdown);
- `--interval` sleeps with `tokio::time::sleep`.
The binary runs the scan on a current-thread runtime that exists only for
the scan. Address resolution (blocking DNS lookups and file reads) runs
before the runtime is created and scripts run after it is dropped, so neither
can stall the scan, and hickory's internal runtime is never nested in ours.
Library users now have to poll the scan futures from a tokio runtime with the
I/O and time drivers enabled. The crate and `Scanner` docs say so, and the
crate example shows how.
Builds on the earlier port in #856 by @vrtgs.
Co-authored-by: Vrtgs <[email protected]>
* perf(scanner): opt the scan out of tokio's cooperative budget
The scan polls every in-flight socket from one future through a
`FuturesUnordered`. tokio's cooperative scheduling gives that future a budget
of 128 units per poll. Once it is spent, every tokio resource returns
`Pending` and defers its wake-up, but `FuturesUnordered` still polls all the
other ready sockets in that same poll. When thousands of connections finish
together (a burst of refusals, or a batch of timeouts firing at once), the
scan keeps re-polling sockets only to park them again, roughly 128 at a time.
async-std had no budget. `tokio::task::unconstrained` restores that
behaviour: one poll handles every ready socket. The future still returns
`Pending`, and so lets the runtime poll I/O and timers, as soon as no socket
is ready.
* perf(scanner): send UDP probes before registering the socket with tokio
tokio's socket I/O is readiness based: `UdpSocket::send` and `recv` first
wait until the reactor has reported the socket ready and only then make the
system call. async-io, which async-std used, made the call first and only
waited after `WouldBlock`.
With a straight port, every UDP probe therefore made an extra trip through
the event loop before its send. Probes to closed ports on the local host
also no longer finished in their first poll: there the ICMP "port
unreachable" is usually queued before `send` returns, so async-std's first
`recv` already saw the refusal.
Bind a non-blocking std socket instead, send the probe and try the first
receive straight away. The socket is only handed to tokio, and registered
with its reactor, when there is really something to wait for. Errors and
timeouts are reported exactly as before.
* ci: add an opt-in scan benchmark comparing a change with its base
The test suite deliberately never opens sockets (see #942), so nothing in CI
showed whether a change to the scanner makes RustScan slower, hungrier or
wrong. The tokio port (#944) needs exactly that evidence.
The "Scan benchmark" workflow runs for pull requests that touch the scanner,
its runtime or its dependencies, and on demand. It builds the change and its
base in release mode on Linux x64/arm64, macOS and Windows runners. It then
runs .github/scan-benchmark/scan_bench.py, which:
- opens 315 TCP listeners and 32 UDP responders on 127.0.0.1 inside the
runner. Nothing outside the runner is scanned. Ports stay out of the
ephemeral range, so a scan can never connect a socket to itself;
- scans them with both builds, alternating the build order between runs:
full TCP sweeps with batch sizes 500/4500/10000, 8 loopback hosts, one
port, a UDP sweep, and on Linux ports that iptables drops (filtered TCP and
UDP, and a mixed sweep), so timeouts are measured too;
- fails unless every run finds every listener and no build reports ports the
base never found, or misses ports the base always found;
- reports medians of throughput (from RustScan's own scan timer), wall time,
time to the first open port, peak RSS, CPU time, and sampled peak
descriptors and threads. The table goes to the job summary, the raw data
to an artifact;
- fails if the change's median throughput or wall time is more than 15%
worse, or its peak RSS more than 25% worse, in any scenario.
contributing.md documents the workflow as the place where scanning is
measured, next to the rule that tests must not scan.
* ci(scan-benchmark): temporarily compare the port's intermediate builds (to be reverted)
* Revert "ci(scan-benchmark): temporarily compare the port's intermediate builds (to be reverted)"
This reverts commit 30ac107c55.
* fix(scanner): let the runtime poll I/O while a batch is started
The scan drives every socket from one future on a current-thread runtime,
so the runtime only polls for I/O and fires timers between two polls of
that future. A poll only ended once no socket was ready, which could take
a long time:
- starting a whole batch at once: 8,191 sockets took longer than a 500 ms
timeout on the Windows runner, so connections that had succeeded during
the fill were only seen after their timers fired. The benchmark found no
open port at all with `-b 10000 -t 500` there;
- UDP probes to closed ports on the local host finish straight away, so a
whole sweep ran in one poll, and the replies from open ports waited until
the end: the first open UDP port was reported 2.6x later than with
async-std.
`scan_sockets` now starts and finishes sockets in rounds of at most 128
(`WORK_PER_TURN`, both counted together) and calls `yield_now()` between
rounds, which defers its wake-up until the runtime has polled the OS
selector without blocking. Each round still keeps up to `batch_size`
sockets in flight; the batch now fills over several rounds instead of in
one go. The cost is one extra non-blocking `epoll_wait` (or equivalent)
per 128 sockets.
* fix(scanner): see ICMP errors on UDP sockets that wait in tokio
A UDP probe that gets no answer straight away is handed to tokio to wait for
the reply. On Linux, an ICMP "port unreachable" that arrives later only
raises EPOLLERR on the socket. tokio does not count that as readable, so
`UdpSocket::recv` slept until the timeout instead of returning the refusal.
async-io treated EPOLLERR as readable.
The straight port (before the eager probe) showed the effect: the UDP sweep
of the local host took 4.1 s instead of 1.0 s, because every closed port
waited for the 500 ms timeout. With the eager probe it only hit closed ports
whose ICMP arrived after the first receive. That is rare on the local host
but the common case for any remote host, where it turned every closed port
into a timeout.
`recv_or_error` waits for `READABLE | ERROR` readiness and hands out the
queued error (`take_error`), so a refused probe ends as soon as the ICMP
arrives, as before.
* ci(scan-benchmark): add a delayed host, fit Windows, compare misses
What the first runs showed:
- Only answers that arrive while the probe is still being sent were
measured: on the loopback interface, refusals and ICMP errors are queued
before connect()/send() returns. A remote host answers a round trip
later, which is the path where tokio's UDP receive missed ICMP errors.
On Linux the workflow now also sets up a host 5 ms away (a network
namespace behind a netem-delayed veth pair, with ICMP rate limiting off,
running its own listeners), and the benchmark sweeps it over TCP and UDP.
- Windows retries a refused connection for about a second. With
`-t 500`, 8,191 concurrent attempts made even the base miss listeners.
Windows now uses the default timeout and sweeps 8,191 ports (2,047 for
the 500-socket batch).
- A build now fails the check only if it misses more listeners than the
base does (any miss at all if the base misses none). Misses by the base
are reported as a warning in the summary.
- The macOS runner has no `net.inet.icmp.icmplim`, which failed the
"describe" step, and caps descriptors at 10240, so the 65536 limit
could not be set. The describe step can no longer fail the job, and
10240 is tried as well.
* docs(address): say that parse_addresses must not run inside async code
hickory's synchronous resolver runs its own tokio runtime, and tokio panics
when a runtime is dropped inside an asynchronous context. That was already
true before, but library users now have to run the scanner on tokio, so
they are more likely to call `parse_addresses` from async code. Document
the two safe ways: call it before starting the runtime (as the binary does)
or through `spawn_blocking`.
---------
Co-authored-by: Vrtgs <[email protected]>
* Refactor SocketIterator for allocation-free performance
Refactor SocketIterator to eliminate boxing and improve memory efficiency. Update documentation and tests to reflect changes.
* fix(socket_iterator): fix clone test off-by-one and skip private doc example
- clone_resumes_independently expected None after 3 of 4 sockets; assert
the exact remaining sequence for both the original and the clone.
- The struct doc example referenced a placeholder crate and a private
module, so it could never compile as a doctest; mark it ignore.
- Add a test for empty IP/port inputs covering size_hint and the
FusedIterator promise.
---------
Co-authored-by: Autumn Skerritt <[email protected]>
Small cleanups in main.rs:
- Iterate over the parsed scripts by reference and clone only the script being run, instead of cloning the whole list for every IP.
- Use `or_default()` for the per-IP port map.
- If the soft file-descriptor limit does not fit in a `usize` (32-bit targets), fall back to `DEFAULT_FILE_DESCRIPTORS_LIMIT` instead of `usize::MAX`, which bypassed all batch-size adjustments.
- Fix a typo.
The effective-batch-size warning fix originally proposed here landed via #921.
Co-authored-by: Autumn Skerritt <[email protected]>
New opt-in `--interval <MS>` option (also `interval` in the config file): after a port has been scanned on every address, wait that many milliseconds before scanning the next port, for slow, low-noise scans. Within a port `--batch-size` still limits concurrency; with the default of 0 scanning behaviour is unchanged.
Library: `Scanner::with_interval(Duration)` is added; `Scanner::new()` is unchanged.
Co-authored-by: Autumn Skerritt <[email protected]>
New `--closed` option (also `closed = true` in the config file) that additionally lists TCP ports that actively refused the connection: printed live as `Closed ip:port` and summarised under `closed ports:` at the end (also in greppable mode). Scripts are never run against closed ports, and without `--closed` scanning behaviour is unchanged.
Library: `Scanner::with_closed_ports()` and `Scanner::run_with_status() -> Vec<PortStatus>` are added; `Scanner::new()` and `run()` are unchanged.
Co-authored-by: Autumn Skerritt <[email protected]>
`-r/--range` now accepts several comma-separated ranges, e.g. `-r 1-100,200-300,5000-5100`. Overlapping/adjacent ranges are merged; random order uses the existing LCG walk extended over the merged ranges (every port visited exactly once), serial order follows the input order and skips duplicates. Reversed ranges (`300-200`) are now rejected instead of underflowing.
`range` in the config file keeps accepting the old `{ start = 1, end = 1000 }` table and additionally accepts `"1-500,1000-2500"` or `[[1, 500], [1000, 2500]]`.
Library API: `input::PortRange { start, end }` is replaced by `input::PortRanges(Vec<(u16, u16)>)`; `PortStrategy::pick` keeps its signature otherwise.
Fixes#835.
Co-authored-by: Autumn Skerritt <[email protected]>
Add regression tests for CIDR inputs whose host bits are set (e.g. `192.168.1.13/29` -> 192.168.1.8–15, `192.168.1.5/23`, `10.0.0.7/30`). The parsing itself was already fixed on master by 3bdac9c (IpInet accepts host bits), so the proposed normalize_cidr helper was dropped as unreachable.
On native Windows, use the configured `-b/--batch-size` instead of a hard-coded 3000, and report the effective batch size (not the raw CLI value) in the "no open ports" hint on all platforms. `--ulimit` is hidden from Windows help and rejected on Windows (exit code 2), including when it comes from the config file. Unix batch-size/ulimit inference is unchanged.
Effective-batch-size reporting fix originally identified by @0xxreacher in #905.
Co-authored-by: 0xxreacher <[email protected]>
Look for the config file at the XDG-style `$XDG_CONFIG_HOME/rustscan/config.toml` first (via `dirs::config_dir()`, so the platform equivalent on macOS/Windows), then fall back to the previous `$XDG_CONFIG_HOME/.rustscan.toml` and `~/.rustscan.toml` locations so existing configs keep working.
Fixes#741.
Build a port -> payload lookup once per UDP scan instead of cloning the whole nmap payload BTreeMap into every scanned socket and scanning it linearly. Payload selection keeps the previous "last match wins" semantics.
Adds a socket-free micro-benchmark (benches/benchmark_helpers.rs) and lookup tests (tests/udp_payload_lookup.rs).
`Scanner` no longer prints each open socket to stdout by default, so library users can embed it and use the returned sockets without unsolicited output. The CLI opts in via the new `Scanner::with_open_port_output()` builder. The UDP socket bind error is now logged at debug level instead of printed.
Fixes#706.
Rewrite the nmap-payloads decoder in build.rs to follow Nmap's C-style escape format: `\xNN` and single-character escapes are decoded, all other characters are kept literally, and multi-line quoted segments are concatenated. Literal protocol text (e.g. the SNMP `public` community string, NetBIOS names, SSDP headers) was previously dropped, producing malformed probes. Also strip CR line endings when reading nmap-payloads.
Adds regression tests pinning the SNMP (161) and SSDP (1900) probe bytes.
Fixes#933.
Route all user-facing stdout writes through tui::println_safe, which exits 0 on BrokenPipe (e.g. `rustscan -g ... | head`) instead of panicking (fatal under panic = "abort"). On Windows, skip hickory-resolver's system configuration and hosts file when SystemRoot is unset, falling back to the existing cloudflare_tls resolver.
Fixes#939, fixes#940.
Add the GitHub-hosted ubuntu-24.04-arm runner to the test matrix so the suite runs natively on arm64 Linux (macos-latest already covers arm64 macOS; build.yml already cross-builds armv7/aarch64 Linux binaries), and document ARM support in docs/arm-support.md.
Fixes#683.
Co-authored-by: Autumn Skerritt <[email protected]>
Build release archives with houseabsolute/actions-rust-release and publish them (plus the .deb and checksums) to the GitHub release when a tag is pushed. CD now runs on pushes to master and tags only.
Also: read-only default workflow token (publish job gets contents: write), third-party actions pinned to release SHAs, fail on unmatched release assets, and the disabled trigger-less dependabot auto-merge workflow is removed.
Fixes#700, fixes#801.
Co-authored-by: Autumn Skerritt <[email protected]>
Replace the deprecated actions-rs/toolchain action with actions-rust-lang/setup-rust-toolchain (pinned to v1.17.0, clippy + rustfmt components, built-in cache and default RUSTFLAGS disabled) and restrict the workflow token to contents: read.
Co-authored-by: Autumn Skerritt <[email protected]>
