Results Output - zmap/zmap GitHub Wiki

ZMap can produce results in several formats through the use of output modules. By default, ZMap only supports CSV and JSON output. The results sent to these output modules may be filtered using an output filter. The fields the output module writes are specified by the user. By default, ZMap will return results in CSV format and if no output file is specified, ZMap will not produce specific results. It is also possible to write your own output module; see Writing Output Modules for information.

• -o, --output-file=p File to write output to
• -O, --output-module=p Invoke a custom output module
• -f, --output-fields=p Comma-separated list of fields to output
• --output-filter=filter Specify an output filter over fields for a given probe
• --list-output-modules Lists available output modules
• --list-output-fields List available output fields for a given probe

ZMap has a variety of fields it can output beyond IP address. These fields can be viewed for a given probe module by running with the --list-output-fields flag.

$ zmap --probe-module="tcp_synscan" --list-output-fields
saddr           string: source IP address of response
saddr_raw          int: network order integer form of source IP address
daddr           string: destination IP address of response
daddr_raw          int: network order integer form of destination IP address
ipid               int: IP identification number of response
ttl                int: time-to-live of response packet
sport              int: TCP source port
dport              int: TCP destination port
seqnum             int: TCP sequence number
acknum             int: TCP acknowledgement number
window             int: TCP window
classification  string: packet classification
success           bool: is response considered success
icmp_responder  string: Source IP of ICMP_UNREACH messages
icmp_type          int: icmp message type
icmp_code          int: icmp message sub type code
icmp_unreach_str string: for icmp_unreach responses, the string version of icmp_code (e.g. network-unreach)
repeat            bool: Is response a repeat response from host
cooldown          bool: Was response received during the cooldown period
timestamp_str   string: timestamp of when response arrived in ISO8601 format.
timestamp_ts       int: timestamp of when response arrived in seconds since Epoch
timestamp_us       int: microsecond part of timestamp (e.g. microseconds since 'timestamp-ts')

To select which fields to output, any combination of the output fields can be specified as a comma-separated list using the --output-fields=fields or -f flags. Example:

$ zmap -p 80 -f "saddr,daddr,sport,seq,ack,cooldown,repeat,timestamp_str" -o output.csv

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 must be either a string or unsigned integer literal, and match the type of . 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.

Write a filter for only successful, non-duplicate responses:

--output-filter="success = 1 && repeat = 0"

Filter for packets that have classification RST and a TTL greater than 10, or for packets with classification SYNACK

--output-filter="(classification = rst && ttl > 10) || classification = synack"

The csv module will produce a comma-separated value file of the output fields requested. For example, the following command produces the following CSV in a file called output.csv.

$ zmap -p 80 -f "response,saddr,daddr,sport,seq,ack,in_cooldown,is_repeat,timestamp-str" -o output.csv

response, saddr, daddr, sport, dport, seq, ack, in_cooldown, is_repeat, timestamp-str
synack, 159.174.153.144, 10.0.0.9, 80, 40555, 3050964427, 3515084203, 0, 0,2013-08-15 18:55:47.681
rst, 141.209.175.1, 10.0.0.9, 80, 40136, 0, 3272553764, 0, 0,2013-08-15 18:55:47.683
rst, 72.36.213.231, 10.0.0.9, 80, 56642, 0, 2037447916, 0, 0,2013-08-15 18:55:47.691
rst, 148.8.49.150, 10.0.0.9, 80, 41672, 0, 1135824975, 0, 0,2013-08-15 18:55:47.692
rst, 50.165.166.206, 10.0.0.9, 80, 38858, 0, 535206863, 0, 0,2013-08-15 18:55:47.694
rst, 65.55.203.135, 10.0.0.9, 80, 50008, 0, 4071709905, 0, 0,2013-08-15 18:55:47.700
synack, 50.57.166.186, 10.0.0.9, 80, 60650, 2813653162, 993314545, 0, 0,2013-08-15 18:55:47.704
synack, 152.75.208.114, 10.0.0.9, 80, 52498, 460383682, 4040786862, 0, 0,2013-08-15 18:55:47.707
synack, 23.72.138.74, 10.0.0.9, 80, 33480, 810393698, 486476355, 0, 0,2013-08-15 18:55:47.710

The JSON output module operates similar to the CSV module, except it writes output in JSON format to a file. The JSON file can then be easily imported into other programs that can read JSON.

Heads Up! ZMap does not build with JSON support by default. If you are building ZMap from source, you can build with JSON support by running CMake with -DWITH_JSON=ON.

ZMap no longer contains support to ouput directly to Redis, due to the fickle nature of external IO in C. If you want to load ZMap results into Redis as they come, we recommend you pipe ZMap output through ZTee (including in the repository), and then write custom scripts (e.g. in Python) to parse ZTee output and send rows to Redis or another database.