besapi 3.8.3__tar.gz → 3.9.4__tar.gz

{besapi-3.8.3/src/besapi.egg-info → besapi-3.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: besapi
-Version: 3.8.3
+Version: 3.9.4
 Summary: Library for working with the BigFix REST API
 Home-page: https://github.com/jgstew/besapi
 Author: Matt Hansen, James Stewart

{besapi-3.8.3 → besapi-3.9.4}/src/besapi/besapi.py

@@ -25,7 +25,7 @@ import lxml.etree
 import lxml.objectify
 import requests
 
-__version__ = "3.8.3"
+__version__ = "3.9.4"
 
 besapi_logger = logging.getLogger("besapi")
 
@@ -283,6 +283,20 @@ def validate_xml_bes_file(file_path):
     return validate_xsd(file_data)
 
 
+def get_bes_conn_using_env():
+    """Get BESConnection using environment variables."""
+    username = os.getenv("BES_USER_NAME")
+    password = os.getenv("BES_PASSWORD")
+    rootserver = os.getenv("BES_ROOT_SERVER")
+
+    if username and password and rootserver:
+        bes_conn = BESConnection(username, password, rootserver)
+        if bes_conn:
+            return bes_conn
+
+    return None
+
+
 def get_bes_conn_using_config_file(conf_file=None):
     """
     Read connection values from config file.
@@ -479,6 +493,8 @@ class BESConnection:
 
         This will submit the relevance string as json instead of html form data.
         """
+        # not sure if the following is needed to handle some cases:
+        # relevance = "(it as string) of ( " + relevance + " )"
         rel_result_array = self.session_relevance_json_array(relevance, **kwargs)
         # Ensure each element is converted to a string
         return "\n".join(map(str, rel_result_array))

{besapi-3.8.3 → besapi-3.9.4}/src/besapi/plugin_utilities.py

@@ -10,6 +10,7 @@ import logging.handlers
 import ntpath
 import os
 import sys
+from typing import Union
 
 import besapi
 
@@ -131,12 +132,35 @@ def get_plugin_logging_config(log_file_path="", verbose=0, console=True):
     }
 
 
-def get_besapi_connection(args):
-    """Get connection to besapi using either args or config file if args not
-    provided.
-    """
+def get_besapi_connection_env_then_config():
+    """Get connection to besapi using env vars first, then config file."""
+    logging.info("attempting connection to BigFix using ENV method.")
+    # try to get connection from env vars:
+    bes_conn = besapi.besapi.get_bes_conn_using_env()
+    if bes_conn:
+        return bes_conn
+
+    logging.info("attempting connection to BigFix using config file method.")
+    bes_conn = besapi.besapi.get_bes_conn_using_config_file()
+    return bes_conn
+
+
+def get_besapi_connection_args(
+    args: argparse.Namespace,
+) -> Union[besapi.besapi.BESConnection, None]:
+    """Get connection to besapi using provided args."""
+    password = None
+    bes_conn = None
+
+    if args.password:
+        password = args.password
 
-    password = args.password
+    # if user was provided as arg but password was not:
+    if args.user and not password:
+        if os.name == "nt":
+            # attempt to get password from windows root server registry:
+            # this is specifically for the case where user is provided for a plugin
+            password = besapi.plugin_utilities_win.get_win_registry_rest_pass()
 
     # if user was provided as arg but password was not:
     if args.user and not password:
@@ -144,7 +168,7 @@ def get_besapi_connection(args):
         print("Password was not provided, provide REST API password:")
         password = getpass.getpass()
 
-    if args.user:
+    if password:
         logging.debug("REST API Password Length: %s", len(password))
 
     # process args, setup connection:
@@ -158,13 +182,13 @@ def get_besapi_connection(args):
     if args.user and password:
         try:
             if not rest_url:
-                raise AttributeError
+                raise AttributeError("args.rest_url is not set.")
             bes_conn = besapi.besapi.BESConnection(args.user, password, rest_url)
         except (
             AttributeError,
             ConnectionRefusedError,
             besapi.besapi.requests.exceptions.ConnectionError,
-        ):
+        ) as e:
             logging.exception(
                 "connection to `%s` failed, attempting `%s` instead",
                 rest_url,
@@ -172,7 +196,7 @@ def get_besapi_connection(args):
             )
             try:
                 if not args.besserver:
-                    raise AttributeError
+                    raise AttributeError("args.besserver is not set.") from e
                 bes_conn = besapi.besapi.BESConnection(
                     args.user, password, args.besserver
                 )
