feat(windows_certificate): add filters.include / filters.exclude for tag-based cert collection scoping (#52441)

### What does this PR do?

Adds `filters.include` and `filters.exclude` configuration to the `windows_certificate` check. Each filter maps a tag key (e.g. `certificate_thumbprint`, `subject_CN`, `subject_alt_name_dns`) to a Go regex pattern matched against the tag's value.

```yaml
filters:
  include:
    <cert_tag_key>: <regex_pattern>
  exclude:
    <cert_tag_key>: <regex_pattern>
```

**Semantics:**
- `include`: a certificate must satisfy **all** include rules to be reported. A cert missing a tag for an include key is excluded.
- `exclude`: a certificate is dropped if **any** exclude rule matches one of its tag values.
- Empty section = no filtering in that direction.
- Invalid regex patterns are rejected at `Configure` time with a clear error.

**A filter rule only ever matches a tag that is actually collected.** Opt-in tag keys (`subject_alt_name_dns`, `certificate_template_name`, `signature_algorithm`, etc.) require their corresponding `*_tag` flag to be enabled to be used as filter criteria. If a rule references a tag key that isn't collected under the current config (its flag is disabled, or the key — `certificate_store`/`server` — is never available as a filter key), `Configure` logs a warning and skips that rule instead of matching against a tag that can never be present.

### Motivation

Addresses FRAGENT-3382 / tracked in TEEP-7268.

Customers running Windows Certificate Store monitoring often have many certificates in a store (IIS, SQL Server, document encryption, etc.) and need to scope collection to specific ones — by thumbprint, SAN, CN, or template name — without creating separate check instances per certificate. Previously the only agent-side filter was `certificate_subjects` (CN substring match).

With this change, operators can use any tag key emitted by the check (or available from the check's opt-in extensions, once the corresponding `*_tag` flag is enabled) as a filter key. The new opt-in tags from PR #49740 (SAN, friendly name, template, EKU) are usable as filter criteria as soon as their flag is turned on.

### Describe how you validated your changes

- **Unit tests** (`windows_certificate_tags_test.go`): cover include-only, exclude-only, combined include+exclude, empty filters (pass-through), cert with no matching tag key, and `pruneUncollectedFilterKeys` dropping rules on disabled-flag tags, unsupported keys (`certificate_store`/`server`), and keeping rules whose flag is enabled.
- **Configure tests** (`windows_certificate_test.go`): valid filter compiles without error; invalid regex returns error from `Configure`; a filter on a disabled opt-in tag is pruned rather than rejecting every certificate.
- **Integration test** (`TestConfigureWithFiltersExcludesNonMatchingCerts`): runs against the live Windows `ROOT` store with an impossible thumbprint include-filter and asserts zero `Gauge` and `ServiceCheck` calls.
- **Cross-compile**: `GOOS=windows GOARCH=amd64 go build ./pkg/collector/corechecks/system/windowscertificate/` — clean.
- **Linter**: `dda inv linter.go --targets=./pkg/collector/corechecks/system/windowscertificate/...` — 0 issues.

### Additional Notes

- Filtering is applied post-collection in `enumerateStoreContents`, after `StoreName` is stamped on each cert, covering both local and remote collection paths.
- `applyTagFilters` evaluates rules against the same `Tags` a certificate emits, so a rule only matches values that are actually collected. `pruneUncollectedFilterKeys` runs once in `Configure` and drops any rule that references a tag whose `*_tag` flag is disabled (logging a warning), so such a rule simply has no effect rather than excluding every certificate.
- `certificate_store` and `server` are not available as filter keys — they are appended to metrics in `Run()` after filtering. `pruneUncollectedFilterKeys` drops rules on these keys too.
- Regex patterns are compiled once at `Configure` time (not per-run), so there is no performance overhead during collection.


Co-authored-by: ian.bucad <ian.bucad@datadoghq.com>

Author: ian28223

cmd/agent/dist/assets/windows_certificate/spec.yaml

@@ -263,6 +263,48 @@ files:
         Set to `true` to attach a `signature_algorithm` tag describing the
         certificate's signature algorithm (e.g. `signature_algorithm:sha256-rsa`).
       required: false
+    - name: filters
+      fleet_configurable: true
+      value:
+        type: object
+        properties:
+          include:
+            type: object
+            additionalProperties:
+              type: string
+            example: {"certificate_thumbprint": "^3a7b9c"}
+            description: |
+              A mapping of tag key to Go regexp pattern. A certificate must match ALL include rules
+              to be reported. A certificate with no tag for a given include key is excluded.
+              Note: `certificate_store` and `server` are not supported as filter keys.
+          exclude:
+            type: object
+            additionalProperties:
+              type: string
+            example: {"subject_CN": "internal\\.example\\.com$"}
+            description: |
+              A mapping of tag key to Go regexp pattern. A certificate is dropped if ANY exclude
+              rule matches one of its tag values.
+              Note: `certificate_store` and `server` are not supported as filter keys.
+      description: |
+        Each rule maps a tag key to a Go regexp pattern matched against the tag's value.
+        Invalid regexp patterns cause the check to fail at configuration time.
+
+        Supported filter keys:
+          certificate_thumbprint     SHA-1 hex thumbprint
+          certificate_serial_number  serial number in hex
+          subject_CN                 Common Name
+          subject_O                  Organization
+          subject_alt_name_dns       DNS SAN entry               (requires subject_alternative_names_tag)
+          subject_alt_name_ip        IP SAN entry                (requires subject_alternative_names_tag)
+          subject_alt_name_email     email SAN entry             (requires subject_alternative_names_tag)
+          friendly_name              Windows friendly name       (requires friendly_name_tag)
+          enhanced_key_usage         EKU short name or OID       (requires enhanced_key_usage_tag)
+          certificate_template_name  template display name       (requires certificate_template_tag)
+          certificate_template_oid   template OID (V2 certs)     (requires certificate_template_tag)
+          issuer_CN                  issuer Common Name          (requires issuer_tag)
+          signature_algorithm        e.g. "SHA256-RSA"           (requires signature_algorithm_tag)
+      required: false
     - name: tags
       fleet_configurable: true
       value:

cmd/agent/dist/conf.d/windows_certificate.d/conf.yaml.example

@@ -180,6 +180,59 @@ instances:
     #
     # signature_algorithm_tag: false
 
+    ## @param filters - mapping - optional
+    ## Each rule maps a tag key to a Go regexp pattern matched against the
+    ## tag's value.
+    ##
+    ## `include`: a certificate must satisfy ALL include rules to be reported.
+    ##   A certificate that has no tag for a given include key fails that rule.
+    ## `exclude`: a certificate is dropped if ANY exclude rule matches one of
+    ##   its tag values.
+    ## When both are specified, include is evaluated first, then exclude.
+    ##
+    ## Supported filter keys:
+    ##   certificate_thumbprint     SHA-1 hex thumbprint
+    ##   certificate_serial_number  serial number in hex
+    ##   subject_CN                 Common Name
+    ##   subject_O                  Organization
+    ##   subject_alt_name_dns       DNS SAN entry               (requires subject_alternative_names_tag)
+    ##   subject_alt_name_ip        IP SAN entry                (requires subject_alternative_names_tag)
+    ##   subject_alt_name_email     email SAN entry             (requires subject_alternative_names_tag)
+    ##   friendly_name              Windows friendly name       (requires friendly_name_tag)
+    ##   enhanced_key_usage         EKU short name or OID       (requires enhanced_key_usage_tag)
+    ##   certificate_template_name  template display name       (requires certificate_template_tag)
+    ##   certificate_template_oid   template OID (V2 certs)     (requires certificate_template_tag)
+    ##   issuer_CN                  issuer Common Name          (requires issuer_tag)
+    ##   signature_algorithm        e.g. "SHA256-RSA"           (requires signature_algorithm_tag)
+    ##
+    ## `certificate_store` and `server` are not supported as filter keys; use
+    ## `certificate_store` / `certificate_store_regex` and `server` instead.
+    ##
+    ## Examples:
+    ##
+    ##   # Report only certificates with a specific thumbprint:
+    ##   filters:
+    ##     include:
+    ##       certificate_thumbprint: "^3a7b9c"
+    ##
+    ##   # Exclude internal-only certificates by CN:
+    ##   filters:
+    ##     exclude:
+    ##       subject_CN: "internal\\.example\\.com$"
+    ##
+    ##   # Scope to IIS certificates and exclude staging:
+    ##   filters:
+    ##     include:
+    ##       certificate_template_name: "WebServer"
+    ##     exclude:
+    ##       subject_CN: "staging"
+    #
+    # filters:
+    #   include:
+    #     <cert_tag_key>: <regex_pattern>
+    #   exclude:
+    #     <cert_tag_key>: <regex_pattern>
+
     ## @param tags - list of strings - optional
     ## A list of tags to attach to every metric and service check emitted by this instance.
     ##

pkg/collector/corechecks/system/windowscertificate/windows_certificate.go

@@ -105,6 +105,20 @@ type certChainValidation struct {
 	CertChainPolicyValidationFlags []string `yaml:"policy_validation_flags" json:"policy_validation_flags" nullable:"true"`
 }
 
+// CertFilters holds include/exclude tag-filter rules. Each entry maps a tag
+// key (e.g. "certificate_thumbprint") to a Go regexp pattern matched against
+// the tag's value. An empty map means no filtering for that direction.
+type CertFilters struct {
+	Include map[string]string `yaml:"include" json:"include" nullable:"true"`
+	Exclude map[string]string `yaml:"exclude" json:"exclude" nullable:"true"`
+}
+
+// compiledCertFilters holds the compiled regexp forms of CertFilters.
+type compiledCertFilters struct {
+	include map[string]*regexp.Regexp
+	exclude map[string]*regexp.Regexp
+}
+
 // Config is the configuration options for this check
 // it is exported so that the yaml parser can read it.
 type Config struct {
@@ -127,13 +141,17 @@ type Config struct {
 	SubjectAlternativeNamesTag bool `yaml:"subject_alternative_names_tag" json:"subject_alternative_names_tag" default:"false"`
 	IssuerTag                  bool `yaml:"issuer_tag" json:"issuer_tag" default:"false"`
 	SignatureAlgorithmTag      bool `yaml:"signature_algorithm_tag" json:"signature_algorithm_tag" default:"false"`
+
+	// Filters controls which collected certificates are reported.
+	Filters CertFilters `yaml:"filters" json:"filters" nullable:"true"`
 }
 
 // WinCertChk is the object representing the check
 type WinCertChk struct {
 	core.CheckBase
 	config           Config
 	certStoreRegexes []*regexp.Regexp // non-nil when certificate_store_regex lists at least one pattern
+	certFilters      compiledCertFilters
 }
 
 type crlInfoCopy struct {
@@ -148,7 +166,7 @@ type crlInfoCopy struct {
 type certInfo struct {
 	SubjectString    string
 	NotAfter         time.Time // certificate expiration
-	Tags             []string  // cert-derived tags
+	Tags             []string  // cert-derived tags (controlled by *_tag flags)
 	Thumbprint       string
 	TrustStatusError uint32 // windows.TrustStatus.ErrorStatus
 	ChainPolicyError uint32 // windows.CertChainPolicyStatus.Error
@@ -242,6 +260,16 @@ func (w *WinCertChk) Configure(senderManager sender.SenderManager, integrationCo
 		}
 	}
 
+	w.certFilters = compiledCertFilters{}
+	if len(config.Filters.Include) > 0 || len(config.Filters.Exclude) > 0 {
+		var filterErr error
+		w.certFilters, filterErr = compileCertFilters(config.Filters)
+		if filterErr != nil {
+			return filterErr
+		}
+		pruneUncollectedFilterKeys(&w.certFilters, config)
+	}
+
 	w.config = config
 
 	if w.config.DaysWarning < w.config.DaysCritical {
@@ -573,6 +601,9 @@ func (w *WinCertChk) enumerateStoreContents(storeHandle windows.Handle, store st
 	for i := range crlInfo {
 		crlInfo[i].StoreName = store
 	}
+	preFilterCount := len(certificates)
+	certificates = applyTagFilters(certificates, w.certFilters)
+	log.Debugf("Tag filters passed %d of %d certificates in store %s", len(certificates), preFilterCount, store)
 	return certificates, crlInfo, nil
 }
 
@@ -655,6 +686,9 @@ func buildCertInfo(certContext *windows.CertContext, storeHandle windows.Handle,
 	}
 
 	// Build cert-derived tags here, while the cert bytes are still valid.
+	// Filters (applied by the caller via applyTagFilters) evaluate against
+	// these same tags, so filter rules only see values whose *_tag flag is
+	// enabled — see pruneUncollectedFilterKeys.
 	tags := getSubjectTags(cert)
 	tags = append(tags, "certificate_thumbprint:"+thumbprint)
 	tags = append(tags, "certificate_serial_number:"+cert.SerialNumber.Text(16))
@@ -972,3 +1006,52 @@ func netCancelConnection(name string) error {
 	log.Debugf("Canceling connection to %s", name)
 	return winutil.WNetCancelConnection2(name)
 }
+
+// compileCertFilters compiles the regexp patterns in a CertFilters into a
+// compiledCertFilters. Returns an error if any pattern is invalid.
+func compileCertFilters(filters CertFilters) (compiledCertFilters, error) {
+	compiled := compiledCertFilters{}
+
+	if len(filters.Include) > 0 {
+		compiled.include = make(map[string]*regexp.Regexp, len(filters.Include))
+		for key, pattern := range filters.Include {
+			re, err := regexp.Compile(pattern)
+			if err != nil {
+				return compiledCertFilters{}, fmt.Errorf("filters.include[%q]: invalid regular expression: %w", key, err)
+			}
+			compiled.include[key] = re
+		}
+	}
+
+	if len(filters.Exclude) > 0 {
+		compiled.exclude = make(map[string]*regexp.Regexp, len(filters.Exclude))
+		for key, pattern := range filters.Exclude {
+			re, err := regexp.Compile(pattern)
+			if err != nil {
+				return compiledCertFilters{}, fmt.Errorf("filters.exclude[%q]: invalid regular expression: %w", key, err)
+			}
+			compiled.exclude[key] = re
+		}
+	}
+
+	return compiled, nil
+}
+
+// pruneUncollectedFilterKeys warns and drops filters on uncollected tags.
+func pruneUncollectedFilterKeys(f *compiledCertFilters, cfg Config) {
+	prune := func(rules map[string]*regexp.Regexp, direction string) {
+		for key := range rules {
+			if key == "certificate_store" || key == "server" {
+				log.Warnf("filters.%s: %q is not a supported filter key, ignoring", direction, key)
+				delete(rules, key)
+				continue
+			}
+			if flagName, requiresFlag := filterKeyTagFlag(key); requiresFlag && !tagFlagEnabled(cfg, flagName) {
+				log.Warnf("filters.%s: %q requires %q to be enabled, ignoring", direction, key, flagName)
+				delete(rules, key)
+			}
+		}
+	}
+	prune(f.include, "include")
+	prune(f.exclude, "exclude")
+}

pkg/collector/corechecks/system/windowscertificate/windows_certificate_tags_test.go

@@ -13,6 +13,7 @@ import (
 	"encoding/asn1"
 	"net"
 	"net/url"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -306,3 +307,118 @@ func TestAppendOptionalTagsFriendlyNameSkippedWhenEmpty(t *testing.T) {
 		require.NotContains(t, tag, "friendly_name:")
 	}
 }
+
+func TestCompileCertFiltersRejectsInvalidRegex(t *testing.T) {
+	_, err := compileCertFilters(CertFilters{
+		Include: map[string]string{"certificate_thumbprint": "["},
+	})
+	require.Error(t, err)
+}
+
+func TestApplyTagFilters(t *testing.T) {
+	certA := certInfo{Tags: []string{"certificate_thumbprint:abc123", "subject_CN:webserver"}}
+	certB := certInfo{Tags: []string{"certificate_thumbprint:def456", "subject_CN:internal-db"}}
+	certC := certInfo{Tags: []string{"certificate_thumbprint:aaa999", "subject_CN:webserver"}}
+
+	// include only thumbprints starting with "a"
+	filters, err := compileCertFilters(CertFilters{
+		Include: map[string]string{"certificate_thumbprint": "^a"},
+	})
+	require.NoError(t, err)
+	got := applyTagFilters([]certInfo{certA, certB, certC}, filters)
+	require.Len(t, got, 2)
+	require.Equal(t, "abc123", tagValue(got[0].Tags, "certificate_thumbprint"))
+	require.Equal(t, "aaa999", tagValue(got[1].Tags, "certificate_thumbprint"))
+
+	// exclude certs with CN matching "internal"
+	filters2, err := compileCertFilters(CertFilters{
+		Exclude: map[string]string{"subject_CN": "internal"},
+	})
+	require.NoError(t, err)
+	got2 := applyTagFilters([]certInfo{certA, certB, certC}, filters2)
+	require.Len(t, got2, 2)
+
+	// include + exclude combined: include "^a" thumbprints, exclude "internal" CN
+	filters3, err := compileCertFilters(CertFilters{
+		Include: map[string]string{"certificate_thumbprint": "^a"},
+		Exclude: map[string]string{"subject_CN": "internal"},
+	})
+	require.NoError(t, err)
+	got3 := applyTagFilters([]certInfo{certA, certB, certC}, filters3)
+	require.Len(t, got3, 2) // certA and certC pass; certB excluded (thumbprint doesn't match include); no "internal" in remaining
+
+	// empty filters: all certs pass
+	filters4, err := compileCertFilters(CertFilters{})
+	require.NoError(t, err)
+	got4 := applyTagFilters([]certInfo{certA, certB, certC}, filters4)
+	require.Len(t, got4, 3)
+
+	// cert has no matching tag key for include rule → cert is excluded
+	filters5, err := compileCertFilters(CertFilters{
+		Include: map[string]string{"cert_san_dns": "example.com"},
+	})
+	require.NoError(t, err)
+	got5 := applyTagFilters([]certInfo{certA, certB, certC}, filters5)
+	require.Len(t, got5, 0)
+}
+
+// TestPruneUncollectedFilterKeysDropsDisabledFlagRules verifies that a filter
+// rule on a tag key gated by a disabled *_tag flag is removed rather than
+// left in place to reject every certificate.
+func TestPruneUncollectedFilterKeysDropsDisabledFlagRules(t *testing.T) {
+	f, err := compileCertFilters(CertFilters{
+		Include: map[string]string{"signature_algorithm": "^sha256"},
+		Exclude: map[string]string{"issuer_CN": "internal"},
+	})
+	require.NoError(t, err)
+
+	pruneUncollectedFilterKeys(&f, Config{})
+
+	require.Empty(t, f.include)
+	require.Empty(t, f.exclude)
+
+	// With no rules left, filtering is a no-op.
+	certs := []certInfo{{Tags: []string{"certificate_thumbprint:abc123"}}}
+	got := applyTagFilters(certs, f)
+	require.Len(t, got, 1)
+}
+
+// TestPruneUncollectedFilterKeysKeepsEnabledFlagRules verifies that a filter
+// rule stays active once its controlling *_tag flag is enabled.
+func TestPruneUncollectedFilterKeysKeepsEnabledFlagRules(t *testing.T) {
+	f, err := compileCertFilters(CertFilters{
+		Include: map[string]string{"signature_algorithm": "^sha256"},
+	})
+	require.NoError(t, err)
+
+	pruneUncollectedFilterKeys(&f, Config{SignatureAlgorithmTag: true})
+
+	require.Len(t, f.include, 1)
+}
+
+// TestPruneUncollectedFilterKeysDropsUnsupportedKeys verifies that
+// certificate_store and server rules — appended to metrics after filtering
+// runs — are always dropped, regardless of config.
+func TestPruneUncollectedFilterKeysDropsUnsupportedKeys(t *testing.T) {
+	f, err := compileCertFilters(CertFilters{
+		Include: map[string]string{"certificate_store": "^MY$"},
+		Exclude: map[string]string{"server": "staging"},
+	})
+	require.NoError(t, err)
+
+	pruneUncollectedFilterKeys(&f, Config{})
+
+	require.Empty(t, f.include)
+	require.Empty(t, f.exclude)
+}
+
+// tagValue extracts the value for the first tag with the given key.
+func tagValue(tags []string, key string) string {
+	prefix := key + ":"
+	for _, t := range tags {
+		if strings.HasPrefix(t, prefix) {
+			return strings.TrimPrefix(t, prefix)
+		}
+	}
+	return ""
+}