tools

README

tools

Set of several tools used by all or most projects at Friends fo Go

1. portscan

portscan

A fast and cool port scanner.

╰─ portscan

A fast and cool port scanner built with love by Friends of Go.
Complete documentation is available at https://github.com/friendsofgo/tools.

Usage:
  portscan [command]

Available Commands:
  help        Help about any command
  range       Does a range port scan (i.e. 0-1024)
  single      Does a single port scan (i.e. 8080)

Flags:
  -f, --file string   results file (stdin by default)
      --fmt string    results format, allowed: plain, json, yaml (default "plain")
  -h, --help          help for portscan

Use "portscan [command] --help" for more information about a command.

Usage examples

Scan a single localhost TCP port:

╰─ portscan single 127.0.0.1 tcp 80
Protocol: tcp    Port: 80    State: closed

Scan a range of localhost UDP ports:

╰─ portscan single 127.0.0.1 tcp 80 90
Protocol: udp    Port: 81    State: closed
Protocol: udp    Port: 90    State: closed
Protocol: udp    Port: 89    State: closed
Protocol: udp    Port: 83    State: closed
Protocol: udp    Port: 84    State: closed
Protocol: udp    Port: 80    State: closed
Protocol: udp    Port: 85    State: closed
Protocol: udp    Port: 86    State: closed
Protocol: udp    Port: 82    State: closed
Protocol: udp    Port: 87    State: closed
Protocol: udp    Port: 88    State: closed

Dump range scan results into a JSON file:

╰─ portscan range 127.0.0.1 tcp 80 83 -f out.json --fmt json

Results file:

[{
	"protocol": "tcp",
	"port": 80,
	"state": "closed"
}, {
	"protocol": "tcp",
	"port": 83,
	"state": "closed"
}, {
	"protocol": "tcp",
	"port": 81,
	"state": "closed"
}, {
	"protocol": "tcp",
	"port": 82,
	"state": "closed"
}]

TODOs / Ideas

• Set up GoReleaser for binaries generation.
• Add unitary & integration coverage.
• Use only the root command for the portscan tool.
• Use other scan techniques for the portscan tool.

Documentation

Index

• Constants
• func IsAllowedProtocol(protocol Protocol) bool
• func IsNumber(n string) bool
• func IsValidPort(port int) bool
• func NewFileWriter(path string) *fileWriter
• func NewJSONScanResultsFormatter() *jsonScanResultsFormatter
• func NewPlainScanResultsFormatter() *plainScanResultsFormatter
• func NewStdWriter() *stdWriter
• func NewYAMLScanResultsFormatter() *yamlScanResultsFormatter
• type Format
  • func FormatFromString(format string) Format
  • func (p Format) String() string
• type Protocol
  • func ProtocolFromString(protocol string) Protocol
  • func (p Protocol) String() string
• type ScanResult
  • func ScanPort(protocol Protocol, hostname string, port int) (ScanResult, error)
  • func ScanPortRange(protocol Protocol, hostname string, from, to int) (results []ScanResult, err error)
• type ScanResultsFormatter
  • func NewScanResultsFormatter(format Format) (ScanResultsFormatter, error)
• type State
• type Writer

Constants

const (
	MinValidPortNumber = 0
	MaxValidPortNumber = 65535

	PortScanTimeout = 60 * time.Second
)

const (
	FileMode = 0644
)

Functions

func IsAllowedProtocol

func IsAllowedProtocol(protocol Protocol) bool

IsAllowedProtocol returns true if the given input is a valid value for the transport layer protocol. TODO: Use const values.

func IsNumber

func IsNumber(n string) bool

IsNumber returns true if the given input can be converted into an integer, otherwise returns false.

func IsValidPort

func IsValidPort(port int) bool

IsValidPort returns true if the given input is within the range of valid port numbers, otherwise returns false.

func NewFileWriter

func NewFileWriter(path string) *fileWriter

NewFileWriter returns a new file writer.

func NewJSONScanResultsFormatter

func NewJSONScanResultsFormatter() *jsonScanResultsFormatter

NewJSONScanResultsFormatter returns a new JSON results formatter.

func NewPlainScanResultsFormatter

func NewPlainScanResultsFormatter() *plainScanResultsFormatter

NewPlainScanResultsFormatter returns a new plain results formatter.

func NewStdWriter

func NewStdWriter() *stdWriter

NewStdWriter returns a new standard (stdin) writer.

func NewYAMLScanResultsFormatter

func NewYAMLScanResultsFormatter() *yamlScanResultsFormatter

NewYAMLScanResultsFormatter returns a new YAML results formatter.

Types

type Format

type Format string

Format represents a valid serialization format.

const (
	Plain Format = "plain"
	JSON  Format = "json"
	YAML  Format = "yaml"
)

func FormatFromString

func FormatFromString(format string) Format

FormatFromString instances a new Format from the given string.

func (Format) String

func (p Format) String() string

String returns a string based on the given format.

type Protocol

type Protocol string

Protocol represents a valid transport layer protocol.

const (
	TCP Protocol = "tcp"
	UDP Protocol = "udp"
)

func ProtocolFromString

func ProtocolFromString(protocol string) Protocol

ProtocolFromString instances a new Protocol from the given string.

func (Protocol) String

func (p Protocol) String() string

String returns a string based on the given protocol.

type ScanResult

type ScanResult struct {
	Protocol Protocol `json:"protocol"`
	Port     int      `json:"port"`
	State    State    `json:"state"`
}

ScanResult contains all the information related with an specific port scan. It includes the protocol, the port and the state {open, closed}.

func ScanPort

func ScanPort(protocol Protocol, hostname string, port int) (ScanResult, error)

ScanPort does a Dial check of the given port at the given address through the given protocol. It returns an ScanResult with the info.

func ScanPortRange

func ScanPortRange(protocol Protocol, hostname string, from, to int) (results []ScanResult, err error)

ScanPortRange does a concurrent ScanPort call for each port present within the given ports range. It returns a slide of ScanResults with the info.

type ScanResultsFormatter

type ScanResultsFormatter interface {
	Format(results []ScanResult) []byte
}

ScanResultFormatter defines the behaviour needed to format a given slide of ScanResults into the formatter format.

func NewScanResultsFormatter

func NewScanResultsFormatter(format Format) (ScanResultsFormatter, error)

NewScanResultsFormatter is a factory method that returns a valid ScanResultsFormatter implementation or an error.

type State

type State string

State represents the state of a given port {open, closed}.

const (
	Open   State = "open"
	Closed       = "closed"
)

type Writer

type Writer interface {
	Write(bytes []byte) error
}

Writer defines the behaviour needed to write an array of bytes.