man page (ef341e05) · Commits · nimrod / masscan

doc/bot.hml

0 → 100644

+17 −0

Original line number	Diff line number	Diff line
		<html>
		<head>
		<title>Masscan/1.0 - fast port scanner</title>
		</head>
		<body>
		<h1>Masscan/1.0 - fast port scanner</h1>

		<p>This tool is not a web spider, but a port scanner. It'll make only one request to a website, usually for the root / webpage. It then records the <b>Server:</b> field from the HTTP header, the <b><title></b> from the page contents, and possibly a few other interesting fields.</p>

		<p>This does not follow links, it doesn't scan your web pages, but the ports on your machine.</p>

		<p>The source code for this tool is at <a href="https://github.com/robertdavidgraham/masscan/">https://github.com/robertdavidgraham/masscan/</a>. This is an open source project, so that this means it's not me (Robert Graham) who is using this tool to scan your website, but likely somebody else. I can't speak for their intentions, but this tool is more useful at doing surveys of the Internet than trying to hack in (tools like 'nmap' or 'nessus' are more often used for that).</p>



		</body>
		</html>

doc/masscan.8.markdown

0 → 100644

+259 −0

Original line number	Diff line number	Diff line
		masscan(8) -- Fast scan of the Internet
		=======================================

		## SYNOPSIS

		masscan <ip addresses/ranges> -p <ports> <options>

		## DESCRIPTION

		masscan is an Internet-scale port scanner, useful for large scal surveys
		of the Internet, or of internal networks. While the default transmit rate
		is only 100 packets/second, it can optional go as fast as 25 million
		packets/second, a rate sufficient to scan the Internet in 3 minutes for
		one port.

		## OPTIONS

		* `<ip/range>`: anything on the command-line not prefixed with a '-' is
		assumed to be an IP address or range. There are three valid formats.
		The first is a single IPv4 address like "192.168.0.1". The second
		is a range like "10.0.0.1-10.0.0.100". The third is a CIDR address,
		like "0.0.0.0/0". At least one target must be specified. Multiple
		targets can be specified. This can be specified as multiple options
		separated by space, or can be separated by a comma as a single option,
		such as `10.0.0.0/8,192.168.0.1`.

		* `--range <ip/range>`: the same as target range spec described above,
		except as a named parameter instead of an unnamed one.

		* `-p <ports`, `--ports <ports>`: specifies the port(s) to be scanned. A single
		port can be specified, like `-p80`. A range of ports can be specified,
		like `-p 20-25`. A list of ports/ranges can be specified, like
		`-p80,20-25`. UDP ports can also be specified, like
		`--ports U:161,U:1024-1100`.

		* `--banners`: specifies that banners should be grabbed, like HTTP server
		versions, HTML title fields, and so forth. Only a few protocols are
		supported.

		* `--rate <packets-per-second>`: specifies the desired rate for transmitting
		packets. This can be very small numbers, like `0.1` for transmitting packets
		at rates of one every 10 seconds, for very large numbers like 10000000,
		which attempts to transmit at 10 million packets/second. In my experience,
		Windows and can do 250 thousand packets per second, and latest versions of
		Linux can do 2.5 million packets per second. The PF_RING driver is needed
		to get to 25 million packets/second.

		* `-c <filename>`, `--conf <filename>`: reads in a configuration file. The
		format of the configuration file is described below.

		* `--resume <filename>`: the same as `--conf`, except that a few options
		are automatically set, such as `--append-output`. The format of the
		configuration file is described below.

		* `--echo`: don't run, but instead dump the current configuration to a file.
		This file can then be used with the `-c` option. The format of this
		output is described below under 'CONFIGURATION FILE'.

		* `-e <ifname>`, `--adapter <ifname>`: use the named raw network interface,
		such as "eth0" or "dna1". If not specified, the first network interface
		found with a default gateway will be used.

		* `--adapter-ip <ip-address>`: send packets using this IP address. If not
		specified, then the first IP address bound to the network interface
		will be used.

		* `--adapter-port <ip-address>`: send packets using this port number as the
		source. If not specified, a random port will be chosen in the range 40000
		through 60000. This port should be filtered by the host firewall (like
		iptables) to prevent the host network stack from interfering with arriving
		packets.

		* `--adapter-mac <mac-address>`: send packets using this as the source MAC
		address. If not specified, then the first MAC address bound to the network
		interface will be used.

		* `--router-mac <mac address>`: send packets to this MAC address as the
		destination. If not specified, then the gateway address of the network
		interface will be ARPed.

		* `--ping`: indicates that the scan should include an ICMP echo request.
		This may be included with TCP and UDP scanning.

		* `--exclude <ip/range>`: blacklist an IP address or range, preventing it
		from being scanned. This overrides any target specification, guaranteeing
		that this address/range won't be scanned. This has the same format
		as the normal target specification.

		* `--excludefile <filename>`: reads in a list of exclude ranges, in the same
		target format described above. These ranges override any targets,
		preventing them from being scanned.

		* `--append-output`: causes output to append to file, rather than
		overwriting the file.

		* `--iflist`: list the available network interfaces, and then exits.

		* `--retries`: the number of retries to send, at 1 second intervals. Note
		that since this scanner is stateless, retries are sent regardless if
		replies have already been received.

		* `--nmap`: print help aobut nmap-compatibility alternatives for these
		options.

		* `--pcap-payloads`: read packets from a libpcap file containing packets
		and extract the UDP payloads, and associate those payloads with the
		destination port. These payloads will then be used when sending UDP
		packets with the matching destination port. Only one payload will
		be remembered per port. Similar to `--nmap-payloads`.

		* `--nmap-payloads <filename>`: read in a file in the same format as
		the nmap file `nmap-payloads`. This contains UDP payload, so that we
		can send useful UDP packets instead of empty ones. Similar to
		`--pcap-payloads`.

		* `--open-only`: report only open ports, not closed ports.

		* `--output-format <fmt>`: indicates the format of the output file, which
		can be `xml` or `binary`. The option `--output-filename` must be
		specified.

		* `--output-filename <filename>`: the file which to save results to. If
		the parameter `--output-format` is not specified, then the default of
		`xml` will be used.

		* `--pcap <filename>`: saves received packets (but not transmitted
		packets) to the libpcap-format file.

		* `--packet-trace`: prints a summary of those packets sent and received.
		This is useful at low rates, like a few packets per second, but will
		overwhelm the terminal at high rates.

		* `--pfring`: force the use of the PF_RING driver. The program will exit
		if PF_RING DNA drvers are not available.

		* `--resume-index`: the point in the scan at when it was paused.

		* `--resume-count`: the maximum number of probes to send before exiting.
		This is useful with the `--resume-index` to chop up a scan and split
		it among multiple instances, though the `--shards` option might be
		better.

		* `--shards <x>/<y>`: splits the scan among instances. `x` is the id
		for this scan, while `y` is the total number of instances. For example,
		`--shards 1/2` tells an instance to send every other packet, starting
		with index 0. Likewise, `--shards 2/2` sends every other packet, but
		starting with index 1, so that it doesn't overlap with the first example.

		* `--rotate <time>`: rotates the output file, renaming it with the
		current timestamp, moving it to a separate directory. The time is
		specified in number of seconds, like "3600" for an hour. Or, units
		of time can be specified, such as "hourly", or "6hours", or "10min".
		Times are aligned on an even boundary, so if "daily" is specified,
		then the file will be rotated every day at midnight.

		* `--rotate-offset <time>`: an offset in the time. This is to accomodate
		timezones.

		* `--rotate-dir <directory>`: when rotating the file, this specifies which
		directory to move the file to. A useful directory is `/var/log/masscan`.

		* `--seed <integer>`: an integer that seeds the random number generator.
		Using a different seed will cause packets to be sent in a different
		random order. Instead of an integer, the string `time` can be specified,
		which seeds using the local timestamp, automatically generating a
		differnet random order of scans.

		* `--regress`: run a regression test, returns '0' on success and '1' on
		failure.

		* `--ttl <num>`: specifies the TTL of outgoing packets, defaults to 255.

		* `--wait <seconds>`: specifies the number of seconds after transmit is
		done to wait for receiving packets before exiting the program. The default
		is 10 seconds. The string `forever` can be specified to never terminate.

		* `--offline`: don't actually transmit packets. This is useful with
		a low rate and `--packet-trace` to look at what packets might've been
		transmitted. Or, it's useful with `--rate 100000000` in order to
		benchmark how fast transmit would work (assuming a zero-overhead
		driver). PF_RING is about 20% slower than the benchmark result from
		offline mode.

		* `-sL`: this doesn't do a scan, but instead creates a list of random
		addresses. This is useful for importing into other tools. The options
		`--shard`, `--resume-index`, and `--resume-count` can be useful with
		this feature.

		## CONFIGURATION FILE FORMAT

		The configuration file uses the same parameter names as on the
		commandline, but without the `--` prefix, and with an `=` sign
		between the name and the value. An example configuration file
		might be:

		# targets
		range = 10.0.0.0/8,192.168.0.0/16
		range = 172.16.0.0/14
		ports = 20-25,80,U:53
		ping = true

		# adapter
		adapter = eth0
		adapter-ip = 192.168.0.1
		router-mac = 66-55-44-33-22-11

		# other
		exclude-file = /etc/masscan/exludes.txt

		By default, the program will read default configuration from the file
		`/etc/masscan/masscan.conf`. This is useful for system-specific settings,
		such as the `--adapter-xxx` options. This is also useful for
		excluded IP addresses, so that you can scan the entire Internet,
		while skipping dangerous addresses, like those owned by the DoD,
		and not make an accidental mistake.


		## CONTROL-C BEHAVIOR

		When the user presses <ctrl-c>, the scan will stop, and the current
		state of the scan will be saved in the file 'paused.conf'. The scan
		can be resumed with the `--resume` option:

		# masscan --resume paused.conf

		The program will not exit immediately, but will wait a default of 10
		seconds to receive results from the Internet and save the results before
		exiting completely. This time can be changed with the `--wait` option.


		## SIMPLE EXAMPLES

		The following example scans all private networks for webservers, and prints
		all open ports that were found.

		# masscan 10.0.0.0/8 192.168.0.0/16 172.16.0.0/12 -p80 --open-only

		The following example scans the entire Internet for DNS servers, grabbing
		their versions, then saves the results in an XML file.

		# masscan 0.0.0.0/0 --excludefile no-dod.txt -pU:53 --banners --output-filename dns.xml

		You should be able to import the XML into databases and such.

		## ADVANCED EXAMPLES

		Let's say that you want to scan the entire Internet and spread the scan
		across three machines. Masscan would be launched on all three machines
		using the following command-lines:

		# masscan 0.0.0.0/0 -p0-65535 --shard 1/3
		# masscan 0.0.0.0/0 -p0-65535 --shard 2/3
		# masscan 0.0.0.0/0 -p0-65535 --shard 3/3


		## SEE ALSO

		nmap(8)

