diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index dabb5a42638d2..9d2b765cc9f98 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -193,6 +193,9 @@ datadog_checks_base/datadog_checks/base/checks/windows/ @DataDog/wi /win32_event_log/ @DataDog/windows-agent @DataDog/agent-integrations /win32_event_log/*.md @DataDog/windows-agent @DataDog/agent-integrations @DataDog/documentation /win32_event_log/manifest.json @DataDog/windows-agent @DataDog/agent-integrations @DataDog/documentation +/windows_certificate/ @DataDog/windows-agent @DataDog/agent-integrations +/windows_certificate/*.md @DataDog/windows-agent @DataDog/agent-integrations @DataDog/documentation +/windows_certificate/manifest.json @DataDog/windows-agent @DataDog/agent-integrations @DataDog/documentation /windows_performance_counters/ @DataDog/windows-agent @DataDog/agent-integrations /windows_performance_counters/*.md @DataDog/windows-agent @DataDog/agent-integrations @DataDog/documentation /windows_performance_counters/manifest.json @DataDog/windows-agent @DataDog/agent-integrations @DataDog/documentation diff --git a/.github/workflows/config/labeler.yml b/.github/workflows/config/labeler.yml index 9c86171272051..5ab652fa5fbd2 100644 --- a/.github/workflows/config/labeler.yml +++ b/.github/workflows/config/labeler.yml @@ -683,6 +683,8 @@ integration/win32_event_log: - win32_event_log/**/* integration/wincrashdetect: - wincrashdetect/**/* +integration/windows_certificate: +- windows_certificate/**/* integration/windows_performance_counters: - windows_performance_counters/**/* integration/windows_registry: diff --git a/windows_certificate/CHANGELOG.md b/windows_certificate/CHANGELOG.md new file mode 100644 index 0000000000000..a2c796d77d647 --- /dev/null +++ b/windows_certificate/CHANGELOG.md @@ -0,0 +1,7 @@ +# CHANGELOG - windows_certificate + +## 1.0.0 / 2025-05-20 + +***Added***: + +* Initial Release diff --git a/windows_certificate/README.md b/windows_certificate/README.md new file mode 100644 index 0000000000000..5f1b278ec6462 --- /dev/null +++ b/windows_certificate/README.md @@ -0,0 +1,76 @@ +# Agent Check: Windows Certificate Store + +## Overview + +This check monitors the Local Machine certificates in the [Windows Certificate Store][1] for ceritificate expiration. + +## Setup + +### Installation + +The Windows Certificate Store check is included in the [Datadog Agent][2] package. Please see the next section to configure the check. + +### Configuration + +Edit the `windows_certificate.d/conf.yaml` file, in the `conf.d/` folder at the root of your [Agent's configuration directory][10]. See the [sample windows_certificate.d/conf.yaml][4] for all available configuration options. When you are done editing the configuration file, [restart the Agent][5] to load the new configuration. + +The check can monitor the expiration of all certiificates in a given store or selectively monitor a few certificates by a given list of strings matching with the certificate subjects. Enter the store name as found in `HKEY_LOCAL_MACHINE\Software\Microsoft\SystemCertificates`. + +This example configuration monitors all certificates in the local machine's `ROOT` store: + +```yaml +instances: + - certificate_store: ROOT +``` +This example configuraiton monitors ceritificates in `ROOT` that have `microsoft` or `verisign` in the subject: +```yaml +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. In the below example the service check will emit a WARNING when a certificate is 10 days from expiring and CRITICAL when it is 5 days away from expiring: +```yaml +instances: + - certificate_store: ROOT + certificate_subjects: + - microsoft + - verisign + days_warning: 10 + days_critical: 5 +``` + +### Validation + +[Run the Agent's status subcommand][6] and look for `windows_certificate` under the Checks section. + +## Data Collected + +### Metrics + +See [metadata.csv][7] for a list of metrics provided by this integration. + +### Events + +The windows_certificate integration does not include any events. + +### Service Checks + +See [service_checks.json][8] for a list of service checks provided by this integration. + +## Troubleshooting + +Need help? Contact [Datadog support][9]. + + +[1]: https://learn.microsoft.com/en-us/windows-hardware/drivers/install/certificate-stores +[2]: https://app.datadoghq.com/account/settings/agent/latest +[3]: https://docs.datadoghq.com/agent/kubernetes/integrations/ +[4]: https://github.com/DataDog/datadog-agent/blob/main/cmd/agent/dist/conf.d/windows_certificate.d/conf.yaml.example +[5]: https://docs.datadoghq.com/agent/guide/agent-commands/#start-stop-and-restart-the-agent +[6]: https://docs.datadoghq.com/agent/guide/agent-commands/#agent-status-and-information +[7]: https://github.com/DataDog/integrations-core/blob/master/windows_certificate/metadata.csv +[8]: https://github.com/DataDog/integrations-core/blob/master/windows_certificate/assets/service_checks.json +[9]: https://docs.datadoghq.com/help/ +[10]: https://docs.datadoghq.com/agent/guide/agent-configuration-files/#agent-configuration-directory diff --git a/windows_certificate/assets/dashboards/windows_certificate_overview.json b/windows_certificate/assets/dashboards/windows_certificate_overview.json new file mode 100644 index 0000000000000..e8412ea00c2e3 --- /dev/null +++ b/windows_certificate/assets/dashboards/windows_certificate_overview.json @@ -0,0 +1,169 @@ +{ + "author_name": "Datadog", + "description": "## Windows Certificate Store Integration Dashboard\n\nThis is an example Windows Certificate Store dashboard demonstrating the information that the integration collects.", + "layout_type": "ordered", + "template_variables": [ + { + "available_values": [], + "default": "*", + "name": "certificate_store", + "prefix": "certificate_store" + }, + { + "available_values": [], + "default": "*", + "name": "subject_common_name", + "prefix": "subject_cn" + } + ], + "title": "Windows Certificate Store Overview", + "widgets": [ + { + "definition": { + "banner_img": "/static/images/logos/windows_small.svg", + "layout_type": "ordered", + "show_title": true, + "title": "Windows Certificate Store", + "type": "group", + "widgets": [] + }, + "id": 1332720998004105, + "layout": { + "height": 5, + "width": 4, + "x": 0, + "y": 0 + } + }, + { + "definition": { + "background_color": "vivid_blue", + "layout_type": "ordered", + "show_title": true, + "title": "Certificate Expiration", + "type": "group", + "widgets": [ + { + "definition": { + "check": "windows_certificate.cert_expiration", + "group_by": [], + "grouping": "cluster", + "tags": [ + "$certificate_store", + "$subject_common_name" + ], + "title": "Certificate Expiration", + "title_align": "center", + "title_size": "16", + "type": "check_status" + }, + "id": 5168903633321084, + "layout": { + "height": 2, + "width": 4, + "x": 0, + "y": 0 + } + }, + { + "definition": { + "background_color": "yellow", + "content": "Included service check:\n\n* `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.", + "font_size": "14", + "has_padding": true, + "show_tick": true, + "text_align": "left", + "tick_edge": "left", + "tick_pos": "50%", + "type": "note", + "vertical_align": "center" + }, + "id": 6717423497232037, + "layout": { + "height": 2, + "width": 4, + "x": 4, + "y": 0 + } + }, + { + "definition": { + "legend_columns": [ + "avg", + "min", + "max", + "value", + "sum" + ], + "legend_layout": "auto", + "requests": [ + { + "display_type": "line", + "formulas": [ + { + "formula": "query1" + } + ], + "queries": [ + { + "data_source": "metrics", + "name": "query1", + "query": "avg:windows_certificate.days_remaining{$certificate_store, $subject_common_name} by {subject_cn}" + } + ], + "response_format": "timeseries", + "style": { + "line_type": "solid", + "line_width": "normal", + "order_by": "values", + "palette": "dog_classic" + } + } + ], + "show_legend": true, + "title": "Days Till Expiration", + "title_align": "left", + "title_size": "16", + "type": "timeseries" + }, + "id": 4514519614660249, + "layout": { + "height": 2, + "width": 4, + "x": 0, + "y": 2 + } + }, + { + "definition": { + "background_color": "yellow", + "content": "Days until certificate(s) expire", + "font_size": "14", + "has_padding": true, + "show_tick": true, + "text_align": "left", + "tick_edge": "left", + "tick_pos": "50%", + "type": "note", + "vertical_align": "center" + }, + "id": 3226539913664578, + "layout": { + "height": 1, + "width": 4, + "x": 4, + "y": 2 + } + } + ] + }, + "id": 3432759619201891, + "layout": { + "height": 5, + "width": 8, + "x": 4, + "y": 0 + } + } + ] +} \ No newline at end of file diff --git a/windows_certificate/assets/monitors/windows_certificate_expiration.json b/windows_certificate/assets/monitors/windows_certificate_expiration.json new file mode 100644 index 0000000000000..babf32a305d58 --- /dev/null +++ b/windows_certificate/assets/monitors/windows_certificate_expiration.json @@ -0,0 +1,35 @@ +{ + "version": 2, + "created_at": "2025-05-13", + "last_updated_at": "2025-05-13", + "title": "A certificate is expired or about to expire", + "description": "This monitor alerts when there are certificates in the Windows Certificate Store that are expired or close to expiring.", + "tags": [ + "integration:windows-certificate" + ], + "definition": { + "name": "A certificate is expired or about to expire", + "type": "service check", + "query": "\"windows_certificate.cert_expiration\".over(\"*\").by(\"certificate_store\",\"host\",\"subject_cn\").last(2).count_by_status()", + "message": "The Windows Certificate integration is reporting the following for Certificate: {{subject_cn.name}} in Store: {{certificate_store.name}}\n\n{{#is_warning}}\n\nWarning: {{check_message}}\n\n{{/is_warning}}\n\n{{#is_alert}}\n\nAlert: {{check_message}}\n\n{{/is_alert}}", + "tags": [ + "integration:windows_certificate" + ], + "options": { + "thresholds": { + "critical": 1, + "warning": 1, + "ok": 1 + }, + "notify_audit": false, + "notify_no_data": false, + "renotify_interval": 0, + "timeout_h": 0, + "threshold_windows": null, + "include_tags": true, + "new_group_delay": 60, + "avalanche_window": 10 + }, + "priority": null + } + } diff --git a/windows_certificate/assets/service_checks.json b/windows_certificate/assets/service_checks.json new file mode 100644 index 0000000000000..f19363ebbf321 --- /dev/null +++ b/windows_certificate/assets/service_checks.json @@ -0,0 +1,22 @@ +[ + { + "agent_version": "7.67.0", + "integration": "Windows Certificate Store", + "groups": [ + "certificate_store", + "subject_cn", + "subject_ou", + "subject_c", + "subject_o", + "subject_l" + ], + "check": "windows_certificate.cert_expiration", + "statuses": [ + "ok", + "critical", + "warning" + ], + "name": "Certificate validation", + "description": "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`." + } +] diff --git a/windows_certificate/manifest.json b/windows_certificate/manifest.json new file mode 100644 index 0000000000000..033e46b3dfba5 --- /dev/null +++ b/windows_certificate/manifest.json @@ -0,0 +1,53 @@ +{ + "manifest_version": "2.0.0", + "app_uuid": "67feed3c-1676-4d6b-9d72-3ca8c0a6e3dc", + "app_id": "windows-certificate", + "display_on_public_website": false, + "tile": { + "overview": "README.md#Overview", + "configuration": "README.md#Setup", + "support": "README.md#Support", + "changelog": "CHANGELOG.md", + "description": "Monitor your Windows hosts' certificates stores for certificate expiration.", + "title": "Windows Certificate Store", + "media": [], + "classifier_tags": [ + "Supported OS::Windows", + "Category::OS & System", + "Category::Windows", + "Offering::Integration", + "Submitted Data Type::Metrics" + ] + }, + "assets": { + "integration": { + "auto_install": true, + "source_type_id": 46050783, + "source_type_name": "Windows Certificate Store", + "configuration": {}, + "events": { + "creates_events": false + }, + "metrics": { + "prefix": "windows_certificate.", + "check": "windows_certificate.days_remaining", + "metadata_path": "metadata.csv" + }, + "service_checks": { + "metadata_path": "assets/service_checks.json" + } + }, + "dashboards": { + "Windows Certificate Store Overview": "assets/dashboards/windows_certificate_overview.json" + }, + "monitors": { + "A certificate is expired or about to expire": "assets/monitors/windows_certificate_expiration.json" + } + }, + "author": { + "support_email": "help@datadoghq.com", + "name": "Datadog", + "homepage": "https://www.datadoghq.com", + "sales_email": "info@datadoghq.com" + } +} diff --git a/windows_certificate/metadata.csv b/windows_certificate/metadata.csv new file mode 100644 index 0000000000000..a80dce66292f9 --- /dev/null +++ b/windows_certificate/metadata.csv @@ -0,0 +1,2 @@ +metric_name,metric_type,interval,unit_name,per_unit_name,description,orientation,integration,short_name,curated_metric,sample_tags +windows_certificate.days_remaining,gauge,,day,,Days until certificate expiration,1,windows_certificate_store,Days until expiration,,