Add runtime configuration validation

win32_event_log/assets/configuration/spec.yaml

@@ -23,6 +23,9 @@ files:
       value:
         type: string
         example: normal
+        enum:
+        - normal
+        - low
     - name: interpret_messages
       description: |
         Whether or not to interpret event messages for unknown sources or sources that have not been registered
@@ -68,6 +71,9 @@ files:
       value:
         type: string
         example: now
+        enum:
+        - now
+        - oldest
     - name: query
       description: |
         A raw XPath or structured XML query used to filter events.
@@ -102,6 +108,26 @@ files:
         If `filters` nor `query` is specified, then all events from the subscribed `path` will be collected.
       value:
         type: object
+        properties:
+        - name: source
+          type: array
+          items:
+            type: string
+        - name: type
+          type: array
+          items:
+            type: string
+            enum:
+            - success
+            - error
+            - warning
+            - information
+            - success audit
+            - failure audit
+        - name: id
+          type: array
+          items:
+            type: integer
         example:
           source:
            - Microsoft-Windows-Ntfs
@@ -169,6 +195,9 @@ files:
       value:
         type: string
         example: normal
+        enum:
+        - normal
+        - low
     - name: auth_type
       description: |
         The type of authentication to use. The available types are:
@@ -183,6 +212,11 @@ files:
       value:
         type: string
         example: default
+        enum:
+        - default
+        - negotiate
+        - kerberos
+        - ntlm
     - name: server
       description: |
         The name of the remote computer to connect to.

win32_event_log/datadog_checks/win32_event_log/check.py

@@ -11,23 +11,35 @@
 from six import PY2
 
 from datadog_checks.base import AgentCheck, ConfigurationError, is_affirmative
+from datadog_checks.base.utils.common import exclude_undefined_keys
 from datadog_checks.base.utils.time import get_timestamp
 
 from .filters import construct_xpath_query
 from .legacy import Win32EventLogWMI
 
+if PY2:
+    ConfigMixin = object
+else:
+    from .config_models import ConfigMixin
 
-class Win32EventLogCheck(AgentCheck):
+
+class Win32EventLogCheck(AgentCheck, ConfigMixin):
     # The lower cased version of the `API SOURCE ATTRIBUTE` column from the table located here:
     # https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value/
     SOURCE_TYPE_NAME = 'event viewer'
 
+    # NOTE: Keep this in sync with config spec:
+    # instances.start.value.enum
+    #
     # https://docs.microsoft.com/en-us/windows/win32/api/winevt/ne-winevt-evt_subscribe_flags
     START_OPTIONS = {
         'now': win32evtlog.EvtSubscribeToFutureEvents,
         'oldest': win32evtlog.EvtSubscribeStartAtOldestRecord,
     }
 
