TLS Utils

retrieve and test certificate of a tls-endpoint

Overview

This node, named "TLS Utils," is designed to retrieve and test the TLS certificate of a specified TLS endpoint. It connects to a given host and port, optionally using a server name for SNI (Server Name Indication), and performs an analysis of the TLS certificate presented by that endpoint.

Common scenarios where this node is beneficial include:

Monitoring the validity and expiration of TLS certificates on web servers or other TLS-enabled services.
Automating security checks in deployment pipelines to ensure certificates are valid before releasing software.
Alerting or logging when certificates are close to expiration based on a configurable grace period.

For example, you could use this node to check the TLS certificate of webserver1.example.com on port 443 and receive detailed information about its validity and remaining lifetime.

Properties

Name	Meaning
Host	The hostname or IP address of the TLS endpoint to connect to (e.g., `webserver1.example.com`). Required.
Port	The port number of the TLS endpoint (default is 443). Required.
Servername	The domain name to use in the SNI header during the TLS handshake (optional).
Additional Fields	Collection of optional additional settings:
- Grace Period	A decimal number between 0 and 1 representing the percent of the certificate's lifetime used as a grace period for warnings (default 0.1).

Output

The node outputs an array of JSON objects, each corresponding to one input item checked. Each output object includes:

host: The host that was checked.
port: The port that was checked.
Additional fields returned from the TLS test utility, which typically include details about the TLS certificate such as:
- Certificate validity status.
- Expiration date.
- Time left until expiration.
- Whether the certificate is currently valid.
- Possibly other metadata related to the TLS connection and certificate.

The exact structure of these additional fields depends on the underlying TLS testing utility but generally provides comprehensive certificate information.

No binary data output is produced by this node.

Dependencies

This node relies on an internal helper function (testTls) imported from a local utilities module to perform the TLS certificate retrieval and testing.
No external API keys or credentials are required.
Requires network access to the specified host and port to establish a TLS connection.

Troubleshooting

Connection failures: If the node cannot connect to the specified host and port, verify network connectivity, firewall rules, and that the target service is listening on the given port.
Invalid host or port: Ensure the host is a valid hostname or IP address and the port is correct.
SNI issues: If the server requires SNI and the Servername property is not set correctly, the TLS handshake may fail or return an unexpected certificate.
Certificate parsing errors: If the certificate is malformed or the TLS handshake fails, the node might throw errors related to certificate retrieval or parsing.
Grace period misconfiguration: Setting the grace period outside the allowed range (0 to 1) may cause unexpected behavior; keep it within bounds.