python4cpm 1.0.21__tar.gz → 1.0.22__tar.gz

{python4cpm-1.0.21/src/python4cpm.egg-info → python4cpm-1.0.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python4cpm
-Version: 1.0.21
+Version: 1.0.22
 Summary: Python for CPM
 Author-email: Gonzalo Atienza Rela <gonatienza@gmail.com>
 License: MIT License
@@ -32,7 +32,7 @@ Dynamic: license-file
 
 # Python4CPM
 
-A simple way of using python scripts with CyberArk CPM rotations.  This module levereages the [Credential Management .NET SDK](https://docs.cyberark.com/privilege-cloud-standard/latest/en/content/pasimp/plug-in-netinvoker.htm) from CyberArk to securely offload a password rotation logic into a python script.
+A simple way of using python scripts with CyberArk CPM rotations.  This module leverages the [Credential Management .NET SDK](https://docs.cyberark.com/privilege-cloud-standard/latest/en/content/pasimp/plug-in-netinvoker.htm) from CyberArk to securely offload a password rotation logic into a python script.
 
 This platform allows you to duplicate it multiple times, simply changing its settings from Privilege Cloud/PVWA to point to different python scripts leveraging the module `python4cpm`.
 
@@ -78,7 +78,127 @@ This platform allows you to duplicate it multiple times, simply changing its set
 
 ## Python Script
 
-### Example:
+### Using the handler (recommended):
+
+```python
+from python4cpm import Python4CPMHandler
+
+
+class MyApp(Python4CPMHandler): # create a subclass for the Handler
+    """
+    These are the usable properties and methods from Python4CPMHandler:
+    
+        self.args.action # action requested from CPM/SRS
+        self.args.address # address from the account address field
+        self.args.username # username from the account username field
+        self.args.reconcile_username # reconcile username from the linked reconcile account
+        self.args.logon_username # logon username from the linked logon account
+        self.args.logging # used to carry the platform logging settings for python
+        self.secrets.password.get() # get str from password received from the vault
+        self.secrets.new_password.get() # get str from new password in case of a rotation
+        self.secrets.logon_password.get() # get str from linked logon account password
+        self.secrets.reconcile_password.get() # get str from linked reconcile account password
+
+    Logging methods -> Will only log if PythonLogging (platform parameters) is set to yes (default is yes)
+    
+        self.log_error("this is an error message") # logs error into Logs/ThirdParty/MyApp.log
+        self.log_warning("this is a warning message") # logs warning into Logs/ThirdParty/MyApp.log
+        self.log_info("this is an info message") # logs info into Logs/ThirdParty/MyApp.log
+    
+    Logging level -> Will only log debug messages if PythonLoggingLevel (platform parameters) is set to debug (default is info)
+    
+        self.log_debug("this is an debug message") # logs info into Logs/ThirdParty/MyApp.log if logging level is set to debug
+
+    =============================
+    REQUIRED TERMINATION SIGNALS
+    =============================
+    Terminate signals -> MUST use one of the following three signals to terminate the script:
+
+        self.close_success() # terminate with success state
+        self.close_fail() # terminate with recoverable failed state
+        self.close_fail(unrecoverable=True) # terminate with unrecoverable failed 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 (MUST DEFINE)
+    # =============================
+    # verify(), logon(), change(), prereconcile(), reconcile()
+
+    def verify(self):
+        self._verify()
+        self.log_info("verification successful")
+        self.close_success()
+
+    def logon(self):
+        self.close_success() # terminate with success state if nothing needs to be done with a given action.
+
+    def change(self):
+        self._change()
+        self.log_error("something went wrong")
+        self.close_fail()
+
+    def prereconcile(self):
+        self._verify(from_reconcile=True)
+        self.close_success()
+
+    def reconcile(self):
+        self._change(from_reconcile=True)
+        self.close_success()
+
+    def _verify(self, from_reconcile=False):
+        if from_reconcile is False:
+            pass
+            # TODO: use self.args.address, self.args.username, self.secrets.password.get()
+            # for your logic in a verification
+        else:
+            pass
+            # TODO: use self.args.address, self.args.reconcile_username, self.secrets.reconcile_password.get()
+            # for your logic in a verification
+        result = True
+        if result is True:
+            self.log_info("verification successful") # logs info message into Logs/ThirdParty/MyApp.log
+        else:
+            self.log_error("something went wrong") # logs error message Logs/ThirdParty/MyApp.log
+            self.close_fail()
+
+    def _change(self, from_reconcile=False):
+        if from_reconcile is False:
+            pass
+            # TODO: use self.args.address, self.args.username, self.secrets.password.get()
+            # and self.secrets.new_password.get() for your logic in a rotation
+        else:
+            pass
+            # TODO: use self.args.address, self.args.username, self.args.reconcile_username,
+            # self.secrets.reconcile_password.get() and self.secrets.new_password.get() for your logic in a reconciliation
+        result = True
+        if result is True:
+            self.log_info("rotation successful") # logs info message into Logs/ThirdParty/MyApp.log
+        else:
+            self.log_error("something went wrong") # logs error message Logs/ThirdParty/MyApp.log
+            self.close_fail()
+
+
+if __name__ == "__main__":
+    MyApp().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/python4cpmhandler).
+
+When doing `verify`, `change` or `reconcile` from Privilege Cloud/PVWA:
+1. Verify -> the sciprt will be executed once with the `MyApp.verify()` method.
+2. Change -> the sciprt will be executed twice, once with the action `MyApp.logon()` method and once as `MyApp.change()` method.
+    - If all 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, once with the action `MyApp.prereconcile()` method and once as `MyApp.reconcile()` method.
+    - If all 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 `MyApp.logon()` or `MyApp.prereconcile()`: `self.secrets.new_password.get()` will always return an empty string.
+5. If a logon account is not linked, `self.args.logon_username` and `self.secrets.logon_password.get()` will return an empty string.
+6. If a reconcile account is not linked, `self.args.reconcile_username` and `self.secrets.reconcile_password.get()` will return an empty string.
+
+
+### Using Python4CPM properties and methods directly (for low level controls):
 
 ```python
 from python4cpm import Python4CPM
@@ -87,7 +207,7 @@ from python4cpm import Python4CPM
 p4cpm = Python4CPM("MyApp") # this instantiates the object and grabs all arguments and secrets shared by the .NET SDK
 
 # These are the usable properties and related methods from the object:
-p4cpm.args.action # action requested from CPM
+p4cpm.args.action # action requested from CPM/SRS
 p4cpm.args.address # address from the account address field
 p4cpm.args.username # username from the account username field
 p4cpm.args.reconcile_username # reconcile username from the linked reconcile account
@@ -98,36 +218,35 @@ p4cpm.secrets.new_password.get() # get str from new password in case of a rotati
 p4cpm.secrets.logon_password.get() # get str from linked logon account password
 p4cpm.secrets.reconcile_password.get() # get str from linked reconcile account password
 
-# Logging methods -> Will only log if Automatic Platform Management -> Additional Policy Settings -> Parameters -> PythonLogging is set to yes (default is yes)
-p4cpm.log_error("this is an error message") # logs error into Logs/ThirdParty/Python4CPM/MyApp.log
-p4cpm.log_warning("this is a warning message") # logs warning into Logs/ThirdParty/Python4CPM/MyApp.log
-p4cpm.log_info("this is an info message") # logs info into Logs/ThirdParty/Python4CPM/MyApp.log
-# Logging level -> Will only log debug messages if Automatic Platform Management -> Additional Policy Settings -> Parameters -> PythonLoggingLevel is set to debug (default is info)
-p4cpm.log_debug("this is an debug message") # logs info into Logs/ThirdParty/Python4CPM/MyApp.log if logging level is set to debug
+# Logging methods -> Will only log if PythonLogging (platform parameters) is set to yes (default is yes)
+p4cpm.log_error("this is an error message") # logs error into Logs/ThirdParty/MyApp.log
+p4cpm.log_warning("this is a warning message") # logs warning into Logs/ThirdParty/MyApp.log
+p4cpm.log_info("this is an info message") # logs info into Logs/ThirdParty/MyApp.log
+# Logging level -> Will only log debug messages if PythonLoggingLevel (platform parameters) is set to debug (default is info)
+p4cpm.log_debug("this is an debug message") # logs info into Logs/ThirdParty/MyApp.log if logging level is set to debug
 
 # Terminate signals -> MUST use one of the following three signals to terminate the script:
 ## p4cpm.close_success() # terminate with success state
 ## p4cpm.close_fail() # terminate with recoverable failed state
 ## p4cpm.close_fail(unrecoverable=True) # terminate with unrecoverable failed 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.
+# 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.
 
 
 # Verification example -> verify the username and password are valid
 def verify(from_reconcile=False):
     if from_reconcile is False:
         pass
-        # Use p4cpm.args.address, p4cpm.args.username, p4cpm.secrets.password.get()
+        # TODO: use p4cpm.args.address, p4cpm.args.username, p4cpm.secrets.password.get()
         # for your logic in a verification
     else:
         pass
-        # Use p4cpm.args.address, p4cpm.args.reconcile_username, p4cpm.secrets.reconcile_password.get()
+        # TODO: use p4cpm.args.address, p4cpm.args.reconcile_username, p4cpm.secrets.reconcile_password.get()
         # for your logic in a verification
     result = True
     if result is True:
-        p4cpm.log_info("verification successful") # logs info message into Logs/ThirdParty/Python4CPM/MyApp.log
+        p4cpm.log_info("verification successful")
     else:
-        p4cpm.log_error("something went wrong") # logs error message Logs/ThirdParty/Python4CPM/MyApp.log
+        p4cpm.log_error("something went wrong")
         raise Exception("verify failed") # raise to trigger failed termination signal
 
 
@@ -135,17 +254,17 @@ def verify(from_reconcile=False):
 def change(from_reconcile=False):
     if from_reconcile is False:
         pass
-        # Use p4cpm.args.address, p4cpm.args.username, p4cpm.secrets.password.get()
+        # TODO: use p4cpm.args.address, p4cpm.args.username, p4cpm.secrets.password.get()
         # and p4cpm.secrets.new_password.get() for your logic in a rotation
     else:
         pass
-        # Use p4cpm.args.address, p4cpm.args.username, p4cpm.args.reconcile_username,
+        # TODO: use p4cpm.args.address, p4cpm.args.username, p4cpm.args.reconcile_username,
         # p4cpm.secrets.reconcile_password.get() and p4cpm.secrets.new_password.get() for your logic in a reconciliation
     result = True
     if result is True:
-        p4cpm.log_info("rotation successful") # logs info message into Logs/ThirdParty/Python4CPM/MyApp.log
+        p4cpm.log_info("rotation successful")
     else:
-        p4cpm.log_error("something went wrong") # logs error message Logs/ThirdParty/Python4CPM/MyApp.log
+        p4cpm.log_error("something went wrong")
         raise Exception("change failed") # raise to trigger failed termination signal
 
 
@@ -153,48 +272,44 @@ if __name__ == "__main__":
     try:
         if p4cpm.args.action == Python4CPM.ACTION_VERIFY: # class attribute ACTION_VERIFY holds the verify action value
             verify()
-            p4cpm.close_success() # terminate with success state
+            p4cpm.close_success()
         elif p4cpm.args.action == Python4CPM.ACTION_LOGON: # class attribute ACTION_LOGON holds the logon action value
-            verify()
-            p4cpm.close_success() # terminate with success state
+            p4cpm.close_success() # terminate with success state if nothing needs to be done with a given action.
         elif p4cpm.args.action == Python4CPM.ACTION_CHANGE: # class attribute ACTION_CHANGE holds the password change action value
             change()
-            p4cpm.close_success() # terminate with success state
+            p4cpm.close_success()
         elif p4cpm.args.action == Python4CPM.ACTION_PRERECONCILE: # class attribute ACTION_PRERECONCILE holds the pre-reconcile action value
             verify(from_reconcile=True)
-            p4cpm.close_success() # terminate with success state
+            p4cpm.close_success()
             # Alternatively ->
             ## p4cpm.log_error("reconciliation is not supported") # let the logs know that reconciliation is not supported
-            ## p4cpm.close_fail() # let CPM know to check the logs
+            ## p4cpm.close_fail() # let CPM/SRS know to check the logs
         elif p4cpm.args.action == Python4CPM.ACTION_RECONCILE: # class attribute ACTION_RECONCILE holds the reconcile action value
             change(from_reconcile=True)
-            p4cpm.close_success() # terminate with success state
+            p4cpm.close_success()
             # Alternatively ->
             ## p4cpm.log_error("reconciliation is not supported") # let the logs know that reconciliation is not supported
-            ## p4cpm.close_fail() # let CPM know to check the logs
-        else:
-            p4cpm.log_error(f"invalid action: '{p4cpm.args.action}'") # logs into Logs/ThirdParty/Python4CPM/MyApp.log
-            p4cpm.close_fail(unrecoverable=True) # terminate with unrecoverable failed state
+            ## p4cpm.close_fail() # let CPM/SRS know to check the logs
     except Exception as e:
         p4cpm.log_error(f"{type(e).__name__}: {e}")
-        p4cpm.close_fail()
+        raise e # CPM/SRS will see any Exception as a p4cpm.close_fail(unrecoverable=True)
 ```
-(*) More realistic examples can be found [here](https://github.com/gonatienza/python4cpm/blob/main/examples).
+(*) More realistic examples can be found [here](https://github.com/gonatienza/python4cpm/blob/main/examples/python4cpm).
 
 When doing `verify`, `change` or `reconcile` from Privilege Cloud/PVWA:
 1. Verify -> the sciprt will be executed once with the `p4cpm.args.action` as `Python4CPM.ACTION_VERIFY`.
 2. Change -> the sciprt will be executed twice, once with the action `p4cpm.args.action` as `Python4CPM.ACTION_LOGON` and once as `Python4CPM.ACTION_CHANGE`.
-    - If all actions are not terminated with `p4cpm.close_success()` and the scripts terminates without any exception, it defaults to a successful return.
+    - If all actions are not terminated with `p4cpm.close_success()` and the scripts terminates without any exception, CPM/SRS will see this as a `p4cpm.close_fail(unrecoverable=True)`.
 3. Reconcile -> the sciprt will be executed twice, once with the `p4cpm.args.action` as `Python4CPM.ACTION_PRERECONCILE` and once as `Python4CPM.ACTION_RECONCILE`.
-    - If all actions are not terminated with `p4cpm.close_success()` the overall reconcile will fail.
+    - If all actions are not terminated with `p4cpm.close_success()` and the scripts terminates without any exception, CPM/SRS will see this as a `p4cpm.close_fail(unrecoverable=True)`.
 4. When `p4cpm.args.action` comes as `Python4CPM.ACTION_VERIFY`, `Python4CPM.ACTION_LOGON` or `Python4CPM.ACTION_PRERECONCILE`: `p4cpm.secrets.new_password.get()` will always return an empty string.
 5. If a logon account is not linked, `p4cpm.args.logon_username` and `p4cpm.secrets.logon_password.get()` will return an empty string.
 6. If a reconcile account is not linked, `p4cpm.args.reconcile_username` and `p4cpm.secrets.reconcile_password.get()` will return an empty string.
 
 
-### Installing dependancies in python venv
+### Installing dependencies in python venv
 
-As with any python venv, you can install dependancies in your venv.
+As with any python venv, you can install dependencies in your venv.
 1. If your CPM can connect to the internet:
    - You can use regular pip install commands (e.g., `c:\venv\Scripts\pip.exe install requests`).
 2. If your CPM cannot connect to the internet:
@@ -203,7 +318,7 @@ As with any python venv, you can install dependancies in your venv.
 
 ## Dev Helper:
 
-For dev purposes, `NETHelper` is a companion helper that simplifies the instantiation of the `Python4CPM` object by simulating how the plugin passes arguments and secrets to `Python4CPM`.
+For dev purposes, `NETHelper` is a companion helper that simplifies the instantiation of the `Python4CPM` or `Python4CPMHandler` objects by simulating how the plugin passes arguments and secrets to the modules.
 Install this module (in a dev workstation) with:
 
 ```bash
@@ -215,7 +330,7 @@ pip install python4cpm
 ### Example:
 
 ```python
-from python4cpm import NETHelper, Python4CPM
+from python4cpm import NETHelper, Python4CPM, Python4CPMHandler
 from getpass import getpass
 
 # Get secrets for your password, logon account password, reconcile account password and new password
@@ -224,8 +339,12 @@ 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
 new_password = getpass("new_password: ") # new password for the rotation
+```
 
-p4cpm = NETHelper.run(
+#### Set your arguments and secrets:
+
+```python
+NETHelper.set(
     action=Python4CPM.ACTION_LOGON, # use actions from Python4CPM.ACTION_*
     address="myapp.corp.local", # populate with the address from your account properties
     username="jdoe", # populate with the username from your account properties
@@ -238,19 +357,48 @@ p4cpm = NETHelper.run(
     reconcile_password=reconcile_password,
     new_password=new_password
 )
+```
+
+#### Using the handler (recommended):
+
+```python
+class MyApp(Python4CPMHandler):
+    def verify(self):
+        # TODO: Add your logic here
+        self.close_success()
+
+    def logon(self):
+        # TODO: Add your logic here
+        self.close_success()
+
+    def change(self):
+        # TODO: Add your logic here
+        self.close_success()
+
+    def prereconcile(self):
+        # TODO: Add your logic here
+        self.close_success()
 
-# Use the p4cpm object during dev to build your script logic
+    def reconcile(self):
+        # TODO: Add your logic here
+        self.close_success()
+
+MyApp().run()
+```
+
+#### Using Python4CPM properties and methods directly:
+
+```python
+p4cpm = NETHelper.get()
+
+# TODO: use the p4cpm object during dev to build your script logic
 assert password == p4cpm.secrets.password.get()
 p4cpm.log_info("success!")
 p4cpm.close_success()
-
-# Remember for your final script:
-## changing the definition of p4cpm from NETHelper.run() to Python4CPM("MyApp")
-## remove any secrets prompting
-## remove the NETHelper import
 ```
 
-Remember for your final script:
-- Change the definition of `p4cpm` from `p4cpm = NETHelper.run(**kwargs)` to `p4cpm = Python4CPM("MyApp")`.
+#### Remember for your final script:
+
+- Change the definition of `p4cpm` from `p4cpm = NETHelper.get()` to `p4cpm = Python4CPM("MyApp")` if you are using the properties and methods directly.
 - Remove any secrets prompting or interactive interruptions.
 - Remove the import of `NETHelper`.