+    # NOTE: Keep this in sync with config spec:
+    # instances.auth_type.value.enum
+    #
     # https://docs.microsoft.com/en-us/windows/win32/api/winevt/ne-winevt-evt_rpc_login_flags
     LOGIN_FLAGS = {
         'default': win32evtlog.EvtRpcLoginAuthDefault,
@@ -65,12 +77,6 @@ def __new__(cls, name, init_config, instances):
     def __init__(self, name, init_config, instances):
         super(Win32EventLogCheck, self).__init__(name, init_config, instances)
 
-        # Event channel or log file with which to subscribe
-        self._path = self.instance.get('path', '')
-
-        # The point at which to start the event subscription
-        self._subscription_start = self.instance.get('start', 'now')
-
         # Raw user-defined query or one we construct based on filters
         self._query = None
 
@@ -90,16 +96,6 @@ def __init__(self, name, init_config, instances):
         # Session used for remote connections, or None if local connection
         self._session = None
 
-        # Connection options
-        self._timeout = int(float(self.instance.get('timeout', 5)) * 1000)
-        self._payload_size = int(self.instance.get('payload_size', 10))
-
-        # How often to update the cached bookmark
-        self._bookmark_frequency = int(self.instance.get('bookmark_frequency', self._payload_size))
-
-        # Custom tags to add to all events
-        self._tags = list(self.instance.get('tags', []))
-
         # Whether or not to interpret messages for unknown sources
         self._interpret_messages = is_affirmative(
             self.instance.get('interpret_messages', self.init_config.get('interpret_messages', True))
@@ -143,7 +139,7 @@ def check(self, _):
             event_payload = {
                 'source_type_name': self.SOURCE_TYPE_NAME,
                 'priority': self._event_priority,
-                'tags': list(self._tags),
+                'tags': list(self.config.tags),
             }
 
             # As seen in every collector, before using members of the enum you need to check for existence. See:
@@ -185,7 +181,7 @@ def collect_provider(self, event_payload, rendered_event, event_object):
             return
 
         event_payload['aggregation_key'] = value
-        event_payload['msg_title'] = '{}/{}'.format(self._path, value)
+        event_payload['msg_title'] = '{}/{}'.format(self.config.path, value)
 
         message = None
 
@@ -272,7 +268,7 @@ def consume_events(self):
         for event in self.poll_events():
             events_since_last_bookmark += 1
 
-            if events_since_last_bookmark >= self._bookmark_frequency:
+            if events_since_last_bookmark >= self.config.bookmark_frequency:
                 events_since_last_bookmark = 0
                 self.update_bookmark(event)
 
@@ -295,7 +291,7 @@ def poll_events(self):
                 # an empty tuple instead https://github.com/mhammond/pywin32/pull/1648
                 # For the moment is logged as a debug line.
                 try:
-                    events = win32evtlog.EvtNext(self._subscription, self._payload_size)
+                    events = win32evtlog.EvtNext(self._subscription, self.config.payload_size)
                 except pywintypes.error as e:
                     self.log_windows_error(e)
                     break
@@ -308,7 +304,7 @@ def poll_events(self):
 
             # https://docs.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitforsingleobjectex
             # http://timgolden.me.uk/pywin32-docs/win32event__WaitForSingleObjectEx_meth.html
-            wait_signal = win32event.WaitForSingleObjectEx(self._event_handle, self._timeout, True)
+            wait_signal = win32event.WaitForSingleObjectEx(self._event_handle, self.config.timeout, True)
 
             # No more events, end check run
             if wait_signal != win32con.WAIT_OBJECT_0:
@@ -328,15 +324,6 @@ def update_bookmark(self, event):
         self.write_persistent_cache('bookmark', bookmark_xml)
 
     def parse_config(self):
-        if not self._path:
-            raise ConfigurationError('You must select a `path`.')
-
-        if self._subscription_start not in self.START_OPTIONS:
-            raise ConfigurationError('Option `start` must be one of: {}'.format(', '.join(sorted(self.START_OPTIONS))))
-
-        if self._event_priority not in ('normal', 'low'):
-            raise ConfigurationError('Option `event_priority` can only be either `normal` or `low`.')
-
         for option in ('included_messages', 'excluded_messages'):
             if option not in self.instance:
                 continue
@@ -347,25 +334,17 @@ def parse_config(self):
 
             setattr(self, '_{}'.format(option), pattern)
 
-        password = self.instance.get('password')
+        password = self.config.password
         if password:
             self.register_secret(password)
 
     def construct_query(self):
-        query = self.instance.get('query')
+        query = self.config.query
         if query:
             self._query = query
             return
 
-        filters = self.instance.get('filters', {})
-        if not isinstance(filters, dict):
-            raise ConfigurationError('The `filters` option must be a mapping.')
-
-        for key, value in filters.items():
-            if not isinstance(value, list):
-                raise ConfigurationError('Value for event filter `{}` must be an array.'.format(key))
-
-        self._query = construct_xpath_query(filters)
+        self._query = construct_xpath_query(exclude_undefined_keys(self.config.filters.dict()))
         self.log.debug('Using constructed query: %s', self._query)
 
     def create_session(self):
@@ -388,7 +367,7 @@ def create_subscription(self):
         if bookmark:
             flags = win32evtlog.EvtSubscribeStartAfterBookmark
         else:
-            flags = self.START_OPTIONS[self._subscription_start]
+            flags = self.START_OPTIONS[self.config.start]
 
             # Set explicitly to None rather than a potentially empty string
             bookmark = None
@@ -400,7 +379,7 @@ def create_subscription(self):
         # https://docs.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtsubscribe
         # http://timgolden.me.uk/pywin32-docs/win32evtlog__EvtSubscribe_meth.html
         self._subscription = win32evtlog.EvtSubscribe(
-            self._path,
+            self.config.path,
             flags,
             SignalEvent=self._event_handle,
             Query=self._query,

win32_event_log/datadog_checks/win32_event_log/config_models/__init__.py

@@ -0,0 +1,18 @@
+# (C) Datadog, Inc. 2021-present
+# All rights reserved
+# Licensed under a 3-clause BSD style license (see LICENSE)
+from .instance import InstanceConfig
+from .shared import SharedConfig
+
+
+class ConfigMixin:
+    _config_model_instance: InstanceConfig
+    _config_model_shared: SharedConfig
+
+    @property
+    def config(self) -> InstanceConfig:
+        return self._config_model_instance
+
+    @property
+    def shared_config(self) -> SharedConfig:
+        return self._config_model_shared