netutils

Documentation

Overview

Package netutils provides helper functions for network related operations such as port scanning or subnet slicing.

Index

• Variables
• func CIDRHosts(cidr string) ([]string, int, error)
• func GetCerts(host string, ipAddr string, port int, timeout time.Duration, ...) ([]*x509.Certificate, error)
• func IsCIDR(s string) bool
• type HostPattern
  • func DedupeHosts(hosts []HostPattern) []HostPattern
  • func ExpandHost(hostPattern string) (HostPattern, error)
• type IPv4AddressOctetsIndex
  • func (idx IPv4AddressOctetsIndex) IndexSize() int
• type PortCheckResult
  • func CheckPort(host PortCheckTarget, port int, timeout time.Duration) PortCheckResult
  • func (rs PortCheckResult) Summary() string
• type PortCheckResults
  • func (rs PortCheckResults) HasOpenPort() bool
  • func (rs PortCheckResults) Host() string
  • func (rs PortCheckResults) Summary() string
• type PortCheckResultsIndex
• type PortCheckTarget

Variables

var ErrHostnameFailsNameResolution = errors.New("failed to resolve name to IP Address")

ErrHostnameFailsNameResolution indicates that a given string value fails name to IP Address resolution.

var ErrIPAddrOctectIdxValidityFailure = errors.New("invalid index of IP Address to octets")

ErrIPAddrOctectIdxValidityFailure indicates that the internal state of an IP Address octet map failed a validity check.

var ErrMissingValue = errors.New("missing expected value")

ErrMissingValue indicates that an expected value was missing.

var ErrUnrecognizedHostOrIPValue = errors.New("unrecognized hostname or IP Address")

ErrUnrecognizedHostOrIPValue indicates that a given string value is unrecognized as a valid hostname or IP Address.

var ErrUnrecognizedIPAddress = errors.New("unrecognized IP Address")

ErrUnrecognizedIPAddress indicates that a given string value is unrecognized as a valid IP Address.

var ErrUnrecognizedIPRange = errors.New("unrecognized IP Address range")

ErrUnrecognizedIPRange indicates that a given string value is unrecognized as a valid IP Address range (partial or CIDR).

Functions

func CIDRHosts

func CIDRHosts(cidr string) ([]string, int, error)

CIDRHosts converts a CIDR network pattern into a slice of hosts within that network, the total count of hosts and an error if any occurred.

https://stackoverflow.com/questions/60540465/go-how-to-list-all-ips-in-a-network https://play.golang.org/p/fe-F2k6prlA https://gist.github.com/kotakanbe/d3059af990252ba89a82

func GetCerts

func GetCerts(host string, ipAddr string, port int, timeout time.Duration, logger zerolog.Logger) ([]*x509.Certificate, error)

GetCerts retrieves and returns the certificate chain from the specified IP Address & port or an error if one occurs. If specified, the given host Name or FQDN is included in the client's handshake to support virtual hosting (SNI).

Enforced certificate verification is intentionally disabled in order to successfully retrieve and examine all certificates in the certificate chain.

func IsCIDR

func IsCIDR(s string) bool

IsCIDR indicates whether a specified string is a CIDR notation IP address and prefix length, like "192.0.2.0/24" or "2001:db8::/32", as defined in RFC 4632 and RFC 4291.

Types

type HostPattern

type HostPattern struct {
	// Given records the host pattern provided by the caller. This can be a
	// single IP Address, a range, a hostname or FQDN.
	Given string

	// Expanded records the individual IP Addresses associated with a given
	// host pattern. This may be a collection of IP Addresses associated with
	// a range or DNS A record, but may also be a single IP Address associated
	// with an A record or the original given single IP Address.
	Expanded []string

	// Resolved indicates whether the given host pattern was resolved to one
	// or more IP Addresses. This is false for IP Addresses and true for
	// hostname or FQDN values which successfully resolve to one or more IP
	// Addresses.
	Resolved bool

	// Range indicates whether the given host pattern was determined to be a
	// CIDR or partial IP Address range.
	Range bool
}

HostPattern represents an original specified host pattern provided by the caller and the collection of IP Addresses expanded from the pattern.

func DedupeHosts

func DedupeHosts(hosts []HostPattern) []HostPattern

DedupeHosts accepts a collection of HostPattern values and returns an unordered, but deduped/unique collection of HostPattern values.

