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
- 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.
- Create a venv in the server, by running
py -m venv c:\venv. If desired, use a custom location and adjust any future references. - Install
python4cpmin 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-*.whlfile from the pypi project files. - Copy the file to the server into a temporary directory called
python4cpm-wheel. - From the parent directory of
python4cpm-wheelrunc:\venv\Scripts\pip.exe install --no-index --find-links=.\python4cpm-wheel python4cpm.
- Download the latest
- If your CPM/SRS can connect to the internet, install with
Importing the platform
If you are using CPM (SaaS or Self-Hosted):
- 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. - Download the
python4cpm-platform-*.zipasset from the latest release. - Import the platform zip file into Privilege Cloud/PVWA
(Administration -> Platform Management -> Import platform). - Craft your python script and place it within a folder in CPM (e.g.,
C:\python4cpm-scripts). - 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). - 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). - Also update
Target Account Platform -> Automatic Platform Management -> Additional Policy Settings -> Parameters -> PythonExePath -> Valuewith the custom path for the venv'spython.exefile (e.g.,c:\venv\Scripts\python.exe). - If you want to change the logging level, update
Target Account Platform -> Automatic Platform Management -> Additional Policy Settings -> Parameters -> PythonLoggingLevel -> Valuetocritical,error,warning,infoordebug. - For new applications repeat steps from 4 to 8.
If you are using SRS (SaaS only):
- Download the
python4cpm-platform-*.zipasset from the latest release. - Import the platform zip file into Privilege Cloud
(Administration -> Platform Management -> Import platform). - 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). - 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). - Edit the duplicated platform and specify the path of your script, under
Plugin Settings -> Additional Parameters -> PythonScriptPath(e.g.,C:\python4cpm-scripts\myapp.py). - Also update
Plugin Settings -> Additional Parameters -> PythonExePathwith the custom path for the venv'spython.exefile (e.g.,c:\venv\Scripts\python.exe). - If you want to change the logging level, update
Plugin Settings -> Additional Parameters -> PythonLoggingLevel -> Valuetocritical,error,warning,infoordebug. - 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:
- Verify -> the script will be executed once running the
verify()method. - Change -> the script will be executed twice: first
logon(), thenchange(). - Reconcile -> the script will be executed twice: first
prereconcile(), thenreconcile(). - When calling
verify(),logon()orprereconcile():target_account.new_passwordwill always returnNone. - If a logon account is not linked,
logon_accountwill returnNone. - If a reconcile account is not linked,
reconcile_accountwill returnNone. - Always use the
close_successorclose_failmethods to signal the proper termination for all actions.close_failtakes the optional argument ofunrecoverableas a bool flag (by default set toFalse). 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.
- The python
Loggerplaces its logs in theLogs/ThirdPartydirectory.
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()andchange(), or betweenprereconcile()andreconcile(). - Implement all five methods. A missing method raises a
TypeErrorwhen the class is created, which returns8900. - If you override
__init__, callsuper().__init__()first. - Check for
None. Empty values are not sent, so these can all beNone:port, anypassword, andnew_password. A linked account can have a username and no password..get()onNoneraises anAttributeError. addressis the raw value from the account. Build URLs yourself, and pick a default for whenportisNone.- 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 insidetry/except Exception, and code after them does not run, exceptfinallyblocks. A bareexcept:orexcept BaseException:catches them, and that action then returns8900. - 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, notprint. Standard output is not captured. Standard error is written to the plugin log when an action fails. - Never log the result of
.get(). Logging aSecretitself 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.pyexample 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.
- If your CPM can connect to the internet:
- You can use regular pip install commands (e.g.,
c:\venv\Scripts\pip.exe install requests).
- You can use regular pip install commands (e.g.,
- 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_nameandtarget_object_nameare required. The log file name is built from them.- A password left out or set to
""becomesNone, as in production. Leave outtarget_new_passwordwhen testingverify(),logon()orprereconcile(). - 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
10means success, and81or89mean the script calledclose_fail(). Anything else returns8900in production. - Your script runs for real.
change()andreconcile()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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.