certcheck

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 12, 2025 License: MIT Imports: 10 Imported by: 0

README

CheckCert - Certificate Validity Checker

checkcert is a CLI tool and Nagios plugin designed to check the validity of SSL/TLS certificates. It evaluates certificate expiration and alerts based on customizable thresholds. The tool provides detailed metrics for performance analysis.

Features

  • Validate SSL/TLS certificates for any hostname.
  • Support for custom warning and critical thresholds (in days).
  • Optional STARTTLS protocol support (smtp, imap, ftp).
  • Configurable connection timeout, DNS timeout, and retries.
  • Performance metrics for DNS lookup, connection, TLS initialization, and handshake.

Usage

$ checkcert -h <hostname> -c <critical_days> -w <warning_days>
Flags
Flag Description Default
-h <HOSTNAME> Hostname to connect to Required
-c <CRITICAL DAYS> Days before expiration to trigger a critical alert 1
-w <WARNING DAYS> Days before expiration to trigger a warning alert 5
-p <PORT> Port to connect to 443
-s <STARTTLS PROTOCOL> Use STARTTLS protocol instead of HTTPS (smtp, imap, ftp) None
-t <CONNECTION TIMEOUT> Timeout for connecting to the server 5s
-i <DNS TIMEOUT> Timeout for resolving the IPs of the hostname 5s
-r <DNS RETRIES> Number of retries if a DNS resolution fails 3
-m Verify that certificate name matches the hostname False
-n <CERTIFICATE NAME> Check for a specific certificate name instead of the hostname Hostname

Exit Codes

  • 0: OK - Certificate is valid beyond the warning threshold.
  • 1: WARNING - Certificate is approaching expiration.
  • 2: CRITICAL - Certificate is near expiration or invalid.

Example

$ checkcert -h example.com -c 3 -w 7

This checks the certificate for example.com on port 443 with a warning threshold of 7 days and a critical threshold of 3 days.

License

This project is licensed under the MIT License. See the LICENSE file for details. Developed by Winni Neessen [email protected].

Documentation

Overview

Package certcheck implements a certificate checker.

This package provides functionality to perform certificate validation and connection diagnostics, including DNS lookups, connection establishment, and optional TLS handshake verification. It supports checking certificates for various protocols, including standard TLS and STARTTLS for SMTP, IMAP, and FTP.

Index

Constants

View Source 
const (
	// DefaultTimeout is the default timeout used for operations when no specific timeout is provided.
	DefaultTimeout = time.Second * 5

	// DefaultRetries is the default number of retries for DNS lookups.
	DefaultRetries = 3

	// DefaultPort is the default port used for TLS connections (443).
	DefaultPort = 443
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Checker 

type Checker struct {
	Config Config
}

Checker represents a certificate checker instance.

Fields:

  • Config: The configuration settings used for the certificate check.

func New 

func New(config Config) *Checker

New initializes a new Checker instance with the provided configuration.

This function ensures that default values are applied to configuration fields if they are not explicitly set:

  • DNSTimeout defaults to DefaultTimeout if not specified.
  • ConnTimeout defaults to DefaultTimeout if not specified.
  • Port defaults to DefaultPort (443) if not specified.
  • Certname defaults to the Hostname if not explicitly provided.

Parameters:

  • config: A Config struct containing the desired configuration settings.

Returns:

  • A pointer to the initialized Checker instance.

func (*Checker) Check 

func (c *Checker) Check(ctx context.Context) (Result, error)

Check performs a certificate check for the configured host.

This function resolves the hostname to its IP address, establishes a connection, and optionally verifies the TLS certificate. It supports STARTTLS protocols (e.g., SMTP, IMAP, FTP) or standard TLS.

Steps:

  1. Perform a DNS lookup with retries based on the configuration.
  2. Connect to the resolved IP address and determine the TLS or STARTTLS protocol.
  3. Retrieve and optionally verify the server's certificate.
  4. Capture performance metrics for each step.

Parameters:

  • ctx: A context.Context used for managing timeouts and cancellations.

Returns:

  • A Result struct containing the certificate's expiration time, performance metrics, and severity level.
  • An error if any step in the process (DNS lookup, connection, or certificate validation) fails.

type Config 

type Config struct {
	Certname    string
	ConnTimeout time.Duration
	DNSTimeout  time.Duration
	Hostname    string
	Port        uint
	DNSRetries  uint
	StartTLS    STARTTLSProto
	VerifyCert  bool
}

Config holds the configuration settings for a certificate check.

Fields:

  • Certname: The name of the certificate to verify, defaults to the Hostname if not provided.
  • ConnTimeout: The timeout for establishing a connection.
  • DNSTimeout: The timeout for DNS lookups.
  • Hostname: The hostname of the server to connect to.
  • Port: The port to connect to, defaults to 443 if not specified.
  • DNSRetries: The number of retries for DNS lookups, defaults to a reasonable value.
  • StartTLS: The STARTTLS protocol to use, if applicable (e.g., SMTP, IMAP, FTP).
  • VerifyCert: A flag indicating whether to verify the certificate against the Certname.

type Metrics 

type Metrics struct {
	ConnTime     time.Duration
	DNSLookup    time.Duration
	TLSInit      time.Duration
	TLSHandshake time.Duration
}

Metrics captures performance metrics for various stages of a certificate check.

Fields:

  • ConnTime: The duration of the connection establishment.
  • DNSLookup: The duration of the DNS lookup.
  • TLSInit: The duration of the TLS initialization phase.
  • TLSHandshake: The duration of the TLS handshake process.

type Result 

type Result struct {
	Addresses  []net.IP
	CertExpire time.Time
	Metrics    *Metrics
	Severity   Severity
}

Result represents the outcome of a certificate check.

Fields:

  • CertExpire: The expiration time of the checked certificate.
  • Metrics: A pointer to the Metrics structure containing performance data for the check.
  • Severity: The severity level of the result, indicating the status or issues detected.

type STARTTLSProto 

type STARTTLSProto int

STARTTLSProto represents the type of STARTTLS protocol to be used during the certificate check.

This type is an integer-based enumeration for different STARTTLS-supported protocols, such as SMTP, IMAP, or FTP. 

const (
	TLSProtoNone STARTTLSProto = iota
	TLSProtoSMTP
	TLSProtoIMAP
	TLSProtoFTP
)

STARTTLS protocol types for use in the certificate check.

Constants:

  • TLSProtoNone: No STARTTLS protocol is used.
  • TLSProtoSMTP: STARTTLS for the SMTP protocol.
  • TLSProtoIMAP: STARTTLS for the IMAP protocol.
  • TLSProtoFTP: STARTTLS for the FTP protocol.

type Severity 

type Severity int

Severity represents the level of importance or criticality of a certificate check result.

This type is used to classify the outcome of a check into categories such as OK, Warning, or Critical. 

const (
	// SeverityOK indicates that the check passed with no issues.
	SeverityOK Severity = iota

	// SeverityWarning indicates that the check passed with some warnings or potential issues.
	SeverityWarning

	// SeverityCritical indicates that the check failed due to critical issues.
	SeverityCritical
)

Severity levels for the result of a certificate check.

Source Files

View all Source files

Directories

Path Synopsis
cmd
nagios command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.