safelinks

Documentation

Overview

Package safelinks provides functionality for decoding Safe Links URLs to their original values.

Index

• Constants
• Variables
• func EncodeURLAsFauxSafeLinksURL(u *url.URL) string
• func FilterURLs(urls []*url.URL, excludeSafeLinkURLs bool) []*url.URL
• func GetRandomSafeLinksFQDN() string
• func ProcessInputAsURL(inputURL string) ([]string, error)
• func ProcessInputURLs(inputURLs []string, okOut io.Writer, errOut io.Writer, verbose bool) bool
• func ReadURLFromUser() (string, error)
• func ReadURLsFromFile(r io.Reader) ([]string, error)
• func URLs(input string) ([]*url.URL, error)
• func ValidSafeLinkURL(input *url.URL) bool
• func ValidURL(input string) bool
• type FoundURLPattern
  • func GetURLPatternsUsingIndex(input string) ([]FoundURLPattern, error)
  • func GetURLPatternsUsingPrefixMatchingOnFields(input string) ([]FoundURLPattern, error)
  • func GetURLPatternsUsingRegex(input string) ([]FoundURLPattern, error)
• type SafeLinkURL
  • func FromURLs(urls []*url.URL) ([]SafeLinkURL, error)
  • func SafeLinkURLs(input string) ([]SafeLinkURL, error)
  • func SafeLinkURLsFromURLs(urls []*url.URL) ([]SafeLinkURL, error)

Constants

const (
	// SafeLinksURLRequiredPrefix is the required prefix for all Safe Links
	// URLs.
	SafeLinksURLRequiredPrefix string = "https://"

	// SafeLinksBaseDomain is the common component of a fully qualified domain
	// name used in Safe Links encoded URLs.
	SafeLinksBaseDomain string = "safelinks.protection.outlook.com"

	// SafeLinksURLTemplate is a template for observed SafeLinks URLs.
	// https://SUBDOMAIN.safelinks.protection.outlook.com/?url=ENCODED_URL&data=data_placeholder&sdata=sdata_placeholder&reserved=0
	SafeLinksURLTemplate string = "%s%s/?url=%s&data=%s&sdata=%s&reserved=%s"
)

Variables

var (
	// ErrInvalidURL indicates that an invalid URL was provided.
	ErrInvalidURL = errors.New("invalid URL provided")

	// ErrOriginalURLNotResolved indicates that we failed to resolve the
	// original URL using the given Safe Links URL.
	ErrOriginalURLNotResolved = errors.New("unable to resolve original URL")

	// ErrNoURLsFound indicates that an attempt to parse an input string for
	// URLs failed.
	ErrNoURLsFound = errors.New("no URLs found in input")

	// ErrURLNotSafeLinkEncoded indicates that a given URL is not recognized
	// as using Safe Link encoding.
	ErrURLNotSafeLinkEncoded = errors.New("given URL not Safe Link encoded")

	// ErrNoSafeLinkURLsFound indicates that no URLs were found to be encoded
	// as Safe Links.
	ErrNoSafeLinkURLsFound = errors.New("no Safe Link URLs found in input")

	// ErrNoNonSafeLinkURLsFound indicates that no URLs were found to not
	// already be encoded as Safe Links.
	ErrNoNonSafeLinkURLsFound = errors.New("no non-Safe Link URLs found in input")
)

Functions

func EncodeURLAsFauxSafeLinksURL

func EncodeURLAsFauxSafeLinksURL(u *url.URL) string

EncodeURLAsFauxSafeLinksURL encodes the provided url.URL in a format that mimics real Safe Links encoded URLs observed in the wild. This output is intended for use with testing encoding/decoding behavior.

func FilterURLs

func FilterURLs(urls []*url.URL, excludeSafeLinkURLs bool) []*url.URL

FilterURLs filters the given collection of URLs, returning the remaining URLs or an error if none remain after filtering.

If specified, Safe Link URLs are excluded from the collection returning only URLs that have not been encoded as Safe Links URLs. Otherwise, only URLs that have been encoded as Safe Links URLs are returned.

An empty collection is returned if no URLs remain after filtering.

func GetRandomSafeLinksFQDN

func GetRandomSafeLinksFQDN() string

GetRandomSafeLinksFQDN returns a pseudorandom FQDN from a list observed to be associated with Safe Links URLs. Entries in the list have a naming pattern of *.safelinks.protection.outlook.com.

func ProcessInputAsURL

func ProcessInputAsURL(inputURL string) ([]string, error)

ProcessInputAsURL processes a given input string as a URL value. This input string represents a single URL given via CLI flag.

If an input string is not provided, this function will attempt to read input URLs from stdin. Each input URL is unescaped and quoting removed.

The collection of input URLs is returned or an error if one occurs.

func ProcessInputURLs

