RustScan Administrator & Developer Guide

This guide is the source-based reference for the architecture, operational posture, security boundaries, configuration surface, and developer internals of RustScan (crate rustscan, version 2.4.1, GPL-3.0-only, Rust edition 2018). It is written for the people who deploy RustScan in environments other than "one analyst on a laptop":

• Security engineers wiring RustScan into pipelines and SIEMs.
• Pentest-platform admins who containerize it for a team.
• Rust developers building on top of the public rustscan library API.
• Anyone who needs to know exactly what RustScan does to a network before approving it for production use.

Refer to the User Guide for everyday CLI usage; this document does not duplicate that material.

1. Architecture Overview

RustScan is a single-binary CLI that performs three things in sequence:

1. Resolve the user's target list (IPs, CIDRs, hostnames, files) into a deduplicated Vec<IpAddr>.
2. Generate a port set from one of three strategies (Manual list, Serial range, Random range), then schedule async TCP connect() (or UDP) probes through a fixed-size pool.
3. Hand off the open-port set to a downstream "script" — by default, an Nmap invocation; optionally a custom shell command parameterised on the discovered IP/port pairs.

The compiled binary is statically linked, ships with an embedded UDP-payload database (built at compile time from nmap-payloads), and depends only on standard async I/O — no privileged operations are required for the default TCP connect mode.

1.1 Component diagram

                           rustscan (single binary)
                                 │
        ┌────────────────────────┼────────────────────────┐
        │                        │                        │
   ┌────▼────┐            ┌──────▼──────┐          ┌──────▼──────┐
   │  Opts   │            │   Config    │          │  Scripts    │
   │ (CLAP)  │── merge ──▶│ (~/.toml)   │          │  registry   │
   └────┬────┘            └─────────────┘          └──────┬──────┘
        │                                                 │
        │                                                 │
        ▼                                                 │
  ┌─────────────┐    ┌─────────────────────┐              │
  │ address.rs  │───▶│  Vec<IpAddr>        │              │
  │ parse_*     │    │  (deduped, excluded)│              │
  └─────────────┘    └──────────┬──────────┘              │
                                │                         │
                     ┌──────────▼──────────┐              │
                     │  PortStrategy       │              │
                     │  Manual / Serial /  │              │
                     │  Random (LCG)       │              │
                     └──────────┬──────────┘              │
                                │                         │
                     ┌──────────▼──────────┐              │
                     │  SocketIterator     │              │
                     │  IP × Port product  │              │
                     └──────────┬──────────┘              │
                                │                         │
                     ┌──────────▼──────────┐              │
                     │  Scanner            │              │
                     │  FuturesUnordered   │              │
                     │  pool (batch_size)  │              │
                     │  TCP connect / UDP  │              │
                     └──────────┬──────────┘              │
                                │                         │
                     ┌──────────▼──────────┐    ┌─────────▼───────────┐
                     │ Vec<SocketAddr>     │───▶│ Default script      │
                     │ (open sockets)      │    │ → nmap -Pn -vvv -p X│
                     └─────────────────────┘    │ Custom script       │
                                                │ → user TOML defs    │
                                                │ None → just print   │
                                                └─────────────────────┘

Note

The pool is asynchronous but not multithreaded by default. Concurrency is via FuturesUnordered over async-std's single-runtime; the kernel does the heavy lifting through non-blocking sockets. That's why batch size is a function of file descriptors, not CPU cores.

1.2 Component inventory

1.3 Technology stack

1.4 Data flow for a single TCP scan

