zmap(1) zmap zmap(1)
NAME
zmap - The Fast Internet Scanner
SYNOPSIS
zmap [ -p <port(s)> ] [ -o <outfile> ] [ OPTIONS... ] [
ip/hostname/range ]
DESCRIPTION
ZMap is a network tool for scanning the entire IPv4 address space (or
large samples). ZMap is capable of scanning the entire Internet in
around 45 minutes on a gigabit network connection, reaching ~98%
theoretical line speed.
OPTIONS
BASIC OPTIONS
ip/hostname/range
IP addresses or DNS hostnames to scan. Accepts IP ranges in CIDR
block notation. Defaults to 0.0.0/8
-p, --target-ports=port(s)
List of TCP/UDP ports and/or port ranges to scan (e.g.,
80,443,100-105). Use '*' to scan all ports, including port 0.
-o, --output-file=name
When using an output module that uses a file, write results to
this file. Use - for stdout.
-b, --blocklist-file=path
File of subnets to exclude, in CIDR notation, one-per line. It
is recommended you use this to exclude RFC 1918 addresses,
multicast, IANA reserved space, and other IANA special-purpose
addresses. An example blocklist file blocklist.conf for this
purpose.
-w, --allowlist-file=path
File of subnets to scan, in CIDR notation, one-per line.
Specifying a allowlist file is equivalent to specifying to
ranges directly on the command line interface, but allows
specifying a large number of subnets. Note: if you are
specifying a large number of individual IP addresses (more than
10 million), you should instead use --list-of-ips-file.
-I, --list-of-ips-file=path
File of individual IP addresses to scan, one-per line. This
feature allows you to scan a large number of unrelated
addresses. If you have a small number of IPs, it is faster to
specify these on the command line or by using --allowlist-file.
This should only be used when scanning more than 10 million
addresses. When used in with --allowlist-path, only hosts in the
intersection of both sets will be scanned. Hosts specified here,
but included in the blocklist will be excluded.
SCAN OPTIONS
-r, --rate=pps
Set the send rate in packets/sec. Note: when combined with
--probes, this is total packets per second, not IPs per second.
Setting the rate to 0 will scan at full line rate. Default:
10000 pps.
-B, --bandwidth=bps
Set the send rate in bits/second (supports suffixes G, M, and K
(e.g. -B 10M for 10 mbps). This overrides the --rate flag.
-n, --max-targets=n
Cap the number of targets to probe. This can either be a number
(e.g. -n 1000) or a percentage (e.g. -n 0.1%) of the scannable
address space (after excluding blocklist). A target is an
IP/port pair, if scanning multiple ports, and an IP otherwise.
-N, --max-results=n
Exit after receiving this many results
-t, --max-runtime=secs
Cap the length of time for sending packets
-c, --cooldown-time=secs
How long to continue receiving after sending has completed
(default=8)
-e, --seed=n
Seed used to select address permutation. Use this if you want to
scan addresses in the same order for multiple ZMap runs.
-P, --probes=n
Number of probes to send to each IP/Port pair (default=1). Since
ZMap composes Ethernet frames directly, probes can be lost
en-route to destination. Increasing the --probes increases the
chance that an online host will receive a probe in an unreliable
network. This is contrasted with --retries which just gives the
number of attempts to send a single probe on the source NIC.
--retries=n
Number of times to try resending a packet if the sendto call
fails (default=10)
--batch=n
Number of packets to batch before calling the appropriate
syscall to send. Used to take advantage of Linux's sendmmsg
syscall to send the entire batch at once. Only available on
Linux, other OS's will send each packet individually.
(default=64)
SCAN SHARDING
--shards=N
Split the scan up into N shards/partitions among different
instances of zmap (default=1). When sharding, --seed is
required.
--shard=n
Set which shard to scan (default=0). Shards are 0-indexed in the
range [0, N), where N is the total number of shards. When
sharding --seed is required.
NETWORK OPTIONS
-s, --source-port=port|range
Source port(s) to send packets from
-S, --source-ip=ip|range
Source address(es) to send packets from. Either single IP or
range (e.g. 10.0.0.1-10.0.0.9)
-G, --gateway-mac=addr
Gateway MAC address to send packets to (in case auto-detection
fails)
--source-mac=addr
Source MAC address to send packets from (in case auto-detection
fails)
-i, --interface=name
Network interface to use
-X, --iplayer
Send IP layer packets instead of ethernet packets (for
non-Ethernet interface)
--netmap-wait-ping=ip
(Netmap only) Wait for ip to respond to ICMP Echo request before
commencing scan. Useful if connected to a switch with STP
enabled, where the PHY reset that is needed for entering and
leaving Netmap mode will cause the switch to mute the port until
the spanning tree protocol has determined that the link should
be set into forward state.
PROBE OPTIONS
ZMap allows users to specify and write their own probe modules. Probe
modules are responsible for generating probe packets to send, and
processing responses from hosts.
--list-probe-modules
List available probe modules (e.g. tcp_synscan)
-M, --probe-module=name
Select probe module (default=tcp_synscan)
--probe-args=args
Arguments to pass to probe module
--probe-ttl=hops
Set TTL value for probe IP packets
--list-output-fields
List the fields the selected probe module can send to the output
module
OUTPUT OPTIONS
ZMap allows users to specify and write their own output modules for use
with ZMap. Output modules are responsible for processing the fieldsets
returned by the probe module, and outputting them to the user. Users
can specify output fields, and write filters over the output fields.
--list-output-modules
List available output modules (e.g. csv)
-O, --output-module=name
Select output module (default=csv)
--output-args=args
Arguments to pass to output module
-f, --output-fields=fields
Comma-separated list of fields to output
--output-filter
Specify an output filter over the fields defined by the probe
module. See the output filter section for more details.
--no-header-row
Excludes any header rows (e.g., CSV header fields) from ZMap
output. This is useful if you're piping results into another
application that expects only data.
RESPONSE DEDUPLICATION
Hosts will oftentimes send multiple responses to a probe (either
because the scanner doesn't send back a RST packet or because the host
has a misimplemented TCP stack. To address this, ZMap will attempt to
deduplicate responsive (ip,port) targets.
--dedup-method
Specifies the method ZMap will use to deduplicate responses.
Options are: full, window, and none. Full deduplication uses a
32-bit bitmap and guarantees that no duplicates will be emitted.
However, full-deduplication requires around 500MB of memory for
a single port. We do not support full deduplication for multiple
ports. Window uses a sliding window of the last (user-defined)
number of responses as set by --dedup-window-size. None will
prevent any deduplication.
--dedup-window-size=targets
Specifies the size of the sliding window as the last n target
responses to be used for deduplication. Only applicable if using
window deduplication.
LOGGING AND METADATA OPTIONS
-q, --quiet
Do not print status updates once per second
-v, --verbosity=n
Level of log detail (0-5, default=3)
-l, --log-file=filename
Output file for log messages. By default, stderr.
-m, --metadata-file=filename
Output file for scan metadata (JSON)
-L, --log-directory
Write log entries to a timestamped file in this directory
-u, --status-updates-file
Write scan progress updates to CSV file"
--disable-syslog
Disables logging messages to syslog
--notes
Inject user-specified notes into scan metadata
--user-metadata
Inject user-specified JSON metadata into scan metadata
ADDITIONAL OPTIONS
-T, --sender-threads=n
Threads used to send packets. ZMap will attempt to detect the
optimal number of send threads based on the number of processor
cores. Defaults to min(4, number of processor cores on host -
1).
-C, --config=filename
Read a configuration file, which can specify any other options.
-d, --dryrun
Print out each packet to stdout instead of sending it (useful
for debugging)
--max-sendto-failures
Maximum NIC sendto failures before scan is aborted
--min-hitrate
Minimum hitrate that scan can hit before scan is aborted
--cores
Comma-separated list of cores to pin to
--ignore-blocklist-errors
Ignore invalid, malformed, or unresolvable entries in
allowlist/blocklist file. Replaces the pre-v3.x
--ignore-invalid-hosts option.
-h, --help
Print help and exit
-V, --version
Print version and exit
OUTPUT FILTERS
Results generated by a probe module can be filtered before being passed
to the output module. Filters are defined over the output fields of a
probe module. Filters are written in a simple filtering language,
similar to SQL, and are passed to ZMap using the --output-filter
option. Output filters are commonly used to filter out duplicate
results, or to only pass only successful responses to the output
module.
Filter expressions are of the form <fieldname> <operation> <value>. The
type of <value> must be either a string or unsigned integer literal,
and match the type of <fieldname>. The valid operations for integer
comparisons are = !=, ,, =,=. The operations for string comparisons are
=, !=. The --list-output-fields flag will print what fields and types
are available for the selected probe module, and then exit.
Compound filter expressions may be constructed by combining filter
expressions using parenthesis to specify order of operations, the &&
(logical AND) and || (logical OR) operators.
For example, a filter for only successful, non-duplicate responses
would be written as: --output-filter="success = 1 && repeat = 0"
UDP PROBE MODULE OPTIONS
These arguments are all passed using the --probe-args=args option. Only
one argument may be passed at a time.
file:/path/to/file
Path to payload file to send to each host over UDP.
template:/path/to/template
Path to template file. For each destination host, the template
file is populated, set as the UDP payload, and sent.
text:<text>
ASCII text to send to each destination host
hex:<hex>
Hex-encoded binary to send to each destination host
template-fields
Print information about the allowed template fields and exit.
MID-SCAN CHANGES
You can change the rate at which ZMap is scanning mid-scan by sending
SIGUSR1 (increase) and SIGUSR2 (decrease) signals to ZMap. These will
result in the scan rate increasing or decreasing by 5%.
ZMap March 2024 zmap(1)
zmap 4.1.0-RC2 - Generated Tue May 7 18:26:52 CDT 2024