python4cpm 1.1.7__py3-none-any.whl → 1.1.9__py3-none-any.whl

python4cpm/accounts.py

@@ -1,5 +1,5 @@
 from python4cpm.envhandler import EnvHandler, Props
-from python4cpm.secret import Secret
+from python4cpm.secrets import Password, NewPassword
 
 
 class BaseAccount(EnvHandler):
@@ -11,7 +11,7 @@ class BaseAccount(EnvHandler):
         password: str | None
     ) -> None:
         self._username = username
-        self._password = Secret.from_env_var(password)
+        self._password = Password.from_env_var(password)
 
     @classmethod
     def get(cls) -> object | None:
@@ -25,7 +25,7 @@ class BaseAccount(EnvHandler):
         return self._username
 
     @property
-    def password(self) -> Secret:
+    def password(self) -> Password:
         return self._password
 
 
@@ -62,7 +62,7 @@ class TargetAccount(BaseAccount):
         self._object_name = object_name
         self._address = address
         self._port = port
-        self._new_password = Secret.from_env_var(new_password)
+        self._new_password = NewPassword.from_env_var(new_password)
 
     @property
     def policy_id(self) -> str | None:
@@ -85,7 +85,7 @@ class TargetAccount(BaseAccount):
         return self._port
 
     @property
-    def new_password(self) -> Secret:
+    def new_password(self) -> NewPassword:
         return self._new_password
 
 

python4cpm/devhelper.py

@@ -5,6 +5,14 @@ import os
 
 
 class DevHelper:
+    @staticmethod
+    def _get_secret_value(value: str | None) -> str | None:
+        if not value:
+            return None
+        if Crypto.ENABLED:
+            return Crypto.encrypt(value)
+        return value
+
     @classmethod
     def set(
         cls,
@@ -23,11 +31,10 @@ class DevHelper:
         reconcile_password: str | None = None,
         target_new_password: str | None = None
     ) -> None:
-        if Crypto.ENABLED:
-            target_password = Crypto.encrypt(target_password)
-            logon_password = Crypto.encrypt(logon_password)
-            reconcile_password = Crypto.encrypt(reconcile_password)
-            target_new_password = Crypto.encrypt(target_new_password)
+        target_password = cls._get_secret_value(target_password)
+        logon_password = cls._get_secret_value(logon_password)
+        reconcile_password = cls._get_secret_value(reconcile_password)
+        target_new_password = cls._get_secret_value(target_new_password)
         keys = (
             Args.get_key(Args.PROPS.action),
             Args.get_key(Args.PROPS.logging_level),
@@ -62,4 +69,6 @@ class DevHelper:
         )
         for i, key in enumerate(keys):
             if values[i] is not None:
-                os.environ.update({key: values[i]})
+                os.environ[key] = values[i]
+            else:
+                os.environ.pop(key, None)

python4cpm/exithandler.py

@@ -0,0 +1,27 @@
+from python4cpm.loggerhandler import LoggerHandler
+import atexit
+import sys
+
+
+class ExitHandler:
+    _ERROR_MESSAGE = "No close signal called"
+    _closed = False
+
+    @classmethod
+    def reset(cls) -> None:
+        cls._closed = False
+
+    @classmethod
+    def set_closed(cls) -> None:
+        cls._closed = True
+
+    @classmethod
+    def on_exit(cls) -> None:
+        if cls._closed is False:
+            for logger in LoggerHandler.get_all_loggers():
+                logger.error(cls._ERROR_MESSAGE)
+            sys.stderr.write(cls._ERROR_MESSAGE)
+            sys.stderr.flush()
+
+
+atexit.register(ExitHandler.on_exit)

python4cpm/{logger.py → loggerhandler.py}

@@ -3,7 +3,7 @@ import logging
 from logging.handlers import RotatingFileHandler
 
 
-class Logger:
+class LoggerHandler:
     _LOGS_DIR = os.path.join("Logs", "ThirdParty")
     _LOGGING_LEVELS = {
         "critical": logging.CRITICAL,
@@ -13,6 +13,7 @@ class Logger:
         "debug": logging.DEBUG
     }
     _DEFAULT_LEVEL = "error"