$ rustscan -a 10.0.0.0/24 -p 80,443 -- -A
       │
       │  (1) Opts::read()  → CLAP parses argv
       │  (2) Config::read() → TOML at $XDG_CONFIG_HOME/.rustscan.toml
       │  (3) opts.merge(&config) → CLI wins, missing fields filled from TOML
       ▼
   parse_addresses(&opts)
       ├─▶ each value: IPAddr::from_str → IpInet::from_str → DNS → file fallback
       ├─▶ exclude_addresses: same parsing, kept as Vec<IpCidr>
       └─▶ dedup via BTreeSet, drop excluded
       ▼
   PortStrategy::pick(range, ports, scan_order)
       ├─▶ Manual(ports) if explicit -p
       ├─▶ Serial(SerialRange) if -r and Serial order
       └─▶ Random(RandomRange{LCG}) if -r and Random order
       ▼
   Scanner::new(...)
       ├─▶ batch_size auto-tuned via infer_batch_size(opts, ulimit) on Unix
       └─▶ tries clamped to NonZeroU8 (0 → 1)
       ▼
   block_on(scanner.run())
       ├─▶ ports = strategy.order().filter(|p| !exclude_ports.contains(p))
       ├─▶ SocketIterator::new(&ips, &ports)  (port outer loop, IP inner)
       ├─▶ FuturesUnordered with batch_size in-flight
       ├─▶ each future: connect(socket, timeout=opts.timeout) × tries
       └─▶ panics if "too many open files" hits the assert
       ▼
   Vec<SocketAddr> open_sockets
       │
       │  group by IP → HashMap<IpAddr, Vec<u16>>
       ▼
   For each IP:
       ├─▶ if greppable: println!("{ip} -> [{ports}]") and continue
       ├─▶ if scripts == None: same as greppable
       └─▶ for each ScriptFile in scripts_to_run:
                 Script::build → Script::run
                 (default = nmap -Pn -vvv -p $PORTS [user args])
       ▼
   benchmarks.summary()  printed with RUST_LOG=info

2. System Requirements

2.1 Compile-time

2.2 Run-time

Note

RustScan does not require root for default TCP connect() scans. Root is needed only if you want --ulimit to actually raise RLIMIT_NOFILE above the soft limit, or if you want Nmap (called by the default script) to do raw-packet operations like -sS.

2.3 Network-policy requirements

3. Configuration Reference

This is the complete, source-based configuration surface. Anything not in these tables is not a valid setting.

3.1 Files

3.2 CLI flags (complete)

Sourced from src/input.rs::Opts (CLAP derive macros). Defaults are the literal default_value strings in the source.

The version flag is auto-injected by CLAP and prints rustscan 2.4.1 (sourced from CARGO_PKG_VERSION).

3.3 Config-file keys (complete)

Each key is the field name on the Config struct in src/input.rs. All are optional; missing keys leave the CLI default in place.

Important

Any TOML parse error aborts the run with Found {error} in configuration file. Aborting scan. This is intentional: silently dropping a typo'd flag would change scan semantics. Validate config files in CI with a linter such as taplo.

3.4 Merge semantics

Opts::merge(&self, &Config) is split into two phases:

• merge_required — for addresses, greppable, accessible, batch_size, timeout, tries, scan_order, scripts, command, udp, no_banner: if the config's value is Some, it overrides the CLI value. (The CLAP defaults are applied first, so the CLI baseline is always non-None.)
• merge_optional — for range, resolver, ulimit, exclude_ports, exclude_addresses: only applied when the CLI didn't set them and the config did. The exception is ports, which is only filled from the config when --top was passed on the CLI.

--no-config short-circuits both phases.

3.5 Environment variables

RustScan does not read any other environment variables.

4. Deployment & Scaling

4.1 Deployment patterns

4.2 Docker reference run

docker run --rm \
  --read-only --tmpfs /tmp \
  --network host \
  rustscan/rustscan:latest \
  -a 10.0.0.0/24 -r 1-1024 --no-banner -- -sV -oX /tmp/result.xml

--network host is needed if you want the container to scan over the host's interfaces and routes (which is usually what you want — RustScan is the scanner, not the target). For multi-tenant deployments, use a dedicated bridge network with deliberate egress rules instead.

Tip

Mount a config volume so analysts share a common policy: -v /etc/rustscan.toml:/root/.config/.rustscan.toml:ro. The container will pick it up automatically.

4.3 Scaling levers

