prtg-pythonscriptadvanced-starttls_certificate_sensor

This repository contains a PRTG Python Script Advanced sensor to monitor SSL Certificates of connections which require STARTTLS to initialize a secure channel.

Sensor Summary

Script Language: Python 3.9+
Version: 2.0.0
Author: Andreas Strobl <astroblx@asgraphics.at>
Verified PRTG Version: 22.2.77.2204
Dependencies: cryptography >=37.0.0, paesslerag_prtg_sensor_api >= 1.0.2

Sensor Description

This custom Python Script Advanced sensor will monitor SSL certificates that require a protocol handshake prior to reading certificate data, and exposes the collected data in channels similar to PRTG's built-in SSL Certificate sensor.

All versions of this sensor support the following application layer protocols:

• SMTP: Simple Mail Transfer Protocol, RFC 5321
• LMTP: Local Mail Transfer Protocol, RFC 2033
• LDAP: Lightweight Directory Access Protocol, RFC 4511

The LDAP protocol handshake has been tested against Active Directory, OpenLDAP, and Sun Enterprise Directory Server (formerly Netscape iPlanet Directory Server) and is also expected to work with RedHat DS 389 directory server.

Sensor Channels

The following channels are implemented:

• Days until Expiration - primary channel
• Common Name Check - with support for CN and CN/SAN validation
• Public Key Size
• Root Authority Trusted
• Self-Signed

All channels but the primary channel use PRTG built-in value lookup definitions.

Common Name Check

PRTGs built-in SSL Certificate sensor allows also to validate SNI Domainname values. Since this is in essence a check of an user-specified domain name against the commonName and/or subjectAltName attribute of the certificate, this sensor ommits the result values SNI Domainname matches and SNI Domainname does not match.

If the device's network address is specified as domain name and is the same as contained in the certificate, the parameter cert_domainname can be omitted.

Root Authority Trusted

This check uses the default mechanisms of the Python ssl module to verify the trust of the certificate. This includes the check of the chain and also that the root CA certificate is in the operating system vendor's certificate store.

One implication of this kind of validation is that it fails if the certificate chain is incorrect and also fails if the root CA certificate is not in the trust store of the system the probe is running on.

The check is skipped entirely if the installed certificate is a self-signed certificate. In this case the channel result is set to Not trusted.

Sensor Parameters

The sensor expects parameters that specify application protocol, port, and certificate name validation. Without those additional parameters the sensor returns an error result.

The parameters MUST be specified in form of key-value pairs with key and value separated by a colon. Multiple key-value pairs are separated by a comma.

The parameter string MUST NOT contain quotes, braces, brackets, and parens. It also MUST NOT contain characters outside the ASCII character set, and it MUST NOT contain the + sign. Use of any of those characters and symbols will cause PRTG to excessively escape those characters, leading to a lot of backslashes in the parameter string, which this sensor DOES NOT handle well.

Parameter port (int)

This parameter specifies the port the sensor should connect to.

Parameter protocol (Enum)

This parameter specifies the application protocol to be used to initiate a secure connection with STARTTLS.

Allowed values are: smtp, lmtp, and ldap.

Parameter cert_domainname (str)

If the device address is specified as IP address or if the device name differs from the name used in the certificate, specify the name contained in the certificate with this parameter.

Parameter cert_domainname_validation (Enum)

This parameter tells the sensor if and how it should validate commonName and/or subjectAltName certificate attributes.

Allowed values:

• None: do not validate names
• cn: validate the domain name against the certificate's commonName attribute
• cn_san: validate the domain name against the certificate's commonName and subjectAltName attributes. With subjectAltName only values of type DNS are validated.

Examples

1. The following parameter string validates the certificate of a mail server listening on port 7025 and expecting the LMTP protocol. The certificate contains multiple names in the subjectAltName attribute, the device address is specified as domain name and is contained in the subjectAltName attribute:

   port: 7025, protocol: lmtp, cert_domainname_validation: cn_san

2. In this example the device address is specified as IP address, the server is a mail server listening on port 25 with the SMTP protocol:

   port: 25, protocol: smtp, cert_domainname: mta.example.com, cert_domainname_validation: cn