src/main-conf.c

+7 −5

Original line number	Diff line number	Diff line
		@@ -248,7 +248,6 @@ masscan_save_state(struct Masscan *masscan)
		}

		fprintf(fp, "\n# resume information\n");
		fprintf(fp, "resume-seed = %llu\n", masscan->resume.seed);
		fprintf(fp, "resume-index = %llu\n", masscan->resume.index);

		masscan_echo(masscan, fp);
		@@ -779,7 +778,7 @@ masscan_set_parameter(struct Masscan *masscan,
		/* Run in "offline" mode where it thinks it's sending packets, but
		* it's not */
		masscan->is_offline = 1;
		} else if (EQUALS("open", name)) {
		} else if (EQUALS("open", name) \|\| EQUALS("open-only", name)) {
		masscan->nmap.open_only = 1;
		} else if (EQUALS("output-status", name)) {
		if (EQUALS("open", value))
		@@ -801,6 +800,8 @@ masscan_set_parameter(struct Masscan *masscan,
		fprintf(stderr, "error: %s=%s\n", name, value);
		}
		} else if (EQUALS("output-filename", name) \|\| EQUALS("output-file", name)) {
		if (masscan->nmap.format == 0)
		masscan->nmap.format = Output_XML;
		strcpy_s(masscan->nmap.filename, sizeof(masscan->nmap.filename), value);
		} else if (EQUALS("pcap", name)) {
		strcpy_s(masscan->pcap_filename, sizeof(masscan->pcap_filename), value);
		@@ -824,8 +825,6 @@ masscan_set_parameter(struct Masscan *masscan,
		} else if (EQUALS("resume", name)) {
		masscan_read_config_file(masscan, value);
		masscan_set_parameter(masscan, "output-append", "true");
		} else if (EQUALS("resume-seed", name)) {
		masscan->resume.seed = parseInt(value);
		} else if (EQUALS("resume-index", name)) {
		masscan->resume.index = parseInt(value);
		} else if (EQUALS("resume-count", name)) {
		@@ -861,6 +860,9 @@ masscan_set_parameter(struct Masscan *masscan,
		fprintf(stderr, "nmap(%s): TCP scan flags not yet supported\n", name);
		exit(1);
		} else if (EQUALS("seed", name)) {
		if (EQUALS("time", value))
		masscan->seed = time(0);
		else
		masscan->seed = parseInt(value);
		} else if (EQUALS("sendq", name)) {
		masscan->is_sendq = 1;

src/masscan.h

+0 −1

Original line number	Diff line number	Diff line
		@@ -105,7 +105,6 @@ struct Masscan


		struct {
		uint64_t seed;
		uint64_t index;
		uint64_t count;
		} resume;

src/proto-tcp.c

+2 −2

Original line number	Diff line number	Diff line
		@@ -603,8 +603,8 @@ tcpcon_handle(struct TCP_ConnectionTable tcpcon, struct TCP_Control_Block tcb,
		switch (tcb->port_them) {
		case 80:
		x = (const unsigned char *)
		"HEAD / HTTP/1.0\r\n"
		"User-Agent: test\r\n"
		"GET / HTTP/1.0\r\n"
		"User-Agent: masscan/1.0 (https://github.com/robertdavidgraham/masscan)\r\n"
		"Connection: Keep-Alive\r\n"
		"Content-Length: 0\r\n"
		"\r\n";