pyaim 1.5.4

CyberArk Application Access Manager Client Library for Python 3

pyAIM

CyberArk Application Access Manager Client Library for Python 3

This project simplifies the interaction between a Python 3 application or script and CyberArk's Application Access Manager's Credential Provider using the appropriate CLIPasswordSDK executable for the Operating System being used. By simplifying this process, developers are only required to change four (4) lines of code in their Python 3 applications and scripts to securely retrieve privileged secrets from CyberArk's Privileged Access Security (PAS) Core Solution as opposed to thirty or more (30+) without the use of this provided Client Library.

Table of Contents

• Install
  • Credential Provider (CLIPasswordSDK) Method
  • Centralized Credential Provider (CCPPasswordREST) Method
  • Windows
    • Install Latest Python 3
    • Install pyAIM via Pip
  • Linux
    • Ubuntu/Debian
      • Install Latest Python 3
      • Install pyAIM via Pip
    • RHEL/CentOS
      • Install Latest Python 3
        • RHEL
        • CentOS
      • Install pyAIM via Pip
  • MacOS
  • Z/OS
    • Install Latest Python 3
    • Install pyAIM via Pip
• Usage
  • Check AIMWebService Availability - check_service()
    • Centralized Credential Provider (CCPPasswordREST) Method
  • Retrieve Account - GetPassword()
    • Credential Provider (CLIPasswordSDK) Method
      • Supported Parameters
        • Query Parameters
      • Example
    • Centralized Credential Provider (CCPPasswordREST) Method
      • Supported Parameters
        • CCPPasswordREST()
        • Query Parameters
      • Example
      • Example with Client Certificate Authentication
      • Example with Custom Service Path
• Maintainer
• Contributing
• License

Install

Credential Provider (CLIPasswordSDK) Method

• CyberArk Application Access Manager Credential Provider installed locally.

Centralized Credential Provider (CCPPasswordREST) Method

• CyberArk Application Access Manager Centralized Credential Provider and AIMWebService

For information on how to install either of these providers, please refer to CyberArk's Application Access Manager Installation Guide or reach out to your assigned Customer Success Technical Advisor.

Windows

Install Latest Python 3

Install the Python 3 release for Windows

Install pyAIM via Pip

> pip3 install pyaim

Linux

Ubuntu/Debian

Install Latest Python 3

$ sudo apt install -y python3 python3-pip

Install pyAIM via Pip

$ pip3 install pyaim

RHEL/CentOS

Install Latest Python 3

RHEL

Follow the EPEL Documentation to ensure you have the EPEL Release repository available.

$ sudo yum install -y https://rhel7.iuscommunity.org/ius-release.rpm

$ sudo yum update

$ sudo yum install -y python36u python36u-libs python36u-devel python36u-pip

CentOS

$ sudo yum install -y https://centos7.iuscommunity.org/ius-release.rpm

$ sudo yum update

$ sudo yum install -y python36u python36u-libs python36u-devel python36u-pip

Install pyAIM via Pip

$ pip3 install pyaim

MacOS

No support provided yet.

Z/OS

pyAIM is untested on Z/OS but should work in theory.

Install Latest Python 3

Rocket Software has ported Python 2 and 3 for Z/OS

Install pyAIM via Pip

$ pip3 install pyaim

Usage

Check AIM Web Service - check_service()

⚠️ Important: In production mode (default), check_service() validates local configuration without making API calls to avoid generating CCP logs. For actual service health checks, use GetPassword() with test credentials.

Centralized Credential Provider (CCPPasswordREST) Method

Configuration Validation (No API Call)

from pyaim import CCPPasswordREST

# Validates configuration locally without contacting CCP
aimccp = CCPPasswordREST('https://ccp.cyberarkdemo.example', verify=True)
config_status = aimccp.check_service()
print(config_status)
# Output: "Configuration validated for ccp.cyberarkdemo.example/AIMWebService. Use GetPassword() to verify service health."

Production Health Check (Recommended)

from pyaim import CCPPasswordREST

