Skip to main content

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 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), 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.
      • 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 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.
  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.
  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

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.

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:

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.

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:

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.

Metadata

Release files for python4cpm 1.1.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python4cpm 1.1.9
File Size Uploaded Provenance Actions
python4cpm-1.1.9.tar.gz 19.0 kB With provenance Details for python4cpm-1.1.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for python4cpm 1.1.9
File Interpreter ABI Platform Actions
python4cpm-1.1.9-py3-none-any.whl Python 3 none any Details for python4cpm-1.1.9-py3-none-any.whl

Total release size: 34.0 kB

Release files / python4cpm-1.1.9.tar.gz

Download URL python4cpm-1.1.9.tar.gz
Size 19.0 kB
Tags Source
SHA-256 checksum
How to use checksums
b2ee410c695a4ad43b4cc3a6c8d70f629a3aacba0b33395b9b5b0e7ec379253a
BLAKE2b-256 checksum
How to use checksums
29b5912f7abd0175066fe50be23e7ca51ab26405eb1353f2d415c594b58d476a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Release files / python4cpm-1.1.9-py3-none-any.whl

Download URL python4cpm-1.1.9-py3-none-any.whl
Size 15.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
358e09cbf31d4b8393837c0516cc6fcc81695a26d323a217ebed358422ba5f45
BLAKE2b-256 checksum
How to use checksums
3928fa78811e16c0a2b2ef2bfd92025045d5f74094fd0e8acf41e28c154792e5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Security for python4cpm 1.1.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for python4cpm-1.1.9.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page