+    _all_loggers = []
 
     @classmethod
     def get_logger(
@@ -42,4 +43,9 @@ class Logger:
         formatter = logging.Formatter(fmt=fmt, datefmt=datefmt)
         handler.setFormatter(formatter)
         logger.addHandler(handler)
+        cls._all_loggers.append(logger)
         return logger
+
+    @classmethod
+    def get_all_loggers(cls):
+        return cls._all_loggers

python4cpm/python4cpm.py

@@ -1,10 +1,10 @@
 import sys
-import atexit
 import logging
-from python4cpm.secret import Secret
+from python4cpm.secrets import Secret
 from python4cpm.args import Args
-from python4cpm.logger import Logger
+from python4cpm.loggerhandler import LoggerHandler
 from python4cpm.accounts import TargetAccount, LogonAccount, ReconcileAccount
+from python4cpm.exithandler import ExitHandler
 
 
 class Python4CPM:
@@ -36,8 +36,6 @@ class Python4CPM:
         self._log_obj(self._target_account)
         self._log_obj(self._logon_account)
         self._log_obj(self._reconcile_account)
-        self._closed = False
-        atexit.register(self._on_exit)
 
     @property
     def args(self) -> Args:
@@ -66,7 +64,7 @@ class Python4CPM:
             self._target_account.object_name
         )
         name = "-".join(name_parts)
-        return Logger.get_logger(name, self._args.logging_level)
+        return LoggerHandler.get_logger(name, self._args.logging_level)
 
     def _verify_action(self) -> None:
         if self._args.action not in self._VALID_ACTIONS:
@@ -91,17 +89,10 @@ class Python4CPM:
         else:
             code = self._FAILED_UNRECOVERABLE_CODE
         self._logger.error(f"Closing with code {code}")
-        self._closed = True
+        ExitHandler.set_closed()
         sys.exit(code)
 
     def close_success(self) -> None:
         self._logger.debug(f"Closing with code {self._SUCCESS_CODE}")
-        self._closed = True
+        ExitHandler.set_closed()
         sys.exit(self._SUCCESS_CODE)
-
-    def _on_exit(self):
-        if self._closed is False:
-            message = "No close signal called"
-            self._logger.error(message)
-            sys.stderr.write(message)
-            sys.stderr.flush()

python4cpm/{secret.py → secrets.py}

@@ -3,7 +3,7 @@ from python4cpm.crypto import Crypto
 
 class Secret:
     def __init__(self, secret: str) -> None:
-        self._secret = secret
+        self._value = secret
 
     @classmethod
     def from_env_var(cls, secret: str | None) -> object | None:
@@ -18,5 +18,13 @@ class Secret:
 
     def get(self) -> str:
         if Crypto.ENABLED:
-            return Crypto.decrypt(self._secret)
-        return self._secret
+            return Crypto.decrypt(self._value)
+        return self._value
+
+
+class Password(Secret):
+    pass
+
+
+class NewPassword(Secret):
+    pass