For shard/parallel approaches, RustScan is stateless — there is no shared coordinator. Aggregate output via -g and any log shipper (Vector, Fluent Bit, journald + Loki, etc.).

4.4 Rolling out a new version

1. Build the image / binary with the new commit.
2. Smoke-test against scanme.nmap.org from staging (docker run rustscan/rustscan:NEW_VER -a scanme.nmap.org -r 22-100 -g).
3. Compare output against the previous version on the same target. Diffs in port list = behavioural change; investigate before promoting.
4. Promote in your registry, update Ansible/Helm references, restart consumer jobs.

There's no daemon and no on-disk state, so rollbacks are just swapping the image tag back.

5. Operations

RustScan is a stateless, short-lived process, so "operations" is mostly about running it predictably and getting useful telemetry out.

5.1 Logging

The binary uses the log crate gated by env_logger. Levels:

RUST_LOG=info rustscan -a 192.0.2.10 -- -sV

[~] RustScan: 1.243s
[~] Portscan: 0.812s
[~] Scripts:  0.314s

Note

The benchmark summary is the most useful operational signal. If Portscan time grows linearly across runs while ports stay similar, you've likely hit a network-side rate limit; reduce batch size or add a sleep between shards.

5.2 Output capture

The greppable format is stable in the sense that the source code structurally produces it ([println!("{} -> [{}]", &ip, ports_str)]) — but RustScan does not commit to it as machine-stable API. If you script around it, pin a version.

5.3 Health checks

There's nothing to liveness-probe — RustScan exits when it's done. For containerized service offerings, build your own health endpoint that runs rustscan --version and confirms the binary is callable.

5.4 Common runbooks

5.4.1 "A scheduled scan went 10x slower yesterday"

1. Pull RUST_LOG=info summary from yesterday vs. today.
2. If Portscan time changed dramatically: network/firewall side. Re-run with --tries 1 -t 800 -b 2000 to isolate timeout vs. throughput.
3. If Scripts time changed: the Nmap call is the variable. Run with --scripts none to confirm.

5.4.2 "RustScan reports zero open ports but I know SSH is open"

1. Re-run with RUST_LOG=debug to see actual connection errors.
2. Bisect: rustscan -a TARGET -p 22 --scripts none -t 5000 (single port, generous timeout).
3. If it still fails: routing / ACL issue, not RustScan.
4. If it succeeds: lower batch size in the original scan.

5.4.3 "We need to onboard a new team to RustScan"

1. Stand up a Docker image in your registry from a known commit.
2. Drop a shared config TOML into a config volume (addresses left blank, opinionated batch_size, tries, timeout).
3. Document the legal-authorization process before granting access (see Section 7).

Tip

Pre-populate command = ["-Pn", "-vvv", "--script", "default"] in the shared TOML so analysts can't accidentally escalate to noisy NSE scripts. Anything they pass after -- extends, doesn't replace.

5.4.4 "Trace a single port-scan to root cause"

RUST_LOG=debug rustscan -a TARGET -p 22 --scripts none -b 1 2>&1 \
  | tee scan.log

The -b 1 forces fully serial execution so the debug log is human-readable. The log contains Connection was successful, shutting down stream (success), or the exact io::Error string.

6. Performance

6.1 Where time goes

Per Benchmark::summary() output, a typical scan splits into three phases:

Portscan is almost always the biggest phase. Scripts is unpredictable because it's whatever Nmap does — version detection (-sV) can take longer than the entire scan.

6.2 Batch-size math

The infer_batch_size function (Unix only, in src/main.rs) implements:

let DEFAULT_FILE_DESCRIPTORS_LIMIT = 8000      // Ubuntu-typical
let AVERAGE_BATCH_SIZE             = 3000

if ulimit < batch_size:
    if ulimit < 3000:
        batch_size = ulimit / 2          # very tight; halve to leave headroom
    elif ulimit > 8000:
        batch_size = 3000                # generous ulimit, conservative batch
    else:
        batch_size = ulimit - 100        # ride right under the limit
