config

Documentation

Overview

Package config provides types and functions to collect, validate and apply user-provided settings.

Index

• Constants
• Variables
• func Branding(msg string) func() string
• func Version() string
• type AppType
• type Config
  • func New(appType AppType) (*Config, error)
  • func (c Config) ApplyCertExpirationValidationResults() bool
  • func (c Config) ApplyCertHostnameValidationResults() bool
  • func (c Config) ApplyCertSANsListValidationResults() bool
  • func (c Config) CertPorts() []int
  • func (c Config) CertTypesToKeep() []string
  • func (c Config) Hosts() []netutils.HostPattern
  • func (c Config) Timeout() time.Duration
  • func (c Config) TimeoutAppInactivity() time.Duration
  • func (c Config) TimeoutPortScan() time.Duration

Constants

const (

	// This flag uses "ignore" wording to make clear that the validation check
	// is still applied, but the results ignored when determining overall
	// certificate chain validation state.
	IgnoreHostnameVerificationFailureIfEmptySANsListFlag string = "ignore-hostname-verification-if-empty-sans"

	IgnoreExpiredIntermediateCertificatesFlag  string = "ignore-expired-intermediate-certs"
	IgnoreExpiredRootCertificatesFlag          string = "ignore-expired-root-certs"
	IgnoreExpiringIntermediateCertificatesFlag string = "ignore-expiring-intermediate-certs"
	IgnoreExpiringRootCertificatesFlag         string = "ignore-expiring-root-certs"

	VersionFlagLong          string = "version"
	OmitSANsListFlagLong     string = "omit-sans-list"
	OmitSANsEntriesFlagLong  string = "omit-sans-entries"
	VerboseFlagLong          string = "verbose"
	VerboseFlagShort         string = "v"
	BrandingFlag             string = "branding"
	PayloadFlag              string = "payload"
	PayloadWithFullChainFlag string = "payload-with-full-chain"
	ServerFlagLong           string = "server"
	ServerFlagShort          string = "s"
	PortFlagLong             string = "port"
	PortFlagShort            string = "p"
	DNSNameFlagLong          string = "dns-name"
	DNSNameFlagShort         string = "dn"

	// Flags used for specifying a list of keywords used to explicitly ignore
	// or apply validation check results when determining final plugin state.
	IgnoreValidationResultFlag string = "ignore-validation-result"
	ApplyValidationResultFlag  string = "apply-validation-result"

	ListIgnoredErrorsFlag             string = "list-ignored-errors"
	FilenameFlagLong                  string = "filename"        // inspector, plugin; potentially deprecated
	InputFilenameFlagLong             string = "input-filename"  // copier
	InputFilenameFlagShort            string = "if"              // copier
	OutputFilenameFlagShort           string = "of"              // copier
	OutputFilenameFlagLong            string = "output-filename" // copier
	CertTypesToKeepFlagLong           string = "keep"            // copier
	EmitCertTextFlagLong              string = "text"
	TimeoutFlagLong                   string = "timeout"
	TimeoutFlagShort                  string = "t"
	LogLevelFlagLong                  string = "log-level"
	LogLevelFlagShort                 string = "ll"
	TimeoutPortScanFlagLong           string = "scan-timeout"
	TimeoutPortScanFlagShort          string = "st"
	HostsFlagLong                     string = "hosts"
	HostsFlagAlt                      string = "ips"
	ScanRateLimitFlagLong             string = "scan-rate-limit"
	ScanRateLimitFlagShort            string = "srl"
	AppTimeoutFlagLong                string = "app-timeout"
	AppTimeoutFlagShort               string = "at"
	PortsFlagLong                     string = "ports"
	PortsFlagShort                    string = "p"
	ShowPortScanResultsFlagLong       string = "show-port-scan-results"
	ShowPortScanResultsFlagShort      string = "spsr"
	ShowHostsWithClosedPortsFlagLong  string = "show-closed-ports"
	ShowHostsWithClosedPortsFlagShort string = "scp"
	ShowHostsWithValidCertsFlagLong   string = "show-hosts-with-valid-certs"
	ShowHostsWithValidCertsFlagShort  string = "shwvc"
	ShowValidCertsFlagLong            string = "show-valid-certs"
	ShowValidCertsFlagShort           string = "svc"
	ShowOverviewFlagLong              string = "show-overview"
	ShowOverviewFlagShort             string = "so"
	SANsEntriesFlagLong               string = "sans-entries"
	SANsEntriesFlagShort              string = "se"
	AgeWarningFlagLong                string = "age-warning"
	AgeWarningFlagShort               string = "w"
	AgeCriticalFlagLong               string = "age-critical"
	AgeCriticalFlagShort              string = "c"
)

