Building an Internal TLS and SSL Certificate Monitoring Agent: From Concept to Deployment

Can you monitor your internal SSL certificates? This was a question we frequently heard from our clients. Many organizations keep their services (web, database, etc.) inaccessible on the public internet, for security, compliance, cost, and other reasons. At TrackSSL, we initially offered public SSL/TLS certificate monitoring, but we often received requests from customers for private SSL certificate monitoring. Thus, we needed to find a way to monitor certificates used on servers that are not typically accessible from the Internet.

In this article, we share our journey of developing a remote certificate monitoring service using an agent that runs on an organization's private network. We share the requirements we defined, the architecture we selected, and the solution we implemented.

Let’s dive in. 

Technical Requirements

Our goal was to build a monitoring system that would monitor certificates on internal networks and we decided on the following requirements:

1. Lightweight and Efficient

The agent we used had to be small and lightweight. It should use minimal data center resources. It has to run seamlessly without affecting the performance of other systems. Scheduling automation should also be built in.

2. Simple Runtime

The agent has to be flexible, running either a containerized application or a single executable. It should be able to run on multiple platforms including Mac, Linux, and Windows.

3. Support for Multiple Agents

It should accommodate distinct private network segments across an organization. The agent should be able to be deployed across the segments. This ensures comprehensive monitoring throughout the entire network infrastructure or even in different offices, buildings, or locations.

4. Delegated Processing

The agent should only handle essential tasks within the private network. More intensive processing can be delegated to the existing cloud-hosted API and dashboard. This approach will cut the load on internal systems and keep the process easy to maintain.

5. Comprehensive Certificate Support

The agent should support self-signed certificates and certificates issued by popular public certification authorities. Additionally, it monitors any type of TLS certificate, including HTTP and LDAP.

6. Open Source Code

It will have a publicly available code. This way, any organization can review and verify its security and reliability. This transparency fosters trust and confidence in our solution.

Here’s what we decided to build based on the requirements we listed.

The Architecture Behind the TLS/SSL Certificate Monitoring Agent

Based on the requirements we outlined, we developed the architecture of our TLS/SSL monitoring agent. Here’s a detailed look at it:

Development and Language Choice

The agent is developed in Ruby, which is consistent with the rest of TrackSSL's infrastructure. This decision leverages our team's expertise, ensuring smooth production and maintenance. Ruby is known as a flexible scripting language used for a wide variety of tasks. Although it might have decreased performance compared to lower-level languages, high-volume performance was not an issue for this use case.

Docker Containerization

The agent is containerized using Docker, providing a robust and industry-standard deployment method. Docker's widespread use in enterprises ensures reliable and consistent performance across various environments.

Configuration

The configuration included:

1. Simple Configuration File  

Configuration is managed through an easily editable text file. It is accessible across platforms with minimal technical knowledge.

2. Public Token and Private API Key  

Firstly, the user creates an agent in the TrackSSL dashboard. Then, a public token and a private API key are generated. The public token is simply a unique identifier used to associate the certificates on that internal network with certificates the user has previously defined inside the TrackSSL dashboard. The private API key is the securely generated secret used to authenticate to the API. This token must be kept private.

3. Easy Setup

Users place the configuration file in the same directory as the Docker container. The agent then automatically pulls the necessary settings and makes API calls back to the cloud-hosted process using the public token and private API key.

Scheduling and Execution

Built-In Scheduling  

The agent uses a “rufus-scheduler” to schedule certificate checks every four hours. This eliminates the need for cron jobs or extra system configuration. This is a lightweight gem that is commonly used in Ruby applications to schedule tasks using standard cron syntax. It’s multi-threaded and has been well-maintained for more than a decade, making it a good candidate.

Asynchronous Execution

With “sucker-punch”, the agent fetches certificates in parallel. Thus it performs high-volume checks without needing an additional daemon like Sidekiq. This is another gem that is widely used and well-maintained, having been in active service for more than 12 years. A gem that’s kept up-to-date and maintained is essential, especially for software that will run unattended on various deployments around the globe.