else if ulimit + 2 > batch_size && opts.ulimit.is_none():
    log "[~] File limit higher than batch size. Can increase speed by '-b {ulimit-100}'."

On non-Unix, batch size is the constant AVERAGE_BATCH_SIZE = 3000.

Tip

The "useful warning" path (ulimit + 2 > batch_size && opts.ulimit.is_none()) is the easiest free speedup: it tells you the exact -b value to use. Capture stderr in CI, grep for '-b and feed the recommendation back into your runbook.

6.3 Memory profile

RustScan's memory grows with three things:

1. The IP list — Vec<IpAddr> (16 bytes each on 64-bit, plus overhead).
2. The port set — Vec<u16> (2 bytes each, up to 65,535 elements ~ 128 KB).
3. The in-flight pool — FuturesUnordered of size batch_size, where each entry is a connect() future plus a BTreeMap<Vec<u16>, Vec<u8>> clone for UDP scans.

A typical full-range scan of a /24 with batch_size=4500 runs in ~30-80 MB RSS depending on platform. Worst case (large CIDR, full range, UDP) is hundreds of MB; size containers accordingly.

6.4 Throughput tuning checklist

• [ ] nofile is at least batch_size + 200 (kernel keeps a few FDs for itself, stdin/stdout, etc.).
• [ ] --timeout is realistic — 1500 ms is generous on a LAN, tight on a transcontinental link.
• [ ] --tries is 1 unless you're on a known-lossy link; each retry is a full timeout.
• [ ] conntrack_max (Linux) > batch_size × number_of_targets; bumping nf_conntrack_max is sometimes the actual fix.
• [ ] Network MTU isn't dropping packets — TCP connect needs three packets; UDP probe is one.
• [ ] You're not double-NAT'ing through a slow appliance.

6.5 Benchmarks

benches/benchmark_portscan.rs uses the Criterion framework to micro-benchmark Scanner::run against 127.0.0.1. Run with:

cargo bench --bench benchmark_portscan

These numbers are useful for regression detection on the scanner core; they are not a real-world throughput estimate (loopback has no network costs).

7. Security

RustScan is a vulnerability-discovery / reconnaissance tool. Operating it correctly means thinking about three threat models:

1. You vs. the target — scanning is regulated; getting authorization wrong is a crime in most jurisdictions.
2. You vs. detection — RustScan's defaults are noisy; understand what an IDS will see.
3. The output vs. attackers — your scan results are an attacker's wish list.

7.1 Legal and authorization posture

Caution

Port scanning systems you do not own and have not been explicitly authorized to scan can violate the Computer Fraud and Abuse Act (US, 18 USC §1030), the Computer Misuse Act 1990 (UK), Article 202c StGB (Germany), and equivalent laws in most jurisdictions. RustScan ships no authorization framework — that responsibility is entirely yours.

Operational guidance:

• Maintain a written, signed statement of work (SOW) or Rules of Engagement (RoE) before scanning third-party infrastructure. Scope should specify CIDRs, port ranges, time windows, and contact persons.
• Internal scanning of your own infrastructure typically falls under a blanket security-team authorization; confirm with legal, especially in cloud (AWS / GCP / Azure all have AUPs about port scanning shared infrastructure).
• scanme.nmap.org (public) and your own loopback are the only universally safe targets.

7.2 Detection posture

RustScan's default behaviour is a fast, full-range TCP connect scan from a single source IP. Every reasonable IDS will flag it.

Warning

"Stealth" scans against systems you're authorized to test are fine. "Stealth" scans against systems you're not authorized to test are still illegal — the legality is independent of the noise level.

7.3 Output handling

Scan output describes attack surface. Treat it the way you'd treat any other recon artifact:

