masscan

README

masscan

Masscan is a golang library to run masscan scans, parse scan results.

What is masscan

Masscan is an Internet-scale port scanner. It can scan the entire Internet in under 5 minutes, transmitting 10 million packets per second, from a single machine.

Its usage (parameters, output) is similar to nmap, the most famous port scanner. When in doubt, try one of those features -- features that support widespread scanning of many machines are supported, while in-depth scanning of single machines aren't.

Internally, it uses asynchronous transmission, similar to port scanners like scanrand, unicornscan, and ZMap. It's more flexible, allowing arbitrary port and address ranges.

Installation

go get github.com/zan8in/masscan

to install the package

import "github.com/zan8in/masscan"

Dependencies

• go (> 1.10)
• masscan (> 1.3.0)
  • download windows masscan
  • download linux masscan

Table of content

• masscan run timeout setting
• Get process ID (PID)
• Select network interface automatically

TODO

• Support more parameters

Simple example

package main

import (
	"fmt"
	"log"

	"github.com/zan8in/masscan"
)

// Example
func main() {
	scanner, err := masscan.NewScanner(
		masscan.SetParamTargets("146.56.202.100/24"),
		masscan.SetParamPorts("80"),
        masscan.EnableDebug(),
		masscan.SetParamWait(0),
		masscan.SetParamRate(10000),
	)
	if err != nil {
		log.Fatalf("unable to create masscan scanner: %v", err)
	}

	scanResult, _, err := scanner.Run()
	if err != nil {
		log.Fatalf("masscan encountered an error: %v", err)
	}

	if scanResult != nil {
		for i, v := range scanResult.Hosts {
			fmt.Printf("Host: %s Port: %v\n", v.IP, scanResult.Ports[i].Port)
		}
		fmt.Println("hosts len : ", len(scanResult.Hosts))
	}

}

The program above outputs:

/usr/bin/masscan 146.56.202.100/24 -p 80 --wait=0 --rate=10000 -oJ -
Host: 146.56.202.15 Port: 80
Host: 146.56.202.251 Port: 80
Host: 146.56.202.112 Port: 80
...
...
Host: 146.56.202.17 Port: 80
Host: 146.56.202.209 Port: 80
Host: 146.56.202.190 Port: 80
Host: 146.56.202.222 Port: 80
Host: 146.56.202.207 Port: 80
hosts len :  37

Async scan example

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/zan8in/masscan"
)

func main() {
	context, cancel := context.WithTimeout(context.Background(), 1*time.Minute)
	defer cancel()

	var (
		scannerResult []masscan.ScannerResult
		errorBytes    []byte
	)

	scanner, err := masscan.NewScanner(
		masscan.SetParamTargets("60.10.116.10"),
		masscan.SetParamPorts("80"),
		masscan.EnableDebug(),
		masscan.SetParamWait(0),
		masscan.SetParamRate(50),
		masscan.WithContext(context),
	)

	if err != nil {
		log.Fatalf("unable to create masscan scanner: %v", err)
	}

	if err := scanner.RunAsync(); err != nil {
		panic(err)
	}

	stdout := scanner.GetStdout()

	stderr := scanner.GetStderr()

	go func() {
		for stdout.Scan() {
			srs := masscan.ParseResult(stdout.Bytes())
			fmt.Println(srs.IP, srs.Port)
			scannerResult = append(scannerResult, srs)
		}
	}()

	go func() {
		for stderr.Scan() {
			fmt.Println("err: ", stderr.Text())
			errorBytes = append(errorBytes, stderr.Bytes()...)
		}
	}()

	if err := scanner.Wait(); err != nil {
		panic(err)
	}

	fmt.Println("masscan result count : ", len(scannerResult), " PID : ", scanner.GetPid())

}

The program above outputs:

