HTTPS certificate monitoring in Home Assistant

Intro

Recently Let's Encrypt has announced that it will drop support for Expiration Notification Emails. When the announcement was made they even suggested a couple of services that provide this functionality, but where is the fun in that?

I decided that I will use a local service for that and since I use Home Assistant for a lot of other stuff, I decided that I will integrate this in my HA dashboard. Using HA also provides notifications out of the box, which I already use in my Home Assistant Companion App

Let the fun begin!

Finding the certificate information

I decided that it would be nice to have a small utility to give me the number of days until the certificate expire.

Fortunately it turns out that it is not that complicated to do it in Go. I've made a script to do that, you can find it here: https://github.com/claudiu-persoiu/domain-expire.

All the interesting logic it is:

1    conn, err := tls.Dial("tcp", domain+":443", conf)
2    ....
3    cert := conn.ConnectionState().PeerCertificates[0]
4
5    diff := cert.NotAfter.Sub(time.Now())

We are just retrieving the chain of certificates, take the first one and subtract the time.

Feel free to download the appropriate executable for your OS from here: https://github.com/claudiu-persoiu/domain-expire/releases and rename it to domain. I will be using that name for the executable for the rest of the tutorial.

Home Assistant setup

To add it in Home Assistant we need to run the command above from time to time.

To make sure HA has access to the executable it should be copied to the /config folder, where the other HA configs are stored. Make sure it is moved and it can be run in that folder using the command line like so:

$ ./domain google.com

The return value should be an integer representing the number of days before the certificate expires.

Now that we know it's working it's time to add the sensor to HA, edit configuration.yaml and add:

1command_line:
2   - sensor:
3         unique_id: days_google_com
4         name: Days Google.com
5         command: "/config/domain google.com"
6         unit_of_measurement: "days"
7         scan_interval: 21600

If you don't want to monitor Google, feel free to change that to your domain.

The scan interval is twice a day, I don't really need that to be any more often as this certificates don't change very often.

Restart HA. At this point the entity should be available in Home Assistant!

Home Assistant notification

Maybe you don't look that often at the HA dashboard, or don't look that often at this entity in particular and it doesn't really change that much over time, a notification would be very useful not to miss it!

I will be using the HA notifications as they are very convenient if you already use the Home Assistant Companion App.

In your /config/automations folder create a new file, called domain.yaml and add the code below:

 1- id: domain_alert
 2  alias: Domain Google.com
 3  trigger:
 4  - trigger: time
 5    at: "09:30:00"
 6  conditions: "{{ states('sensor.days_google_com') | float < 10 }}"
 7  action:
 8  - data:
 9      title: 'Update the certificate!'
10      message: 'Remember to update the certificate for Google.com!'
11      data:
12        sticky: 'true'
13        clickAction: "/lovelace/default_view"
14    service: notify.ALL_DEVICES

Again, if you don't work for Google you may need to change the sensor.days_google_com.

I've done some assumptions, the script will only run at 9:30AM, since the script doesn't change that often it doesn't make a lot of sense to do it very often, you may need to modify that.

Also the notification is send to all devices, if you have your spouse uses HA, maybe you don't want to do that, just keep that in mind.

Conclusion

In just a few easy (hopefully) steps you can now monitor your ssl certificates using your on HA instance, instead of using some other free service...