• Scan logs go to a private bucket with a short retention window (30-90 days unless evidence is needed for an ongoing engagement).
• Encrypt at rest. AWS S3 server-side encryption / GCS CMEK / Azure SSE — pick one and enforce via bucket policy.
• Restrict access to the security team only. Audit log every read.
• Strip / mask before sharing with clients — internal IPs, internal hostnames, and user-agent fingerprints can leak more than you intended.
• For multi-client engagements, segregate output by client into separate prefixes / projects with hard IAM boundaries.

Important

Greppable output (-g) is structured but not stable across versions. Version-pin RustScan (or the Docker image) for any pipeline that parses its output as data.

7.4 Logging posture

What to log:

• Operator identity (who ran the scan).
• Authorization reference (SOW / RoE id).
• Target scope (-a and -r values).
• Time window (start, end, duration).
• Source IP and egress path.
• Tool version (rustscan --version).

What not to log persistently:

• Per-port success/failure timing — useful for debug only, not retained.
• Full Nmap NSE script output where it contains harvested credentials, version banners, or service-specific data — segregate to client-restricted storage.

7.5 Default rate limits and avoiding IDS lockouts

RustScan has no built-in rate limiter — batch_size is the only knob. The kernel's TCP stack provides natural backpressure when nofile is exhausted, and that's it.

To avoid being detected:

• Stay under whatever flow-rate threshold your target IDS uses (commonly 100 SYN/sec/source). With default -b 4500 -t 1500, RustScan can easily exceed that for a /24.
• Throttle by lowering -b and shard by host: scan one /28 at a time with -b 500.
• Combine with --scan-order random so the bursts aren't temporally clustered on adjacent ports.
• For long-running engagements, distribute scans across multiple egress points (different VPC / different VPN endpoint).

7.6 Supply-chain considerations

• Cargo.lock is committed; lto = true and panic = 'abort' in [profile.release] keep the binary small and the panic behaviour deterministic.
• Compile with --locked (cargo install --locked rustscan) to refuse silent dependency drift.
• The Docker image bundles Nmap; track Nmap CVEs, not just RustScan ones.
• The project carries a .travis.yml and CI history but the canonical CI configuration in newer revisions may live in .github/workflows/; verify against the source commit you're deploying.

7.7 Code-level safety properties

• The crate compiles under #![deny(clippy::all)] and #![warn(clippy::pedantic)]. New code that adds unsafe blocks or unhandled panics will fail CI.
• The "too many open files" assertion in scan_socket is intentional: rather than silently degrading, RustScan panics so an automated wrapper sees a non-zero exit and can re-tune. Do not "fix" this by removing the assert.
• Opts::default() initialises every field; tests rely on it. If you add a new option, update both the struct, Default, and Config.

8. Developer Internals

8.1 Repository layout

RustScan/
├── Cargo.toml                       Crate manifest — pinned deps, package metadata
├── Cargo.lock                       Reproducible build (committed)
├── build.rs                         Compile-time generator → src/generated.rs
├── nmap-payloads                    UDP probe database (text)
├── config.toml                      Embedded top-1000 ports for --top
├── Makefile / justfile / release.sh Convenience scripts
├── contributing.Dockerfile          Dev container for contributors
├── src/
│   ├── main.rs                      Entry point, batch-size math, opening banner
│   ├── lib.rs                       Public API (mod declarations + doc example)
│   ├── input.rs                     Opts, Config, ScanOrder, ScriptsRequired, PortRange
│   ├── address.rs                   IP/CIDR/host/file parsing, exclusions, DNS
│   ├── tui.rs                       warning! / detail! / output! / funny_opening!
│   ├── benchmark/mod.rs             NamedTimer + Benchmark struct
│   ├── port_strategy/
│   │   ├── mod.rs                   PortStrategy enum + Serial/Random
│   │   └── range_iterator.rs        LCG RangeIterator
│   ├── scanner/
│   │   ├── mod.rs                   Scanner core, scan_socket, scan_udp_socket
│   │   └── socket_iterator.rs       (port × ip) cartesian product
│   └── scripts/mod.rs               Script registry, builder, runner
├── tests/timelimits.rs              Integration tests with timeouts (ignored by default)
├── benches/benchmark_portscan.rs    Criterion micro-benchmark
└── fixtures/                        Test data (hosts.txt, naughty_strings.txt, etc.)

