target

Documentation

Overview

Package target parses target specifications (IPs, ranges, CIDR, hostnames, @file references) into a lazy iterator of addresses.

Supported input forms (see §4.1 of scry-plan.md):

192.168.1.10                  single IPv4
::1                           single IPv6
192.168.1.10-50               last-octet IPv4 range
192.168.1.10-192.168.2.20     arbitrary IPv4 range
2001:db8::1-2001:db8::ff      arbitrary IPv6 range
192.168.1.0/24                IPv4 CIDR
2001:db8::/120                IPv6 CIDR
example.com                   hostname (resolved via Options.Resolver)
@targets.txt                  file, one target per line, # comments allowed

Any input may itself be a comma-separated list. Whitespace around tokens is stripped.

Index

• type FileReader
• type Iterator
  • func Parse(specs []string, opts Options) (*Iterator, error)
  • func (it *Iterator) Next() (netip.Addr, bool)
  • func (it *Iterator) Total() (uint64, bool)
• type Options
• type Resolver

Types

type FileReader

type FileReader func(path string) ([]byte, error)

FileReader reads the contents of a file referenced via @path.

type Iterator

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

Iterator yields target addresses lazily. It is not safe for concurrent use.

func Parse

func Parse(specs []string, opts Options) (*Iterator, error)

Parse parses one or more target specs and returns an iterator. Each spec may itself be a comma-separated list.

func (*Iterator) Next

func (it *Iterator) Next() (netip.Addr, bool)

Next returns the next address and true, or zero-value and false when done.

func (*Iterator) Total

func (it *Iterator) Total() (uint64, bool)

Total returns the total number of addresses this iterator will produce, if known statically, and a second value indicating whether the count is known. The count is not known when any source is a hostname that has not yet been resolved. Excludes are not subtracted from the count.

type Options

type Options struct {
	// Excludes are target specs (single, range, CIDR) whose addresses will be
	// skipped by the iterator.
	Excludes []string

	// Resolver is called for hostname targets. If nil, net.DefaultResolver is
	// used. Set to a function returning an error to forbid DNS.
	Resolver Resolver

	// FileReader is called for @file targets. If nil, os.ReadFile is used.
	FileReader FileReader

	// Context is passed to the Resolver. If nil, context.Background() is used.
	Context context.Context
}

Options tunes parser behavior. All fields are optional; zero values are sane.

type Resolver

type Resolver func(ctx context.Context, host string) ([]netip.Addr, error)

Resolver resolves a hostname to one or more addresses.