psPAS: PowerShell Module for CyberArk Idira API

psPAS is a PowerShell module providing over 250 commands for interacting with the CyberArk / Idira REST API. It covers a wide range of operations including accounts, safes, users, platforms, discovery, reporting, and CPM operations.

Key Features

• Broad Compatibility: Supports CyberArk Self-Hosted, Privilege Cloud, and Identity Shared Services, including legacy API versions.
• Cross-Platform: Fully compatible with both Windows PowerShell and PowerShell Core (enabling automation on Windows, Linux, and macOS).
• PowerShell-Native Experience: Commands use standard Verb-Noun naming, support the PowerShell pipeline, and return structured objects instead of raw JSON.

psPAS is a comprehensive PowerShell interface for CyberArk Idira Privileged Access Security. It provides a consistent, pipeline-native experience for both Privilege Cloud (SaaS) and Privileged Access Manager Self-Hosted.

Key features include:

• Unified Interface: Use the same module for Privilege Cloud and Self-Hosted environments. The module automatically enforces platform-specific command availability.
• Full API Coverage: Over 250 commands covering Accounts, Safes, Users & Directories, Platforms, Authentication, PSM, Reports, and more.
• Pipeline Native: Commands emit and accept typed objects, allowing for seamless PowerShell pipeline usage (e.g., Get-PASSafe | Get-PASSafeMember) without manual JSON parsing.

Before using psPAS, ensure your environment meets the following requirements:

• PowerShell: PowerShell Core or Windows PowerShell v5 (minimum).
• CyberArk Connectivity: Access to the CyberArk PAS REST API/PVWA Web Service via HTTPS using TLS 1.2.
• Permissions: A user account capable of authenticating and possessing the necessary Vault/Safe permissions.

psPAS functions have minimum CyberArk version requirements. The module automatically attempts to verify if your CyberArk version meets the requirements for a specific command. If the version requirement is not met, the module may prevent the operation from executing to ensure stability and prevent errors.

Always check the function list (provided in the documentation) to ensure your CyberArk environment supports the specific function and its parameters, as CyberArk versions can affect available capabilities.

When using Get-PASAccount, certain parameter combinations force the use of the Gen1 API. Specifically, using the -Safe (instead of -SafeName) or -keywords parameters triggers this behavior.

Important Limitations of Gen1 API:

• It only returns details for the first matching account found.
• If multiple accounts match, you will receive a warning: WARNING: X matching accounts found. Only the first result will be returned.

To retrieve all matching accounts and avoid the Gen1 API limitations, use the -SafeName parameter instead of -Safe.

# This triggers Gen1 API and returns only the first result
Get-PASAccount -Safe 3_TestSafe_028_XYJ

# This avoids Gen1 API and returns all matching results
Get-PASAccount -SafeName "3_TestSafe_028_XYJ"

To replace an existing platform with a new package, use the Update parameter set. This requires the -Force switch to confirm that you intend to overwrite the existing platform configuration.

Required Parameters:

• -PlatformId: The identifier of the existing platform you wish to update.
• -Force: A switch that must be present to allow the replacement of the existing platform.

Import-PASPlatform -PlatformId CustomApp -Force

psPAS includes built-in version awareness to ensure API compatibility:

• Automatic Version Detection: All logon functions attempt to query the CyberArk version and return the ExternalVersion as an output property.
• Skipping Version Checks: You can skip the automatic version check during logon by using the -SkipVersionCheck parameter.
• Version Assertions: Functions that require specific CyberArk features will check the detected version. If the version is too low, a descriptive error is thrown. If the version is unknown or the check was skipped, assertions are bypassed.
• Pipeline Compatibility: Because ExternalVersion is included in the output of functions, you can pass objects through the PowerShell pipeline and still perform version-based logic.

The Add-PASDiscoveryScan cmdlet accepts pipeline input by property name. You can pipe PSCustomObject instances that contain the following properties directly to the command:

• scanType
• scanCredentials
• managingScanner

Every psPAS command follows a consistent four-step lifecycle to ensure compatibility and reliability across different CyberArk environments:

1. Version Check: Validates that the current CyberArk API version supports the requested command or parameters.
2. Parameter Processing: Extracts relevant parameters from $PSBoundParameters, filtering out plumbing parameters (like -Verbose or -TimeoutSec) and converting them into URL query strings or request bodies.
3. Command Invocation: Sends the request via Invoke-PASRestMethod, which handles authentication (using the session from New-PASSession), TLS settings, and error normalization.
4. Output Formatting: Transforms the raw HTTP response into usable PowerShell objects (JSON to objects, or byte arrays for files) and handles pagination via Get-NextLink.

The Set-PASSafeMember cmdlet behaves differently based on the CyberArk API version being used.

Gen1 API

To force the use of the Gen1 API endpoint (required for CyberArk versions earlier than 12.2), use the -UseGen1API switch. In Gen1, you can also specify the authorization level using -RequestsAuthorizationLevel (valid values: 0, 1, or 2).

Gen2 API (Default)

Gen2 is the default. For Gen2, specific authorization level permissions are available if the CyberArk version is 12.2 or higher:

• -requestsAuthorizationLevel1: Boolean switch for level 1 permission.
• -requestsAuthorizationLevel2: Boolean switch for level 2 permission.

# Force Gen1 for older CyberArk versions
Set-PASSafeMember -SafeName "MySafe" -MemberName "User" -UseGen1API -RequestsAuthorizationLevel 1