python4cpm 1.1.2__tar.gz → 1.1.4__tar.gz

{python4cpm-1.1.2/src/python4cpm.egg-info → python4cpm-1.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python4cpm
-Version: 1.1.2
+Version: 1.1.4
 Summary: Python for CPM
 Author-email: Gonzalo Atienza Rela <gonatienza@gmail.com>
 License-Expression: MIT
@@ -19,7 +19,7 @@ This module leverages the [Credential Management .NET SDK](https://docs.cyberark
 
 All objects are collected from the SDK and sent as environment context to be picked up by the `python4cpm` module during the subprocess execution of python. All secrets of such environment are protected and encrypted by [Data Protection API (DPAPI)](https://learn.microsoft.com/en-us/dotnet/standard/security/how-to-use-data-protection), until they are explicitely retrieved in your python script runtime, invoking the `Secret.get()` method.  Finally, python controls the termination signal sent back to the SDK, which is consequently used as the return code to CPM/SRS.  Such as a successful or failed (recoverable or not) result of the requested action.
 
-This platform allows you to duplicate it multiple times, simply changing its settings (with regular day two operations from Privilege Cloud/PVWA) to point to different venvs and/or python scripts.
+This platform allows you to duplicate it multiple times, simply changing its settings (from Privilege Cloud/PVWA) to point to different venvs and/or python scripts.
 
 ## Installation
 
@@ -67,136 +67,85 @@ This platform allows you to duplicate it multiple times, simply changing its set
 from python4cpm import Python4CPMHandler
 
 
-class MyRotator(Python4CPMHandler): # create a subclass for the Handler
+class CredManager(Python4CPMHandler):
     """
-    These are the usable properties and methods from Python4CPMHandler:
-
-        self.args.action
-        # action requested from CPM/SRS
-
-        ## Target Account
-
-        self.target_account.username
-        # address from account
-
-        self.target_account.address
-        # address from account
-
-        self.target_account.port
-        # port from account
-
-        self.target_account.password.get()
-        # get plaintext str from password object
-
-        ## Logon Account
-        self.logon_account.username
-        self.logon_account.password.get()
-
-        ## Reconcile Account
-        self.reconcile_account.username
-        self.reconcile_account.password.get()
-
-        ## Logging
-
-        self.logger.critical("this is critical message")
-        self.logger.error("this is an error message")
-        self.logger.warning("this is a warning message")
-        self.logger.info("this is an info message")
-        self.logger.debug("this is a debug message")
-
-        # The logging level comes from PythonLoggingLevel (platform parameters) (default is error)
-
-    =============================
-    REQUIRED TERMINATION SIGNALS
-    =============================
-    Terminate signals -> MUST use one of the following three signals to terminate the script:
-
-        self.close_success()
-        # terminate and provide CPM/SRS with a success state
-
-        self.close_fail()
-        # terminate and provide CPM/SRS with a failed recoverable state
-        
-        self.close_fail(unrecoverable=True)
-        # terminate and provide CPM/SRS with a failed unrecoverable state
-
-    When calling a signal sys.exit is invoked and the script is terminated.
-    If no signal is called, and the script finishes without any exception,
-    it will behave like p4cpm.close_fail(unrecoverable=True) and log an error message.
-    =============================
-    =============================
+    Properties:
+        target_account (TargetAccount): Account being managed.
+            .policy_id (str): Platform name.
+            .object_name (str): Account name.
+            .username (str): Account username.
+            .address (str): Target address.
+            .port (str): Target port.
+            .password (Secret): Current password. Call .get() to retrieve value.
+            .new_password (Secret): Replacement password. Call .get() to retrieve value.
+
+        logon_account (LogonAccount): Linked Logon Account.
+            .username (str): Account username.
+            .password (Secret): Logon password. Call .get() to retrieve value.
+
+        reconcile_account (ReconcileAccount): Linked Reconcile Account.
+            .username (str): Account username.
+            .password (Secret): Reconcile password. Call .get() to retrieve value.
+
+        logger (logging.Logger): Logger instance.
+
+    Methods:
+        close_success(): Signal successful completion and terminate.
+        close_fail(): Signal failed completion and terminate.
     """
 
-    # =============================
-    # REQUIRED METHODS (MUST DEFINE)
-    # =============================
-    # verify(), logon(), change(), prereconcile(), reconcile()
 
     def verify(self):
-        self._verify()
-        self.log_info("verification successful")
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
     def logon(self):
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
     def change(self):
-        self._change()
-        self.log_error("something went wrong")
-        self.close_fail()
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
+        self.close_success()
 
     def prereconcile(self):
-        self._verify(from_reconcile=True)
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
     def reconcile(self):
-        self._change(from_reconcile=True)
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
-    def _verify(self, from_reconcile=False):
-        if from_reconcile is False:
-            pass
-            # TODO: use account objects for your logic
-        else:
-            pass
-            # TODO: use account objects for your logic
-        result = True
-        if result is True:
-            self.log_info("verification successful")
-        else:
-            self.log_error("something went wrong")
-            self.close_fail()
-
-    def _change(self, from_reconcile=False):
-        if from_reconcile is False:
-            pass
-            # TODO: use account objects for your logic
-        else:
-            pass
-            # TODO: use account objects for your logic
-        result = True
-        if result is True:
-            self.log_info("rotation successful")
-        else:
-            self.log_error("something went wrong")
-            self.close_fail()
-
 
 if __name__ == "__main__":
-    MyRotator().run() # initializes the class and calls the action that was requested from CPM/SRS.
+    CredManager().run() # initializes the class and calls the action that was requested from CPM/SRS.
 ```
 (*) More realistic examples can be found [here](https://github.com/gonatienza/python4cpm/blob/main/examples).
 
 When doing `verify`, `change` or `reconcile` from Privilege Cloud/PVWA:
-1. Verify -> the sciprt will be executed once running the `MyRotator.verify()` method.
-2. Change -> the sciprt will be executed twice, running first the `MyRotator.logon()` method and secondly the `MyRotator.change()` method.
-    - If both actions are not terminated with `self.close_success()` and the scripts terminates without any exception, CPM/SRS will see this as a `self.close_fail(unrecoverable=True)`.
-3. Reconcile -> the sciprt will be executed twice, running first the `MyRotator.prereconcile()` method and secondly the `MyRotator.reconcile()` method.
-    - If both actions are not terminated with `self.close_success()` and the scripts terminates without any exception, CPM/SRS will see this as a `self.close_fail(unrecoverable=True)`.
-4. When calling `MyRotator.verify()`, `MyRotator.logon()` or `MyRotator.prereconcile()`: `self.target_account.new_password.get()` will always return an empty string.
-5. If a logon account is not linked, `self.logon_account.username` and `self.logon_account.password.get()` will return empty strings.
-6. If a reconcile account is not linked, `self.reconcile_account.username` and `self.reconcile_account.password.get()` will return empty strings.
-7. The python `Logger` places its logs in the `Logs/ThirdParty` directory.  The filename will be based on the name of the subclass created (e.g., `MyRotator`).
+1. Verify -> the script will be executed once running the `verify()` method.
+2. Change -> the script will be executed twice: first `logon()`, then `change()`.
+3. Reconcile -> the script will be executed twice: first `prereconcile()`, then `reconcile()`.
+4. When calling `verify()`, `logon()` or `prereconcile()`: `target_account.new_password` will always return `None`.
+5. If a logon account is not linked, `logon_account` will return `None`.
+6. If a reconcile account is not linked, `reconcile_account` will return `None`.
+7. Always use the `close_success` or `close_fail` methods to signal the proper termination for all actions.
+    - If any action is not terminated with a termination method, CPM/SRS will see this as a `close_fail(unrecoverable=True)`, even if no exceptions are raised.
+8. The python `Logger` places its logs in the `Logs/ThirdParty` directory.  The filename will be based on `target_account.policy_id` and `target_account.object_name`.
 
 
 ### Installing dependencies in python venv
@@ -210,7 +159,7 @@ As with any python venv, you can install dependencies in your venv.
 
 ## Dev Helper:
 
-For dev purposes, `NETHelper` is a companion helper to test your scripts before shipping to CPM/SRS.  It simplifies the instantiation of the `Python4CPM` or `Python4CPMHandler` objects by simulating how the plugin creates the environment context for the python module.
+For dev purposes, `NETHelper` is a companion helper to test your scripts without CPM/SRS.  It simplifies the instantiation of the `Python4CPM` or `Python4CPMHandler` objects by simulating how the plugin creates the environment context for the python module.
 
 **Note**: As CPM and the SRS management agent run in Windows, the plugin was built to encrypt secrets using DPAPI (a windows only library).  For dev purposes in Linux/Mac dev workstations, those secrets put in the environment context by `NETHelper` will be in plaintext.  In windows dev workstations, `NETHelper` encrypts the secrets as the .NET plugin does.  This is informational only, **the module will use its encryption/decryption capabilities automatically based on the platform** it is running on and you do not have to do anything specific to enable it.
 
@@ -220,30 +169,24 @@ For dev purposes, `NETHelper` is a companion helper to test your scripts before
 
 ```python
 from python4cpm import NETHelper, Python4CPM, Python4CPMHandler
-from getpass import getpass
-
-# Get secrets for your password, logon account password, reconcile account password and new password
-# You can use an empty string if it does not apply
-target_password = getpass("password: ") # password from account
-logon_password = getpass("logon_password: ") # password from linked logon account
-reconcile_password = getpass("reconcile_password: ") # password from linked reconcile account
-target_new_password = getpass("new_password: ") # new password for the rotation
 
 NETHelper.set(
     action=Python4CPM.ACTION_CHANGE, # use actions from Python4CPM.ACTION_*
-    target_username="jdoe", # -> will fall under MyRotator.target_account.username
-    target_address="myapp.corp.local", # -> will fall under MyRotator.target_account.address
-    target_port="8443", # -> will fall under MyRotator.target_account.port
-    logon_username="ldoe", # -> will fall under MyRotator.logon_account.username
-    reconcile_username="rdoe", # -> will fall under MyRotator.reconcile_account.username
-    logging_level="debug", # "critical", "error", "warning", "info" or "debug"
-    target_password=target_password, # -> will fall under MyRotator.target_account.password.get()
-    logon_password=logon_password, # -> will fall under MyRotator.logon_account.password.get()
-    reconcile_password=reconcile_password, # -> will fall under MyRotator.reconcile_account.password.get()
-    target_new_password=target_new_password # -> will fall under MyRotator.target_account.new_password.get()
+    logging_level="debug",
+    target_policy_id="NETHelper",
+    target_object_name="Objectname",
+    target_username="jdoe",
+    target_address="myapp.corp.local",
+    target_port="8443",
+    logon_username="ldoe",
+    reconcile_username="rdoe",
+    target_password="", # str value of target password 
+    logon_password="", # str value of logon password
+    reconcile_password="", # str value of reconcile password
+    target_new_password="" # str value of new password
 )
 
-class MyRotator(Python4CPMHandler):
+class CredManager(Python4CPMHandler):
     def verify(self):
         # TODO: Add your logic here
         self.close_success()
@@ -264,12 +207,10 @@ class MyRotator(Python4CPMHandler):
         # TODO: Add your logic here
         self.close_success()
 
-MyRotator().run()
+CredManager().run()
 ```
 
 #### Remember for your final script:
 
 - Remove the import of `NETHelper`.
 - Remove the `NETHelper.set()` call.
-- If applicable, change the definition of `p4cpm` from `p4cpm = NETHelper.get()` to `p4cpm = Python4CPM("MyApp")`.
-- Remove any secrets prompting or interactive interruptions.

{python4cpm-1.1.2 → python4cpm-1.1.4}/README.md

@@ -8,7 +8,7 @@ This module leverages the [Credential Management .NET SDK](https://docs.cyberark
 
 All objects are collected from the SDK and sent as environment context to be picked up by the `python4cpm` module during the subprocess execution of python. All secrets of such environment are protected and encrypted by [Data Protection API (DPAPI)](https://learn.microsoft.com/en-us/dotnet/standard/security/how-to-use-data-protection), until they are explicitely retrieved in your python script runtime, invoking the `Secret.get()` method.  Finally, python controls the termination signal sent back to the SDK, which is consequently used as the return code to CPM/SRS.  Such as a successful or failed (recoverable or not) result of the requested action.
 
-This platform allows you to duplicate it multiple times, simply changing its settings (with regular day two operations from Privilege Cloud/PVWA) to point to different venvs and/or python scripts.
+This platform allows you to duplicate it multiple times, simply changing its settings (from Privilege Cloud/PVWA) to point to different venvs and/or python scripts.
 
 ## Installation
 
@@ -56,136 +56,85 @@ This platform allows you to duplicate it multiple times, simply changing its set
 from python4cpm import Python4CPMHandler
 
 
-class MyRotator(Python4CPMHandler): # create a subclass for the Handler
+class CredManager(Python4CPMHandler):
     """
-    These are the usable properties and methods from Python4CPMHandler:
-
-        self.args.action
-        # action requested from CPM/SRS
-
-        ## Target Account
-
-        self.target_account.username
-        # address from account
-
-        self.target_account.address
-        # address from account
-
-        self.target_account.port
-        # port from account
-
-        self.target_account.password.get()
-        # get plaintext str from password object
-
-        ## Logon Account
-        self.logon_account.username
-        self.logon_account.password.get()
-
-        ## Reconcile Account
-        self.reconcile_account.username
-        self.reconcile_account.password.get()
-
-        ## Logging
-
-        self.logger.critical("this is critical message")
-        self.logger.error("this is an error message")
-        self.logger.warning("this is a warning message")
-        self.logger.info("this is an info message")
-        self.logger.debug("this is a debug message")
-
-        # The logging level comes from PythonLoggingLevel (platform parameters) (default is error)
-
-    =============================
-    REQUIRED TERMINATION SIGNALS
-    =============================
-    Terminate signals -> MUST use one of the following three signals to terminate the script:
-
-        self.close_success()
-        # terminate and provide CPM/SRS with a success state
-
-        self.close_fail()
-        # terminate and provide CPM/SRS with a failed recoverable state
-        
-        self.close_fail(unrecoverable=True)
-        # terminate and provide CPM/SRS with a failed unrecoverable state
-
-    When calling a signal sys.exit is invoked and the script is terminated.
-    If no signal is called, and the script finishes without any exception,
-    it will behave like p4cpm.close_fail(unrecoverable=True) and log an error message.
-    =============================
-    =============================
+    Properties:
+        target_account (TargetAccount): Account being managed.
+            .policy_id (str): Platform name.
+            .object_name (str): Account name.
+            .username (str): Account username.
+            .address (str): Target address.
+            .port (str): Target port.
+            .password (Secret): Current password. Call .get() to retrieve value.
+            .new_password (Secret): Replacement password. Call .get() to retrieve value.
+
+        logon_account (LogonAccount): Linked Logon Account.
+            .username (str): Account username.
+            .password (Secret): Logon password. Call .get() to retrieve value.
+
+        reconcile_account (ReconcileAccount): Linked Reconcile Account.
+            .username (str): Account username.
+            .password (Secret): Reconcile password. Call .get() to retrieve value.
+
+        logger (logging.Logger): Logger instance.
+
+    Methods:
+        close_success(): Signal successful completion and terminate.
+        close_fail(): Signal failed completion and terminate.
     """
 
-    # =============================
-    # REQUIRED METHODS (MUST DEFINE)
-    # =============================
-    # verify(), logon(), change(), prereconcile(), reconcile()
 
     def verify(self):
-        self._verify()
-        self.log_info("verification successful")
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
     def logon(self):
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
     def change(self):
-        self._change()
-        self.log_error("something went wrong")
-        self.close_fail()
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
+        self.close_success()
 
     def prereconcile(self):
-        self._verify(from_reconcile=True)
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
     def reconcile(self):
-        self._change(from_reconcile=True)
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
-    def _verify(self, from_reconcile=False):
-        if from_reconcile is False:
-            pass
-            # TODO: use account objects for your logic
-        else:
-            pass
-            # TODO: use account objects for your logic
-        result = True
-        if result is True:
-            self.log_info("verification successful")
-        else:
-            self.log_error("something went wrong")
-            self.close_fail()
-
-    def _change(self, from_reconcile=False):
-        if from_reconcile is False:
-            pass
-            # TODO: use account objects for your logic
-        else:
-            pass
-            # TODO: use account objects for your logic
-        result = True
-        if result is True:
-            self.log_info("rotation successful")
-        else:
-            self.log_error("something went wrong")
-            self.close_fail()
-
 
 if __name__ == "__main__":
-    MyRotator().run() # initializes the class and calls the action that was requested from CPM/SRS.
+    CredManager().run() # initializes the class and calls the action that was requested from CPM/SRS.
 ```
 (*) More realistic examples can be found [here](https://github.com/gonatienza/python4cpm/blob/main/examples).
 
 When doing `verify`, `change` or `reconcile` from Privilege Cloud/PVWA:
-1. Verify -> the sciprt will be executed once running the `MyRotator.verify()` method.
-2. Change -> the sciprt will be executed twice, running first the `MyRotator.logon()` method and secondly the `MyRotator.change()` method.
-    - If both actions are not terminated with `self.close_success()` and the scripts terminates without any exception, CPM/SRS will see this as a `self.close_fail(unrecoverable=True)`.
-3. Reconcile -> the sciprt will be executed twice, running first the `MyRotator.prereconcile()` method and secondly the `MyRotator.reconcile()` method.
-    - If both actions are not terminated with `self.close_success()` and the scripts terminates without any exception, CPM/SRS will see this as a `self.close_fail(unrecoverable=True)`.
-4. When calling `MyRotator.verify()`, `MyRotator.logon()` or `MyRotator.prereconcile()`: `self.target_account.new_password.get()` will always return an empty string.
-5. If a logon account is not linked, `self.logon_account.username` and `self.logon_account.password.get()` will return empty strings.
-6. If a reconcile account is not linked, `self.reconcile_account.username` and `self.reconcile_account.password.get()` will return empty strings.
-7. The python `Logger` places its logs in the `Logs/ThirdParty` directory.  The filename will be based on the name of the subclass created (e.g., `MyRotator`).
+1. Verify -> the script will be executed once running the `verify()` method.
+2. Change -> the script will be executed twice: first `logon()`, then `change()`.
+3. Reconcile -> the script will be executed twice: first `prereconcile()`, then `reconcile()`.
+4. When calling `verify()`, `logon()` or `prereconcile()`: `target_account.new_password` will always return `None`.
+5. If a logon account is not linked, `logon_account` will return `None`.
+6. If a reconcile account is not linked, `reconcile_account` will return `None`.
+7. Always use the `close_success` or `close_fail` methods to signal the proper termination for all actions.
+    - If any action is not terminated with a termination method, CPM/SRS will see this as a `close_fail(unrecoverable=True)`, even if no exceptions are raised.
+8. The python `Logger` places its logs in the `Logs/ThirdParty` directory.  The filename will be based on `target_account.policy_id` and `target_account.object_name`.
 
 
 ### Installing dependencies in python venv
@@ -199,7 +148,7 @@ As with any python venv, you can install dependencies in your venv.
 
 ## Dev Helper:
 
-For dev purposes, `NETHelper` is a companion helper to test your scripts before shipping to CPM/SRS.  It simplifies the instantiation of the `Python4CPM` or `Python4CPMHandler` objects by simulating how the plugin creates the environment context for the python module.
+For dev purposes, `NETHelper` is a companion helper to test your scripts without CPM/SRS.  It simplifies the instantiation of the `Python4CPM` or `Python4CPMHandler` objects by simulating how the plugin creates the environment context for the python module.
 
 **Note**: As CPM and the SRS management agent run in Windows, the plugin was built to encrypt secrets using DPAPI (a windows only library).  For dev purposes in Linux/Mac dev workstations, those secrets put in the environment context by `NETHelper` will be in plaintext.  In windows dev workstations, `NETHelper` encrypts the secrets as the .NET plugin does.  This is informational only, **the module will use its encryption/decryption capabilities automatically based on the platform** it is running on and you do not have to do anything specific to enable it.
 
@@ -209,30 +158,24 @@ For dev purposes, `NETHelper` is a companion helper to test your scripts before
 
 ```python
 from python4cpm import NETHelper, Python4CPM, Python4CPMHandler
-from getpass import getpass
-
-# Get secrets for your password, logon account password, reconcile account password and new password
-# You can use an empty string if it does not apply
-target_password = getpass("password: ") # password from account
-logon_password = getpass("logon_password: ") # password from linked logon account
-reconcile_password = getpass("reconcile_password: ") # password from linked reconcile account
-target_new_password = getpass("new_password: ") # new password for the rotation
 
 NETHelper.set(
     action=Python4CPM.ACTION_CHANGE, # use actions from Python4CPM.ACTION_*
-    target_username="jdoe", # -> will fall under MyRotator.target_account.username
-    target_address="myapp.corp.local", # -> will fall under MyRotator.target_account.address
-    target_port="8443", # -> will fall under MyRotator.target_account.port
-    logon_username="ldoe", # -> will fall under MyRotator.logon_account.username
-    reconcile_username="rdoe", # -> will fall under MyRotator.reconcile_account.username
-    logging_level="debug", # "critical", "error", "warning", "info" or "debug"
-    target_password=target_password, # -> will fall under MyRotator.target_account.password.get()
-    logon_password=logon_password, # -> will fall under MyRotator.logon_account.password.get()
-    reconcile_password=reconcile_password, # -> will fall under MyRotator.reconcile_account.password.get()
-    target_new_password=target_new_password # -> will fall under MyRotator.target_account.new_password.get()
+    logging_level="debug",
+    target_policy_id="NETHelper",
+    target_object_name="Objectname",
+    target_username="jdoe",
+    target_address="myapp.corp.local",
+    target_port="8443",
+    logon_username="ldoe",
+    reconcile_username="rdoe",
+    target_password="", # str value of target password 
+    logon_password="", # str value of logon password
+    reconcile_password="", # str value of reconcile password
+    target_new_password="" # str value of new password
 )
 
-class MyRotator(Python4CPMHandler):
+class CredManager(Python4CPMHandler):
     def verify(self):
         # TODO: Add your logic here
         self.close_success()
@@ -253,12 +196,10 @@ class MyRotator(Python4CPMHandler):
         # TODO: Add your logic here
         self.close_success()
 
-MyRotator().run()
+CredManager().run()
 ```
 
 #### Remember for your final script:
 
 - Remove the import of `NETHelper`.
 - Remove the `NETHelper.set()` call.
-- If applicable, change the definition of `p4cpm` from `p4cpm = NETHelper.get()` to `p4cpm = Python4CPM("MyApp")`.
-- Remove any secrets prompting or interactive interruptions.

{python4cpm-1.1.2 → python4cpm-1.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python4cpm"
-version = "1.1.2"
+version = "1.1.4"
 description = "Python for CPM"
 authors = [
   { name = "Gonzalo Atienza Rela", email = "gonatienza@gmail.com" }

python4cpm-1.1.4/src/python4cpm/accounts.py

@@ -0,0 +1,90 @@
+from python4cpm.envhandler import EnvHandler, Props
+from python4cpm.secret import Secret
+
+
+class BaseAccount(EnvHandler):
+    PROPS = Props("username", "password")
+
+    def __init__(
+        self,
+        username: str | None,
+        password: str | None
+    ) -> None:
+        self._username = username
+        self._password = Secret.from_env_var(password)
+
+    @classmethod
+    def get(cls) -> object | None:
+        kwargs = cls.get_kwargs()
+        if all(value is None for value in kwargs.values()):
+            return None
+        return cls(**kwargs)
+
+    @property
+    def username(self) -> str:
+        return self._username
+
+    @property
+    def password(self) -> Secret:
+        return self._password
+
+
+class TargetAccount(BaseAccount):
+    OBJ_PREFIX = "target_"
+    PROPS = Props(
+        "policy_id",
+        "object_name",
+        "username",
+        "password",
+        "address",
+        "port",
+        "new_password"
+    )
+
+    def __init__(
+        self,
+        policy_id: str | None,
+        object_name: str | None,
+        username: str | None,
+        password: str | None,
+        address: str | None,
+        port: str | None,
+        new_password: str | None
+    ) -> None:
+        super().__init__(
+            username,
+            password
+        )
+        self._policy_id = policy_id
+        self._object_name = object_name
+        self._address = address
+        self._port = port
+        self._new_password = Secret.from_env_var(new_password)
+
+    @property
+    def policy_id(self) -> str | None:
+        return self._policy_id
+
+    @property
+    def object_name(self) -> str | None:
+        return self._object_name
+
+    @property
+    def address(self) -> str | None:
+        return self._address
+
+    @property
+    def port(self) -> str | None:
+        return self._port
+
+    @property
+    def new_password(self) -> Secret:
+        return self._new_password
+
+
+class LogonAccount(BaseAccount):
+    OBJ_PREFIX = "logon_"
+
+
+class ReconcileAccount(BaseAccount):
+    OBJ_PREFIX = "reconcile_"

{python4cpm-1.1.2 → python4cpm-1.1.4}/src/python4cpm/args.py

@@ -7,16 +7,16 @@ class Args(EnvHandler):
 
     def __init__(
         self,
-        action: str,
-        logging_level: str
+        action: str | None,
+        logging_level: str | None
     ) -> None:
         self._action = action
         self._logging_level = logging_level
 
     @property
-    def action(self) -> str:
+    def action(self) -> str | None:
         return self._action
 
     @property
-    def logging_level(self) -> str:
+    def logging_level(self) -> str | None:
         return self._logging_level

{python4cpm-1.1.2 → python4cpm-1.1.4}/src/python4cpm/envhandler.py

@@ -20,10 +20,13 @@ class EnvHandler:
         env_key = f"{cls.PREFIX}{cls.OBJ_PREFIX}{key}"
         return env_key.upper()
 
+    @classmethod
+    def get_kwargs(cls) -> dict:
+        return {
+            prop: os.environ.get(cls.get_key(prop))
+            for prop in cls.PROPS
+        }
+
     @classmethod
     def get(cls) -> object:
-        kwargs = {}
-        for prop in cls.PROPS:
-            value = os.environ.get(cls.get_key(prop))
-            kwargs[prop] = value if value is not None else ""
-        return cls(**kwargs)
+        return cls(**cls.get_kwargs())

{python4cpm-1.1.2 → python4cpm-1.1.4}/src/python4cpm/logger.py

@@ -12,22 +12,23 @@ class Logger:
         "info": logging.INFO,
         "debug": logging.DEBUG
     }
-    _DEFAULT_LEVEL = _LOGGING_LEVELS["error"]
+    _DEFAULT_LEVEL = "error"
 
     @classmethod
     def get_logger(
         cls,
         name: str,
-        logging_level: str
+        logging_level: str | None
     ) -> logging.Logger:
         os.makedirs(cls._LOGS_DIR, exist_ok=True)
-        logs_file = os.path.join(cls._LOGS_DIR, f"{__name__}-{name}.log")
-        _id = os.urandom(4).hex()
-        logger = logging.getLogger(_id)
-        if logging_level.lower() in cls._LOGGING_LEVELS:
-            logger.setLevel(cls._LOGGING_LEVELS[logging_level.lower()])
-        else:
-            logger.setLevel(cls._DEFAULT_LEVEL)
+        uid = os.urandom(4).hex()
+        logger = logging.getLogger(uid)
+        _logging_level = logging_level.lower()
+        if _logging_level not in cls._LOGGING_LEVELS:
+            _logging_level = cls._DEFAULT_LEVEL
+        logger.setLevel(cls._LOGGING_LEVELS[_logging_level])
+        file_name = f"{__name__}_{_logging_level}_{name}.log"
+        logs_file = os.path.join(cls._LOGS_DIR, file_name)
         handler = RotatingFileHandler(
             filename=logs_file,
             maxBytes=1024 ** 2,

{python4cpm-1.1.2 → python4cpm-1.1.4}/src/python4cpm/nethelper.py

@@ -9,17 +9,19 @@ class NETHelper:
     @classmethod
     def set(
         cls,
-        action: str = "",
-        logging_level: str = "",
-        target_username: str = "",
-        target_address: str = "",
-        target_port: str = "",
-        logon_username: str = "",
-        reconcile_username: str = "",
-        target_password: str = "",
-        logon_password: str = "",
-        reconcile_password: str = "",
-        target_new_password: str = ""
+        action: str | None = None,
+        logging_level: str | None = None,
+        target_policy_id: str | None = None,
+        target_object_name: str | None = None,
+        target_username: str | None = None,
+        target_address: str | None = None,
+        target_port: str | None = None,
+        logon_username: str | None = None,
+        reconcile_username: str | None = None,
+        target_password: str | None = None,
+        logon_password: str | None = None,
+        reconcile_password: str | None = None,
+        target_new_password: str | None = None
     ) -> None:
         if Crypto.ENABLED:
             target_password = Crypto.encrypt(target_password)
@@ -29,6 +31,8 @@ class NETHelper:
         keys = (
             Args.get_key(Args.PROPS.action),
             Args.get_key(Args.PROPS.logging_level),
+            TargetAccount.get_key(TargetAccount.PROPS.policy_id),
+            TargetAccount.get_key(TargetAccount.PROPS.object_name),
             TargetAccount.get_key(TargetAccount.PROPS.username),
             TargetAccount.get_key(TargetAccount.PROPS.address),
             TargetAccount.get_key(TargetAccount.PROPS.port),
@@ -42,6 +46,8 @@ class NETHelper:
         values = (
             action,
             logging_level,
+            target_policy_id,
+            target_object_name,
             target_username,
             target_address,
             target_port,
@@ -53,8 +59,9 @@ class NETHelper:
             target_new_password
         )
         for i, key in enumerate(keys):
-            os.environ.update({key: values[i]})
+            if values[i] is not None:
+                os.environ.update({key: values[i]})
 
     @classmethod
     def get(cls) -> Python4CPM:
-        return Python4CPM(cls.__name__)
+        return Python4CPM()

{python4cpm-1.1.2 → python4cpm-1.1.4}/src/python4cpm/python4cpm.py

@@ -3,7 +3,6 @@ import atexit
 import logging
 from python4cpm.secret import Secret
 from python4cpm.args import Args
-from python4cpm.crypto import Crypto
 from python4cpm.logger import Logger
 from python4cpm.accounts import TargetAccount, LogonAccount, ReconcileAccount
 
@@ -25,13 +24,15 @@ class Python4CPM:
     _FAILED_RECOVERABLE_CODE = 81
     _FAILED_UNRECOVERABLE_CODE = 89
 
-    def __init__(self, name: str) -> None:
-        self._name = name
+    def __init__(self) -> None:
         self._args = Args.get()
         self._target_account = TargetAccount.get()
         self._logon_account = LogonAccount.get()
         self._reconcile_account = ReconcileAccount.get()
-        self._logger = Logger.get_logger(self._name, self._args.logging_level)
+        self._logger = Logger.get_logger(
+            f"{self._target_account.policy_id}-{self._target_account.object_name}",
+            self._args.logging_level
+        )
         self._logger.debug("Initiating...")
         self._log_obj(self._args)
         self._verify_action()
@@ -65,20 +66,18 @@ class Python4CPM:
         if self._args.action not in self._VALID_ACTIONS:
             self._logger.warning(f"Unkonwn action -> '{self._args.action}'")
 
-    def _log_obj(self, obj: object) -> None:
-        for key, value in vars(obj).items():
-            _key = f"{obj.__class__.__name__}.{key.strip('_')}"
-            if value:
-                if not isinstance(value, Secret):
-                    logging_value = f"'{value}'"
-                else:
-                    if Crypto.ENABLED is True:
-                        logging_value = "[ENCRYPTED]"
+    def _log_obj(self, obj: object | None) -> None:
+        if obj is not None:
+            for key, value in vars(obj).items():
+                _key = f"{obj.__class__.__name__}.{key.removeprefix('_')}"
+                if value is not None:
+                    if not isinstance(value, Secret):
+                        logging_value = f"'{value}'"
                     else:
-                        logging_value = "[SET]"
-            else:
-                logging_value = "[NOT SET]"
-            self._logger.debug(f"{_key} -> {logging_value}")
+                        logging_value = str(value)
+                else:
+                    logging_value = "[NOT SET]"
+                self._logger.debug(f"{_key} -> {logging_value}")
 
     def close_fail(self, unrecoverable: bool = False) -> None:
         if unrecoverable is False:

{python4cpm-1.1.2 → python4cpm-1.1.4}/src/python4cpm/python4cpmhandler.py

@@ -3,9 +3,6 @@ from python4cpm.python4cpm import Python4CPM
 
 
 class Python4CPMHandler(ABC, Python4CPM):
-    def __init__(self) -> None:
-        super().__init__(self.__class__.__name__)
-
     def run(self) -> None:
         actions = {
             self.ACTION_VERIFY: self.verify,
@@ -18,7 +15,7 @@ class Python4CPMHandler(ABC, Python4CPM):
         if action is not None:
             action()
         else:
-            raise ValueError(f"Unknown action: {self._args.action}")
+            raise ValueError(f"Unknown action: '{self._args.action}'")
 
     @abstractmethod
     def verify(self) -> None:

python4cpm-1.1.4/src/python4cpm/secret.py

@@ -0,0 +1,24 @@
+from python4cpm.crypto import Crypto
+
+
+class Secret:
+    def __init__(self, secret: str) -> None:
+        self._secret = secret
+
+    @classmethod
+    def from_env_var(cls, secret: str | None) -> object | None:
+        if secret is not None:
+            return cls(secret)
+        return None
+
+    def __str__(self) -> str:
+        if Crypto.ENABLED:
+            return "[ENCRYPTED]"
+        else:
+            return "[SET]"
+
+    def get(self) -> str:
+        if Crypto.ENABLED:
+            return Crypto.decrypt(self._secret)
+        else:
+            return self._secret

{python4cpm-1.1.2 → python4cpm-1.1.4/src/python4cpm.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python4cpm
-Version: 1.1.2
+Version: 1.1.4
 Summary: Python for CPM
 Author-email: Gonzalo Atienza Rela <gonatienza@gmail.com>
 License-Expression: MIT
@@ -19,7 +19,7 @@ This module leverages the [Credential Management .NET SDK](https://docs.cyberark
 
 All objects are collected from the SDK and sent as environment context to be picked up by the `python4cpm` module during the subprocess execution of python. All secrets of such environment are protected and encrypted by [Data Protection API (DPAPI)](https://learn.microsoft.com/en-us/dotnet/standard/security/how-to-use-data-protection), until they are explicitely retrieved in your python script runtime, invoking the `Secret.get()` method.  Finally, python controls the termination signal sent back to the SDK, which is consequently used as the return code to CPM/SRS.  Such as a successful or failed (recoverable or not) result of the requested action.
 
-This platform allows you to duplicate it multiple times, simply changing its settings (with regular day two operations from Privilege Cloud/PVWA) to point to different venvs and/or python scripts.
+This platform allows you to duplicate it multiple times, simply changing its settings (from Privilege Cloud/PVWA) to point to different venvs and/or python scripts.
 
 ## Installation
 
@@ -67,136 +67,85 @@ This platform allows you to duplicate it multiple times, simply changing its set
 from python4cpm import Python4CPMHandler
 
 
-class MyRotator(Python4CPMHandler): # create a subclass for the Handler
+class CredManager(Python4CPMHandler):
     """
-    These are the usable properties and methods from Python4CPMHandler:
-
-        self.args.action
-        # action requested from CPM/SRS
-
-        ## Target Account
-
-        self.target_account.username
-        # address from account
-
-        self.target_account.address
-        # address from account
-
-        self.target_account.port
-        # port from account
-
-        self.target_account.password.get()
-        # get plaintext str from password object
-
-        ## Logon Account
-        self.logon_account.username
-        self.logon_account.password.get()
-
-        ## Reconcile Account
-        self.reconcile_account.username
-        self.reconcile_account.password.get()
-
-        ## Logging
-
-        self.logger.critical("this is critical message")
-        self.logger.error("this is an error message")
-        self.logger.warning("this is a warning message")
-        self.logger.info("this is an info message")
-        self.logger.debug("this is a debug message")
-
-        # The logging level comes from PythonLoggingLevel (platform parameters) (default is error)
-
-    =============================
-    REQUIRED TERMINATION SIGNALS
-    =============================
-    Terminate signals -> MUST use one of the following three signals to terminate the script:
-
-        self.close_success()
-        # terminate and provide CPM/SRS with a success state
-
-        self.close_fail()
-        # terminate and provide CPM/SRS with a failed recoverable state
-        
-        self.close_fail(unrecoverable=True)
-        # terminate and provide CPM/SRS with a failed unrecoverable state
-
-    When calling a signal sys.exit is invoked and the script is terminated.
-    If no signal is called, and the script finishes without any exception,
-    it will behave like p4cpm.close_fail(unrecoverable=True) and log an error message.
-    =============================
-    =============================
+    Properties:
+        target_account (TargetAccount): Account being managed.
+            .policy_id (str): Platform name.
+            .object_name (str): Account name.
+            .username (str): Account username.
+            .address (str): Target address.
+            .port (str): Target port.
+            .password (Secret): Current password. Call .get() to retrieve value.
+            .new_password (Secret): Replacement password. Call .get() to retrieve value.
+
+        logon_account (LogonAccount): Linked Logon Account.
+            .username (str): Account username.
+            .password (Secret): Logon password. Call .get() to retrieve value.
+
+        reconcile_account (ReconcileAccount): Linked Reconcile Account.
+            .username (str): Account username.
+            .password (Secret): Reconcile password. Call .get() to retrieve value.
+
+        logger (logging.Logger): Logger instance.
+
+    Methods:
+        close_success(): Signal successful completion and terminate.
+        close_fail(): Signal failed completion and terminate.
     """
 
-    # =============================
-    # REQUIRED METHODS (MUST DEFINE)
-    # =============================
-    # verify(), logon(), change(), prereconcile(), reconcile()
 
     def verify(self):
-        self._verify()
-        self.log_info("verification successful")
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
     def logon(self):
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
     def change(self):
-        self._change()
-        self.log_error("something went wrong")
-        self.close_fail()
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
+        self.close_success()
 
     def prereconcile(self):
-        self._verify(from_reconcile=True)
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
     def reconcile(self):
-        self._change(from_reconcile=True)
+        """
+        REQUIRED METHOD
+        """
+        # TODO: use account objects for your logic
         self.close_success()
 
-    def _verify(self, from_reconcile=False):
-        if from_reconcile is False:
-            pass
-            # TODO: use account objects for your logic
-        else:
-            pass
-            # TODO: use account objects for your logic
-        result = True
-        if result is True:
-            self.log_info("verification successful")
-        else:
-            self.log_error("something went wrong")
-            self.close_fail()
-
-    def _change(self, from_reconcile=False):
-        if from_reconcile is False:
-            pass
-            # TODO: use account objects for your logic
-        else:
-            pass
-            # TODO: use account objects for your logic
-        result = True
-        if result is True:
-            self.log_info("rotation successful")
-        else:
-            self.log_error("something went wrong")
-            self.close_fail()
-
 
 if __name__ == "__main__":
-    MyRotator().run() # initializes the class and calls the action that was requested from CPM/SRS.
+    CredManager().run() # initializes the class and calls the action that was requested from CPM/SRS.
 ```
 (*) More realistic examples can be found [here](https://github.com/gonatienza/python4cpm/blob/main/examples).
 
 When doing `verify`, `change` or `reconcile` from Privilege Cloud/PVWA:
-1. Verify -> the sciprt will be executed once running the `MyRotator.verify()` method.
-2. Change -> the sciprt will be executed twice, running first the `MyRotator.logon()` method and secondly the `MyRotator.change()` method.
-    - If both actions are not terminated with `self.close_success()` and the scripts terminates without any exception, CPM/SRS will see this as a `self.close_fail(unrecoverable=True)`.
-3. Reconcile -> the sciprt will be executed twice, running first the `MyRotator.prereconcile()` method and secondly the `MyRotator.reconcile()` method.
-    - If both actions are not terminated with `self.close_success()` and the scripts terminates without any exception, CPM/SRS will see this as a `self.close_fail(unrecoverable=True)`.
-4. When calling `MyRotator.verify()`, `MyRotator.logon()` or `MyRotator.prereconcile()`: `self.target_account.new_password.get()` will always return an empty string.
-5. If a logon account is not linked, `self.logon_account.username` and `self.logon_account.password.get()` will return empty strings.
-6. If a reconcile account is not linked, `self.reconcile_account.username` and `self.reconcile_account.password.get()` will return empty strings.
-7. The python `Logger` places its logs in the `Logs/ThirdParty` directory.  The filename will be based on the name of the subclass created (e.g., `MyRotator`).
+1. Verify -> the script will be executed once running the `verify()` method.
+2. Change -> the script will be executed twice: first `logon()`, then `change()`.
+3. Reconcile -> the script will be executed twice: first `prereconcile()`, then `reconcile()`.
+4. When calling `verify()`, `logon()` or `prereconcile()`: `target_account.new_password` will always return `None`.
+5. If a logon account is not linked, `logon_account` will return `None`.
+6. If a reconcile account is not linked, `reconcile_account` will return `None`.
+7. Always use the `close_success` or `close_fail` methods to signal the proper termination for all actions.
+    - If any action is not terminated with a termination method, CPM/SRS will see this as a `close_fail(unrecoverable=True)`, even if no exceptions are raised.
+8. The python `Logger` places its logs in the `Logs/ThirdParty` directory.  The filename will be based on `target_account.policy_id` and `target_account.object_name`.
 
 
 ### Installing dependencies in python venv
@@ -210,7 +159,7 @@ As with any python venv, you can install dependencies in your venv.
 
 ## Dev Helper:
 
-For dev purposes, `NETHelper` is a companion helper to test your scripts before shipping to CPM/SRS.  It simplifies the instantiation of the `Python4CPM` or `Python4CPMHandler` objects by simulating how the plugin creates the environment context for the python module.
+For dev purposes, `NETHelper` is a companion helper to test your scripts without CPM/SRS.  It simplifies the instantiation of the `Python4CPM` or `Python4CPMHandler` objects by simulating how the plugin creates the environment context for the python module.
 
 **Note**: As CPM and the SRS management agent run in Windows, the plugin was built to encrypt secrets using DPAPI (a windows only library).  For dev purposes in Linux/Mac dev workstations, those secrets put in the environment context by `NETHelper` will be in plaintext.  In windows dev workstations, `NETHelper` encrypts the secrets as the .NET plugin does.  This is informational only, **the module will use its encryption/decryption capabilities automatically based on the platform** it is running on and you do not have to do anything specific to enable it.
 
@@ -220,30 +169,24 @@ For dev purposes, `NETHelper` is a companion helper to test your scripts before
 
 ```python
 from python4cpm import NETHelper, Python4CPM, Python4CPMHandler
-from getpass import getpass
-
-# Get secrets for your password, logon account password, reconcile account password and new password
-# You can use an empty string if it does not apply
-target_password = getpass("password: ") # password from account
-logon_password = getpass("logon_password: ") # password from linked logon account
-reconcile_password = getpass("reconcile_password: ") # password from linked reconcile account
-target_new_password = getpass("new_password: ") # new password for the rotation
 
 NETHelper.set(
     action=Python4CPM.ACTION_CHANGE, # use actions from Python4CPM.ACTION_*
-    target_username="jdoe", # -> will fall under MyRotator.target_account.username
-    target_address="myapp.corp.local", # -> will fall under MyRotator.target_account.address
-    target_port="8443", # -> will fall under MyRotator.target_account.port
-    logon_username="ldoe", # -> will fall under MyRotator.logon_account.username
-    reconcile_username="rdoe", # -> will fall under MyRotator.reconcile_account.username
-    logging_level="debug", # "critical", "error", "warning", "info" or "debug"
-    target_password=target_password, # -> will fall under MyRotator.target_account.password.get()
-    logon_password=logon_password, # -> will fall under MyRotator.logon_account.password.get()
-    reconcile_password=reconcile_password, # -> will fall under MyRotator.reconcile_account.password.get()
-    target_new_password=target_new_password # -> will fall under MyRotator.target_account.new_password.get()
+    logging_level="debug",
+    target_policy_id="NETHelper",
+    target_object_name="Objectname",
+    target_username="jdoe",
+    target_address="myapp.corp.local",
+    target_port="8443",
+    logon_username="ldoe",
+    reconcile_username="rdoe",
+    target_password="", # str value of target password 
+    logon_password="", # str value of logon password
+    reconcile_password="", # str value of reconcile password
+    target_new_password="" # str value of new password
 )
 
-class MyRotator(Python4CPMHandler):
+class CredManager(Python4CPMHandler):
     def verify(self):
         # TODO: Add your logic here
         self.close_success()
@@ -264,12 +207,10 @@ class MyRotator(Python4CPMHandler):
         # TODO: Add your logic here
         self.close_success()
 
-MyRotator().run()
+CredManager().run()
 ```
 
 #### Remember for your final script:
 
 - Remove the import of `NETHelper`.
 - Remove the `NETHelper.set()` call.
-- If applicable, change the definition of `p4cpm` from `p4cpm = NETHelper.get()` to `p4cpm = Python4CPM("MyApp")`.
-- Remove any secrets prompting or interactive interruptions.

python4cpm-1.1.2/src/python4cpm/accounts.py

@@ -1,63 +0,0 @@
-from python4cpm.envhandler import EnvHandler, Props
-from python4cpm.secret import Secret
-
-
-class BaseAccount(EnvHandler):
-    PROPS = Props("username", "password")
-
-    def __init__(
-        self,
-        username: str,
-        password: str
-    ) -> None:
-        self._username = username
-        self._password = Secret(password)
-
-    @property
-    def username(self) -> str:
-        return self._username
-
-    @property
-    def password(self) -> Secret:
-        return self._password
-
-
-class TargetAccount(BaseAccount):
-    OBJ_PREFIX = "target_"
-    PROPS = Props("username", "password", "address", "port", "new_password")
-
-    def __init__(
-        self,
-        username: str,
-        password: str,
-        address: str,
-        port: str,
-        new_password: str
-    ) -> None:
-        super().__init__(
-            username,
-            password
-        )
-        self._address = address
-        self._port = port
-        self._new_password = Secret(new_password)
-
-    @property
-    def address(self) -> str:
-        return self._address
-
-    @property
-    def port(self) -> str:
-        return self._port
-
-    @property
-    def new_password(self) -> Secret:
-        return self._new_password
-
-
-class LogonAccount(BaseAccount):
-    OBJ_PREFIX = "logon_"
-
-
-class ReconcileAccount(BaseAccount):
-    OBJ_PREFIX = "reconcile_"

python4cpm-1.1.2/src/python4cpm/secret.py

@@ -1,15 +0,0 @@
-from python4cpm.crypto import Crypto
-
-
-class Secret:
-    def __init__(self, secret: str) -> None:
-        self._secret = secret
-
-    def __bool__(self) -> bool:
-        return bool(self._secret)
-
-    def get(self) -> str:
-        if Crypto.ENABLED and self._secret:
-            return Crypto.decrypt(self._secret)
-        else:
-            return self._secret