Flag names for consistent references. Exported so that they're available from tests.

const (
	ValidationKeywordExpiration string = "expiration"
	ValidationKeywordHostname   string = "hostname"
	ValidationKeywordSANsList   string = "sans"
)

Validation keywords used when explicitly ignoring or applying validation check results to determine final plugin state.

NOTE: These need to be manually kept in sync with Flag Help Text.

const (
	CertTypeAll          string = "all"
	CertTypeLeaf         string = "leaf"
	CertTypeIntermediate string = "intermediate"
	CertTypeRoot         string = "root"
)

Certificate type keywords used when filtering specific certificate types for the output file.

const (

	// LogLevelDisabled maps to zerolog.Disabled logging level
	LogLevelDisabled string = "disabled"

	// LogLevelPanic maps to zerolog.PanicLevel logging level
	LogLevelPanic string = "panic"

	// LogLevelFatal maps to zerolog.FatalLevel logging level
	LogLevelFatal string = "fatal"

	// LogLevelError maps to zerolog.ErrorLevel logging level
	LogLevelError string = "error"

	// LogLevelWarn maps to zerolog.WarnLevel logging level
	LogLevelWarn string = "warn"

	// LogLevelInfo maps to zerolog.InfoLevel logging level
	LogLevelInfo string = "info"

	// LogLevelDebug maps to zerolog.DebugLevel logging level
	LogLevelDebug string = "debug"

	// LogLevelTrace maps to zerolog.TraceLevel logging level
	LogLevelTrace string = "trace"
)

const ExitCodeCatchall int = 1

ExitCodeCatchall indicates a general or miscellaneous error has occurred. This exit code is not directly used by monitoring plugins in this project. See https://tldp.org/LDP/abs/html/exitcodes.html for additional details.

const SkipSANSCheckKeyword string = "SKIPSANSCHECKS"

SkipSANSCheckKeyword is used as the sole argument to SANsEntriesFlagLong if the user wishes to ignore SANs entry validation check results. This seemingly illogical option allows defining the SANsEntriesFlagLong flag in a command definition used by a group-based service check even though some systems targeted by that service check may use a certificate which does not have any SANs entries present.

Variables

var (
	// ErrVersionRequested indicates that the user requested application
	// version information.
	ErrVersionRequested = errors.New("version information requested")

	// ErrInvalidPosArgPattern indicates that the user provided an invalid
	// pattern for a positional argument.
	ErrInvalidPosArgPattern = errors.New("invalid positional argument pattern")

	// ErrUnsupportedOption indicates that an unsupported option was specified.
	ErrUnsupportedOption = errors.New("unsupported option")
)

Functions

func Branding

func Branding(msg string) func() string

Branding accepts a message and returns a function that concatenates that message with version information. This function is intended to be called as a final step before application exit after any other output has already been emitted.

func Version

func Version() string

Version emits application name, version and repo location.

Types

type AppType

type AppType struct {

	// Scanner represents an application intended for bulk operations across a
	// range of hosts.
	Scanner bool

	// Plugin represents an application used as a Nagios plugin.
	Plugin bool

	// Inspector represents an application used for one-off or isolated
	// checks. Unlike a Nagios plugin which is focused on specific attributes
	// resulting in a severity-based outcome, an Inspector application is
	// intended for examining a small set of targets for
	// informational/troubleshooting purposes.
	Inspector bool

	// Copier represents an application used for copying or manipulating
	// certificates.
	Copier bool
}

