1ZMAP(1) zmap ZMAP(1)
2
3
4
6 zmap - The Fast Internet Scanner
7
9 zmap [ -p <port> ] [ -o <outfile> ] [ OPTIONS... ] [ ip/hostname/range
10 ]
11
13 ZMap is a network tool for scanning the entire IPv4 address space (or
14 large samples). ZMap is capable of scanning the entire Internet in
15 around 45 minutes on a gigabit network connection, reaching ~98% theo‐
16 retical line speed.
17
19 BASIC OPTIONS
20 ip/hostname/range
21 IP addresses or DNS hostnames to scan. Accepts IP ranges in CIDR
22 block notation. Defaults to 0.0.0/8
23
24 -p, --target-port=port
25 TCP or UDP port number to scan (for SYN scans and basic UDP
26 scans)
27
28 -o, --output-file=name
29 When using an output module that uses a file, write results to
30 this file. Use - for stdout.
31
32 -b, --blocklist-file=path
33 File of subnets to exclude, in CIDR notation, one-per line. It
34 is recommended you use this to exclude RFC 1918 addresses, mul‐
35 ticast, IANA reserved space, and other IANA special-purpose ad‐
36 dresses. An example blocklist file blocklist.conf for this pur‐
37 pose.
38
39 -w, --allowlist-file=path
40 File of subnets to scan, in CIDR notation, one-per line. Speci‐
41 fying a allowlist file is equivalent to specifying to ranges di‐
42 rectly on the command line interface, but allows specifying a
43 large number of subnets. Note: if you are specifying a large
44 number of individual IP addresses (more than 10 million), you
45 should instead use --list-of-ips-file.
46
47 -I, --list-of-ips-file=path
48 File of individual IP addresses to scan, one-per line. This fea‐
49 ture allows you to scan a large number of unrelated addresses.
50 If you have a small number of IPs, it is faster to specify these
51 on the command line or by using --allowlist-file. This should
52 only be used when scanning more than 10 million addresses. When
53 used in with --allowlist-path, only hosts in the intersection of
54 both sets will be scanned. Hosts specified here, but included in
55 the blocklist will be excluded.
56
57 SCAN OPTIONS
58 -r, --rate=pps
59 Set the send rate in packets/sec. Note: when combined with
60 --probes, this is total packets per second, not IPs per second.
61
62 -B, --bandwidth=bps
63 Set the send rate in bits/second (supports suffixes G, M, and K
64 (e.g. -B 10M for 10 mbps). This overrides the --rate flag.
65
66 -n, --max-targets=n
67 Cap the number of targets to probe. This can either be a number
68 (e.g. -n 1000) or a percentage (e.g. -n 0.1%) of the scannable
69 address space (after excluding blocklist)
70
71 -N, --max-results=n
72 Exit after receiving this many results
73
74 -t, --max-runtime=secs
75 Cap the length of time for sending packets
76
77 -c, --cooldown-time=secs
78 How long to continue receiving after sending has completed (de‐
79 fault=8)
80
81 -e, --seed=n
82 Seed used to select address permutation. Use this if you want to
83 scan addresses in the same order for multiple ZMap runs.
84
85 --shards=N
86 Split the scan up into N shards/partitions among different in‐
87 stances of zmap (default=1). When sharding, --seed is required.
88
89 --shard=n
90 Set which shard to scan (default=0). Shards are 0-indexed in the
91 range [0, N), where N is the total number of shards. When shard‐
92 ing --seed is required.
93
94 -P, --probes=n
95 Number of probes to send to each IP (default=1)
96
97 --retries=n
98 Number of times to try resending a packet if the sendto call
99 fails (default=10)
100
101 NETWORK OPTIONS
102 -s, --source-port=port|range
103 Source port(s) to send packets from
104
105 -S, --source-ip=ip|range
106 Source address(es) to send packets from. Either single IP or
107 range (e.g. 10.0.0.1-10.0.0.9)
108
109 -G, --gateway-mac=addr
110 Gateway MAC address to send packets to (in case auto-detection
111 fails)
112
113 --source-mac=addr
114 Source MAC address to send packets from (in case auto-detection
115 fails)
116
117 -i, --interface=name
118 Network interface to use
119
120 -X, --iplayer
121 Send IP layer packets instead of ethernet packets (for non-Eth‐
122 ernet interface)
123
124 PROBE OPTIONS
125 ZMap allows users to specify and write their own probe modules. Probe
126 modules are responsible for generating probe packets to send, and pro‐
127 cessing responses from hosts.
128
129 --list-probe-modules
130 List available probe modules (e.g. tcp_synscan)
131
132 -M, --probe-module=name
133 Select probe module (default=tcp_synscan)
134
135 --probe-args=args
136 Arguments to pass to probe module
137
138 --list-output-fields
139 List the fields the selected probe module can send to the output
140 module
141
142 OUTPUT OPTIONS
143 ZMap allows users to specify and write their own output modules for use
144 with ZMap. Output modules are responsible for processing the fieldsets
145 returned by the probe module, and outputting them to the user. Users
146 can specify output fields, and write filters over the output fields.
147
148 --list-output-modules
149 List available output modules (e.g. csv)
150
151 -O, --output-module=name
152 Select output module (default=csv)
153
154 --output-args=args
155 Arguments to pass to output module
156
157 -f, --output-fields=fields
158 Comma-separated list of fields to output
159
160 --output-filter
161 Specify an output filter over the fields defined by the probe
162 module. See the output filter section for more details.
163
164 LOGGING AND METADATA OPTIONS
165 -q, --quiet
166 Do not print status updates once per second
167
168 -v, --verbosity=n
169 Level of log detail (0-5, default=3)
170
171 -l, --log-file=filename
172 Output file for log messages. By default, stderr.
173
174 -m, --metadata-file=filename
175 Output file for scan metadata (JSON)
176
177 -L, --log-directory
178 Write log entries to a timestamped file in this directory
179
180 -u, --status-updates-file
181 Write scan progress updates to CSV file"
182
183 --disable-syslog
184 Disables logging messages to syslog
185
186 --notes
187 Inject user-specified notes into scan metadata
188
189 --user-metadata
190 Inject user-specified JSON metadata into scan metadata
191
192 ADDITIONAL OPTIONS
193 -T, --sender-threads=n
194 Threads used to send packets. ZMap will attempt to detect the
195 optimal number of send threads based on the number of processor
196 cores.
197
198 -C, --config=filename
199 Read a configuration file, which can specify any other options.
200
201 -d, --dryrun
202 Print out each packet to stdout instead of sending it (useful
203 for debugging)
204
205 --max-sendto-failures
206 Maximum NIC sendto failures before scan is aborted
207
208 --min-hitrate
209 Minimum hitrate that scan can hit before scan is aborted
210
211 --cores
212 Comma-separated list of cores to pin to
213
214 --ignore-blocklist-errors
215 Ignore invalid, malformed, or unresolvable entries in al‐
216 lowlist/blocklist file. Replaces the pre-v3.x --ignore-in‐
217 valid-hosts option.
218
219 -h, --help
220 Print help and exit
221
222 -V, --version
223 Print version and exit
224
225 OUTPUT FILTERS
226 Results generated by a probe module can be filtered before being passed
227 to the output module. Filters are defined over the output fields of a
228 probe module. Filters are written in a simple filtering language, simi‐
229 lar to SQL, and are passed to ZMap using the --output-filter option.
230 Output filters are commonly used to filter out duplicate results, or to
231 only pass only successful responses to the output module.
232
233 Filter expressions are of the form <fieldname> <operation> <value>. The
234 type of <value> must be either a string or unsigned integer literal,
235 and match the type of <fieldname>. The valid operations for integer
236 comparisons are = !=, ,, =,=. The operations for string comparisons are
237 =, !=. The --list-output-fields flag will print what fields and types
238 are available for the selected probe module, and then exit.
239
240 Compound filter expressions may be constructed by combining filter ex‐
241 pressions using parenthesis to specify order of operations, the &&
242 (logical AND) and || (logical OR) operators.
243
244 For example, a filter for only successful, non-duplicate responses
245 would be written as: --output-filter="success = 1 && repeat = 0"
246
247 UDP PROBE MODULE OPTIONS
248 These arguments are all passed using the --probe-args=args option. Only
249 one argument may be passed at a time.
250
251 file:/path/to/file
252 Path to payload file to send to each host over UDP.
253
254 template:/path/to/template
255 Path to template file. For each destination host, the template
256 file is populated, set as the UDP payload, and sent.
257
258 text:<text>
259 ASCII text to send to each destination host
260
261 hex:<hex>
262 Hex-encoded binary to send to each destination host
263
264 template-fields
265 Print information about the allowed template fields and exit.
266
267 MID-SCAN CHANGES
268 You can change the rate at which ZMap is scanning mid-scan by sending
269 SIGUSR1 (increase) and SIGUSR2 (decrease) signals to ZMap. These will
270 result in the scan rate increasing or decreasing by 5%.
271
272
273
274ZMap June 2017 ZMAP(1)