📜Documentation
CyberArk's Official SDK and CLI for different services operations
- Extensive and Interactive CLI
-
Different Authenticators
- Identity Authentication Methods
- MFA Support for Identity
- Identity Security Platform
-
Services API
- DPA VM / Databases Policies and Policies Interactive Editor Service
- DPA Databases Onboarding
- DPA Databases Secrets
- DPA Certificates Service
- DPA SSO Service
- DPA K8S Service
- DPA DB Service
- Session Monitoring Service
- Identity Users Service
- Identity Roles Service
- Identity Policies Service
- Identity Directories Service
- PCloud Accounts Service
- PCloud Safes Service
- PCloud Platforms Service
- All services contains CRUD and Statistics per respective service
- Ready to use SDK in Python
- CLI and SDK Examples
-
Fully Interactive CLI comprising of 3 main actions
- Configure
- Login
- Exec
- Filesystem Inputs and Outputs for the CLI
- Silent and Verbose logging
- Profile Management and Authentication Caching
One can install the SDK via the community pypi with the following command:
pip3 install ark-sdk-pythonBoth the SDK and the CLI works with profiles
The profiles can be configured upon need and be used for the consecutive actions
The CLI has the following basic commands:
- configure - Configures profiles and their respective authentication methods
- login - Logs into the profile authentication methods
- exec - Executes different commands based on the supported services
- profiles - Manage multiple profiles on the machine
The configure command is used to create a profile to work on
The profile consists of infomration regarding which authentication methods to use and what are their method settings, along with other related information such as MFA
How to run:
ark configureThe profiles are saved to ~/.ark_profiles
No arguments are required, and interactive questions will be asked
If you wish to only supply arguments in a silent fashion, --silent can be added along with the arugments
Usage:
usage: ark configure [-h] [-r] [-s] [-ao] [-v] [-ls {default}] [-ll {DEBUG,INFO,WARN,ERROR,CRITICAL}]
[-dcv] [-tc TRUSTED_CERT] [-pn PROFILE_NAME] [-pd PROFILE_DESCRIPTION] [-wwis]
[-isam {identity,identity_service_user}] [-iu ISP_USERNAME]
[-iimm {pf,sms,email,otp}] [-iiu ISP_IDENTITY_URL]
[-iiaa ISP_IDENTITY_AUTHORIZATION_APPLICATION]
optional arguments:
-h, --help show this help message and exit
-r, --raw Whether to raw output
-s, --silent Silent execution, no interactiveness
-ao, --allow-output Allow stdout / stderr even when silent and not interactive
-v, --verbose Whether to verbose log
-ls {default}, --logger-style {default}
Which verbose logger style to use
-ll {DEBUG,INFO,WARN,ERROR,CRITICAL}, --log-level {DEBUG,INFO,WARN,ERROR,CRITICAL}
Log level to use while verbose
-dcv, --disable-cert-verification
Disables certificate verification on HTTPS calls, unsafe!
-tc TRUSTED_CERT, --trusted-cert TRUSTED_CERT
Certificate to use for HTTPS calls
-pn PROFILE_NAME, --profile-name PROFILE_NAME
Profile name for storage
-pd PROFILE_DESCRIPTION, --profile-description PROFILE_DESCRIPTION
Info about the profile
-wwis, --work-with-isp
Whether to work with Identity Security Platform services
-isam {identity,identity_service_user}, --isp-auth-method {identity,identity_service_user}
-iu ISP_USERNAME, --isp-username ISP_USERNAME
Username to authenticate with
-iimm {pf,sms,email,otp}, --isp-identity-mfa-method {pf,sms,email,otp}
MFA method if mfa is needed
-iiu ISP_IDENTITY_URL, --isp-identity-url ISP_IDENTITY_URL
Identity url to use for authentication instead of fqdn resolving
-iiaa ISP_IDENTITY_AUTHORIZATION_APPLICATION, --isp-identity-authorization-application ISP_IDENTITY_AUTHORIZATION_APPLICATION
Identity application to authorize once logged in with the service userThe logn command is used to login to the authentication methods configured for the profile
You will be asked to write a password for each respective authentication method that supports password, and alongside that, any needed MFA prompt
Once the login is done, the access tokens are stored on the computer keystore for their lifetime
Once they are expired, a consecutive login will be required
How to run:
ark loginUsage:
usage: ark login [-h] [-r] [-s] [-ao] [-v] [-ls {default}] [-ll {DEBUG,INFO,WARN,ERROR,CRITICAL}]
[-dcv] [-tc TRUSTED_CERT] [-pn PROFILE_NAME] [-f] [-nss] [-st] [-ra]
[-isu ISP_USERNAME] [-iss ISP_SECRET]
optional arguments:
-h, --help show this help message and exit
-r, --raw Whether to raw output
-s, --silent Silent execution, no interactiveness
-ao, --allow-output Allow stdout / stderr even when silent and not interactive
-v, --verbose Whether to verbose log
-ls {default}, --logger-style {default}
Which verbose logger style to use
-ll {DEBUG,INFO,WARN,ERROR,CRITICAL}, --log-level {DEBUG,INFO,WARN,ERROR,CRITICAL}
Log level to use while verbose
-dcv, --disable-cert-verification
Disables certificate verification on HTTPS calls, unsafe!
-tc TRUSTED_CERT, --trusted-cert TRUSTED_CERT
Certificate to use for HTTPS calls
-pn PROFILE_NAME, --profile-name PROFILE_NAME
Profile name to load
-f, --force Whether to force login even thou token has not expired yet
-nss, --no-shared-secrets
Do not share secrets of identity between different authenticators with the
same username
-st, --show-tokens Print out tokens as well if not silent
-ra, --refresh-auth If a cache exists, will also try to refresh it
-isu ISP_USERNAME, --isp-username ISP_USERNAME
Username to authenticate with to Identity Security Platform
-iss ISP_SECRET, --isp-secret ISP_SECRET
Secret to authenticate with to Identity Security PlatformNotes:
- You may disable certificate validation for login to different authenticators using the --disable-certificate-verification or supply a certificate to be used, not recommended to disable
The exec command is used to execute various commands based on supported services for the fitting logged in authenticators
The following services and commands are supported:
-
dpa - Dynamic Privilege Access Services
-
policies - DPA Policies Management
-
vm - DPA VM Policies Service
- editor - DPA Policies Interactive Editor
-
db - DPA DB Policies Service
- editor - DPA Policies Interactive Editor
-
vm - DPA VM Policies Service
-
workspaces - DPA Workspaces Management
- db - DPA DB Workspace Service
-
secrets - DPA Secrets / Strong Accounts Management
- db - DPA DB Secrets Service
- certificates - DPA Certificates Management
- db - DPA DB Enduser Operations
- sso - DPA SSO Enduser Operations
- k8s - DPA kubernetes service
-
policies - DPA Policies Management
- sm - Session Monitoring Service
-
identity - Identity Service
- users - Identity Users Management
- roles - Identity Roles Management
- policies - Identity Policies Management
- directories - Identity Directories Reading
-
pcloud - PCloud Service
- accounts - PCloud Accounts Management
- safes - PCloud Safes Management
- platforms - PCloud Platforms Management
Any command has its own subcommands, with respective arguments
For example configure a profile to login to that respective tenant and perform DPA actions such as:
Add DPA Database Secret
ark exec dpa secrets db add-secret --secret-name mysecret --secret-type username_password --username user --password mypassDelete DPA Database Secret
ark exec dpa secrets db delete-secret --secret-name mysecretAdd DPA Database
ark exec dpa workspaces db add-database --name mydb --provider-engine postgres-sh --read-write-endpoint myendpoint.domain.comList DPA Databases
ark exec dpa workspaces db list-databasesGet VM policies stats
ark exec dpa policies vm policies-statsEdit policies interactively
This gives the ability to locally work with a policies workspace, and edit / reset / create policies, applied to both databases and vm policies
When they are ready, once can commit all the policies changes to the remote
Initially, the policies can be loaded and reloaded using
ark exec dpa policies vm editor load-policiesOnce they are loaded locally, they can be edited using the following commands
ark exec dpa policies vm editor edit-policies
ark exec dpa policies vm editor view-policies
ark exec dpa policies vm editor reset-policies
ark exec dpa policies vm editor generate-policy
ark exec dpa policies vm editor remove-policies
ark exec dpa policies vm editor policies diffEvantually, they can be committed using
ark exec dpa policies vm editor commit-policiesGenerate a short lived SSO password for databases connection
ark exec dpa sso short-lived-passwordGenerate a short lived SSO oracle wallet for oracle database connection
ark exec dpa sso short-lived-oracle-wallet --folder ~/walletGenerate kubectl config file
ark exec dpa k8s generate-kubeconfig Generate kubectl config file and save on specific path
ark exec dpa k8s generate-kubeconfig --folder=/Users/My.User/.kubeCreate a PCloud Safe
ark exec pcloud safes add-safe --safe-name=safeCreate a PCloud Account
ark exec pcloud accounts add-account --name account --safe-name safe --platform-id='UnixSSH' --username root --address 1.2.3.4 --secret-type=password --secret mypassList available platforms
ark exec pcloud platforms list-platformsYou can view all of the commands via the --help for each respective exec action
Notes:
- You may disable certificate validation for login to different authenticators using the --disable-certificate-verification or supply a certificate to be used, not recommended to disable
Usafe Env Vars:
- ARK_PROFILE - Sets the profile to be used across the CLI
- ARK_DISABLE_CERTIFICATE_VERIFICATION - Disables certificate verification on REST API's
As one may have multiple environments to manage, this would also imply that multiple profiles are required, either for multiple users in the same environment or multiple tenants
Therefore, the profiles command manages those profiles as a convenice set of methods
Using the profiles as simply running commands under:
ark profilesUsage:
usage: ark profiles [-h] [-r] [-s] [-ao] [-v] [-ls {default}] [-ll {DEBUG,INFO,WARN,ERROR,CRITICAL}] [-dcv]
[-tc TRUSTED_CERT]
{list,show,delete,clear,clone,add} ...
positional arguments:
{list,show,delete,clear,clone,add}
list List all profiles
show Show a profile
delete Delete a specific profile
clear Clear all profiles
clone Clones a profile
add Adds a profile to the profiles folder from a given path
optional arguments:
-h, --help show this help message and exit
-r, --raw Whether to raw output
-s, --silent Silent execution, no interactiveness
-ao, --allow-output Allow stdout / stderr even when silent and not interactive
-v, --verbose Whether to verbose log
-ls {default}, --logger-style {default}
Which verbose logger style to use
-ll {DEBUG,INFO,WARN,ERROR,CRITICAL}, --log-level {DEBUG,INFO,WARN,ERROR,CRITICAL}
Log level to use while verbose
-dcv, --disable-cert-verification
Disables certificate verification on HTTPS calls, unsafe!
-tc TRUSTED_CERT, --trusted-cert TRUSTED_CERT
Certificate to use for HTTPS callsAs well as using the CLI, one can also develop under the ark sdk using its API / class driven design
The same idea as the CLI applies here as well
For example, let's say we want to create a demo environment containing all needed DPA DB assets
To do so, we can use the following script:
ArkSystemConfig.disable_verbose_logging()
# Authenticate to the tenant with an auth profile to configure DPA
username = 'user@cyberark.cloud.12345'
print(f'Authenticating to the created tenant with user [{username}]')
isp_auth = ArkISPAuth()
isp_auth.authenticate(
auth_profile=ArkAuthProfile(
username=username, auth_method=ArkAuthMethod.Identity, auth_method_settings=IdentityArkAuthMethodSettings()
),
secret=ArkSecret(secret='CoolPassword'),
)
# Create DPA DB Secret, Database, Connector and DB Policy
dpa_service = ArkDPAAPI(isp_auth)
print('Adding DPA DB User Secret')
secret = dpa_service.secrets_db.add_secret(
ArkDPADBAddSecret(secret_type=ArkDPADBSecretType.UsernamePassword, username='Administrator', password='CoolPassword')
)
print('Adding DPA Database')
dpa_service.workspace_db.add_database(
ArkDPADBAddDatabase(
name='mydomain.com',
provider_engine=ArkDPADBDatabaseEngineType.PostgresSH,
secret_id=secret.secret_id,
read_write_endpoint="myendpoint.mydomain.com",
)
)
print('Adding DPA DB Policy')
dpa_service.policies_db.add_policy(
ArkDPADBAddPolicy(
policy_name='IT Policy',
status=ArkDPARuleStatus.Active,
description='IT Policy',
providers_data=ArkDPADBProvidersData(
postgres=ArkDPADBPostgres(
resources=['postgres-onboarded-asset'],
),
),
user_access_rules=[
ArkDPADBAuthorizationRule(
rule_name='IT Rule',
user_data=ArkDPAUserData(roles=['DpaAdmin'], groups=[], users=[]),
connection_information=ArkDPADBConnectionInformation(
grant_access=2,
idle_time=10,
full_days=True,
hours_from='07:00',
hours_to='17:00',
time_zone='Asia/Jerusalem',
connect_as=ArkDPADBConnectAs(
db_auth=[
ArkDPADBLocalDBAuth(
roles=['rds_superuser'],
applied_to=[
ArkDPADBAppliedTo(
name='postgres-onboarded-asset',
type=ArkDPADBResourceIdentifierType.RESOURCE,
)
],
),
],
),
),
)
],
)
)More examples can be found in the examples folder
This project is licensed under Apache License 2.0 - see LICENSE for more details
Copyright (c) 2023 CyberArk Software Ltd. All rights reserved.