AppType represents the type of application that is being configured/initialized. Not all application types will use the same features and as a result will not accept the same flags. Unless noted otherwise, each of the application types are incompatible with each other, though some flags are common to all types.

type Config

type Config struct {

	// SANsEntries is the list of Subject Alternate Names (SANs) to verify are
	// present on the examined certificate. This value is provided as a
	// comma-separated list.
	SANsEntries multiValueStringFlag

	// InputFilename is the fully-qualified path to an input file containing
	// one or more certificates.
	InputFilename string

	// OutputFilename is the fully-qualified path to an output file where one
	// or more certificates will be written.
	OutputFilename string

	// Server is the fully-qualified domain name or IP Address of the system
	// running a certificate-enabled service.
	Server string

	// PosArgInputPattern is either the fully-qualified domain name or IP
	// Address of the system running a certificate-enabled service or the
	// fully-qualified path to an input file containing one or more
	// certificates.
	PosArgInputPattern string

	// PosArgOutputPattern is the fully-qualified path to an output file where
	// one or more certificates will be written.
	PosArgOutputPattern string

	// ScanRateLimit is the maximum number of concurrent port scan attempts.
	ScanRateLimit int

	// DNSName is the fully-qualified domain name associated with the
	// certificate. This is usually specified when the FQDN or IP used to make
	// the connection is different than the Common Name or Subject Alternate
	// Names entries associated with the certificate.
	DNSName string

	// Port is the TCP port used by the certificate-enabled service.
	Port int

	// LoggingLevel is the supported logging level for this application.
	LoggingLevel string

	// AgeWarning is the number of days remaining before certificate
	// expiration when this application will flag the NotAfter certificate
	// field as a WARNING state.
	AgeWarning int

	// AgeCritical is the number of days remaining before certificate
	// expiration when this application will flag the NotAfter certificate
	// field as a CRITICAL state.
	AgeCritical int

	// EmitBranding controls whether "generated by" text is included at the
	// bottom of application output. This output is included in the Nagios
	// dashboard and notifications. This output may not mix well with branding
	// output from other tools such as atc0005/send2teams which also insert
	// their own branding output.
	EmitBranding bool

	// EmitPayload controls whether an encoded certificate chain payload is
	// included at the bottom of plugin output.
	EmitPayload bool

	// EmitPayloadWithFullChain controls whether an encoded certificate chain
	// payload (included at the bottom of plugin output) also bundles the full
	// original certificate chain. If enabled this significantly increases the
	// payload size.
	EmitPayloadWithFullChain bool

	// VerboseOutput controls whether detailed certificate metadata is emitted
	// along with standard certificate details.
	VerboseOutput bool

	// OmitSANsEntries controls whether SANs entry list items from a leaf
	// certificate are included in certificate details.
	OmitSANsEntries bool

	// EmitCertText controls whether x509 TLS certificates are printed to
	// stdout using an OpenSSL-inspired text format. There is a good bit of
	// output text, so this setting defaults to false.
	EmitCertText bool

	// ShowVersion is a flag indicating whether the user opted to display only
	// the version string and then immediately exit the application.
	ShowVersion bool

	// ShowHostsWithClosedPorts indicates whether hosts without any open ports
	// are included in the port scan results summary output.
	ShowHostsWithClosedPorts bool

	// ShowHostsWithValidCerts indicates whether hosts with valid certificates
	// are included in the overview summary output.
	ShowHostsWithValidCerts bool

	// ShowValidCerts indicates whether all certificates are included in
	// output summary, even certificates which have passed all validity
	// checks.
	ShowValidCerts bool

	// ShowOverview indicates whether a brief overview of certificate scan
	// findings is provided, or whether the detailed certificate results list
	// is shown at the end of scanning specified hosts.
	ShowOverview bool

	// ShowResultsDuringScan indicates whether host scan results should be
	// shown during a port scan. See also ShowHostsWithClosedPorts. Enabling
	// either of these options results in live scan result details being
	// shown.
	ShowPortScanResults bool

	// IgnoreHostnameVerificationFailureIfEmptySANsList indicates whether
	// hostname verification failure should be ignored if a certificate has an
	// empty SANs list.
	//
	// Go 1.17 removed support for the legacy behavior of treating the
	// CommonName field on X.509 certificates as a host name when no Subject
	// Alternative Names are present. Go 1.17 also removed support for
	// re-enabling the behavior by way of adding the value x509ignoreCN=0 to
	// the GODEBUG environment variable.
	//
	// This setting is provided in order to still allow validating a
	// certificate's expiration date for older certificates when a SANs list
	// is empty and would otherwise result in validation check results
	// failure.
	IgnoreHostnameVerificationFailureIfEmptySANsList bool

	// IgnoreExpiringIntermediateCertificates indicates whether expiring
	// intermediate certificates should be ignored.
	IgnoreExpiringIntermediateCertificates bool

	// IgnoreExpiringRootCertificates indicates whether expiring root
	// certificates should be ignored.
	IgnoreExpiringRootCertificates bool

	// IgnoreExpiredIntermediateCertificates indicates whether expired
	// intermediate certificates should be ignored.
	IgnoreExpiredIntermediateCertificates bool

	// IgnoreExpiredRootCertificates indicates whether expired root
	// certificates should be ignored.
	IgnoreExpiredRootCertificates bool

	// ListIgnoredValidationCheckResultErrors indicates whether validation
	// check result errors should be included in the final plugin report
	// output. By default, ignored errors are not included as this may prove
	// confusing (e.g., when all results are either successful or ignored).
	ListIgnoredValidationCheckResultErrors bool

	// Log is an embedded zerolog Logger initialized via config.New().
	Log zerolog.Logger
	// contains filtered or unexported fields
}

