datadog-tls-cert-integration

README documentation for datadog-tls-cert-integration

stableRepositoryPowerShellprivate

11 min readUpdated Jul 24, 2026@observability-teamObservability

Source: ZoosGlobal/datadog-tls-cert-integration Visibility: Private This page is automatically synchronized from the repository README. Do not edit this generated file directly.

Zoos Global TLS Certificate Monitor

PowerShell → Windows Cert Store → Datadog TLS Check → conf.yaml → Dashboards & Alerts

Automatically scans Windows Certificate Stores (Personal, Root, CA), exports certificates,
generates Datadog TLS conf.yaml, and restarts the Agent — with a weekly fallback every Sunday at 02:00 AM.

❓ The Problem — Why This Exists

TLS/SSL certificates expire silently, and on a Windows server fleet there was no centralized, automated way to know when one was about to. This created real operational risk:

No visibility into certificate expiry — Certificates living in the Windows Certificate Store (Personal, Root, CA) were never inventoried centrally; nobody knew what was installed where, or when it expired, until something broke.
Outages caused by expired certs — Without proactive alerting, an expired certificate typically surfaced as a production incident (failed connections, broken trust chains) rather than a planned renewal.
Manual, error-prone tracking — Tracking expiry dates via spreadsheets or tribal knowledge doesn’t scale across dozens/hundreds of servers and three separate cert stores per host.
No TLS version compliance visibility — There was no automated way to detect servers still negotiating outdated, insecure TLS versions (TLS 1.0/1.1).
No integration with existing monitoring — Even when certs were tracked, that data lived outside Datadog, disconnected from the dashboards and alerting the team already relied on for everything else.
Risk of one-time setup going stale — A one-off manual export of certs is a snapshot in time; new certs get added, old ones renewed, and without a recurring process the inventory drifts out of date almost immediately.

✅ The Solution — What We Built

We built a self-contained PowerShell automation that scans the Windows Certificate Store, exports every certificate, and wires the results directly into Datadog’s native TLS check — with a weekly fallback so coverage never goes stale.

Architecture

Windows Certificate Store (My / Root / CA)
        ↓
  Deploy-TLSMonitor.ps1 (scan + export)
        ↓
  Datadog conf.d\tls.d\conf.yaml (auto-generated, one instance per cert)
        ↓
  Datadog Agent restart + validation (agent check tls)
        ↓
  Datadog Metrics (tls.days_left, tls.responded, tls.version, ...) → Dashboards & Monitors

Key Design Decisions

Decision	Rationale
Scan all three relevant cert stores (My, Root, CA)	Covers personal/server certs, trusted root CAs, and intermediate CAs — full chain visibility, not just the leaf cert
Auto-generate `conf.yaml` from live scan results	Removes manual YAML editing entirely; the config always reflects what’s actually installed on the host
Backup existing `conf.yaml` before overwrite	Safe to re-run repeatedly; a bad scan never permanently destroys a working config
Rollback on agent restart failure	Guarantees the Agent is never left in a broken state after a deployment run
One-click `setup.ps1`	Turns a multi-step manual process (install, configure, schedule, validate) into a single command run once as Administrator
Weekly scheduled fallback (Sunday 02:00 AM, root Task Scheduler Library)	Keeps the certificate inventory and Datadog config continuously up to date without relying on someone to remember to re-run it; root-folder placement avoids event-trigger bugs seen in custom subfolders on some Windows Server versions
`-DryRun` mode	Lets engineers validate scan/config-generation behavior without touching the live Agent or production config
Per-cert Datadog tagging (`cert_store`, `host`, `org`, `managed_by`)	Enables precise filtering and ownership tracking across dashboards and monitors
Pre-built monitors for expiry and TLS version	Turns raw metrics into actionable alerts (Critical < 14 days, Warning < 30 days, not-responding, insecure TLS version) out of the box

Outcome

Certificate expiry across the entire fleet is now visible in Datadog as a standard metric (tls.days_left), with pre-built dashboards and monitors.
Renewals become a planned, proactive task instead of a reactive incident response.
TLS version compliance (no TLS 1.0/1.1) is continuously monitored, not just checked at audit time.
The weekly fallback ensures the inventory self-heals — new certs are picked up and stale data is refreshed automatically, with zero ongoing manual effort.

