4.3 CPM Plug-in Architecture, Process/Prompts Files & Custom Plug-in Troubleshooting

4.3 CPM Plug-in Architecture, Process/Prompts Files & Custom Plug-in Troubleshooting

Quick Answer: The Central Policy Manager (CPM) Plug-in Architecture decouples target protocol communications from the core policy engine. While standard out-of-the-box plug-ins manage Windows (via NetAPI/RPC/WMI), Databases (via ODBC), and Cloud APIs (via REST), terminal-based systems (Unix, Linux, routers, firewalls) are managed by the modern Terminal Plugin Controller (CyberArk.TPC.exe). TPC replaced the legacy 32-bit Cygwin-based PMTerminal.exe with a 64-bit .NET engine supporting modern SSH ciphers. Plug-ins are driven by three components: the platform INI file (executable binding and timeouts), the Process file (state-machine transition steps), and the Prompts file (regex patterns matching target output).

---

The CPM Plug-in Framework & Protocol Handlers

The Central Policy Manager does not hardcode target protocol communications into its primary service (PasswordManager.exe). Instead, it utilizes an extensible plug-in framework. When a credential operation (Change, Verify, Reconcile) is triggered, the CPM identifies the target platform, loads the associated plug-in binary or script, and spawns an isolated execution process.

During execution, the CPM passes account metadata, target host addresses, and credentials into the plug-in via command-line arguments, environment variables, or temporary staging files within Password Manager\Tmp. Upon completion, the plug-in returns a standard exit code to the CPM engine:

• Exit Code 0: Operation completed successfully.
• Exit Code 8000–8999: Standardized CyberArk plug-in error codes denoting authentication failures, network timeouts, prompt mismatches, or syntax rejections.

This modular architecture allows organizations to import specialized plug-ins from the CyberArk Marketplace or author completely custom plug-ins for proprietary mainframes, network appliances, and web management portals without modifying core software.

---

Standard Out-of-the-Box Plug-ins Across Target Platforms

CyberArk provides robust, pre-packaged plug-ins for common enterprise technologies:

1. Windows Operating Systems & Active Directory

• Protocols: Microsoft RPC (TCP port 135) and SMB (TCP port 445), utilizing native Windows NetAPI functions (NetUserChangePassword for user changes, NetUserSetInfo for administrative resets).
• Active Directory: Communicates with domain controllers over LDAP (TCP port 389) or LDAPS (TCP port 636) to modify domain user attributes.
• Service Account Dependencies: Detects and automatically restarts dependent Windows Services, Scheduled Tasks, and IIS Application Pools associated with rotated credentials.

2. Databases (Oracle, MS SQL, MySQL, PostgreSQL, DB2)

• Protocols: Relational database connections established via Open Database Connectivity (ODBC) or OLE DB drivers.
• Execution: Authenticates over database listener ports (e.g., Oracle TCP 1521, MS SQL TCP 1433, MySQL TCP 3306) and executes Data Definition/Control Language statements, such as ALTER USER <username> IDENTIFIED BY "<newpassword>".

3. Unix, Linux & Network Appliances

• Protocols: Secure Shell (SSH over TCP port 22) or legacy Telnet (TCP port 23).
• Execution: Spawns an interactive terminal emulation session, navigates command shells, executes /usr/bin/passwd or administrative commands, and handles privilege escalation via su or sudo.

---

Evolution from PMTerminal to Terminal Plugin Controller (TPC)

For over a decade, CyberArk utilized PMTerminal.exe to manage terminal-based targets. Understanding the architectural shift from PMTerminal to TPC is a prominent topic on the PAM-DEF certification exam:

• The Legacy PMTerminal Architecture: PMTerminal.exe was a 32-bit application compiled against the Cygwin POSIX emulation layer. While functional, it introduced severe limitations in modern enterprise environments:
  • Required 32-bit runtime libraries on 64-bit Windows Server.
  • Relied on outdated cryptographic libraries that lacked support for modern SSH ciphers, Elliptic Curve algorithms (ECDSA, Ed25519), and SHA-2 key exchange algorithms (such as rsa-sha2-256 and diffie-hellman-group14-sha256).
  • Frequently triggered false positives with enterprise Endpoint Detection and Response (EDR) agents due to Cygwin memory injection techniques.
• The Modern Terminal Plugin Controller (CyberArk.TPC.exe): Developed as a native 64-bit .NET Core / .NET Framework application built upon the robust SSH.NET library:
  • Full Cipher Support: Natively supports modern cryptographic standards, advanced SSH key algorithms, and strong key exchange methods required by modern Linux distributions (RHEL 9, Ubuntu 22.04+) and network firewalls.
  • Backward Compatibility: TPC directly consumes existing Process.ini and Prompts.ini configuration files without requiring state-machine rewrites.
  • Performance: Eliminates the Cygwin emulation layer, drastically reducing CPU overhead and execution latency during large-scale rotation waves.

