besapi 3.8.3__tar.gz → 3.9.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: besapi
-Version: 3.8.3
+Version: 3.9.1
 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.1}/src/besapi/besapi.py

@@ -25,7 +25,7 @@ import lxml.etree
 import lxml.objectify
 import requests
 
-__version__ = "3.8.3"
+__version__ = "3.9.1"
 
 besapi_logger = logging.getLogger("besapi")
 
@@ -479,6 +479,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.9.1/src/besapi/plugin_utilities_win.py

@@ -0,0 +1,167 @@
+"""
+Plugin utilities for Windows systems, including DPAPI encryption/decryption
+and Windows Registry access.
+"""
+
+import base64
+import logging
+import sys
+from typing import Union
+
+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,
+    )
+
+    return decrypted_bytes.decode("utf-8") if decrypted_bytes else 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.error("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():
+    """
+    Retrieves the base64 encrypted REST Password from the Windows Registry.
+
+    Returns:
+        The REST Password if found, otherwise None.
+    """
+    hive = winreg.HKEY_LOCAL_MACHINE
+    # 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.error("No registry value found for RESTPassword.")
+        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:
+        return win_dpapi_decrypt_base64(reg_value)
+
+    return None

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: besapi
-Version: 3.8.3
+Version: 3.9.1
 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.1}/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.1}/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."""
@@ -259,9 +262,20 @@ def test_bes_conn_json():
         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 bes computers'
+        )
+        print(result)
+        assert result is not None
+        assert "TestString" in result
+        # 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 result
 
 
-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 +296,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