aimccp = CCPPasswordREST('https://ccp.cyberarkdemo.example', verify=True)

# Health check using actual credential retrieval
try:
    response = aimccp.GetPassword(
        appid='monitoring_appid',
        safe='health_check_safe',
        object='health_check_account'
    )
    print("✓ CCP service is healthy and accessible")
    print(f"Retrieved account: {response.get('Username', 'N/A')}")
except ConnectionError as e:
    print(f"✗ CCP service unhealthy: {e}")
    # Handle service down/unreachable scenario
except ValueError as e:
    print(f"✗ Configuration error: {e}")
    # Handle parameter validation errors
except Exception as e:
    print(f"✗ CCP error: {e}")
    # Handle other errors

Retrieve Account - GetPassword()

Credential Provider (CLIPasswordSDK) Method

Supported Parameters

Query Parameters

• appid (required)
• safe (required)
• folder (default: root)
• object (this or username required)
• username (this or object required)
• address
• database
• policyid
• reason
• query_format (default: 1)
• connport
• sendhash (default: False)
• output (default: Password)
• delimiter (default: ,)
• dual_accounts (default: False)

For compatibility with Dual Accounts where you are referencing a VirtualUsername - use the username parameter and ensure dual_accounts=True.

Example

from pyaim import CLIPasswordSDK

aimcp = CLIPasswordSDK('/opt/CARKaim/sdk/clipasswordsdk')
response = aimcp.GetPassword(appid='appID',safe='safeName',object='objectName',output='PassProps.Username,Password',delimiter='|')

print('Full Response: {}'.format(response))
print('Username: {}'.format(response['PassProps.Username']))
print('Password: {}'.format(response['Password']))

Centralized Credential Provider (CCPPasswordREST) Method

Supported Parameters

CCPPasswordREST()

• url (required)
• verify (default: True) - SSL certificate verification. Accepts:
  • True - Use system's default certificate bundle
  • False - Disable SSL verification (not recommended for production)
  • /path/to/cert.pem - Path to custom certificate bundle file
  • /path/to/cert/dir - Path to directory containing certificates (must be processed with c_rehash)
• cert (default: None)
• timeout (default: 30)

Query Parameters

• appid (required)
• safe (required)
• folder (default: root)
• object (this or username required)
• username (this or object required)
• address
• database
• policyid
• reason
• query_format (default: exact)
• dual_accounts (default: False)

For compatibility with Dual Accounts where you are referencing a VirtualUsername - use the username parameter and ensure dual_accounts=True.

Example

from pyaim import CCPPasswordREST

# set verify=False to ignore SSL
aimccp = CCPPasswordREST('https://ccp.cyberarkdemo.example', 'AIMWebService', verify=True, timeout=10)

service_status = aimccp.check_service()

if service_status == 'SUCCESS: AIMWebService Found. Status Code: 200':
    response = aimccp.GetPassword(appid='appid',safe='safe',object='objectName',reason='Reason message')
    print('Full Python Object: {}'.format(response))
    print('Username: {}'.format(response['Username']))
    print('Password: {}'.format(response['Content']))
else:
    raise Exception(service_status)

Example with Client Certificate Authentication

from pyaim import CCPPasswordREST

# set verify=False to ignore SSL
aimccp = CCPPasswordREST('https://ccp.cyberarkdemo.example', verify=True, cert=('/path/to/cert.pem', '/path/to/key.pem'))

...

Example with Custom Service Path

from pyaim import CCPPasswordREST

# set verify=False to ignore SSL
aimccp = CCPPasswordREST('https://ccp.cyberarkdemo.example', 'AIMWebServiceDEV', verify=True)

...

Example with Custom Certificate Bundle

from pyaim import CCPPasswordREST

# Use custom certificate bundle for SSL verification
aimccp = CCPPasswordREST('https://ccp.cyberarkdemo.example', verify='/path/to/custom-ca-bundle.pem')

# Or use a directory of certificates
aimccp = CCPPasswordREST('https://ccp.cyberarkdemo.example', verify='/etc/ssl/certs')

