python4cpm 1.1.3__tar.gz → 1.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python4cpm
-Version: 1.1.3
+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,105 +67,85 @@ This platform allows you to duplicate it multiple times, simply changing its set
 from python4cpm import Python4CPMHandler
 
 
-class MyRotator(Python4CPMHandler):
+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.
-
-    =============================
-    REQUIRED METHODS
-    =============================
-    verify(), logon(), change(), prereconcile(), reconcile()
+    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.
     """
 
+
     def verify(self):
+        """
+        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):
+        """
+        REQUIRED METHOD
+        """
         # TODO: use account objects for your logic
         self.close_success()
 
     def prereconcile(self):
+        """
+        REQUIRED METHOD
+        """
         # TODO: use account objects for your logic
         self.close_success()
 
     def reconcile(self):
+        """
+        REQUIRED METHOD
+        """
         # TODO: use account objects for your logic
         self.close_success()
 
 
 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` will always return `None`.
-5. If a logon account is not linked, `self.logon_account` will return `None`.
-6. If a reconcile account is not linked, `self.reconcile_account` will return `None`.
-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
@@ -189,30 +169,24 @@ For dev purposes, `NETHelper` is a companion helper to test your scripts without
 
 ```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 may set to None any argument that does not apply or simply leaving it to its default None value.
-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()
@@ -233,11 +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.
-- Remove any secrets prompting or interactive interruptions.

{python4cpm-1.1.3 → 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,105 +56,85 @@ This platform allows you to duplicate it multiple times, simply changing its set
 from python4cpm import Python4CPMHandler
 
 
-class MyRotator(Python4CPMHandler):
+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.
-
-    =============================
-    REQUIRED METHODS
-    =============================
-    verify(), logon(), change(), prereconcile(), reconcile()
+    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.
     """
 
+
     def verify(self):
+        """
+        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):
+        """
+        REQUIRED METHOD
+        """
         # TODO: use account objects for your logic
         self.close_success()
 
     def prereconcile(self):
+        """
+        REQUIRED METHOD
+        """
         # TODO: use account objects for your logic
         self.close_success()
 
     def reconcile(self):
+        """
+        REQUIRED METHOD
+        """
         # TODO: use account objects for your logic
         self.close_success()
 
 
 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` will always return `None`.
-5. If a logon account is not linked, `self.logon_account` will return `None`.
-6. If a reconcile account is not linked, `self.reconcile_account` will return `None`.
-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
@@ -178,30 +158,24 @@ For dev purposes, `NETHelper` is a companion helper to test your scripts without
 
 ```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 may set to None any argument that does not apply or simply leaving it to its default None value.
-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()
@@ -222,11 +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.
-- Remove any secrets prompting or interactive interruptions.

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

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

{python4cpm-1.1.3 → python4cpm-1.1.4}/src/python4cpm/accounts.py

@@ -31,10 +31,20 @@ class BaseAccount(EnvHandler):
 
 class TargetAccount(BaseAccount):
     OBJ_PREFIX = "target_"
-    PROPS = Props("username", "password", "address", "port", "new_password")
+    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,
@@ -45,10 +55,20 @@ class TargetAccount(BaseAccount):
             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

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

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

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

@@ -12,7 +12,7 @@ class Logger:
         "info": logging.INFO,
         "debug": logging.DEBUG
     }
-    _DEFAULT_LEVEL = _LOGGING_LEVELS["error"]
+    _DEFAULT_LEVEL = "error"
 
     @classmethod
     def get_logger(
@@ -21,14 +21,14 @@ class Logger:
         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)
-        is_logging_level_str = isinstance(logging_level, str)
-        if is_logging_level_str and 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.3 → python4cpm-1.1.4}/src/python4cpm/nethelper.py

@@ -11,6 +11,8 @@ class NETHelper:
         cls,
         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,
@@ -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,
@@ -58,4 +64,4 @@ class NETHelper:
 
     @classmethod
     def get(cls) -> Python4CPM:
-        return Python4CPM(cls.__name__)
+        return Python4CPM()

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

@@ -24,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()

{python4cpm-1.1.3 → 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,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python4cpm
-Version: 1.1.3
+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,105 +67,85 @@ This platform allows you to duplicate it multiple times, simply changing its set
 from python4cpm import Python4CPMHandler
 
 
-class MyRotator(Python4CPMHandler):
+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.
-
-    =============================
-    REQUIRED METHODS
-    =============================
-    verify(), logon(), change(), prereconcile(), reconcile()
+    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.
     """
 
+
     def verify(self):
+        """
+        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):
+        """
+        REQUIRED METHOD
+        """
         # TODO: use account objects for your logic
         self.close_success()
 
     def prereconcile(self):
+        """
+        REQUIRED METHOD
+        """
         # TODO: use account objects for your logic
         self.close_success()
 
     def reconcile(self):
+        """
+        REQUIRED METHOD
+        """
         # TODO: use account objects for your logic
         self.close_success()
 
 
 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` will always return `None`.
-5. If a logon account is not linked, `self.logon_account` will return `None`.
-6. If a reconcile account is not linked, `self.reconcile_account` will return `None`.
-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
@@ -189,30 +169,24 @@ For dev purposes, `NETHelper` is a companion helper to test your scripts without
 
 ```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 may set to None any argument that does not apply or simply leaving it to its default None value.
-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()
@@ -233,11 +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.
-- Remove any secrets prompting or interactive interruptions.