Documentation
¶
Overview ¶
Package safelinks provides functionality for decoding Safe Links URLs to their original values.
Index ¶
- Constants
- Variables
- func CleanURL(s string) string
- func DecodeInput(txt string) (string, error)
- func EncodeInput(txt string, randomlyEncode bool) (string, error)
- func EncodeParsedURLAsFauxSafeLinksURL(pURL ParsedURL) string
- func FilterURLs(urls []*url.URL, excludeSafeLinkURLs bool) []*url.URL
- func GetRandomSafeLinksFQDN() string
- func QueryEscapeInput(txt string, randomlyEscape bool) (string, error)
- func ReadFromFile(r io.Reader) ([]string, error)
- func ReadURLFromUser() (string, error)
- func ValidSafeLinkURL(u *url.URL) bool
- func ValidURL(u *url.URL) bool
- func ValidURLPattern(input string) bool
- type FoundURLPattern
- type ParsedURL
- type SafeLinkURL
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" )
const ( // HTTPPlainURLPrefix is the plaintext prefix used for unencrypted // connections to a HTTP-enabled site/service. HTTPPlainURLPrefix string = "http://" )
Variables ¶
var ( // ErrMissingValue indicates that an expected value was missing. ErrMissingValue = errors.New("missing expected value") // 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 matching requirements 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") // ErrQueryEscapingUnsuccessful indicates that an attempt to query escape // input was unsuccessful. ErrQueryEscapingUnsuccessful = errors.New("failed to query escape input") // ErrEncodingUnsuccessful indicates that an attempt to encode input was // unsuccessful. ErrEncodingUnsuccessful = errors.New("failed to encode input") )
Functions ¶
func CleanURL ¶ added in v0.5.0
CleanURL strips away quoting, escaping of characters or other problematic leading or trailing characters in a given URL.
func DecodeInput ¶ added in v0.5.0
DecodeInput processes given input replacing any Safe Links encoded URL with the original decoded value. Other input is returned unmodified.
func EncodeInput ¶ added in v0.5.0
EncodeInput processes given input replacing any normal URL with an encoded value similar to a real Safe Links value. Other input is returned unmodified.
func EncodeParsedURLAsFauxSafeLinksURL ¶ added in v0.5.0
EncodeParsedURLAsFauxSafeLinksURL encodes the provided ParsedURL 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 ¶ added in v0.5.0
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 ¶ added in v0.5.0
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 QueryEscapeInput ¶ added in v0.5.0
QueryEscapeInput processes given input replacing any normal URL with an escaped string so it can be safely placed inside a URL query. Other input is returned unmodified.
func ReadFromFile ¶ added in v0.5.0
ReadFromFile attempts to read newline separated entries from a given file (io.Reader).
The collection of entries is returned or an error if one occurs.
func ReadURLFromUser ¶
ReadURLFromUser attempts to read input from the user via stdin prompt. The user is prompted for a URL but validation of that input is left to the caller to perform.
func ValidSafeLinkURL ¶ added in v0.4.0
ValidSafeLinkURL validates whether a given url.URL is a valid Safe Links URL.
func ValidURL ¶ added in v0.4.0
ValidURL attempts to validate whether a given url.URL value is a valid / usable URL. On its down url.Parse is *very* forgiving so we apply additional checks to ensure the url.URL value meets our minimum requirements.
func ValidURLPattern ¶ added in v0.5.0
ValidURLPattern attempts to validate whether a given input string is a valid URL.
Types ¶
type FoundURLPattern ¶ added in v0.4.0
type FoundURLPattern struct {
URLPattern string
// contains filtered or unexported fields
}
FoundURLPattern is an unvalidated URL pattern match found in given input.
func GetURLPatternsUsingIndex ¶ added in v0.4.0
func GetURLPatternsUsingIndex(input string, evalAllHTTPURLs bool) ([]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. If specified, non-HTTPS URLs are evaluated also. nil is returned if no matching patterns 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://' (or optionally 'http://') and ending with a whitespace character or a right angle bracket. The caller is responsible for trimming angle brackets and other unwanted characters.
func GetURLPatternsUsingPrefixMatchingOnFields ¶ added in v0.4.0
func GetURLPatternsUsingPrefixMatchingOnFields(input string, evalPlainHTTP bool) ([]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. If specified, non-HTTPS URLs are evaluated also. nil is returned if no matching patterns 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 with a left angle bracket, then 'https://' (or 'http://' if specified) and ending with a whitespace character. The caller is responsible for trimming angle brackets and other unwanted characters.
func GetURLPatternsUsingRegex ¶ added in v0.4.0
func GetURLPatternsUsingRegex(input string, evalPlainHTTP bool) ([]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. If specified, non-HTTPS URLs are evaluated also. nil is returned if no matching patterns 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://' (or 'http://' if specified) and ending with a whitespace character or a right angle bracket. The caller is responsible for trimming angle brackets and other unwanted characters.
type ParsedURL ¶ added in v0.5.0
type ParsedURL struct {
// Original is the untrimmed, unmodified original match pattern.
Original string
// Parsed is the parsed form of the original match pattern *after* it has
// been trimmed of unwanted/invalid characters (e.g., angle brackets,
// period).
Parsed *url.URL
}
ParsedURL contains the original matched URL pattern and a parsed URL.
func FilterParsedURLs ¶ added in v0.5.0
FilterParsedURLs filters the given collection of parsed URLs, returning the remaining parsed 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 URLs ¶ added in v0.4.0
URLs parses the given input and returns a collection of ParsedURL 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. If specified, non-HTTPS URLs are also evaluated. nil is returned if no matching patterns are found.
The result is a collection of ParsedURL values containing the original URL match pattern and a parsed
type SafeLinkURL ¶ added in v0.4.0
SafeLinkURL contains the encoded and decoded URLs for a matched Safe Link.
func FromURLs ¶ added in v0.4.0
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 ¶ added in v0.4.0
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 SafeLinkURLsFromParsedURLs ¶ added in v0.5.0
func SafeLinkURLsFromParsedURLs(parsedURLs []ParsedURL) ([]SafeLinkURL, error)
SafeLinkURLsFromParsedURLs evaluates a given collection of parsed 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.
func SafeLinkURLsFromURLs ¶ added in v0.4.0
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.
Source Files