Note

src/generated.rs is not committed; it's produced by build.rs from nmap-payloads on first build. Check .gitignore to confirm.

8.2 Public library API

The rustscan crate is also a Rust library. The public surface (per src/lib.rs and the modules it re-exports):

use std::{net::IpAddr, time::Duration};
use async_std::task::block_on;

use rustscan::input::{PortRange, ScanOrder};
use rustscan::port_strategy::PortStrategy;
use rustscan::scanner::Scanner;

fn main() {
    let addrs = vec!["127.0.0.1".parse::<IpAddr>().unwrap()];
    let range = PortRange { start: 1, end: 1_000 };

    let strategy = PortStrategy::pick(&Some(range), None, ScanOrder::Random);

    let scanner = Scanner::new(
        &addrs,
        10,                              // batch_size
        Duration::from_millis(100),      // timeout
        1,                               // tries
        true,                            // greppable
        strategy,
        true,                            // accessible
        vec![9000],                      // exclude_ports
        false,                           // udp
    );

    let scan_result = block_on(scanner.run());
    println!("{:?}", scan_result);
}

Public items (selected) — all from src/:

• rustscan::input::{Opts, Config, ScanOrder, ScriptsRequired, PortRange, default_config_path, old_default_config_path}
• rustscan::address::{parse_addresses, parse_address, parse_excluded_networks}
• rustscan::scanner::Scanner
• rustscan::port_strategy::PortStrategy
• rustscan::scripts::{init_scripts, Script, ScriptFile}
• rustscan::benchmark::{Benchmark, NamedTimer}
• Macros (re-exported): warning!, detail!, output!, funny_opening!

8.3 The async port-scanning pool

Scanner::run is the heart of RustScan. The pseudocode:

pub async fn run(&self) -> Vec<SocketAddr> {
    let ports = self.port_strategy.order()
        .into_iter()
        .filter(|p| !self.exclude_ports.contains(p))
        .collect::<Vec<u16>>();

    let mut socket_iterator = SocketIterator::new(&self.ips, &ports);
    let mut futures        = FuturesUnordered::new();
    let mut open_sockets   = Vec::new();

    // Prime the pool
    for _ in 0..self.batch_size {
        if let Some(s) = socket_iterator.next() {
            futures.push(self.scan_socket(s, udp_map.clone()));
        } else {
            break;
        }
    }

    // Drain + refill: each completed future is replaced by one fresh socket
    while let Some(result) = futures.next().await {
        if let Some(s) = socket_iterator.next() {
            futures.push(self.scan_socket(s, udp_map.clone()));
        }
        if let Ok(socket) = result {
            open_sockets.push(socket);
        }
    }

    open_sockets
}

Two design choices to know:

1. Fixed-size pool. Concurrency is at most batch_size in-flight sockets. This is the only knob that controls pressure on the network and the local FD table.
2. Cartesian iteration order. SocketIterator yields (port, ip) in the form "all IPs for port 22, then all IPs for port 23, ..." — visible in the test in src/scanner/socket_iterator.rs. This distributes load instead of pounding one host at a time.

8.4 Per-socket scan path

scan_socket (TCP):

1. Try connect(socket) with a self.timeout deadline.
2. On Ok: shutdown the stream both ways, format and print "Open IP:PORT" (unless greppable), return Ok(socket).
3. On Err containing "too many open files" (case-insensitive): assert-fail with a remediation message — by design.
4. On any other error: retry up to self.tries times, then return Err(io::Error::other(error_string)) with the IP appended.

scan_udp_socket (UDP):

1. Look up the port in the embedded payload BTreeMap.
2. Bind a local UDP socket, send the payload, recv with timeout.
3. On a non-empty response: success.
4. On timeout: not open (continue with next try).
5. After all tries: Err.

8.5 The Linear Congruential Generator (random scan order)