NOTE: Each HostPattern value consists of the user-specified host pattern and a collection of IP Addresses that were expanded from the given host pattern. Deduping only takes place for the given host patterns, not the IP Addresses that the host patterns resolve to.

For example, if www1.example.com and www2.example.com both resolve to the same IP Address both given host patterns remain after deduping. This allows a user to check certificate chains for specific FQDNs. Likewise, if the IP Address for www1.example.com and www2.example.com is given alongside those FQDNs (three values total) all three host patterns remain after deduping. This allows retrieving a default certificate chain alongside FQDN-specific certificate chains. This is intended to be stable behavior.

However, if two IP Address ranges such as 192.168.5.10-15 and 192.168.5.10-20 are given, both are treated as separate values and not deduped. Because this is a potential source of confusion, this behavior is not considered stable and may change in the future.

func ExpandHost

func ExpandHost(hostPattern string) (HostPattern, error)

ExpandHost accepts a host pattern as a string value that represents either an individual IP Address, a CIDR IP range or a partial (dash-separated) range (e.g., 192.168.2.10-15) and returns a HostPattern value. The HostPattern value represents the original host pattern and a collection of IP Addresses expanded from the original pattern.

An error is returned if an invalid host pattern is provided (e.g., invalid IP Address range) or if it fails name resolution (e.g., invalid hostname or FQDN).

type IPv4AddressOctetsIndex

type IPv4AddressOctetsIndex map[int][]int

IPv4AddressOctetsIndex is a map of IPv4 octets to values within those octets associated with partial ranges. This type is used to help implement support for octet range addressing.

func (IPv4AddressOctetsIndex) IndexSize

func (idx IPv4AddressOctetsIndex) IndexSize() int

IndexSize returns the number of entries in the index.

type PortCheckResult

type PortCheckResult struct {
	// Host is the hostname or FQDN value (if available) used to evaluate the
	// TCP port state.
	Host string

	// IPAddress represents the parsed address of an IP end point. This value
	// should always be populated.
	IPAddress net.IPAddr

	// Port is the specific TCP port evaluated on a host.
	Port int

	// Open indicates whether a TCP port was found to be open during a port
	// check.
	Open bool

	// Err is what error (if any) which occurred while checking a TCP port.
	Err error
}

PortCheckResult indicates the discovered TCP port state for a given host and what error (if any) occurred while checking the port.

func CheckPort

func CheckPort(host PortCheckTarget, port int, timeout time.Duration) PortCheckResult

CheckPort checks whether a specified TCP port for a given host is open.

The given host value must provide a valid IP Address and optionally a resolvable hostname. If provided, the hostname is recorded to enable SNI support when retrieving certificates later.

Any errors encountered are returned along with the port status.

NOTE: This function explicitly returns real values for host & port instead of zero values so that they may be used in summary output by callers.

func (PortCheckResult) Summary

func (rs PortCheckResult) Summary() string

Summary generates a one-line summary of port check result.

type PortCheckResults

type PortCheckResults []PortCheckResult

PortCheckResults is a collection of PortCheckResult intended for bulk operations such as filtering or generating summaries.

func (PortCheckResults) HasOpenPort

func (rs PortCheckResults) HasOpenPort() bool

HasOpenPort indicates whether at least one specified port was found to be open for a scanned host.

func (PortCheckResults) Host

func (rs PortCheckResults) Host() string

Host returns the (single) host associated with port check results.

func (PortCheckResults) Summary

func (rs PortCheckResults) Summary() string

Summary generates a one-line summary of port check results.

type PortCheckResultsIndex

type PortCheckResultsIndex map[string]PortCheckResults

PortCheckResultsIndex maps the results slice from scan attempts against a specified list of ports to an IP Address associated with scanned ports.

type PortCheckTarget

type PortCheckTarget struct {
	// Name is the hostname or FQDN associated with a scan target. This field
	// is used to track an optional hostname or FQDN associated with a scan
	// target. This value is used in logging output and later passed to called
	// functions in order to provide SNI support.
	Name string

	// IPAddress is the resolved value used to evaluate the TCP port state.
	IPAddress string

	// Ports is the collection of TCP ports to evaluate for a host.
	Ports []int
}

PortCheckTarget specifies values used to check the TCP port state for a given host.