func ProcessInputURLs(inputURLs []string, okOut io.Writer, errOut io.Writer, verbose bool) bool

ProcessInputURLs processes a given collection of input URL strings and emits successful decoding results to the specified results output sink. Errors are emitted to the specified error output sink if encountered but bulk processing continues until all input URLs have been evaluated.

If requested, decoded URLs are emitted in verbose format.

A boolean value is returned indicating whether any errors occurred.

func ReadURLFromUser

func ReadURLFromUser() (string, error)

ReadURLFromUser attempts to read a given URL pattern from the user via stdin prompt.

func ReadURLsFromFile

func ReadURLsFromFile(r io.Reader) ([]string, error)

ReadURLsFromFile attempts to read URL patterns from a given file (io.Reader).

The collection of input URLs is returned or an error if one occurs.

func URLs

func URLs(input string) ([]*url.URL, error)

URLs parses the given input and returns a collection of *url.URL values.

Since all Safe Links URLs observed in the wild begin with a HTTPS scheme we require that all matched URLs begin with that protocol scheme. nil is returned if no valid URLs using that scheme are found.

func ValidSafeLinkURL

func ValidSafeLinkURL(input *url.URL) bool

ValidSafeLinkURL validates whether a given url.URL is a valid Safe Links URL.

func ValidURL

func ValidURL(input string) bool

ValidURL attempts to validate whether a given input string is a valid URL.

Types

type FoundURLPattern

type FoundURLPattern struct {
	URLPattern string
	// contains filtered or unexported fields
}

FoundURLPattern is an unvalidated URL pattern match found in given input.

func GetURLPatternsUsingIndex

func GetURLPatternsUsingIndex(input string) ([]FoundURLPattern, error)

GetURLPatternsUsingIndex parses the given input and returns a collection of FoundURLPattern values.

Since all Safe Links URLs observed in the wild begin with a HTTPS scheme we require that all matched URL patterns begin with that protocol scheme. nil is returned if no patterns using that scheme are found.

NOTE: Validation has not been performed to ensure that matched patterns are valid URLs.

Internal logic uses slice indexing/iteration to match URL patterns beginning with 'https://' and ending with a whitespace character or a right angle bracket. Any angle brackets present are trimmed from returned matches.

func GetURLPatternsUsingPrefixMatchingOnFields

func GetURLPatternsUsingPrefixMatchingOnFields(input string) ([]FoundURLPattern, error)

GetURLPatternsUsingPrefixMatchingOnFields parses the given input and returns a collection of FoundURLPattern values.

Since all Safe Links URLs observed in the wild begin with a HTTPS scheme we require that all matched URL patterns begin with that protocol scheme. nil is returned if no patterns using that scheme are found.

NOTE: Validation has not been performed to ensure that matched patterns are valid URLs.

Internal logic uses string splitting on whitespace and prefix matching to match URL patterns optionally beginning a left angle bracket, then 'https://' and ending with a whitespace character.

func GetURLPatternsUsingRegex

func GetURLPatternsUsingRegex(input string) ([]FoundURLPattern, error)

GetURLPatternsUsingRegex parses the given input and returns a collection of FoundURLPattern values.

Since all Safe Links URLs observed in the wild begin with a HTTPS scheme we require that all matched URL patterns begin with that protocol scheme. nil is returned if no patterns using that scheme are found.

NOTE: Validation is not performed to ensure that matched patterns are valid URLs.

Internal logic uses a regular expression to match URL patterns optionally beginning with a left angle bracket, then 'https://' and ending with a whitespace character or a right angle bracket. Any angle brackets present are trimmed from returned matches. Internal logic uses a regular expression to match URL patterns optionally beginning with a left angle bracket, then 'https://' and ending with a whitespace character or a right angle bracket. Any angle brackets present are trimmed from returned matches.

type SafeLinkURL

type SafeLinkURL struct {
	EncodedURL string
	DecodedURL string
}

SafeLinkURL contains the encoded and decoded URLs for a matched Safe Link.

func FromURLs

func FromURLs(urls []*url.URL) ([]SafeLinkURL, error)

FromURLs evaluates a given collection of URLs and returns a collection of SafeLinkURL values for any that are found to be encoded as Safe Links. Deduplication is *not* performed.

An error is returned if no valid matches are found.

func SafeLinkURLs

func SafeLinkURLs(input string) ([]SafeLinkURL, error)

SafeLinkURLs parses the given input and returns a collection of parsed and decoded URLs. Deduplication is *not* performed.

An error is returned if no valid matches are found.

func SafeLinkURLsFromURLs

func SafeLinkURLsFromURLs(urls []*url.URL) ([]SafeLinkURL, error)

SafeLinkURLsFromURLs evaluates a given collection of URLs and returns any that are found to be encoded as Safe Links. Deduplication is *not* performed. An error is returned if no valid matches are found.