Random order isn't a Vec::shuffle — it's an LCG that produces a non-repeating permutation of the range without storing the full vector first:

For range [start, end], normalize to [0, end - start]:
    step = pick_random_coprime(end - start + 1)
    first_pick = rng.random_range(0..normalized_end)
    next(N) = (current + step) % normalized_end
    iteration ends when next == first_pick

pick_random_coprime searches up to 10 candidates in the middle half of the range (end/4..end - end/4); if none are coprime, it falls back to end - 1 (always coprime with end).

Why care: the iterator avoids cluster-of-adjacent-ports patterns even compared to a pre-shuffled vector, because a coprime step deliberately makes consecutive picks far apart.

8.6 Address parsing pipeline

parse_addresses (in src/address.rs) handles four input shapes for each token in -a:

1. IpAddr::from_str — bare IPv4 / IPv6 → single-element Vec<IpAddr>.
2. IpInet::from_str — CIDR → expand via cidr_utils to all host addresses.
3. to_socket_addrs("{addr}:80") — system DNS lookup → first resolved IP.
4. backup_resolver.lookup_ip — fallback DNS-over-TLS resolver if (3) fails.
5. If still empty, treat the token as a file path: read line-by-line and recurse.

Final dedup is via BTreeSet<IpAddr>; exclusions (from -x) are subtracted with IpCidr::contains.

Note

The DNS fallback uses ResolverConfig::cloudflare_tls() (1.1.1.1 over DoT) when /etc/resolv.conf can't be parsed. If you can't tolerate that egress, pass --resolver with your own list (or 127.0.0.1 to force a local resolver).

8.7 Scripting engine (Rhai-style descriptors)

Note