📁 Directory Structure

C:\scripts\TLSMonitor\
├── Deploy-TLSMonitor.ps1       # Main engine: scan → export → conf.yaml → agent restart
├── certs\                      # Exported .cer files per store (auto-created)
│   ├── LocalMachine_My\
│   ├── LocalMachine_Root\
│   └── LocalMachine_CA\
├── logs\                       # Per-run log files (auto-created)
└── reports\                    # Text certificate inventory reports (auto-created)

setup.ps1                       # One-click setup: first run + registers weekly scheduled task
README.md                       # This file

⚙️ How It Works

setup.ps1 runs once (as Administrator)
        │
        ▼
Deploy-TLSMonitor.ps1 copied to C:\scripts\TLSMonitor\
        │
        ▼
Initial deployment runs immediately
  ├── Scans Cert:\LocalMachine\My, \Root, \CA
  ├── Exports each cert as .cer file
  ├── Generates Datadog conf.d\tls.d\conf.yaml
  ├── Restarts Datadog Agent
  ├── Validates with: agent check tls
  └── Writes text inventory report
        │
        ▼
Weekly Scheduled Task registered in Task Scheduler Library (root)
  └── Fires every Sunday at 02:00 AM as NT AUTHORITY\SYSTEM
        │
        ▼
Datadog Agent reads conf.yaml → TLS Check → Metrics & Monitors

Note: The task is created in the root Task Scheduler Library (no custom subfolder).
This avoids event-trigger type mismatch issues present on some Windows Server versions.

📊 Datadog TLS Check — What Gets Tracked

Each certificate in conf.yaml generates the following Datadog TLS metrics per instance:

Metric	Description
`tls.days_left`	Days until certificate expiry — triggers Warning / Critical thresholds
`tls.seconds_left`	Seconds until expiry (raw value for dashboards)
`tls.responded`	Agent successfully read the cert `1=yes 0=no`
`tls.version`	TLS version detected against `allowed_versions`
`tls.cert.valid`	Certificate valid flag `1=valid 0=invalid/expired`
`tls.cert.expiry_date`	Expiry date tag for filtering in Datadog

Tags applied to every instance:

Tag	Value	Purpose
`cert_store`	`LocalMachine_My` / `LocalMachine_Root` / `LocalMachine_CA`	Store source
`host`	Hostname	Per-server filtering
`org`	`zoosglobal`	Organisation label
`source`	`windows_cert_store`	Origin identifier
`managed_by`	`zoosglobal_tls_monitor`	Ownership label

⚙️ System Requirements

Requirement	Version
Windows Server	2016 / 2019 / 2022 / 2025
Datadog Agent	v7+ (TLS Check built-in)
PowerShell	5.1+
Privileges	Administrator / SYSTEM
Disk Space	~50 MB for exported certs + logs

1️⃣ Install Datadog Agent

# Download installer
Invoke-WebRequest `
  -Uri     "https://s3.amazonaws.com/ddagent-windows-stable/datadog-agent-7-latest.amd64.msi" `
  -OutFile "C:\ddagent.msi"

# Install with your API key
Start-Process -Wait msiexec `
  -ArgumentList '/qn /i C:\ddagent.msi APIKEY="<your_api_key>"'

Verify Agent is running:

Get-Service -Name "datadogagent"
# Expected: Status = Running

Verify TLS check is available:

& "C:\Program Files\Datadog\Datadog Agent\bin\agent.exe" check tls

2️⃣ One-Click Setup (Recommended)

Run as Administrator from the folder containing both scripts.

PowerShell.exe -ExecutionPolicy Bypass -File .\setup.ps1

setup.ps1 performs 7 steps automatically:

[1/7]  Validate Datadog Agent is installed and running
[2/7]  Create C:\scripts\TLSMonitor directory structure
[3/7]  Copy Deploy-TLSMonitor.ps1 to destination
[4/7]  Unblock scripts (remove Zone.Identifier)
[5/7]  Run Deploy-TLSMonitor.ps1 immediately (first run)
[6/7]  Register WEEKLY task in root Task Scheduler Library (Sunday 02:00 AM)
[7/7]  Print final status summary

Task registered in Task Scheduler Library (root):

Task	Trigger	Folder
`ZoosGlobal-TLS-Weekly-Fallback`	Every Sunday at 02:00 AM	Root (Task Scheduler Library)

3️⃣ Manual Validation

# Dry run — scans and generates conf.yaml, skips agent restart
PowerShell.exe -ExecutionPolicy Bypass -File `
  "C:\scripts\TLSMonitor\Deploy-TLSMonitor.ps1" -DryRun