python4cpm-1.1.9.dist-info/METADATA

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: python4cpm
+Version: 1.1.9
+Summary: Python for CPM
+Author-email: Gonzalo Atienza Rela <gonatienza@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Python4CPM
+
+A simple and secure way of using python scripts with Idira/CyberArk CPM/SRS password rotations.
+
+## How it works
+
+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 Python.
+
+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 (from Privilege Cloud/PVWA) to point to different venvs and/or python scripts.
+
+## Installation
+
+### Preparing Python
+
+1. Install Python 3.11 or later along CPM or the SRS Connector Management Agent.
+    - **Python must be installed for all users**.  Follow the custom install steps from the installation wizard to check the checkbox.
+2. Create a venv in the server, by running `py -m venv c:\venv`.  If desired, use a custom location and adjust any future references.
+3. Install `python4cpm` in your venv:
+    - If your CPM/SRS can connect to the internet, install with `c:\venv\Scripts\pip.exe install python4cpm`.
+    - If your CPM/SRS cannot connect to the internet:
+        - Download the latest `python4cpm-*.whl` file from the [pypi project files](https://pypi.org/project/python4cpm/#files).
+        - Copy the file to the server into a temporary directory called `python4cpm-wheel`.
+        - From the parent directory of `python4cpm-wheel` run `c:\venv\Scripts\pip.exe install --no-index --find-links=.\python4cpm-wheel python4cpm`.
+
+
+### Importing the platform
+
+#### If you are using CPM (SaaS or Self-Hosted):
+1. Download the latest [Credential Management .NET SDK](https://community.cyberark.com/marketplace/s/#a3550000000EkA0AAK-a3950000000jjoOAAQ) and place its content in the bin folder of CPM (`C:\Program Files (x86)\CyberArk\Password Manager\bin`).  The files for this may already be present.
+2. Download the `python4cpm-platform-*.zip` asset from the latest  [release](https://github.com/gonatienza/python4cpm/releases).
+3. Import the platform zip file into Privilege Cloud/PVWA `(Administration -> Platform Management -> Import platform)`.
+4. Craft your python script and place it within a folder in CPM (e.g., `C:\python4cpm-scripts`).
+5. Duplicate the imported platform in Privilege Cloud/PVWA `(Administration -> Platform Management -> Application -> Python for CPM)` and name it after your application (e.g., My App).
+6. Edit the duplicated platform and specify the path of your script, under `Target Account Platform -> Automatic Platform Management -> Additional Policy Settings -> Parameters -> PythonScriptPath -> Value` (e.g., `C:\python4cpm-scripts\myapp.py`).
+7. Also update `Target Account Platform -> Automatic Platform Management -> Additional Policy Settings -> Parameters -> PythonExePath -> Value` with the custom path for the venv's `python.exe` file (e.g., `c:\venv\Scripts\python.exe`).
+8. If you want to change the logging level, update `Target Account Platform -> Automatic Platform Management -> Additional Policy Settings -> Parameters -> PythonLoggingLevel -> Value` to `critical`, `error`, `warning`, `info` or `debug`.
+9. For new applications repeat steps from 4 to 8.
+
+#### If you are using SRS (SaaS only):
+1. Download the `python4cpm-platform-*.zip` asset from the latest  [release](https://github.com/gonatienza/python4cpm/releases).
+2. Import the platform zip file into Privilege Cloud `(Administration -> Platform Management -> Import platform)`.
+3. Craft your python script and place it within a folder in the Cloud Connector (where the SRS Management Agent runs) (e.g., `C:\python4cpm-scripts`).
+4. Duplicate the imported platform in Privilege Cloud/PVWA `(Administration -> Platform Management -> Application -> Python for CPM)` and name it after your application (e.g., My App).
+5. Edit the duplicated platform and specify the path of your script, under `Plugin Settings -> Additional Parameters -> PythonScriptPath` (e.g., `C:\python4cpm-scripts\myapp.py`).
+6. Also update `Plugin Settings -> Additional Parameters -> PythonExePath` with the custom path for the venv's `python.exe` file (e.g., `c:\venv\Scripts\python.exe`).
+7. If you want to change the logging level, update `Plugin Settings -> Additional Parameters -> PythonLoggingLevel -> Value` to `critical`, `error`, `warning`, `info` or `debug`.
+8. For new applications repeat steps from 3 to 7.
+
+### Platform defaults
+
+**Automatic verification and change are enabled by default.**  Only assign accounts to a duplicated platform that has `PythonExePath` and `PythonScriptPath` set.  The imported platform ships with the placeholder `ReplaceWithAbsolutePath`, which fails with `8900` without starting Python.  Adjust these defaults to match your application:
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `PerformPeriodicChange` | `Yes` | Rotate automatically |
+| `ExpirationPeriod` | `90` | Days before a password expires |
+| `VFPerformPeriodicVerification` | `Yes` | Verify automatically |
+| `Interval` | `1440` | Minutes |
+| `Timeout` | `120` | Seconds |
+| `MaximumRetries` | `5` | Retries |
+| `MinDelayBetweenRetries` | `90` | Minutes between retries |
+| `UnrecoverableErrors` | `8900` | Return codes treated as unrecoverable |
+| `RCAutomaticReconcileWhenUnsynched` | `Yes` | Reconcile when unsynched |
+| `PasswordLength`, `MinUpperCase`, `MinLowerCase`, `MinDigit`, `MinSpecial` | `12`, `2`, `2`, `1`, `1` | Rules for generating `new_password` |
+| `PasswordForbiddenChars` | Empty | Characters the new password must not contain |
+
+The new password is generated for you, so **make the password rules match the target system's policy**.  Your script only applies it.
+
+Accounts require `Username` and `Address`, and `Port` is optional.  Link a `LogonAccount` and a `ReconcileAccount` if your script needs them.
+
+## Python Script
+
+```python
+from python4cpm import Python4CPMHandler
+
+
+class CredManager(Python4CPMHandler):
+    """
+    Properties:
+        target_account (TargetAccount): Account being managed.
+            .username (str): Account username.
+            .address (str): Target address.
+            .port (str | None): Target port.
+            .policy_id (str): Platform ID.
+            .safe_name (str): Safe name.
+            .object_name (str): Account name in the vault.
+            .password (Secret | None): Current password. Call .get() to retrieve value as many times as needed.
+            .new_password (Secret | None): Replacement password. Call .get() to retrieve value as many times as needed.
+
+        logon_account (LogonAccount | None): Linked Logon Account.
+            .username (str): Account username.
+            .password (Secret | None): Logon password. Call .get() to retrieve value.
+
+        reconcile_account (ReconcileAccount | None): Linked Reconcile Account.
+            .username (str): Account username.
+            .password (Secret | None): Reconcile password. Call .get() to retrieve value.
+
+        args (Args): Execution arguments.
+            .action (str): Requested action.
+            .logging_level (str | None): Value of PythonLoggingLevel.
+
+        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__":
+    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 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.
+    - `close_fail` takes the optional argument of `unrecoverable` as a bool flag (by default set to `False`).  It signals CPM whether the error you encountered cannot be solved through the rotation logic or requires manual intervention.  E.g., a regular rotation fails (which is still recoverable) and when called for a reconciliation process it fails too (at this point the error encountered is not recoverable).
+    - If any action is not terminated with a termination method, CPM/SRS will see this as a `close_fail(unrecoverable=True)`.  This happens regardless of whether it was terminated by an exception or no exception was raised.  **If you rotate a credential successfully and do not close with success, you will have a rotated credential that will be lost and not saved into the vault**.
+8. The python `Logger` places its logs in the `Logs/ThirdParty` directory.
+
+### Writing a rotation script
+
+#### What each method should do
+
+| Method | Action | `new_password` | What to do |
+| --- | --- | --- | --- |
+| `verify()` | `verifypass` | `None` | Authenticate with `target_account`. |
+| `logon()` | `logon` | `None` | Prepare for `change()`.  It can just call `close_success()`. |
+| `change()` | `changepass` | Set | Authenticate, then set `target_account.new_password` on the target. |
+| `prereconcile()` | `prereconcilepass` | `None` | Authenticate with `reconcile_account`. |
+| `reconcile()` | `reconcilepass` | Set | Authenticate with `reconcile_account`, then set `target_account.new_password` on `target_account.username`. |
+
+Use `reconcile_account` for `prereconcile()` and `reconcile()`, because `target_account.password` is not expected to work when reconciling.
+
+#### Return codes
+
+| Script result | Python exit code | Returned to CPM/SRS |
+| --- | --- | --- |
+| `close_success()` | `10` | `0` (success) |
+| `close_fail()` | `81` | `8100` (recoverable) |
+| `close_fail(unrecoverable=True)` | `89` | `8900` (unrecoverable) |
+| Unhandled exception | `1` | `8900` (unrecoverable) |
+| No close method called | `0` | `8900` (unrecoverable) |
+| Any other exit code | That code | `8900` (unrecoverable) |
+| `PythonExePath` or `PythonScriptPath` not found | Python is not started | `8900` (unrecoverable) |
+
+#### Rules for your script
+
+- **Every method runs in a new python process.**  Nothing in memory is shared between `logon()` and `change()`, or between `prereconcile()` and `reconcile()`.
+- **Implement all five methods.**  A missing method raises a `TypeError` when the class is created, which returns `8900`.
+- **If you override `__init__`, call `super().__init__()` first.**
+- **Check for `None`.**  Empty values are not sent, so these can all be `None`: `port`, any `password`, and `new_password`.  A linked account can have a username and no password.  `.get()` on `None` raises an `AttributeError`.
+- **`address` is the raw value from the account.**  Build URLs yourself, and pick a default for when `port` is `None`.
+- **Change the password last.**  Close with `close_success()` straight after the target accepts it, and do nothing that can fail in between.
+- **Close methods raise `SystemExit`.**  They are safe inside `try/except Exception`, and code after them does not run, except `finally` blocks.  A bare `except:` or `except BaseException:` catches them, and that action then returns `8900`.
+- **Set a timeout on every network call.**  The plugin waits for python with no time limit of its own, so keep each action under the platform's `Timeout`.
+- **Use `self.logger`, not `print`.**  Standard output is not captured.  Standard error is written to the plugin log when an action fails.
+- **Never log the result of `.get()`.**  Logging a `Secret` itself is safe and shows `[ENCRYPTED]`.  Keep secrets out of exception messages too, as tracebacks reach the plugin log.
+- **Use absolute paths.**  The working directory is inherited from the CPM/SRS process, not taken from your script's folder.
+- **Keep TLS verification on in production.**  The `simpleauthcredmanager.py` example turns it off.
+
+Common failures can be handled like this:
+
+```python
+def verify(self):
+    try:
+        self._login(self.target_account)
+    except Exception as e:
+        self.logger.error(f"{type(e).__name__}: {e}")
+        self.close_fail()
+    self.close_success()
+```
+
+Use `close_fail()` for what a later attempt could fix, like a timeout or a rejected password.  Use `close_fail(unrecoverable=True)` for what needs manual intervention.
+
+#### Logs
+
+All logs are in `Logs/ThirdParty`, relative to the working directory.
+
+| File | Content |
+| --- | --- |
+| `python4cpm.loggerhandler_<level>_<PolicyID>-<SafeName>-<ObjectName>.log` | `self.logger` output.  Rotates at 1 MB and keeps one backup. |
+| `<PolicyID>-<SafeName>-<FolderName>-<ObjectName>.Log` | The last error, with its error code. |
+| `Debug_<PolicyID>-<SafeName>-<FolderName>-<ObjectName>_CANetPluginInvoker_<date>.log` | Plugin trace, written with `Debug=Yes` in a manual run, including paths, values and standard error. |
+
+The default level is `error`, so `self.logger.info()` and `self.logger.debug()` write nothing until you change `PythonLoggingLevel`.  An unknown level falls back to `error`, and `critical` is the quietest.  Logging cannot be turned off.
+
+#### Troubleshooting
+
+| Log message | Cause |
+| --- | --- |
+| `PythonExePath: '...' not found` or `PythonScriptPath: '...' not found` | Wrong path, or the account is still on the imported platform. |
+| `Python closed with exit code: 0` and `No close signal called` | A method ended without a close method. |
+| `Python closed with exit code: 1` | Unhandled exception.  The traceback follows in `StdErr Output`. |
+| `Python closed with failed recoverable` | The script called `close_fail()`. |
+| `Python closed with failed unrecoverable` | The script called `close_fail(unrecoverable=True)`. |
+| `can't open file '...\ C:\...'` | A manual `.ini` file has spaces around `=`. |
+
+
+### Installing dependencies in python 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:
+   - You can download packages for an offline install.  More info [here](https://pip.pypa.io/en/stable/cli/pip_download/).
+
+
+## Dev Helper:
+
+For dev purposes, `DevHelper` 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 `DevHelper` will be in plaintext.  In windows dev workstations, `DevHelper` 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.
+
+### Example:
+
+#### Set your arguments and secrets:
+
+```python
+from python4cpm import DevHelper, Python4CPM, Python4CPMHandler
+
+DevHelper.set(
+    action=Python4CPM.ACTION_CHANGE, # use actions from Python4CPM.ACTION_*
+    logging_level="debug",
+    target_policy_id="DevHelper", # name of platform
+    target_safe_name="Safename", # name of safe
+    target_object_name="Objectname", # name of account
+    target_username="jdoe",
+    target_address="myapp.corp.local",
+    target_port="8443",
+    logon_username="ldoe",
+    reconcile_username="rdoe",
+    target_password="", # str value of target password (required by most scripts)
+    logon_password="", # str value of logon password (leave out if not linked)
+    reconcile_password="", # str value of reconcile password (leave out if not linked)
+    target_new_password="" # str value of new password (only for change and reconcile)
+)
+
+class CredManager(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()
+
+    def reconcile(self):
+        # TODO: Add your logic here
+        self.close_success()
+
+CredManager().run()
+```
+
+#### Remember when using `DevHelper`:
+
+- `target_policy_id`, `target_safe_name` and `target_object_name` are required.  The log file name is built from them.
+- A password left out or set to `""` becomes `None`, as in production.  Leave out `target_new_password` when testing `verify()`, `logon()` or `prereconcile()`.
+- Each `DevHelper.set()` call replaces the previous one, so anything left out is cleared.
+- Each run tests one `action`, so set it to test each of the five methods.
+- Exit code `10` means success, and `81` or `89` mean the script called `close_fail()`.  Anything else returns `8900` in production.
+- **Your script runs for real.**  `change()` and `reconcile()` change the password on the target, so use a test account.
+
+#### Remember for your final script:
+
+- Remove the import of `DevHelper`.
+- Remove the `DevHelper.set()` call.

python4cpm-1.1.9.dist-info/RECORD

@@ -0,0 +1,16 @@
+python4cpm/__init__.py,sha256=GQvsXZY2escF3zucv3d68s2ydqHSIYi5tnNDCkhTjcM,302
+python4cpm/accounts.py,sha256=MSRcHotQ_ITGCy02nNVkZyfxbBP31OIcH9PbRS9aUbo,2231
+python4cpm/args.py,sha256=PQDDlMakP-YsDLd3HdwIZtxVpIM4m4aHl2GuRj9kHpI,504
+python4cpm/crypto.py,sha256=FufZdKcm36-HYnSYrBGdADPVk2YmRPl0WDVZ29FfUU0,2337
+python4cpm/devhelper.py,sha256=pU90ErFMbPWTmNHSKPqC2PTSF74zF5sNNalMrAaOW-Q,2860
+python4cpm/envhandler.py,sha256=mNDOaYVemmxKREXyOf7IuQdFDXrvZ7f_7sNaqWV7TsI,678
+python4cpm/exithandler.py,sha256=en_Xy8cnRk5w6xOuQgkxipLSyRWrB3AEZfhoc9T1Cvg,623
+python4cpm/loggerhandler.py,sha256=OrFayXn2VENO2bm0hNmlrBH_Bc_ew8WYxSICuFPr91g,1610
+python4cpm/python4cpm.py,sha256=FD9HMWwN_MIhHTVvN4aj-q7Yr0nmpav3UMSNgRDjvK4,3228
+python4cpm/python4cpmhandler.py,sha256=SXKsnFAwUp8cHEhv2TygpNpptUkN3bVQZt1i-3TWql4,935
+python4cpm/secrets.py,sha256=ijY2t4gSuVZyfDSiGNSqjjNjIhSL4K4yhKrPF-DrGOs,606
+python4cpm-1.1.9.dist-info/licenses/LICENSE,sha256=vF2wZA3GchZjH5lUmhonEwd4snuBc6o0ytpZNxVFyCw,1077
+python4cpm-1.1.9.dist-info/METADATA,sha256=EUi2prlUIfVNj5veDoz66CBszZE-tcf37feeSWAnLs8,19336
+python4cpm-1.1.9.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python4cpm-1.1.9.dist-info/top_level.txt,sha256=EhbshwpANmL0wYXaET8_6V9ZENtSwIyAd-kM3jGhUlE,11
+python4cpm-1.1.9.dist-info/RECORD,,

{python4cpm-1.1.7.dist-info → python4cpm-1.1.9.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

python4cpm-1.1.7.dist-info/METADATA

@@ -1,215 +0,0 @@
-Metadata-Version: 2.4
-Name: python4cpm
-Version: 1.1.7
-Summary: Python for CPM
-Author-email: Gonzalo Atienza Rela <gonatienza@gmail.com>
-License-Expression: MIT
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# Python4CPM
-
-A simple and secure way of using python scripts with CyberArk CPM/SRS password rotations.
-
-## How it works
-
-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 Python.
-
-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 (from Privilege Cloud/PVWA) to point to different venvs and/or python scripts.
-
-## Installation
-
-### Preparing Python
-
-1. Install Python along CPM or the SRS Connector Management Agent.
-    - **Python must be installed for all users**.  Follow the custom install steps from the installation wizard to check the checkbox.
-3. Create a venv in the server, by running `py -m venv c:\venv`.  If desired, use a custom location and adjust any future references.
-4. Install `python4cpm` in your venv:
-    - If your CPM can connect to the internet, install with `c:\venv\Scripts\pip.exe install python4cpm`.
-    - If your CPM cannot connect to the internet:
-        - Download the latest `python4cpm-*.whl` file from the [pypi project files](https://pypi.org/project/python4cpm/#files).
-        - Copy the file to the server into a temporary directory called `python4cpm-wheel`.
-        - From the parent directory of `python4cpm-wheel` run `c:\venv\Scripts\pip.exe install --no-index --find-links=.\python4cpm-wheel python4cpm`.
-
-
-### Importing the platform
-
-#### If you are using CPM (SaaS or Self-Hosted):
-1. Download the latest [Credential Management .NET SDK](https://community.cyberark.com/marketplace/s/#a3550000000EkA0AAK-a3950000000jjoOAAQ) and place its content in the bin folder of CPM (`C:\Program Files (x86)\CyberArk\Password Manager\bin`).  The files for this may already be present.
-2. Download the `python4cpm-platform-*.zip` asset from the latest  [release](https://github.com/gonatienza/python4cpm/releases).
-3. Import the platform zip file into Privilege Cloud/PVWA `(Administration -> Platform Management -> Import platform)`.
-4. Craft your python script and place it within a folder in CPM (e.g., `C:\python4cpm-scripts`).
-5. Duplicate the imported platform in Privilege Cloud/PVWA `(Administration -> Platform Management -> Application -> Python for CPM)` and name it after your application (e.g., My App).
-6. Edit the duplicated platform and specify the path of your script, under `Target Account Platform -> Automatic Platform Management -> Additional Policy Settings -> Parameters -> PythonScriptPath -> Value` (e.g., `C:\python4cpm-scripts\myapp.py`).
-7. Also update `Target Account Platform -> Automatic Platform Management -> Additional Policy Settings -> Parameters -> PythonExePath -> Value` with the custom path for the venv's `python.exe` file (e.g., `c:\venv\Scripts\python.exe`).
-8. If you want to disable logging, update `Target Account Platform -> Automatic Platform Management -> Additional Policy Settings -> Parameters -> PythonLogging -> Value` to `no`.
-9. If you want to change the logging level to `debug`, update `Target Account Platform -> Automatic Platform Management -> Additional Policy Settings -> Parameters -> PythonLoggingLevel -> Value` to `debug`.
-10. For new applications repeat steps from 4 to 9.
-
-#### If you are using SRS (SaaS only):
-1. Download the `python4cpm-platform-*.zip` asset from the latest  [release](https://github.com/gonatienza/python4cpm/releases).
-2. Import the platform zip file into Privilege Cloud `(Administration -> Platform Management -> Import platform)`.
-3. Craft your python script and place it within a folder in the Cloud Connector (where the SRS Management Agent runs) (e.g., `C:\python4cpm-scripts`).
-4. Duplicate the imported platform in Privilege Cloud/PVWA `(Administration -> Platform Management -> Application -> Python for CPM)` and name it after your application (e.g., My App).
-5. Edit the duplicated platform and specify the path of your script, under `Plugin Settings -> Additional Parameters -> PythonScriptPath` (e.g., `C:\python4cpm-scripts\myapp.py`).
-6. Also update `Plugin Settings -> Additional Parameters -> PythonExePath` with the custom path for the venv's `python.exe` file (e.g., `c:\venv\Scripts\python.exe`).
-7. If you want to disable logging, update `Plugin Settings -> Additional Parameters -> PythonLogging` to `no`.
-8. If you want to change the logging level to `debug`, update `Plugin Settings -> Additional Parameters -> PythonLoggingLevel -> Value` to `debug`.
-9. For new applications repeat steps from 3 to 8.
-
-## Python Script
-
-```python
-from python4cpm import Python4CPMHandler
-
-
-class CredManager(Python4CPMHandler):
-    """
-    Properties:
-        target_account (TargetAccount): Account being managed.
-            .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__":
-    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 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.
-
-
-### Installing dependencies in python 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:
-   - You can download packages for an offline install.  More info [here](https://pip.pypa.io/en/stable/cli/pip_download/).
-
-
-## Dev Helper:
-
-For dev purposes, `DevHelper` 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 `DevHelper` will be in plaintext.  In windows dev workstations, `DevHelper` 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.
-
-### Example:
-
-#### Set your arguments and secrets:
-
-```python
-from python4cpm import DevHelper, Python4CPM, Python4CPMHandler
-
-DevHelper.set(
-    action=Python4CPM.ACTION_CHANGE, # use actions from Python4CPM.ACTION_*
-    logging_level="debug",
-    target_policy_id="DevHelper", # name of platform
-    target_safe_name="Safename", # name of safe
-    target_object_name="Objectname", # name of account
-    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 CredManager(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()
-
-    def reconcile(self):
-        # TODO: Add your logic here
-        self.close_success()
-
-CredManager().run()
-```
-
-#### Remember for your final script:
-
-- Remove the import of `DevHelper`.
-- Remove the `DevHelper.set()` call.

python4cpm-1.1.7.dist-info/RECORD

@@ -1,15 +0,0 @@
-python4cpm/__init__.py,sha256=GQvsXZY2escF3zucv3d68s2ydqHSIYi5tnNDCkhTjcM,302
-python4cpm/accounts.py,sha256=tzLr6kFeHD6jDF-dZXjp2FeoABFsWn2hp4bO5uYN2Zg,2201
-python4cpm/args.py,sha256=PQDDlMakP-YsDLd3HdwIZtxVpIM4m4aHl2GuRj9kHpI,504
-python4cpm/crypto.py,sha256=FufZdKcm36-HYnSYrBGdADPVk2YmRPl0WDVZ29FfUU0,2337
-python4cpm/devhelper.py,sha256=iv5zHSMyMNMdksGkkTh_8c_ObocJfQormQ4S3nZzo0Y,2609
-python4cpm/envhandler.py,sha256=mNDOaYVemmxKREXyOf7IuQdFDXrvZ7f_7sNaqWV7TsI,678
-python4cpm/logger.py,sha256=66lkgsGsSyXJLeMfn8zq6DinTPJWRfFyMBiUYySM2Ec,1461
-python4cpm/python4cpm.py,sha256=hkVKd_pEiCA7VPPSUgGFxJ_9sWb3p4GB-EJ034HLxfA,3446
-python4cpm/python4cpmhandler.py,sha256=SXKsnFAwUp8cHEhv2TygpNpptUkN3bVQZt1i-3TWql4,935
-python4cpm/secret.py,sha256=H3TUjhVN9uPPtr3BUaENEPG1odc3SJXj-u7wD-bCz58,536
-python4cpm-1.1.7.dist-info/licenses/LICENSE,sha256=vF2wZA3GchZjH5lUmhonEwd4snuBc6o0ytpZNxVFyCw,1077
-python4cpm-1.1.7.dist-info/METADATA,sha256=Kh0gEBT3OepZHxMrTGjQY9llpEprDnLAHBPP7_V4bFI,11193
-python4cpm-1.1.7.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python4cpm-1.1.7.dist-info/top_level.txt,sha256=EhbshwpANmL0wYXaET8_6V9ZENtSwIyAd-kM3jGhUlE,11
-python4cpm-1.1.7.dist-info/RECORD,,