---

Anatomy of a Plug-in: INI, Process, and Prompts Files

A terminal plug-in consists of three tightly coupled configuration artifacts:

1. Platform Policy File (<PlatformName>.ini)

Stored in the Vault's PVWAConfig Safe and cached locally. Governs execution binaries and timing:

• ExeName=CyberArk.TPC.exe: Defines the executable invoked by CPM.
• ProcessFile=UnixProcess.ini: Names the state machine sequence file.
• PromptsFile=UnixPrompts.ini: Names the regex pattern definitions file.
• Timeout=60: Maximum overall execution time (seconds) before terminating.
• ConnectionTimeout=30: Maximum time allowed to establish initial TCP/SSH connectivity.

2. The Prompts File (<Name>Prompts.ini)

Defines Regular Expressions (regex) matching expected output and prompt strings emitted by the target operating system:

[Prompts]
Username=(?i)login:\s*$
Password=(?i)password:\s*$
PasswordNew=(?i)(new|enter new)\s*password:\s*$
PasswordConfirm=(?i)re-enter\s*new\s*password:\s*$
StandardPrompt=(?i)[\$#>\~]\s*$
ErrorPrompt=(?i)(permission denied|incorrect|invalid|failed|abort)

3. The Process File (<Name>Process.ini)

Defines the finite state machine directing the sequence of interactions for each supported action ([Change], [Verify], [Reconcile]):

[Change]
WaitPrompt=Username
SendUsername=<username>
WaitPrompt=Password
SendPassword=<currentpassword>
WaitPrompt=StandardPrompt
SendCommand=passwd
WaitPrompt=Password
SendPassword=<currentpassword>
WaitPrompt=PasswordNew
SendPassword=<newpassword>
WaitPrompt=PasswordConfirm
SendPassword=<newpassword>
WaitPrompt=StandardPrompt
SendCommand=exit

---

Creating & Extending Custom Plug-ins

When developing custom plug-ins for proprietary devices, administrators must account for common terminal behavioral nuances:

• Banners & MotD Screens: Corporate login banners (e.g., "Authorized Access Only - Press Enter to Continue") break default state machines. Prompts must be configured to catch banner text and send carriage returns (\r\n).
• Terminal Pagination: Network switches (such as Cisco IOS or HP ProCurve) paginate long outputs with --More--. The Prompts file must detect pagination strings and inject spaces to advance output.
• Privilege Escalation: In Unix reconciliation workflows, the state machine logs in as an unprivileged user, executes sudo su -, expects the root password prompt, and transitions to # before executing passwd.
• Regex Precision: Prompts must account for variable hostnames, trailing whitespace, and non-printable ANSI terminal color escape sequences (e.g., \[\033[01;32m\]).

---

Plug-in Troubleshooting: PMTrace.log, Error Codes & Standalone Simulation

When a CPM plug-in fails, administrators utilize a structured diagnostic methodology:

1. Enabling Granular Tracing

Navigate to PVWA -> Administration -> Platform Management, edit the target platform under Additional Policy Settings, and configure:

• EnableTrace=yes
• DebugLevel=3

This instructs TPC to write detailed execution traces into Password Manager\Logs\PMTrace.log.

2. Analyzing PMTrace.log

PMTrace.log records every byte sent and received across the network. Key troubleshooting indicators include:

• Prompt Mismatch: The log shows the device sent admin@router> , but TPC hung until timing out because the regex expected #.
• Cipher Negotiation Mismatch: The log records No compatible key exchange method found, indicating the remote SSH daemon requires older or newer ciphers not enabled in TPC configuration.
• Echoed Passwords: Verifies whether the remote system erroneously echoed plaintext passwords into the terminal buffer.

3. Standalone Plug-in Simulation

The most effective troubleshooting technique is bypassing the Vault entirely by running CyberArk.TPC.exe in standalone test mode from an administrative command prompt on the CPM server:

cd "C:\Program Files (x86)\CyberArk\Password Manager\bin"
CyberArk.TPC.exe /action=Verify /processfile=UnixProcess.ini /promptsfile=UnixPrompts.ini /address=192.168.10.50 /username=svc_monitor /password=SecretPass123! /trace=yes

This isolates the plug-in execution from Vault state, providing instant visibility into terminal interactions, regex matches, and authentication outcomes.

---

PMTerminal vs. Terminal Plugin Controller (TPC) Comparison

---

Common CPM Plug-in Error Codes & Remediation Guide