Config represents the application configuration as specified via command-line flags.

func New

func New(appType AppType) (*Config, error)

New is a factory function that produces a new Config object based on user provided flag and config file values. It is responsible for validating user-provided values and initializing the logging settings used by this application.

func (Config) ApplyCertExpirationValidationResults

func (c Config) ApplyCertExpirationValidationResults() bool

ApplyCertExpirationValidationResults indicates whether certificate expiration check results should be applied when performing final plugin state evaluation. Precedence is given for explicit request to ignore this validation result.

func (Config) ApplyCertHostnameValidationResults

func (c Config) ApplyCertHostnameValidationResults() bool

ApplyCertHostnameValidationResults indicates whether certificate hostname validation check results should be applied when performing final plugin state evaluation. Precedence is given for explicit request to ignore this validation result.

func (Config) ApplyCertSANsListValidationResults

func (c Config) ApplyCertSANsListValidationResults() bool

ApplyCertSANsListValidationResults indicates whether certificate SANs list validation check results should be applied when performing final plugin state evaluation. Precedence is given for explicit request to ignore this validation result.

func (Config) CertPorts

func (c Config) CertPorts() []int

CertPorts returns the user-specified list of ports to check for certificates or the default value if not specified.

func (Config) CertTypesToKeep

func (c Config) CertTypesToKeep() []string

CertTypesToKeep returns the user-specified list of certificate types to keep when copying a given certificates chain or the default value if not specified.

func (Config) Hosts

func (c Config) Hosts() []netutils.HostPattern

Hosts returns a list of individual IP Addresses expanded from any user-specified IP Addresses (single or ranges) and hostnames or FQDNs that passed name resolution checks.

func (Config) Timeout

func (c Config) Timeout() time.Duration

Timeout converts the user-specified connection timeout value in seconds to an appropriate time duration value for use with setting net.Dial timeout.

func (Config) TimeoutAppInactivity

func (c Config) TimeoutAppInactivity() time.Duration

TimeoutAppInactivity converts the user-specified application inactivity timeout value in seconds to an appropriate time duration value for use with setting automatic context cancellation.

func (Config) TimeoutPortScan

func (c Config) TimeoutPortScan() time.Duration

TimeoutPortScan converts the user-specified port scan timeout value in milliseconds to an appropriate time duration value for use with setting net.Dial timeout.