@@ -185,7 +209,7 @@ def get_besapi_connection(args):
                 )
                 return None
             except BaseException as err:
-                # always log error and stop the current process
+                # always log error
                 logging.exception("ERROR: %s", err)
                 logging.exception(
                     "----- ERROR: BigFix Connection Failed! Unknown reason ------"
@@ -193,8 +217,46 @@ def get_besapi_connection(args):
                 return None
     else:
         logging.info(
-            "attempting connection to BigFix using config file method as user command arg was not provided"
+            "No user arg provided, no password found. Cannot create connection."
+        )
+        return None
+
+    return bes_conn
+
+
+def get_besapi_connection(
+    args: Union[argparse.Namespace, None] = None,
+) -> Union[besapi.besapi.BESConnection, None]:
+    """Get connection to besapi.
+
+    If on Windows, will attempt to get connection from Windows Registry first.
+    If args provided, will attempt to get connection using provided args.
+    If no args provided, will attempt to get connection from env vars.
+    If no env vars, will attempt to get connection from config file.
+
+    Arguments:
+        args: argparse.Namespace object, usually from setup_plugin_argparse()
+    Returns:
+        A BESConnection object if successful, otherwise None.
+    """
+    # if windows, try to get connection from windows registry:
+    if os.name == "nt":
+        bes_conn = besapi.plugin_utilities_win.get_besconn_root_windows_registry()
+        if bes_conn:
+            return bes_conn
+
+    # if no args provided, try to get connection from env then config file:
+    if not args:
+        logging.info("no args provided, attempting connection using env then config.")
+        return get_besapi_connection_env_then_config()
+
+    # attempt bigfix connection with provided args:
+    if args.user:
+        bes_conn = get_besapi_connection_args(args)
+    else:
+        logging.info(
+            "no user arg provided, attempting connection using env then config."
         )
-        bes_conn = besapi.besapi.get_bes_conn_using_config_file()
+        return get_besapi_connection_env_then_config()
 
     return bes_conn

besapi-3.9.4/src/besapi/plugin_utilities_win.py

@@ -0,0 +1,216 @@
+"""
+Plugin utilities for Windows systems, including DPAPI encryption/decryption
+and Windows Registry access.
+"""
+
+import base64
+import logging
+import sys
+from typing import Union
+
+import besapi
+
+logger = logging.getLogger(__name__)
+
+try:
+    import winreg
+except (ImportError, ModuleNotFoundError) as e:
+    if not sys.platform.startswith("win"):
+        raise RuntimeError(
+            "This script requires the 'winreg' module, which is only available on Windows."
+        ) from e
+    else:
+        raise e
+
+try:
+    import win32crypt
+except (ImportError, ModuleNotFoundError) as e:
+    if not sys.platform.startswith("win"):
+        raise RuntimeError("This script only works on Windows systems") from e
+    raise ImportError(
+        "This script requires the pywin32 package. Install it via 'pip install pywin32'."
+    ) from e
+
+
+def win_dpapi_encrypt_str(
+    plaintext: str, scope_flags: int = 4, entropy: Union[str, bytes, None] = None
+) -> Union[str, None]:
+    """Encrypt a string using Windows DPAPI and return it as a base64-encoded string.
+
+    Args:
+        plaintext (str): The string to encrypt.
+        scope_flags (int): The context scope for encryption (default is 4).
+        entropy (bytes | None): Optional entropy for encryption.
+
+    Returns:
+        str: The base64-encoded encrypted string.
+    """
+    if not plaintext or plaintext.strip() == "":
+        logger.warning("No plaintext provided for encryption.")
+        return None
+
+    # 1. Convert the plaintext string to bytes
+    plaintext_bytes = plaintext.encode("utf-8")
+
+    # 2. Call CryptProtectData.
+    # The last parameter (flags) is set to 4
+    # to indicate that the data should be encrypted in the machine context.
+    #
+    # The function returns a tuple: (description, encrypted_bytes)
+    # We only need the second element.
+    encrypted_bytes = win32crypt.CryptProtectData(
+        plaintext_bytes,
+        None,  # Description
+        entropy,  # Optional entropy
+        None,  # Reserved
+        None,  # Prompt Struct
+        scope_flags,
+    )
+
+    # 3. Encode the encrypted bytes to a Base64 string
+    encrypted_b64 = base64.b64encode(encrypted_bytes).decode("utf-8")
+
+    return encrypted_b64
+
+
+def win_dpapi_decrypt_base64(
+    encrypted_b64: str, scope_flags: int = 4, entropy: Union[str, bytes, None] = None
+) -> Union[str, None]:
+    """Decrypt a base64-encoded string encrypted with Windows DPAPI.
+
+    Args:
+        encrypted_b64 (str): The base64-encoded encrypted string.
+        scope_flags (int): The context scope for decryption (default is 4).
+        entropy (bytes | None): Optional entropy for decryption.
+
+    Returns:
+        str: The decrypted string.
+    """
+    if not encrypted_b64 or encrypted_b64.strip() == "":
+        logger.warning("No encrypted data provided for decryption.")
+        return None
+
+    # 1. Decode the Base64 string to get the raw encrypted bytes
+    encrypted_bytes = base64.b64decode(encrypted_b64)
+
+    # 2. Call CryptUnprotectData.
+    # The last parameter (flags) is set to 4
+    # to indicate that the data was encrypted in the machine context.
+    #
+    # The function returns a tuple: (description, decrypted_bytes)
+    # We only need the second element.
+    _, decrypted_bytes = win32crypt.CryptUnprotectData(
+        encrypted_bytes,
+        entropy,  # Optional entropy
+        None,  # Reserved
+        None,  # Prompt Struct
+        scope_flags,
+    )
+
+    if decrypted_bytes:
+        decrypted_string = decrypted_bytes.decode("utf-8").strip()
+        return decrypted_string
+
+    logger.debug("Decryption returned no data.")
+    return None
+
+
+def win_registry_value_read(hive, subkey, value_name):
+    """
+    Reads a value from the Windows Registry.
+
+    Args:
+        hive: The root hive (e.g., winreg.HKEY_LOCAL_MACHINE, winreg.HKEY_CURRENT_USER).
+        subkey: The path to the subkey (e.g., "SOFTWARE\\Microsoft\\Windows\\CurrentVersion").
+        value_name: The name of the value to read.
+
+    Returns:
+        The value data if found, otherwise None.
+    """
+    try:
+        # Open the specified registry key
+        key = winreg.OpenKey(hive, subkey, 0, winreg.KEY_READ)
+
+        # Query the value data
+        value_data, _ = winreg.QueryValueEx(key, value_name)
+
+        # Close the key
+        winreg.CloseKey(key)
+
+        return value_data
+    except FileNotFoundError:
+        logger.debug("Registry key or value '%s\\%s' not found.", subkey, value_name)
+        return None
+    except Exception as e:
+        logger.error("An error occurred: %s", e)
+        return None
+
+
+def get_win_registry_rest_pass() -> Union[str, None]:
+    """
+    Retrieves the base64 encrypted REST Password from the Windows Registry.
+
+    Returns:
+        The REST Password if found, otherwise None.
+    """
+    hive = winreg.HKEY_LOCAL_MACHINE  # type: ignore[attr-defined]
+    # HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\BigFix\Enterprise Server\MFSConfig
+    subkey = r"SOFTWARE\Wow6432Node\BigFix\Enterprise Server\MFSConfig"
+    value_name = "RESTPassword"
+
+    reg_value = win_registry_value_read(hive, subkey, value_name)
+
+    if not reg_value:
+        logger.debug("No registry value found for %s.", value_name)
+        return None
+
+    # remove {obf} from start of string if present:
+    if reg_value and reg_value.startswith("{obf}"):
+        reg_value = reg_value[5:]
+
+    if reg_value and len(reg_value) > 50:
+        password = win_dpapi_decrypt_base64(reg_value)
+        if password and len(password) > 3:
+            return password
+
+    logger.debug("Decryption failed or decrypted password length is too short.")
+    return None
+
+
+def get_besconn_root_windows_registry() -> Union[besapi.besapi.BESConnection, None]:
+    """
+    Attempts to create a BESConnection using credentials stored in the Windows
+    Registry.
+
+    Returns:
+        A BESConnection object if successful, otherwise None.
+    """
+    password = get_win_registry_rest_pass()
+    if not password:
+        return None
+
+    hive = winreg.HKEY_LOCAL_MACHINE  # type: ignore[attr-defined]
+    subkey = r"SOFTWARE\Wow6432Node\BigFix\Enterprise Server\MFSConfig"
+
+    user = win_registry_value_read(hive, subkey, "RESTUsername")
+
+    if not user:
+        return None
+
+    rest_url = win_registry_value_read(hive, subkey, "RESTURL")
+
+    if not rest_url:
+        return None
+
+    # normalize url to https://HostOrIP:52311
+    if rest_url and rest_url.endswith("/api"):
+        rest_url = rest_url.replace("/api", "")
+
+    if user and password and rest_url:
+        try:
+            return besapi.besapi.BESConnection(user, password, rest_url)
+        except Exception as e:
+            logger.error("Failed to create BESConnection from registry values: %s", e)
+            return None
+
+    return None

{besapi-3.8.3 → besapi-3.9.4/src/besapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: besapi
-Version: 3.8.3
+Version: 3.9.4
 Summary: Library for working with the BigFix REST API
 Home-page: https://github.com/jgstew/besapi
 Author: Matt Hansen, James Stewart

{besapi-3.8.3 → besapi-3.9.4}/src/besapi.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ src/besapi/__init__.py
 src/besapi/__main__.py
 src/besapi/besapi.py
 src/besapi/plugin_utilities.py
+src/besapi/plugin_utilities_win.py
 src/besapi.egg-info/PKG-INFO
 src/besapi.egg-info/SOURCES.txt
 src/besapi.egg-info/dependency_links.txt

{besapi-3.8.3 → besapi-3.9.4}/tests/test_besapi.py

@@ -25,6 +25,9 @@ if not os.getenv("TEST_PIP"):
 import besapi
 import besapi.plugin_utilities
 
+if os.name == "nt":
+    import besapi.plugin_utilities_win
+
 
 def test_besapi_version():
     """Test that the besapi version is not None."""
@@ -228,40 +231,92 @@ def test_bescli():
         assert bes_conn.login()
 
 
+def test_plugin_utilities_win_get_besconn_root_windows_registry():
+    """Test getting a BESConnection from the Windows Registry."""
+    if "BES_ROOT_SERVER" not in os.environ:
+        pytest.skip("Skipping Windows Registry test, BES_ROOT_SERVER not set.")
+    if "BES_USER_NAME" not in os.environ:
+        pytest.skip("Skipping Windows Registry test, BES_USER_NAME not set.")
+    if "BES_PASSWORD" not in os.environ:
+        pytest.skip("Skipping Windows Registry test, BES_PASSWORD not set.")
+
+    if not os.name == "nt":
+        pytest.skip("Skipping Windows Registry test on non-Windows system.")
+
+    # only run this test if besapi > v3.9.1:
+    if besapi.besapi.__version__ <= "3.9.1":
+        pytest.skip("Skipping test for besapi <= 3.9.1")
+
+    # get env vars for testing:
+    root_server = os.getenv("BES_ROOT_SERVER")
+    root_user = os.getenv("BES_USER_NAME")
+    root_user_password = os.getenv("BES_PASSWORD")
+
+    encrypted_str = besapi.plugin_utilities_win.win_dpapi_encrypt_str(
+        root_user_password
+    )
+
+    import winreg
+
+    # write user and encrypted password to registry for testing:
+    # HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\BigFix\Enterprise Server\MFSConfig
+    subkey = r"SOFTWARE\Wow6432Node\BigFix\Enterprise Server\MFSConfig"
+    hive = winreg.HKEY_LOCAL_MACHINE  # type: ignore[attr-defined]
+
+    key = winreg.CreateKey(hive, subkey)
+    winreg.SetValueEx(
+        key, "RESTURL", 0, winreg.REG_SZ, "https://" + root_server + ":52311/api"
+    )
+    winreg.SetValueEx(key, "RESTUsername", 0, winreg.REG_SZ, root_user)
+    winreg.SetValueEx(key, "RESTPassword", 0, winreg.REG_SZ, "{obf}" + encrypted_str)
+    winreg.CloseKey(key)
+    bes_conn = besapi.plugin_utilities_win.get_besconn_root_windows_registry()
+    assert bes_conn is not None
+
+
 def test_bes_conn_json():
     """Test the BESConnection class with JSON output."""
-    bes_conn = besapi.besapi.get_bes_conn_using_config_file()
+
+    bes_conn = besapi.plugin_utilities.get_besapi_connection(None)
+
     if bes_conn and bes_conn.login():
         print("testing session_relevance_json")
-        result = bes_conn.session_relevance_json("number of bes computers")
+        result = bes_conn.session_relevance_json("number of all bes sites")
         assert result is not None
         assert int(result["result"][0]) > 0
         result = bes_conn.session_relevance_json(
-            """("[%22" & it & "%22]") of concatenation "%22, %22" of names of bes computers"""
+            """("[%22" & it & "%22]") of concatenation "%22, %22" of names of all bes sites"""
         )
         assert result is not None
         string_first_result_json = result["result"][0]
         print(string_first_result_json)
         assert '", "' in string_first_result_json
         assert '["' in string_first_result_json
-        # NOTE: the following check is specific to my env:
-        if "10.0." in bes_conn.rootserver:
-            print("doing check specific to my env")
-            assert '", "BIGFIX", "' in string_first_result_json
+        assert '"BES Support"' in string_first_result_json
 
         print("testing session_relevance_json_array")
-        result = bes_conn.session_relevance_json_array("number of bes computers")
+        result = bes_conn.session_relevance_json_array("number of all bes sites")
         print(result)
         assert result is not None
         assert int(result[0]) > 0
         print("testing session_relevance_json_string")
-        result = bes_conn.session_relevance_json_string("number of bes computers")
+        result = bes_conn.session_relevance_json_string("number of all bes sites")
         print(result)
         assert result is not None
         assert int(result) > 0
+        print("testing session_relevance_json_string tuple")
+        result = bes_conn.session_relevance_json_string(
+            '(ids of it, names of it, "TestString") of all bes sites'
+        )
+        print(result)
+        assert result is not None
+        assert "TestString" in result
+        assert "BES Support" in result
+    else:
+        pytest.skip("Skipping BESConnection test, no config file or login failed.")
 
 
-def test_plugin_utilities():
+def test_plugin_utilities_logging():
     """Test the plugin_utilities module."""
     print(besapi.plugin_utilities.get_invoke_folder())
     print(besapi.plugin_utilities.get_invoke_file_name())
@@ -282,3 +337,72 @@ def test_plugin_utilities():
         logging.warning("Just testing to see if logging is working!")
 
         assert os.path.isfile("./tests.log")
+
+
+def test_plugin_utilities_win_dpapi():
+    """Test the Windows DPAPI encryption function, if on Windows."""
+    if not os.name == "nt":
+        pytest.skip("Skipping Windows Registry test on non-Windows system.")
+
+    # only run this test if besapi > v3.8.3:
+    if besapi.besapi.__version__ <= "3.8.3":
+        pytest.skip("Skipping test for besapi <= 3.8.3")
+
+    test_string = "This is just a test string " + str(random.randint(0, 9999))
+    encrypted_str = besapi.plugin_utilities_win.win_dpapi_encrypt_str(test_string)
+    print("Encrypted string:", encrypted_str)
+    assert encrypted_str != ""
+    assert encrypted_str != test_string
+    decrypted_str = besapi.plugin_utilities_win.win_dpapi_decrypt_base64(encrypted_str)
+    print("Decrypted string:", decrypted_str)
+    assert decrypted_str == test_string
+
+
+def test_plugin_utilities_win_win_registry_value_read():
+    """Test reading a Windows registry value."""
+    if not os.name == "nt":
+        pytest.skip("Skipping Windows Registry test on non-Windows system.")
+
+    # only run this test if besapi > v3.8.3:
+    if besapi.besapi.__version__ <= "3.8.3":
+        pytest.skip("Skipping test for besapi <= 3.8.3")
+
+    import winreg
+
+    registry_key = r"SOFTWARE\Microsoft\Windows\CurrentVersion"
+    registry_value = "ProgramFilesDir"
+    result = besapi.plugin_utilities_win.win_registry_value_read(
+        winreg.HKEY_LOCAL_MACHINE, registry_key, registry_value
+    )
+
+    assert result is not None
+    print("Registry value:", result)
+    assert "Program Files" in result
+
+
+def test_plugin_utilities_win_get_win_registry_rest_pass():
+    """Test getting the Windows Registry REST password."""
+    if not os.name == "nt":
+        pytest.skip("Skipping Windows Registry test on non-Windows system.")
+
+    # only run this test if besapi > v3.8.3:
+    if besapi.besapi.__version__ <= "3.8.3":
+        pytest.skip("Skipping test for besapi <= 3.8.3")
+
+    import winreg
+
+    test_string = "This is just a test string " + str(random.randint(0, 9999))
+    encrypted_str = besapi.plugin_utilities_win.win_dpapi_encrypt_str(test_string)
+
+    # write encrypted string to registry for testing:
+    # HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\BigFix\Enterprise Server\MFSConfig
+    subkey = r"SOFTWARE\Wow6432Node\BigFix\Enterprise Server\MFSConfig"
+
+    key = winreg.CreateKey(winreg.HKEY_LOCAL_MACHINE, subkey)
+    winreg.SetValueEx(key, "RESTPassword", 0, winreg.REG_SZ, "{obf}" + encrypted_str)
+    winreg.CloseKey(key)
+
+    result = besapi.plugin_utilities_win.get_win_registry_rest_pass()
+    assert result is not None
+    print("Windows Registry REST password:", result)
+    assert result == test_string