Overview

This integration monitors the Local Machine certificates in the Windows Certificate Store to check whether any have expired.

Minimum Agent version: 7.67.0

Setup

Installation

The Windows Certificate Store integration is included in the Datadog Agent package but requires configuration (see instructions below). The Windows Certificate Store integration requires Agent versions 7.67.0 or later.

Configuration

Edit the windows_certificate.d/conf.yaml file, in the conf.d/ folder at the root of your Agent’s configuration directory. See the sample windows_certificate.d/conf.yaml for all available configuration options. When you are done editing the configuration file, restart the Agent to load the new configuration.

The integration can monitor the expiration of all certificates in a given store or selectively monitor specific certificates from a given list of strings matching with the certificate subjects. The store names that are available for monitoring are listed in HKEY_LOCAL_MACHINE\Software\Microsoft\SystemCertificates.

This example configuration monitors all certificates in the local machine’s ROOT store:

instances:
  - certificate_store: ROOT

This example configuration monitors certificates in ROOT that have microsoft or verisign in the subject:

instances:
  - certificate_store: ROOT
    certificate_subjects:
      - microsoft
      - verisign

The parameters days_warning and days_critical are used to specify the number of days before certificate expiration from which the service check windows_certificate.cert_expiration begins emitting WARNING/CRITICAL alerts. In the below example the service check emits a WARNING alert when a certificate is 10 days from expiring and CRITICAL when it is 5 days away from expiring:

instances:
  - certificate_store: ROOT
    certificate_subjects:
      - microsoft
      - verisign
    days_warning: 10
    days_critical: 5

Beginning with Agent v7.69.0, the integration can monitor the expiration of certificate revocation lists (CRL) in a given certificate store. When CRL monitoring is enabled, all CRLs in that store are monitored. To enable CRL monitoring, set enable_crl_monitoring: true in the integration.

This example configuration monitors Microsoft and Verisign certificates, and all CRLs in the local machine’s CA store:

instances:
  - certificate_store: CA
    certificate_subjects:
      - microsoft
      - verisign
    enable_crl_monitoring: true

Beginning with Agent v7.70, the integration can validate certificates and their certificate chains. To enable the certificate chain validation, set the following in the integration:

instances:    
  - certificate_store: CA
    cert_chain_validation:
      enabled: true
      policy_validation_flags:
        - CERT_CHAIN_POLICY_IGNORE_ALL_NOT_TIME_VALID_FLAGS
        - CERT_CHAIN_POLICY_IGNORE_ALL_REV_UNKNOWN_FLAGS
        - CERT_CHAIN_POLICY_ALLOW_UNKNOWN_CA_FLAG 

The policy_validation_flags suppress specific validation errors that may not be relevant for your use case. See the sample windows_certificate.d/conf.yaml for a list of all the flags available for use.

Beginning with Agent v7.80.0, the integration supports certificate_store_regex, a list of Go regexp patterns matched against store names enumerated from HKEY_LOCAL_MACHINE\Software\Microsoft\SystemCertificates. Either certificate_store, certificate_store_regex, or both must be configured.

This example configuration monitors all certificates in the ROOT store as well as any stores whose names start with Trusted:

instances:
  - certificate_store: ROOT
    certificate_store_regex:
      - ^Trusted

This example configuration monitors all certificates across all stores:

instances:
  - certificate_store_regex:
      - .*

Tags

The integration automatically tags all metrics and service checks with the name of the store in the certificate_store:<STORE> tag. Certificate metrics and service checks are tagged with the certificate’s subjects, thumbprints and serial numbers. CRL metrics and service checks are tagged with the CRL’s issuer and thumbprint.

Beginning with Agent v7.80, six opt-in flags expose additional certificate metadata as tags on per-certificate metrics and service checks. Each flag defaults to false. Set the value to true in your instance configuration to emit the corresponding tags.

Example configuration that enables the issuer and signature algorithm tags:

instances:
  - certificate_store: ROOT
    issuer_tag: true
    signature_algorithm_tag: true

Validation

Run the Agent’s status subcommand and look for windows_certificate under the Checks section.

Data Collected

Metrics

Events

The windows_certificate integration does not include any events.

Service Checks

windows_certificate.cert_expiration

Returns CRITICAL if the certificate has expired or expires in less than days_critical, returns WARNING if the certificate expires in less than days_warning, otherwise returns OK.

Statuses: ok, critical, warning

windows_certificate.crl_expiration

Returns CRITICAL if the certificate revocation list (CRL) has expired. Returns WARNING if the CRL expires in less than crl_days_warning. Otherwise, returns OK.

Statuses: ok, critical, warning

windows_certificate.cert_chain_validation

Returns CRITICAL if the certificate chain validation fails. Otherwise, returns OK.

Statuses: ok, critical, warning

Troubleshooting

Certificates with identical subjects

When multiple certificates share the same subject but have different serial numbers or thumbprints (for example, an expired certificate and its renewed replacement), the integration may only detect one of them, often the expired certificate.

Agent v7.70.0 and later: The certificate_thumbprint and certificate_serial_number tags are available on metrics and service checks, allowing you to distinguish between certificates with identical subjects in Datadog monitors and dashboards. While these tags cannot be used for filtering in the integration configuration (only certificate_subjects is supported), you can create custom monitors that group by certificate_thumbprint or certificate_serial_number instead of the default subject_cn grouping to monitor each certificate separately.

Agent versions prior to v7.70.0: If you are running an Agent version older than v7.70.0, delete the expired certificate from the Windows Certificate Store so only the valid, renewed certificate is monitored.

Need additional help? Contact Datadog support.