atomicshop 2.11.47__py3-none-any.whl → 3.10.5__py3-none-any.whl

atomicshop/dns.py

@@ -1,6 +1,14 @@
+import socket
+import argparse
+
+# noinspection PyPackageRequirements
 import dns.resolver
 
-from .print_api import print_api
+from . import print_api
+from . import networks
+from .permissions import permissions
+from .wrappers.pywin32w.wmis import win32networkadapter
+from .wrappers import netshw
 
 
 # Defining Dictionary of Numeric to String DNS Query Types.
@@ -18,15 +26,6 @@ TYPES_DICT = {
     '255': 'ANY'
 }
 
-# Event Tracing DNS info.
-ETW_DNS_INFO = {
-    'provider_name': 'Microsoft-Windows-DNS-Client',
-    'provider_guid': '{1C95126E-7EEA-49A9-A3FE-A378B03DDB4D}',
-    # Event ID 3008 got DNS Queries and DNS Answers. Meaning, that information in ETW will arrive after DNS Response
-    # is received and not After DNS Query is sent.
-    'event_id': 3008
-}
-
 
 def resolve_dns_localhost(domain_name: str, dns_servers_list: list = None, print_kwargs: dict = None) -> str:
     """
@@ -61,10 +60,127 @@ def resolve_dns_localhost(domain_name: str, dns_servers_list: list = None, print
         # Get only the first entry of the list of IPs [0]
         connection_ip = function_server_address[0].to_text()
         message = f"Resolved to [{connection_ip}]"
-        print_api(message, **print_kwargs)
+        print_api.print_api(message, **print_kwargs)
     except dns.resolver.NXDOMAIN:
         message = f"Domain {domain_name} doesn't exist - Couldn't resolve with {dns_servers_list}."
-        print_api(message, **print_kwargs, error_type=True, logger_method='error')
+        print_api.print_api(message, **print_kwargs, error_type=True, logger_method='error')
         pass
 
     return connection_ip
+
+
+def get_default_dns_gateway() -> tuple[bool, list[str]]:
+    """
+    Get the default DNS gateway from the system.
+    :return: tuple(is dynamic boolean, list of DNS server IPv4s).
+    """
+
+    interfaces_with_dns_settings: list[dict] = netshw.get_netsh_ipv4()
+
+    default_interface_ipv4 = socket.gethostbyname(socket.gethostname())
+    is_dynamic, dns_servers = None, None
+    for interface in interfaces_with_dns_settings:
+        if default_interface_ipv4 in interface['ip_addresses']:
+            is_dynamic = interface['dns_mode']
+            dns_servers = interface['dns_servers']
+            break
+
+    return is_dynamic, dns_servers
+
+
+def get_default_dns_gateway_with_dns_resolver() -> list[str]:
+    """
+    Get the default DNS gateway from the system using dns.resolver.
+    :return: tuple(is dynamic boolean, list of DNS server IPv4s).
+    """
+
+    resolver = dns.resolver.Resolver()
+    dns_servers = list(resolver.nameservers)
+    return dns_servers
+
+
+def set_interface_dns_gateway_static(
+        interface_name: str,
+        dns_servers: list[str]
+) -> None:
+    """
+    Set the DNS servers for a network adapter.
+    :param interface_name: string, adapter name as shown in the network settings.
+    :param dns_servers: list of strings, DNS server IPv4 addresses.
+    :return: None
+    """
+
+    win32networkadapter.set_dns_server(interface_name=interface_name, dns_servers=dns_servers)
+
+
+def set_interface_dns_gateway_dynamic(
+        interface_name: str = None
+) -> None:
+    """
+    Set the DNS servers for a network adapter to obtain them automatically from DHCP.
+    :param interface_name: string, adapter name as shown in the network settings.
+    :return: None
+    """
+
+    win32networkadapter.set_dns_server(
+        interface_name=interface_name, dns_servers=None)
+
+
+def default_dns_gateway_main() -> int:
+    """
+    Main function for the default DNS gateway manipulations.
+    :return: None
+    """
+
+    argparse_obj = argparse.ArgumentParser(description="Get/Set the DNS gateway for the network adapter.")
+    arg_action_group = argparse_obj.add_mutually_exclusive_group(required=True)
+    arg_action_group.add_argument(
+        '-g', '--get', action='store_true', help='Get the default DNS gateway for the system.')
+    arg_action_group.add_argument(
+        '-s', '--set', type=str, nargs='+',
+        help='Set static DNS gateway for the system, provide values with spaces between each value.\n'
+             '   Example: -s 8.8.8.8 1.1.1.1.')
+    arg_action_group.add_argument(
+        '-d', '--dynamic', action='store_true',
+        help='Set the DNS gateway to obtain automatically from DHCP.')
+
+    arg_interface_group = argparse_obj.add_mutually_exclusive_group()
+    arg_interface_group.add_argument(
+        '-in', '--interface_name', type=str, help='Network Interface name as shown in the network settings.')
+    arg_interface_group.add_argument(
+        '-id', '--interface_default', action='store_true', help='Use the default network interface.')
+
+    args = argparse_obj.parse_args()
+
+    if (args.set or args.dynamic) and not (args.interface_name or args.interface_default):
+        print_api.print_api(
+            "Please provide the interface name [-in] or use the default interface [-id].", color='red')
+        return 1
+
+    if args.set or args.dynamic:
+        if not permissions.is_admin():
+            print_api.print_api("You need to run this script as an administrator", color='red')
+            return 1
+
+    def get_interface_name() -> str:
+        if args.interface_default:
+            return networks.get_default_interface_name()
+        else:
+            return args.interface_name
+
+    if args.get:
+        is_dynamic, dns_servers = get_default_dns_gateway()
+
+        if is_dynamic:
+            is_dynamic_string = 'Dynamic'
+        else:
+            is_dynamic_string = 'Static'
+        print_api.print_api(f'DNS Gateway: {is_dynamic_string} - {dns_servers}', color='blue')
+    elif args.set:
+        # dns_servers_list: list = args.dns_servers.split(',')
+        set_interface_dns_gateway_static(
+            dns_servers=args.set, interface_name=get_interface_name())
+    elif args.dynamic:
+        set_interface_dns_gateway_dynamic(interface_name=get_interface_name())
+
+    return 0

atomicshop/etws/_pywintrace_fix.py

@@ -0,0 +1,17 @@
+"""
+Need to fix the
+etw.etw
+file, in the
+EventConsumer._unpackSimpleType
+function.
+"""
+"""
+data = formatted_data.value
+# Convert the formatted data if necessary
+if isinstance(data, str):
+    if data.endswith(' '):
+        data = data[:-1]
+else:
+    if out_type in tdh.TDH_CONVERTER_LOOKUP and type(data) != tdh.TDH_CONVERTER_LOOKUP[out_type]:
+        data = tdh.TDH_CONVERTER_LOOKUP[out_type](data)
+"""

atomicshop/etws/const.py

@@ -0,0 +1,38 @@
+ETW_DNS = {
+    'provider_name': 'Microsoft-Windows-DNS-Client',
+    'provider_guid': '{1C95126E-7EEA-49A9-A3FE-A378B03DDB4D}',
+    'event_ids': {
+        # Event ID 3008 got DNS Queries and DNS Answers. Meaning, that information in ETW will arrive after DNS Response
+        # is received and not after DNS Query Request is sent.
+        'dns_request_response': 3008
+    }
+}
+
+
+# Event Tracing Kernel-Process.
+ETW_KERNEL_PROCESS = {
+    'provider_name': 'Microsoft-Windows-Kernel-Process',
+    'provider_guid': '{22FB2CD6-0E7B-422B-A0C7-2FAD1FD0E716}',
+    'event_ids': {
+        'process_create': 1  # Emits all the processes that are started.
+    }
+}
+
+
+# You need SYSTEM privileges to execute this one. Try with psexec -s -i
+ETW_SECURITY_AUDITING = {
+    'provider_name': 'Microsoft-Windows-Security-Auditing',
+    'provider_guid': '{54849625-5478-4994-A5BA-3E3B0328C30D}',
+    'event_ids': {
+        'process_create': 4688      # Emits all the processes that are started.
+    }
+}
+
+
+ETW_SYSMON = {
+    'provider_name': 'Microsoft-Windows-Sysmon',
+    'provider_guid': '{5770385F-C22A-43E0-BF4C-06F5698FFBD9}',
+    'event_ids': {
+        'process_create': 1         # Emits all the processes that are started.
+    }
+}

atomicshop/etws/providers.py

@@ -0,0 +1,21 @@
+from typing import Literal
+
+from ..wrappers.ctyping.etw_winapi import etw_functions
+
+
+def get_providers(key_as: Literal['name', 'guid'] = 'name'):
+    return etw_functions.get_all_providers(key_as=key_as)
+
+
+def get_provider_guid_by_name(provider_name):
+    providers = get_providers(key_as='name')
+
+    try:
+        provider_guid = providers[provider_name]
+    except KeyError:
+        provider_guid = None
+
+    if not provider_guid:
+        raise ValueError(f"Provider '{provider_name}' not found")
+
+    return provider_guid

atomicshop/etws/sessions.py

@@ -0,0 +1,43 @@
+from ..wrappers.ctyping.etw_winapi import etw_functions
+
+
+def stop_and_delete(session_name: str) -> tuple[bool, int]:
+    """
+    Stop and delete ETW session.
+
+    :param session_name: The name of the session to stop and delete.
+    :return: A tuple containing a boolean indicating success and an integer status code.
+        True, 0: If the session was stopped and deleted successfully.
+        False, <status>: If the session could not be stopped and deleted and the status code, why it failed.
+    """
+
+    return etw_functions.stop_and_delete_etw_session(session_name)
+
+
+def get_running_list() -> list[dict]:
+    """
+    List all running ETW sessions.
+
+    :return: A list of strings containing the names of all running ETW sessions.
+    """
+
+    return etw_functions.list_etw_sessions()
+
+
+def is_session_running(session_name: str) -> bool:
+    """
+    Check if an ETW session is running.
+
+    :param session_name: The name of the session to check.
+    :return: A boolean indicating if the session is running.
+    """
+
+    # Get all running sessions.
+    running_sessions = get_running_list()
+
+    # Check if the session is in the list of running sessions.
+    for session in running_sessions:
+        if session['session_name'] == session_name:
+            return True
+
+    return False

atomicshop/etws/trace.py

@@ -0,0 +1,168 @@
+import queue
+import sys
+import multiprocessing.managers
+from datetime import datetime
+
+# Import FireEye Event Tracing library.
+import etw
+
+from ..print_api import print_api
+from . import sessions
+from ..process_poller import simple_process_pool
+
+
+class EventTrace(etw.ETW):
+    def __init__(
+            self,
+            providers: list,
+            event_callback: callable = None,
+            event_id_filters: list = None,
+            session_name: str = None,
+            close_existing_session_name: bool = True,
+            enable_process_poller: bool = False,
+            process_pool_shared_dict_proxy: multiprocessing.managers.DictProxy = None
+    ):
+        """
+        :param providers: List of tuples with provider name and provider GUID.
+            tuple[0] = provider name
+            tuple[1] = provider GUID
+
+            Example: [('Microsoft-Windows-DNS-Client', '{1c95126e-7ee8-4e23-86b2-6e7e4a5a8e9b}')]
+        :param event_callback: Reference to the callable callback function that will be called for each occurring event.
+        :param event_id_filters: List of event IDs that we want to filter. If not provided, all events will be returned.
+            The default in the 'etw.ETW' method is 'None'.
+        :param session_name: The name of the session to create. If not provided, a UUID will be generated.
+        :param close_existing_session_name: Boolean to close existing session names.
+        :param enable_process_poller: Boolean to enable process poller. Gets the process PID, Name and CommandLine.
+            Since the DNS events doesn't contain the process name and command line, only PID.
+            Then DNS events will be enriched with the process name and command line from the process poller.
+        :param process_pool_shared_dict_proxy: multiprocessing.managers.DictProxy,
+            multiprocessing shared dict proxy that contains current processes.
+            Check the 'atomicshop\process_poller\simple_process_pool.py' SimpleProcessPool class for more information.
+
+            If None, the process poller will create a new shared dict proxy.
+            If provided, then the provided shared dict proxy will be used.
+            Off course valid only if 'enable_process_poller' is True.
+
+        ------------------------------------------
+
+        You should stop the ETW tracing when you are done with it.
+            'pywintrace' module starts a new session for ETW tracing, and it will not stop the session when the script
+            exits or exception is raised.
+            This can cause problems when you want to start the script again, and the session is already running.
+            If the session is already running, and you start a new session with the same session name, you will get
+            the buffer from when you stopped getting the events from the buffer.
+            If you give different session name for new session, the previous session will still continue to run,
+            filling the buffer with events, until you will stop getting new events on all sessions or get an
+            exception that the buffer is full (WinError 1450).
+
+            Example to stop the ETW tracing at the end of the script:
+            from atomicshop.basics import atexits
+
+
+            event_tracing = EventTrace(<Your parameters>)
+            atexits.run_callable_on_exit_and_signals(EventTrace.stop)
+        """
+        self.event_queue = queue.Queue()
+        self.close_existing_session_name: bool = close_existing_session_name
+        self.enable_process_poller: bool = enable_process_poller
+        self.process_pool_shared_dict_proxy: multiprocessing.managers.DictProxy = process_pool_shared_dict_proxy
+
+        # If no callback function is provided, we will use the default one, which will put the event in the queue.
+        if not event_callback:
+            function_callable = lambda x: self.event_queue.put(x)
+        # If a callback function is provided, we will use it.
+        else:
+            function_callable = lambda x: event_callback(x)
+
+        # Defining the list of specified ETW providers in 'etw' library format.
+        etw_format_providers: list = list()
+        for provider in providers:
+            etw_format_providers.append(etw.ProviderInfo(provider[0], etw.GUID(provider[1])))
+
+        self.self_hosted_poller: bool = False
+        if self.enable_process_poller:
+            if self.process_pool_shared_dict_proxy is None:
+                self.self_hosted_poller = True
+                self.process_poller = simple_process_pool.SimpleProcessPool()
+                self.multiprocessing_manager: multiprocessing.managers.SyncManager = multiprocessing.Manager()
+                self.process_pool_shared_dict_proxy = self.multiprocessing_manager.dict()
+
+            self.pid_process_converter = simple_process_pool.PidProcessConverter(
+                process_pool_shared_dict_proxy=self.process_pool_shared_dict_proxy)
+
+        super().__init__(
+            providers=etw_format_providers, event_callback=function_callable, event_id_filters=event_id_filters,
+            session_name=session_name
+        )
+
+    def start(self):
+        if self.enable_process_poller and self.self_hosted_poller:
+            self.process_poller.start()
+
+        # Check if the session name already exists.
+        if sessions.is_session_running(self.session_name):
+            print_api(f'ETW Session already running: {self.session_name}', color='yellow')
+
+            # Close the existing session name.
+            if self.close_existing_session_name:
+                print_api(f'Closing existing session: {self.session_name}', color='blue')
+                sessions.stop_and_delete(self.session_name)
+            else:
+                print_api(f'Using existing session: {self.session_name}', color='yellow')
+
+        try:
+            super().start()
+        except OSError as e:
+            message = f"PyWinTrace Error: {e}\n" \
+                        f"PyWinTrace crashed, didn't find solution to this, RESTART computer."
+            print_api(message, error_type=True, logger_method='critical')
+            sys.exit(1)
+
+    def stop(self):
+        super().stop()
+
+        if self.self_hosted_poller:
+            self.process_poller.stop()
+
+            self.multiprocessing_manager.shutdown()
+
+    def emit(self):
+        """
+        The Function will return the next event from the queue.
+        The queue is blocking, so if there is no event in the queue, the function will wait until there is one.
+
+        Usage Example:
+            while True:
+                dns_dict = dns_trace.emit()
+                print(dns_dict)
+
+        event object:
+            event[0]: is the event ID. Example: for DNS Tracing, it is event id 3008.
+            event[1]: contains a dictionary with all the event's parameters.
+
+        :return: etw event object.
+        """
+
+        event: tuple = self.event_queue.get()
+
+        current_datetime = datetime.now()
+        readable_time = current_datetime.strftime('%Y-%m-%d %H:%M:%S.%f')
+
+        event_dict: dict = {
+            'EventId': event[0],
+            'EventHeader': event[1],
+            'timestamp': readable_time
+        }
+
+        if 'ProcessId' not in event[1]:
+            event_dict['pid'] = event[1]['EventHeader']['ProcessId']
+        else:
+            event_dict['pid'] = event[1]['ProcessId']
+
+        if self.enable_process_poller:
+            process_info: dict = self.pid_process_converter.get_process_by_pid(event_dict['pid'])
+            event_dict['name'] = process_info['name']
+            event_dict['cmdline'] = process_info['cmdline']
+
+        return event_dict

atomicshop/etws/traces/trace_dns.py

@@ -0,0 +1,162 @@
+import multiprocessing.managers
+
+from .. import trace, const
+from ...basics import dicts
+from ... import dns, ip_addresses
+
+
+ETW_DEFAULT_SESSION_NAME: str = 'AtomicShopDnsTrace'
+
+PROVIDER_NAME: str = const.ETW_DNS['provider_name']
+PROVIDER_GUID: str = const.ETW_DNS['provider_guid']
+REQUEST_RESP_EVENT_ID: int = const.ETW_DNS['event_ids']['dns_request_response']
+
+
+class DnsRequestResponseTrace:
+    """DnsTrace class use to trace DNS events from Windows Event Tracing for EventId 3008."""
+    def __init__(
+            self,
+            attrs: list = None,
+            session_name: str = None,
+            close_existing_session_name: bool = True,
+            skip_record_list: list = None,
+            process_pool_shared_dict_proxy: multiprocessing.managers.DictProxy = None
+    ):
+        """
+        :param attrs: List of attributes to return. If None, all attributes will be returned.
+        :param session_name: The name of the session to create. If not provided, a UUID will be generated.
+        :param close_existing_session_name: Boolean to close existing session names.
+            True: if ETW session with 'session_name' exists, you will be notified and the session will be closed.
+                Then the new session with this name will be created.
+            False: if ETW session with 'session_name' exists, you will be notified and the new session will not be
+                created. Instead, the existing session will be used. If there is a buffer from the previous session,
+                you will get the events from the buffer.
+        :param skip_record_list: List of DNS Records to skip emitting. Example: ['PTR', 'SRV']
+        :param process_pool_shared_dict_proxy: multiprocessing.managers.DictProxy, multiprocessing shared dict proxy
+            that contains current processes.
+            Check the 'atomicshop\process_poller\simple_process_pool.py' SimpleProcessPool class for more information.
+
+            For this specific class it means that you can run the process poller outside of this class and pass the
+            'process_pool_shared_dict_proxy' to this class. Then you can get the process name and command line for
+            the DNS events from the 'process_pool_shared_dict_proxy' and use it also in other classes.
+
+        -------------------------------------------------
+
+        Usage Example:
+            from atomicshop.etw import dns_trace
+
+
+            dns_trace_w = dns_trace.DnsTrace(
+                attrs=['pid', 'name', 'cmdline', 'query', 'query_type'],
+                session_name='MyDnsTrace',
+                close_existing_session_name=True,
+                enable_process_poller=True
+            )
+            dns_trace_w.start()
+            while True:
+                dns_dict = dns_trace_w.emit()
+                print(dns_dict)
+            dns_trace_w.stop()
+        """
+
+        self.attrs = attrs
+        self.process_pool_shared_dict_proxy: multiprocessing.managers.DictProxy = process_pool_shared_dict_proxy
+
+        if skip_record_list:
+            self.skip_record_list: list = skip_record_list
+        else:
+            self.skip_record_list: list = list()
+
+        if not session_name:
+            session_name = ETW_DEFAULT_SESSION_NAME
+
+        self.event_trace = trace.EventTrace(
+            providers=[(PROVIDER_NAME, PROVIDER_GUID)],
+            # lambda x: self.event_queue.put(x),
+            event_id_filters=[REQUEST_RESP_EVENT_ID],
+            session_name=session_name,
+            close_existing_session_name=close_existing_session_name,
+            enable_process_poller=True,
+            process_pool_shared_dict_proxy=self.process_pool_shared_dict_proxy
+        )
+
+    def start(self):
+        self.event_trace.start()
+
+    def stop(self):
+        self.event_trace.stop()
+
+    def emit(self):
+        """
+        Function that will return the next event from the queue.
+        The queue is blocking, so if there is no event in the queue, the function will wait until there is one.
+
+        Usage Example:
+            while True:
+                dns_dict = dns_trace.emit()
+                print(dns_dict)
+
+        :return: Dictionary with the event data.
+        """
+
+        # Get the event from ETW as is.
+        event = self.event_trace.emit()
+
+        # Get the raw query results string from the event.
+        query_results: str = event['EventHeader']['QueryResults']
+
+        if query_results != '':
+            query_results_list: list = query_results.split(';')
+
+            addresses_ips: list = list()
+            addresses_cnames: list = list()
+            for query_result in query_results_list:
+                # If there is a type in the query result, it means it is a cname (domain).
+                if 'type' in query_result:
+                    query_result = query_result.split(' ')[-1]
+
+                # But we'll still make sure that the query result is an IP address or not.
+                if ip_addresses.is_ip_address(query_result):
+                    addresses_ips.append(query_result)
+                # If it is not empty, then it is a cname.
+                elif query_result != '':
+                    addresses_cnames.append(query_result)
+        # if the query results are empty, then we'll just set the addresses to empty lists.
+        else:
+            addresses_ips: list = list()
+            addresses_cnames: list = list()
+
+        status_id: str = str(event['EventHeader']['QueryStatus'])
+
+        # Getting the 'QueryStatus' key. If DNS Query Status is '0' then it was executed successfully.
+        # And if not, it means there was an error. The 'QueryStatus' indicate what number of an error it is.
+        if status_id == '0':
+            status = 'Success'
+        else:
+            status = 'Error'
+
+        event_dict: dict = {
+            'timestamp': event['timestamp'],
+            'event_id': event['EventId'],
+            'query': event['EventHeader']['QueryName'],
+            'query_type_id': str(event['EventHeader']['QueryType']),
+            'query_type': dns.TYPES_DICT[str(event['EventHeader']['QueryType'])],
+            'result_ips': ','.join(addresses_ips),
+            'result_cnames': ','.join(addresses_cnames),
+            'status_id': status_id,
+            'status': status,
+            'pid': event['pid'],
+            'name': event['name'],
+            'cmdline': event['cmdline']
+        }
+
+        # Skip emitting the record if it is in the 'skip_record_list'.
+        # Just recall the function to get the next event and return it.
+        if event_dict['query_type'] in self.skip_record_list:
+            return self.emit()
+
+        if self.attrs:
+            event_dict = dicts.reorder_keys(
+                event_dict, self.attrs, skip_keys_not_in_list=True)
+
+        return event_dict