The Process of Checking Certificates

When checking certificates, we ensured the following: 

API Call

The agent calls the TrackSSL API to retrieve the list of certificates every four hours. Using the private API key, the agent fetches the list of certificates that have been previously assigned to its unique identifier, the public token.

Certificate Retrieval

The agent connects to specified servers and ports on the local network. This is the key step that is only possible on the local network. Because these can often be non-routable IPs or internal hostnames that don’t resolve publicly, it’s essential this step runs inside the local network. The agent retrieves certificates based on hostnames or IP addresses and does not access any other data. Once it connects to the port and fetches the certificate, the connection is closed. This maintains privacy and security within the private network.

Security Considerations

The agent strictly retrieves certificates without making HTTP connections. So, it adheres to high-security standards and fosters customer trust. Because the agent is open source, users can see that no other data is accessed by the agent.

Integrating With TrackSSL API

When integrating with the TrackSSL API, we considered the following two factors:

1. Certificate Handling 

The agent posts the retrieved certificates to the TrackSSL API. Then they are processed and handled like any public certificate. Because detailed analysis of the certificate does not happen inside the agent, we can limit the surface area of the deployed agents.

2. Centralized Notifications

All notifications are managed in the cloud, so the customers do not handle email notifications, SMTP management, or certificate parsing.

Our solution is a daemon process written in Ruby. It uses OpenSSL for certificate handling. OpenSSL offers simplicity, a small footprint, and reliable encryption. These are its core strengths in certificate management.

We plan to scale up to handle more certificates and enhance error and exception handling.

User’s Perspective: The Launching Process

When launching, we kept our users in mind. So, we considered the following: 

1. Creating an Agent Instance

Users start by creating an agent in their TrackSSL account. You can name the agent after your internal network or choose any memorable name. Each internal network requires its own agent. 

You can create many agents for your separate networks, subnets, or VPCs. Each one will be responsible for its set of certificates. Copy the generated token for your agent, referred to as  TRACKSSL_AGENT_TOKEN.

2. Assign Domains to the Agent

Next, a user needs to add a domain representing a hostname or IP address that serves as the endpoint for an SSL/TLS certificate. Navigate to the "Domains" section on the left to assign domains for your internal agent. Then select the domain and choose the corresponding agent.

3. Generate an API Token

Next, create an API token for your agent to use. One API token suffices regardless of the number of agents. However, you can create multiple tokens and revoke them as needed.

• The generated API token is called TRACKSSL_AUTH_TOKEN.
• Place both TRACKSSL_AUTH_TOKEN and TRACKSSL_AGENT_TOKEN into a file named environment.txt, formatted as follows:

TRACKSSL_AUTH_TOKEN=your_api_token_here

TRACKSSL_AGENT_TOKEN=your_agent_token_here

4. Pull and Run the Docker Container

Download and run the Docker container with the following commands:

$ docker pull ghcr.io/trackssl/trackssl-agent:latest

$ docker run -d --env-file ./environment.txt --name trackssl-agent ghcr.io/trackssl/trackssl-agent

Once the agent instance is launched on a local network, it operates on a schedule every four hours. The agent will:

• Make an API call to the platform’s cloud-hosted dashboard.
• Fetch the list of certificates it monitors.
• Retrieve each certificate from your local network.
• Push the certificates to TrackSSL in the cloud for notification and monitoring.

By following these steps, we ensured a seamless launching experience. 

Conclusion

Our monitoring agent addresses the need to monitor internal TLS/SSL certificates. It supports a wide range of certificates and provides flexible deployment options.

One improvement we plan to make is to simplify the installation process further. One of our core assumptions is that Docker is widely installed across the enterprise and available in most environments. However, this turned out not to be true. Many TrackSSL customers don’t have Docker and prefer a single runtime executable they can use on any platform. This iteration is in the works.

Let us know what you think about our approach to internal SSL certificate monitoring in the comments below. What would you do differently?