C:\masscan\masscan.exe 146.56.202.100-146.56.202.200 -p 3306 --wait=0 --rate=2000
err:  Starting masscan 1.3.2 (http://bit.ly/14GZzcT) at 2021-03-19 14:52:27 GMT
err:  Initiating SYN Stealth Scan
err:  Scanning 101 hosts [1 port/host]
146.56.202.115 3306
146.56.202.190 3306
146.56.202.188 3306
146.56.202.125 3306
146.56.202.185 3306
146.56.202.117 3306
146.56.202.112 3306
146.56.202.161 3306
146.56.202.165 3306
146.56.202.166 3306
                                                                             
masscan result count :  10

Process finished with exit code 0

The development soul comes from

Ullaakut

Special thanks

李雪松 XueSong Lee

Documentation

Index

• func EnableDebug(debug bool) func(*Scanner)
• func SetBinaryPath(binaryPath string) func(*Scanner)
• func SetConfigPath(config string) func(*Scanner)
• func SetParamExclude(excludes ...string) func(*Scanner)
• func SetParamInterface(eth string) func(*Scanner)
• func SetParamPorts(ports ...string) func(*Scanner)
• func SetParamRate(maxRate int) func(*Scanner)
• func SetParamTargets(targets ...string) func(*Scanner)
• func SetParamTargetsFile(targetsFile string) func(*Scanner)
• func SetParamTopPorts(top bool) func(*Scanner)
• func SetParamWait(delay int) func(*Scanner)
• func SetSeed(x int) func(*Scanner)
• func SetShard(x int, y int) func(*Scanner)
• type Option
  • func WithContext(ctx context.Context) Option
• type Scanner
  • func NewScanner(options ...Option) (*Scanner, error)
  • func (s *Scanner) GetPid() int
  • func (s *Scanner) GetStderr() bufio.Scanner
  • func (s *Scanner) GetStdout() bufio.Scanner
  • func (s *Scanner) PauseAsync(resumefp string) error
  • func (s *Scanner) ResumeAsync(resumefp string) error
  • func (s *Scanner) Run() (result *tools.MasscanResult, warnings []string, err error)
  • func (s *Scanner) RunAsync() error
  • func (s *Scanner) Wait() error
• type ScannerResult
  • func ParseResult(content []byte) (sr ScannerResult)

Functions

func EnableDebug

func EnableDebug(debug bool) func(*Scanner)

EnableDebug set debug mode is true eg:C:\masscan\masscan.exe 146.56.202.100/24 -p 80,8000-8100 --rate=10000 -oJ -

func SetBinaryPath

func SetBinaryPath(binaryPath string) func(*Scanner)

SetParamTopPorts eg: --top-ports

func SetConfigPath

func SetConfigPath(config string) func(*Scanner)

SetConfigPath set the scanner config-file path eg: --conf /etc/masscan/masscan.conf

func SetParamExclude

func SetParamExclude(excludes ...string) func(*Scanner)

SetParamExclude sets the targets which to exclude from the scan, this also allows scanning of range 0.0.0.0/0 eg: 127.0.0.1,255.255.255.255

func SetParamInterface

func SetParamInterface(eth string) func(*Scanner)

SetParamPorts sets the ports which the scanner should scan on each host. eg: -p 80,8000-8100

func SetParamPorts

func SetParamPorts(ports ...string) func(*Scanner)

SetParamPorts sets the ports which the scanner should scan on each host. eg: -p 80,8000-8100

func SetParamRate

func SetParamRate(maxRate int) func(*Scanner)

SetParamRate set the rate masscan -p80,8000-8100 10.0.0.0/8 --rate=10000 scan some web ports on 10.x.x.x at 10kpps

func SetParamTargets

func SetParamTargets(targets ...string) func(*Scanner)

SetParamTargets set the target of a scanner eg: 192.168.88.0/24 192.168.88.0-255 192.168.88.0.255-192.168.88.255

func SetParamTargetsFile

func SetParamTargetsFile(targetsFile string) func(*Scanner)

SetConfigPath set the scanner config-file path eg: --conf /etc/masscan/masscan.conf

func SetParamTopPorts

func SetParamTopPorts(top bool) func(*Scanner)

SetParamTopPorts eg: --top-ports

func SetParamWait

func SetParamWait(delay int) func(*Scanner)

SetParamWait The waiting time after sending the packet, the default is 10 seconds --wait=10s default is 10 seconds

func SetSeed

func SetSeed(x int) func(*Scanner)

SetSeed sets the seed for scanning randomization (allows for distributed scanning as well as SetShard) eg: --seed 01123581321345589144233377

func SetShard

func SetShard(x int, y int) func(*Scanner)

SetShard sets the shard number (x) and the total shard amount (y) for distributed scanning eg: --shard 1/2

Types

type Option

type Option func(*Scanner)

func WithContext

func WithContext(ctx context.Context) Option

WithContext adds a context to a scanner, to make it cancellable and able to timeout.

type Scanner

type Scanner struct {
	// contains filtered or unexported fields
}

Scanner ...

func NewScanner

func NewScanner(options ...Option) (*Scanner, error)

NewScanner Create a new Scanner, and can take options to apply to the scanner

func (*Scanner) GetPid

func (s *Scanner) GetPid() int

获得 pid

func (*Scanner) GetStderr

func (s *Scanner) GetStderr() bufio.Scanner

GetStderr returns stderr variable for scanner.

func (*Scanner) GetStdout

func (s *Scanner) GetStdout() bufio.Scanner

GetStdout returns stdout variable for scanner.

func (*Scanner) PauseAsync

func (s *Scanner) PauseAsync(resumefp string) error

Pauses the masscan proccess by sending a control-c signal to the proccess the proccess can then be resumed by calling Resume

func (*Scanner) ResumeAsync

func (s *Scanner) ResumeAsync(resumefp string) error

NB: there is a bug in the latest release of masscan that will lead to this feature not working but if you build masscan from source, you shouldn't experience any issues.

func (*Scanner) Run

func (s *Scanner) Run() (result *tools.MasscanResult, warnings []string, err error)

Run run masscan and returns the result of the scan

func (*Scanner) RunAsync

func (s *Scanner) RunAsync() error

func (*Scanner) Wait

func (s *Scanner) Wait() error

Wait waits for the cmd to finish and returns error.

type ScannerResult

type ScannerResult struct {
	IP   string `json:"ip"`
	Port string `json:"port"`
}

func ParseResult

func ParseResult(content []byte) (sr ScannerResult)