# ZMap Copyright 2013 Regents of the University of Michigan

# Licensed under the Apache License, Version 2.0 (the "License"); you may not
# use this file except in compliance with the License. You may obtain a copy of
# the License at http://www.apache.org/licenses/LICENSE-2.0

# zmap option description to be processed by gengetopt

package "zmap"
version "@ZMAP_VERSION@"
purpose "A fast Internet-wide scanner."

section "Basic Arguments"

option "target-ports"           p "comma-delimited list of ports and port ranges to scan (for TCP and UDP scans)"
    typestr="ports"
    optional string
option "output-file"            o "Output file"
    typestr="name"
    optional string
option "blocklist-file"         b "File of subnets to exclude, in CIDR notation, e.g. 192.168.0.0/16"
    typestr="path"
    optional string
option "allowlist-file"         w "File of subnets to constrain scan to, in CIDR notation, e.g. 192.168.0.0/16"
    typestr="path"
    optional string
option "list-of-ips-file"       I "List of individual addresses to scan in random order. Use --allowlist-file unless >1 million IPs"
    typestr="path"
    optional string


section "Scan Options"

option "rate"                   r "Set send rate in packets/sec"
    typestr="pps"
    optional int
option "bandwidth"              B "Set send rate in bits/second (supports suffixes G, M and K)"
    typestr="bps"
    optional string
option "batch"                  - "Set batch size for how many packets to send in a single syscall. Advantageous on Linux or with netmap (default=64)"
    typestr="pps"
    optional int
option "max-targets"            n "Cap number of targets to probe (as a number '-n 1000' or a percentage '-n 1%' of the target search space). A target is an IP/port pair, if scanning multiple ports, and an IP otherwise."
    typestr="n"
    optional string
option "max-runtime"            t "Cap length of time for sending packets"
    typestr="secs"
    optional int
option "max-results"            N "Cap number of results to return"
    typestr="n"
    optional int
option "probes"                 P "Number of probes to send to each IP/Port pair"
    typestr="n"
    default="1"
    optional int
option "cooldown-time"          c "How long to continue receiving after sending last probe"
    typestr="secs"
    default="8"
    optional int
option "seed"                   e "Seed used to select address permutation"
    typestr="n"
    optional longlong
option "retries"                - "Max number of times to try to send packet if send fails"
    typestr="n"
    default="10"
    optional int
option "dryrun"                 d "Don't actually send packets"
    optional
option "fast-dryrun"            - "Don't actually send packets, print out a binary representation probe dst IP and dst Port. Used for faster integration tests, not for general use."
    optional


section "Scan Sharding"

option "shards"                 - "Set the total number of shards"
    typestr="N"
    optional int
    default="1"
option "shard"                  - "Set which shard this scan is (0 indexed)"
    typestr="n"
    optional int
    default="0"

section "Network Options"

option "source-port"            s "Source port(s) for scan packets"
    typestr="port|range"
    optional string
option "validate-source-port" - "Override to validate if probe responses have a valid src port corresponding to sent probe's dst port. \"enable\" or \"disable\""
    typestr="enable|disable"
    optional string
option "source-ip"              S "Source address(es) for scan packets"
    typestr="ip|range"
    optional string
option "gateway-mac"            G "Specify gateway MAC address"
    typestr="addr"
    optional string
option "source-mac"             - "Source MAC address"
    typestr="addr"
    optional string
option "interface"              i "Specify network interface to use"
    typestr="name"
    optional string
option "iplayer"                X "Sends IP packets instead of Ethernet (for VPNs)"
    optional
option "netmap-wait-ping"       - "Wait for IP to respond to ping before commencing scan (netmap only)"
    typestr="ip"
    optional string

section "Probe Modules"
option "probe-module"           M "Select probe module"
    typestr="name"
    default="tcp_synscan"
    optional string
option "probe-args"             - "Arguments to pass to probe module"
    typestr="args"
    optional string
option "probe-ttl"              - "Set TTL value for probe IP packets"
    typestr="n"
    default="64"
    optional int
option "list-probe-modules"     - "List available probe modules"
        optional

section "Results Output"
option "output-fields"          f "Fields that should be output in result set"
    typestr="fields"
    optional string
option "output-module"          O "Select output module"
    typestr="name"
    optional string
option "output-args"            - "Arguments to pass to output module"
    typestr="args"
    optional string
option "output-filter"          - "Specify a filter over the response fields to limit what responses get sent to the output module"
    typestr="filter"
    optional string
option "list-output-modules"    - "List available output modules"
        optional
option "list-output-fields"     - "List all fields that can be output by selected probe module"
    optional
option "no-header-row"          - "Precludes outputting any header rows in data (e.g., CSV headers)"
    optional


section "Response Deduplication"
option "dedup-method"           - "Specifies how response deduplication should be performed. Options: default, none, full, window"
    typestr="method"
    optional string
option "dedup-window-size"      - "Specifies window size for how many recent responses to keep in memory for deduplication"
    typestr="targets"
    default="1000000"
    optional int

section "Logging and Metadata"
option "verbosity"              v "Level of log detail (0-5)"
    typestr="n"
    default="3"
    optional int
option "log-file"               l "Write log entries to file"
    typestr="name"
    optional string
option "log-directory"          L "Write log entries to a timestamped file in this directory"
    typestr="directory"
    optional string
option "metadata-file"          m "Output file for scan metadata (JSON)"
    typestr="name"
    optional string
option "status-updates-file"    u "Write scan progress updates to CSV file"
    typestr="name"
    optional string
option "quiet"                  q "Do not print status updates"
    optional
option "disable-syslog"         - "Disables logging messages to syslog"
    optional
option "notes"                  - "Inject user-specified notes into scan metadata"
    typestr="notes"
    optional string
option "user-metadata"          - "Inject user-specified JSON metadata into scan metadata"
    typestr="json"
    optional string

section "Additional Options"
option "config"                 C "Read a configuration file, which can specify any of these options"
    typestr="filename"
    default="/etc/zmap/zmap.conf"
    optional string

option "max-sendto-failures"    - "Maximum NIC sendto failures before scan is aborted"
    typestr="n"
    default="-1"
    optional int

option "min-hitrate"            - "Minimum hitrate that scan can hit before scan is aborted"
    typestr="n"
    default="0.0"
    optional float

option "sender-threads"         T "Threads used to send packets"
    typestr="n"
    default="4"
    optional int

option "cores"                  - "Comma-separated list of cores to pin to"
    optional string
option "ignore-blocklist-errors" - "Ignore invalid entries in allowlist/blocklist file."
    optional
option "help"                   h "Print help and exit"
    optional
option "version"                V "Print version and exit"
    optional

text "\nExamples:\n\
    zmap -p 80 (scan full IPv4 address space for hosts on TCP/80)\n\
    zmap -N 5 -B 10M -p 80 (find 5 HTTP servers, scanning at 10 Mb/s)\n\
    zmap -p 80 10.0.0.0/8 192.168.0.0/16 (scan both subnets on TCP/80)\n\
    zmap -p 80 1.2.3.4 10.0.0.3 (scan 1.2.3.4, 10.0.0.3 on TCP/80)\n\
    zmap -p 80,100-102 (scan full IPv4 on ports 80, 100, 101, 102)"