# Validate configuration
config_status = aimccp.check_service()
print(config_status)

# Actual credential retrieval
response = aimccp.GetPassword(appid='appid',safe='safe',object='objectName',reason='Reason message')
print('Username: {}'.format(response['Username']))
print('Password: {}'.format(response['Content']))

Health Check Best Practices

Why GetPassword() for Health Checks?

The GetPassword() method is the recommended approach for health checking because:

1. No False Logs: Doesn't generate error logs in CCP with blank AppID/query fields
2. Real Validation: Actually tests the full authentication and retrieval flow
3. Production Ready: Uses legitimate credentials, avoiding synthetic health check calls
4. Actionable Errors: Provides specific error messages for troubleshooting

Setting Up Health Check Accounts

Create a dedicated account in CCP for health monitoring:

1. Create a safe called health_check_safe (or similar)
2. Store a test account called health_check_account with a known password
3. Create an AppID called monitoring_appid with read-only access to the safe
4. Use these credentials in your health check scripts

Benefits of this approach:

• Uses real CCP functionality
• Generates legitimate, filterable audit logs
• Provides accurate service status
• Allows alert suppression based on AppID if needed

Migration from Legacy check_service()

If upgrading from versions < 1.5.4 that relied on check_service() for actual health checks:

1. Replace check_service() calls with GetPassword() using test credentials
2. Set up dedicated health check AppID and safe (see above)
3. Configure monitoring to catch ConnectionError exceptions for service down alerts
4. Update alert filtering to use the new health check AppID instead of generic error patterns

Security Best Practices

SSL Certificate Configuration

Production Environments (Recommended)

# Use system's default certificate bundle (most secure)
aimccp = CCPPasswordREST('https://ccp.company.com', verify=True)

# Use custom CA bundle for internal certificates
aimccp = CCPPasswordREST('https://ccp.company.com', verify='/etc/ssl/certs/company-ca.pem')

# Use certificate directory (ensure proper permissions)
aimccp = CCPPasswordREST('https://ccp.company.com', verify='/etc/ssl/certs/')

Certificate File Security

File Permissions:

# Certificate files should be readable by application only
chmod 600 /path/to/cert.pem
chmod 600 /path/to/key.pem

# Certificate directories should have restricted access
chmod 755 /etc/ssl/certs/
chmod 600 /etc/ssl/certs/*

Important Security Notes:

• ⚠️ Never use verify=False in production - this disables SSL certificate validation
• 🔒 Protect private key files - ensure only the application user can read them
• 📋 Regular certificate rotation - monitor certificate expiration dates
• 🔐 Use client certificates for additional authentication when available

Troubleshooting SSL Issues

Common SSL Errors and Solutions:

1. Certificate Verification Failed

   Error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
   Solution: Use custom CA bundle or check certificate chain
   

2. Certificate Path Issues

   Error: Certificate path does not exist: /path/to/cert
   Solution: Verify file exists and has correct permissions
   

3. Corporate Firewalls/Proxies

   # For environments with corporate certificates
   aimccp = CCPPasswordREST(
       'https://ccp.company.com',
       verify='/etc/ssl/certs/corporate-bundle.pem'
   )
   

AppID Security

Health Check AppID Configuration:

• Create dedicated AppID for monitoring (e.g., monitoring_appid)
• Grant read-only access to health check safe only
• Use specific safe permissions rather than broad access
• Monitor AppID usage through CCP audit logs
• Rotate credentials according to security policy

Example Secure Setup:

# Production health check with dedicated, limited-privilege AppID
try:
    response = aimccp.GetPassword(
        appid='health_monitor_readonly',  # Limited scope AppID
        safe='monitoring_safe',           # Dedicated safe for health checks
        object='health_check_account',    # Non-sensitive test account
        reason='Automated health check'   # Clear audit trail
    )
    # Service healthy
except ConnectionError as e:
    # Log security-relevant connection issues
    logger.error(f"CCP health check failed: {e}")

Maintainer

@infamousjoeg

Contributing

Contributions are open! Check out CONTRIBUTING.md for more details!

License

MIT