Plugin info

name: tls-inspect

inspects TLS properties for tcp or unix domain socket endpoints:

• TLS certificate time to expiration
• TLS certificate verification

Events

• tls/inspect/cert_verify_error indicates server certificate verification problem identified by
  • source, the tcp or unix domain socket address
  • server_name, the server name used for the TLS connection
  • origin, the hostname that the check was originated from
• tls/inspect/error indicates an inspection error agains an endpoint identified by
  • source, the hostname that the check was originated from

Metrics

• tls/inspect/cert_expire_time, the time in hours in which the server certificate will expire identified by
  • source, the tcp or unix domain socket address
  • server_name, the server name used for the TLS connection
  • origin, the hostname that the check was originated from

TLDR

# list of endpoints to inspect
endpoints:
  - addr: example.com:443 # inspect tcp address in host:port format
  - addr: crm.example.com # port defaults to 443
  - addr: example.com:8443 
    network: tcp # the default
    sni: crm-stage.example.com # your DNS cannot resolve crm-stage.example.com but can resolve example.com
  - addr: 192.168.56.2:8443
    sni: erp.example.com # certificate issued for erp.example.com but no DNS for it in this network 
  - addr: /var/run/crm/listen.sock # path to unix domain socket to inspect
    network: unix    

Configuration

The plugin is configured with a list of endpoint checks and optionally a chain of trusted certificates on top of the system root certificates configured in your OS. You can also specify an HTTP proxy, that supports the CONNECT method, to route checks through.

Name	Type	Required	Default	Description
timeout	duration	No	10s	Connection timeout
trusted_root_certs_path	string	No		Path to certificate PEM chain of trusted root certificates. Added to system root certificates defined by your OS
trusted_root_certs	string			Same as trusted_root_certs_path but inline
skip_verify	bool	No	false	Do not verify server certificates
proxy	Proxy Configuration	No		HTTP proxy setup. Requests will be configured through this proxy using HTTP CONNECT
no_proxy	string	No		Comma-separated values specifying hosts that should be excluded from proxying.
endpoints	list[Endpoint Configuration]	No		List of endpoints to inspect

no_proxy values configuration:

• IP address prefix such as 1.2.3.4
• IP address prefix in CIDR notation such as 1.2.3.4/24
• A domain name
  • matches the domain name and all sub domains
  • a leading . matches subdomains only
    • example.com will match example.com and org.example.com
    • .example.com will match org.example.com but not example.com
• A single * indicates that no proxying will be done
• IP address prefixes and domain names can also include a port number such as 1.2.3.4:8443 and example.com:8443

Proxy Configuration

Unix domain sockets, localhost and loopback addresses are never proxied

Name	Type	Required	Default	Description
url	string	Yes		the HTTP proxy URL, e.g. http://proxy.example.com:3128
user	string	No		username for basic authentication to the proxy. It can be feteched from secrets store when specified as ${secret-name}
password	string	No		password for basic authentication to the proxy. It can be feteched from secrets store when specified as ${secret-name}

Endpoint Configuration

Name	Type	Required	Default	Description
network	string	No	tcp	One of tcp or unix
addr	string	Yes		The endpoint address. - for tcp networks in host:port format with port defaulting to 443. - for unix networks the path to the unix domain socket
sni	string	No		The hostname to use in the TLS handshake, for tcp defaults to the address without the port. Use when address cannot be resolved by DNS