# Live run — full deployment with agent restart
PowerShell.exe -ExecutionPolicy Bypass -File `
  "C:\scripts\TLSMonitor\Deploy-TLSMonitor.ps1"

Expected output:

======================================================================
  ZOOS GLOBAL -- Datadog TLS Certificate Monitor
  Version  : 2.1.0
======================================================================

  [1/6] Validating prerequisites...
  [ OK ] Datadog Agent is running (Status: Running)
  [ .. ] Agent version : Agent 7.x.x

  [2/6] Backing up existing conf.yaml...
  [ OK ] Backup created : C:\ProgramData\Datadog\conf.d\tls.d\conf.yaml.bak_20260415_020000

  [3/6] Scanning Windows Certificate Stores...
  [WARN] Store LocalMachine_My - 0 certs
  [ OK ] Store LocalMachine_Root - 29 cert(s)
  [ OK ] Store LocalMachine_CA - 3 cert(s)
  [ OK ] Scan complete - Exported: 32 | Skipped: 0

  [4/6] Generating conf.yaml (32 instances)...
  [ OK ] conf.yaml written : C:\ProgramData\Datadog\conf.d\tls.d\conf.yaml

  [5/6] Deploying to Datadog Agent...
  [ OK ] Agent restarted successfully.
  [ OK ] Validation - OK: 32 | ERROR: 0

  [6/6] Generating report and summary...
  [ OK ] Text report : C:\scripts\TLSMonitor\reports\TLSReport_SERVER01_20260415_020000.txt

Verify in Datadog:
Metrics → Explorer → search tls.days_left

4️⃣ Execution Timeline

setup.ps1 runs once
  └── Deploy-TLSMonitor.ps1 runs immediately (first deployment)
        ├── Scan  : LocalMachine\My, \Root, \CA
        ├── Export: .cer files to C:\scripts\TLSMonitor\certs\
        ├── Write : conf.d\tls.d\conf.yaml (all instances)
        ├── Restart: datadogagent service
        ├── Validate: agent check tls
        └── Report: text inventory → C:\scripts\TLSMonitor\reports\

Every Sunday 02:00 AM (weekly task in Task Scheduler Library root)
  └── Deploy-TLSMonitor.ps1 runs automatically (same steps as above)

Datadog Agent reads updated conf.yaml → emits tls.days_left per cert

5️⃣ Pre-built Datadog Monitors

🔴 Certificate Expiry — Critical

Query    : min(last_5m):min:tls.days_left{managed_by:zoosglobal_tls_monitor} by {host,instance} < 14
Critical : < 14 days
Message  : Certificate expiring in {{value}} days on {{host.name}}
           Instance: {{instance.name}} -- renew immediately.

⚠️ Certificate Expiry — Warning

Query   : min(last_5m):min:tls.days_left{managed_by:zoosglobal_tls_monitor} by {host,instance} < 30
Warning : < 30 days
Message : Certificate expiring in {{value}} days on {{host.name}}
          Instance: {{instance.name}} -- schedule renewal.

🔴 Certificate Not Responding

Query   : max(last_5m):min:tls.responded{managed_by:zoosglobal_tls_monitor} by {host,instance} < 1
Alert   : < 1
Message : TLS check failed on {{host.name}} -- {{instance.name}} is not responding.

⚠️ TLS Version Mismatch

Query   : max(last_5m):max:tls.version{managed_by:zoosglobal_tls_monitor} by {host,instance} < 2
Alert   : < 2  (TLSv1.0 or TLSv1.1 detected)
Message : Insecure TLS version on {{host.name}} -- only TLSv1.2 and TLSv1.3 permitted.

6️⃣ Datadog Dashboard Queries

Widget	Query
Minimum days left across all certs	`min:tls.days_left{managed_by:zoosglobal_tls_monitor} by {host}`
Days left per cert (table)	`min:tls.days_left{*} by {host,instance,cert_store}`
Certs expiring within 30 days	`min:tls.days_left{managed_by:zoosglobal_tls_monitor} by {instance}`
Certs not responding	`min:tls.responded{managed_by:zoosglobal_tls_monitor} by {host,instance}`
Cert count per store	`count:tls.days_left{*} by {cert_store}`
TLS version compliance	`avg:tls.version{managed_by:zoosglobal_tls_monitor} by {host,instance}`
Expired certs (days_left < 0)	`min:tls.days_left{managed_by:zoosglobal_tls_monitor} by {instance}`
Per-host cert health	`min:tls.days_left{*} by {host}`

🛡️ Production Features

Feature	Status
Scans `Cert:\LocalMachine\My` (Personal)	✅
Scans `Cert:\LocalMachine\Root` (Trusted Root CAs)	✅
Scans `Cert:\LocalMachine\CA` (Intermediate CAs)	✅
Exports each cert as `.cer` file	✅
Auto-generates `conf.d\tls.d\conf.yaml`	✅
Backs up existing conf.yaml before overwrite	✅
Rollback on agent restart failure	✅
Weekly Scheduled Task in root Task Scheduler Library	✅
Fires every Sunday at 02:00 AM as NT AUTHORITY\SYSTEM	✅
Datadog Agent validation via `agent check tls`	✅
Per-cert Datadog tags (store, host, org, source)	✅
Warning threshold: 30 days	✅
Critical threshold: 14 days	✅
Plain text inventory report per run	✅
Per-run log file with timestamps	✅
Dry-run mode (`-DryRun`) – no agent restart	✅
SYSTEM scheduler compatible	✅
Graceful skip on empty stores	✅
Duplicate cert protection (thumbprint-based naming)	✅
ASCII-safe – no encoding issues on any Windows codepage	✅

✅ Production Checklist

🚨 Troubleshooting

Issue	Fix
`ExecutionPolicy` error	Run: `PowerShell.exe -ExecutionPolicy Bypass -File .\setup.ps1`
`tls.days_left` not in Datadog	Run `agent check tls` – check output for errors
`conf.yaml` not generated	Check stores have certs; check log file
Agent restart failed	Check Event Log → Application → `datadogagent`; rollback is automatic
`[WARN] Cannot access store`	Ensure script runs as Administrator or SYSTEM
Scheduled task not running	Run: `Get-ScheduledTask -TaskName 'ZoosGlobal-TLS-Weekly-Fallback'`
Certs showing as expired	Expected for old root/intermediate CAs – filter by `cert_store:LocalMachine_My`
conf.yaml not updated	Manually trigger: `Start-ScheduledTask -TaskName 'ZoosGlobal-TLS-Weekly-Fallback'`

🔧 Manage Task

# Trigger manually
Start-ScheduledTask -TaskName 'ZoosGlobal-TLS-Weekly-Fallback'

# Check status
Get-ScheduledTask -TaskName 'ZoosGlobal-TLS-Weekly-Fallback'

# View last run result
Get-ScheduledTaskInfo -TaskName 'ZoosGlobal-TLS-Weekly-Fallback'

# Remove everything
Unregister-ScheduledTask -TaskName 'ZoosGlobal-TLS-Weekly-Fallback' -Confirm:$false
Remove-Item -Recurse -Force 'C:\scripts\TLSMonitor'

👤 Author


Name	Shivam Anand
Title	Sr. DevOps Engineer \| Engineering
Organisation	Zoos Global
Email	[email protected]
Web	www.zoosglobal.com
Address	Violena, Pali Hill, Bandra West, Mumbai - 400050

Version 2.1.0 · Last Updated: April 15, 2026