Scripts in RustScan 2.4.1 are TOML descriptors that parameterize an external shell command — not in-process Rhai/Lua execution. The src/scripts/mod.rs module loads ~/.rustscan_scripts/*.toml and .rustscan_scripts.toml, validates required fields, and produces a ScriptFile per descriptor. At scan time, each ScriptFile is rendered via the text_placeholder crate ({{ip}}, {{port}}) and executed with std::process::Command.

Descriptor fields the project recognizes (per Script::build):

The default-mode script is the well-known Nmap handoff — its call_format is something like:

nmap -Pn -vvv -p {{port}} {{ip}}

…with command from Opts appended at runtime, which is how user -- -A -sC ends up at the end of the Nmap call.

--scripts none short-circuits the loop: RustScan still resolves and scans, then prints IP -> [PORTS] and exits. --scripts custom loads only descriptors matched against tags from ~/.rustscan_scripts.toml.

8.8 Code patterns and conventions

• #![deny(clippy::all)] + #![warn(clippy::pedantic)] in src/main.rs enforce a strict lint profile. New code that fails clippy fails CI.
• #[cfg(not(tarpaulin_include))] marks blocks excluded from coverage measurement (typically functions whose effect is observable only in main).
• #[cfg(unix)] gates rlimit-based logic; the #[cfg(not(unix))] branch sets a fixed AVERAGE_BATCH_SIZE = 3000.
• TUI macros in src/tui.rs are dual-form: warning!("msg") is the simple form; warning!("msg", greppable, accessible) honours operator-mode flags. Always prefer the three-arg form in new code so --accessible / -g stay correct.
• Tests live next to source in #[cfg(test)] mod tests, plus integration tests in tests/timelimits.rs and benches in benches/.
• Default-implementations are explicit. Opts::default() is hand-written (not #[derive(Default)]) because some defaults differ from the type defaults (e.g., greppable: true in Default, false in CLAP — that's deliberate; the Default is for tests).

8.9 Testing strategy

Run the full local test sweep with:

ulimit -n 5000 && cargo test && cargo test timelimits:: -- --ignored --test-threads=1 --show-output

(That's the literal command from .travis.yml.)

8.10 Potential improvements (open features in upstream)

8.11 Contributing workflow

1. Fork → branch from master.
2. Implement the change. New crates go in Cargo.toml with explicit version pins.
3. cargo fmt --all (Travis enforces this).
4. cargo test and cargo clippy --all-targets -- -D warnings.
5. Update tests next to source; if it touches scanning behaviour, add an integration test in tests/.
6. PR with a clear before/after — the clippy + format gate catches the rest.

9. Integration Points

RustScan is deliberately small; integration is mostly about the seam at the command-line, the seam at Nmap, and the seam at the public Rust crate.

9.1 With Nmap

The default --scripts default mode invokes Nmap with at minimum -Pn -vvv -p $PORTS $IP, plus anything you appended after --. Practical implications:

• Nmap is mandatory unless you set --scripts none. The .deb package declares it as a dependency; the Docker image ships it.
• All Nmap behaviour — version detection, OS fingerprint, NSE — is configured via the trailing --. You don't need a wrapper script to get Nmap features.
• Nmap output appears on stdout interleaved with RustScan's lines. If your downstream parser is brittle, run with -g --scripts none to get only RustScan's output, then call Nmap separately.

9.2 Shell pipelines

Greppable mode (-g) makes RustScan a first-class citizen in any tool chain that reads IP -> [PORTS]:

rustscan -g --no-banner -a 10.0.0.0/24 -r 1-1024 \
  | tee scans/$(date +%F).txt \
  | awk -F' -> ' '$2 != "[]"' \
  | mail -s "Open ports today" [email removed]

For structured downstream tools, write your own greppable parser:

import re, subprocess
out = subprocess.check_output(["rustscan", "-g", "-a", "10.0.0.0/24"], text=True)
for line in out.splitlines():
    m = re.match(r'(\S+) -> \[(.*)\]', line)
    if not m: continue
    ip, ports = m.group(1), [int(p) for p in m.group(2).split(',') if p]
    yield ip, ports

9.3 As a Rust library

Add to your Cargo.toml:

[dependencies]
rustscan = "2.4"
async-std = "1.13"
futures = "0.3"

Drive the scanner directly from your code (see Section 8.2 for the canonical example). The library doesn't pull in CLAP unless you depend on it through rustscan::input::Opts::parse(), but the main scanning path (Scanner + PortStrategy + parse_addresses) is dependency-light.

9.4 In CI

# GitHub Actions
- uses: docker://rustscan/rustscan:latest
  with:
    args: >-
      -g --no-banner --scripts none
      -a ${{ secrets.SCAN_TARGET }}
      -r 1-1024

The container starts, scans, prints, exits. Pair with actions/upload-artifact to retain results for the security team.

9.5 SIEM ingestion

Greppable output ships well into:

• Splunk / Elastic: line-based IP -> [PORTS] with timestamp from the log shipper.
• Loki: same, with job=rustscan label.
• Datadog Logs: parse with a custom grok pattern (?<ip>%{IP}) -> \[(?<ports>[^\]]*)\].

Don't ingest the full default output (banner + Nmap interleaved) — it's interactive-shaped, not log-shaped.

9.6 Container orchestration

RustScan exits when done; there is no idle process to keep alive. For Kubernetes:

• Run as a Job (or CronJob for scheduled scans).
• restartPolicy: OnFailure so a transient DNS hiccup retries.
• securityContext.capabilities.add: ["SYS_RESOURCE"] if you want --ulimit to actually raise FDs.
• Bind the config TOML with a ConfigMap volume if your team shares a policy.

9.7 What RustScan does NOT integrate with

To keep the negative-knowledge surface explicit:

• No daemon mode. RustScan does not run as a long-lived service. There is no socket, no REST endpoint, no metrics scrape target.
• No webhook / event push. It writes to stdout and exits. Hook your own.
• No proxy support. Tracked in #825. Use proxychains or namespace routing.
• No raw SYN scanning. Connect-only. Use Nmap -sS after the fact for that.
• No IPv4-mapped IPv6 special casing. Whatever the resolver returns is what RustScan scans.
• No persistence. No database, no on-disk cache. Each run is independent.