Validate SSH Example + Extra documentation (#30)

ofiriluz · web-flow · commit 4ff3af4caacd · 2025-04-08T22:41:41.000+03:00
diff --git a/ark_sdk_python/common/ark_jwt_utils.py b/ark_sdk_python/common/ark_jwt_utils.py
@@ -10,3 +10,13 @@ def get_unverified_claims(token: str) -> Dict[str, Any]:
             token,
             options={'verify_signature': False},
         )
+
+    @staticmethod
+    def get_subdomain_from_token(token: str) -> str:
+        claims = ArkJWTUtils.get_unverified_claims(token)
+        return claims.get('subdomain', '')
+
+    @staticmethod
+    def get_platform_domain_from_token(token: str) -> str:
+        claims = ArkJWTUtils.get_unverified_claims(token)
+        return claims.get('platform_domain', '')
diff --git a/ark_sdk_python/common/connections/ssh/__init__.py b/ark_sdk_python/common/connections/ssh/__init__.py
@@ -1,3 +1,4 @@
+from ark_sdk_python.common.connections.ssh.ark_pty_ssh_connection import ArkPTYSSHConnection
 from ark_sdk_python.common.connections.ssh.ark_ssh_connection import SSH_PORT, ArkSSHConnection
 
-__all__ = ['ArkSSHConnection', 'SSH_PORT']
+__all__ = ['ArkSSHConnection', 'ArkPTYSSHConnection', 'SSH_PORT']
diff --git a/ark_sdk_python/common/connections/ssh/ark_pty_ssh_connection.py b/ark_sdk_python/common/connections/ssh/ark_pty_ssh_connection.py
@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Optional
+
+from overrides import overrides
+from pexpect import pxssh
+
+from ark_sdk_python.common.connections.ark_connection import ArkConnection
+from ark_sdk_python.common.connections.ssh.ark_ssh_connection import SSH_PORT
+from ark_sdk_python.models import ArkException
+from ark_sdk_python.models.common.connections import ArkConnectionCommand, ArkConnectionDetails, ArkConnectionResult
+
+
+class ArkPTYSSHConnection(ArkConnection):
+    __ANSI_STRIPPER: Any = re.compile(r'\x1b[^m]*m|\x1b\[\?2004[hl]')
+
+    def __init__(self):
+        super().__init__()
+        self.__is_connected: bool = False
+        self.__is_suspended: bool = False
+        self.__ssh_client: Optional[pxssh.pxssh] = None
+
+    @overrides
+    def connect(self, connection_details: ArkConnectionDetails) -> None:
+        """
+        Performs SSH connection with given details or keys
+        Saves the ssh session to be used for command executions
+
+        Args:
+            connection_details (ArkConnectionDetails): _description_
+
+        Raises:
+            ArkException: _description_
+        """
+        if self.__is_connected:
+            return
+        try:
+            target_port = SSH_PORT
+            user = None
+            if connection_details.port:
+                target_port = connection_details.port
+            credentials_map = {}
+            if connection_details.credentials:
+                user = connection_details.credentials.user
+                if connection_details.credentials.password:
+                    credentials_map['password'] = connection_details.credentials.password.get_secret_value()
+                elif connection_details.credentials.private_key_filepath:
+                    path = Path(connection_details.credentials.private_key_filepath)
+                    if not path.exists():
+                        raise ArkException(f'Given private key path [{path}] does not exist')
+                    credentials_map['ssh_key'] = connection_details.credentials.private_key_filepath
+            self.__ssh_client = pxssh.pxssh()
+            self.__ssh_client.login(
+                server=connection_details.address,
+                username=user,
+                port=target_port,
+                login_timeout=30,
+                **credentials_map,
+            )
+            self.__is_connected = True
+            self.__is_suspended = False
+        except Exception as ex:
+            raise ArkException(f'Failed to ssh connect [{str(ex)}]') from ex
+
+    @overrides
+    def disconnect(self) -> None:
+        """
+        Disconnects the ssh session
+        """
+        if not self.__is_connected:
+            return
+        self.__ssh_client.logout()
+        self.__ssh_client = None
+        self.__is_connected = False
+        self.__is_suspended = False
+
+    @overrides
+    def suspend_connection(self) -> None:
+        """
+        Suspends execution of ssh commands
+        """
+        self.__is_suspended = True
+
+    @overrides
+    def restore_connection(self) -> None:
+        """
+        Restores execution of ssh commands
+        """
+        self.__is_suspended = False
+
+    @overrides
+    def is_suspended(self) -> bool:
+        """
+        Checks whether ssh commands can be executed or not
+
+        Returns:
+            bool: _description_
+        """
+        return self.__is_suspended
+
+    @overrides
+    def is_connected(self) -> bool:
+        """
+        Checks whether theres a ssh session connected
+
+        Returns:
+            bool: _description_
+        """
+        return self.__is_connected
+
+    @overrides
+    def run_command(self, command: ArkConnectionCommand) -> ArkConnectionResult:
+        """
+        Runs a command over ssh session, returning the result accordingly
+
+        Args:
+            command (ArkConnectionCommand): _description_
+
+        Raises:
+            ArkException: _description_
+
+        Returns:
+            ArkConnectionResult: _description_
+        """
+        if not self.__is_connected or self.__is_suspended:
+            raise ArkException('Cannot run command while not being connected')
+        self._logger.debug(f'Running command [{command.command}]')
+        self.__ssh_client.sendline(command.command)
+        self.__ssh_client.prompt()
+        stdout = self.__ssh_client.before.decode()
+        self.__ssh_client.sendline('echo $?')
+        self.__ssh_client.prompt()
+        exit_code_output = self.__ssh_client.before.decode()
+        exit_code_output = ArkPTYSSHConnection.__ANSI_STRIPPER.sub('', exit_code_output)
+        rc = int(exit_code_output.strip().splitlines()[-1])
+        if rc != command.expected_rc and command.raise_on_error:
+            raise ArkException(f'Failed to execute command [{command.command}] - [{rc}] - [{stdout}]')
+        self._logger.debug(f'Command rc: [{rc}]')
+        self._logger.debug(f'Command stdout: [{stdout}]')
+        return ArkConnectionResult(stdout=stdout, rc=rc)
diff --git a/ark_sdk_python/examples/validate_ssh_connection.py b/ark_sdk_python/examples/validate_ssh_connection.py
@@ -0,0 +1,145 @@
+import argparse
+import tempfile
+
+from ark_sdk_python.auth import ArkISPAuth
+from ark_sdk_python.common.ark_jwt_utils import ArkJWTUtils
+from ark_sdk_python.common.connections.ssh.ark_pty_ssh_connection import ArkPTYSSHConnection
+from ark_sdk_python.models.auth import ArkAuthMethod, ArkAuthProfile, ArkSecret
+from ark_sdk_python.models.auth.ark_auth_method import IdentityServiceUserArkAuthMethodSettings
+from ark_sdk_python.models.common.connections.ark_connection_command import ArkConnectionCommand
+from ark_sdk_python.models.common.connections.ark_connection_credentials import ArkConnectionCredentials
+from ark_sdk_python.models.common.connections.ark_connection_details import ArkConnectionDetails
+from ark_sdk_python.models.services.sia.sso.ark_sia_sso_get_ssh_key import ArkSIASSOGetSSHKey
+from ark_sdk_python.services.sia.sso import ArkSIASSOService
+
+
+def login_to_identity_security_platform(service_user: str, service_token: str, application_name: str) -> ArkISPAuth:
+    """
+    This will perform login to the tenant with the given service user credentials
+    Caching the logged in token is disabled and will perform a full login on each call
+    Will return an identity security platform authenticated class
+
+    Args:
+        service_user (str): _description_
+        service_token (str): _description_
+        application_name (str): _description_
+
+    Returns:
+        ArkISPAuth: _description_
+    """
+    print('Logging in to the tenant')
+    isp_auth = ArkISPAuth(cache_authentication=False)
+    isp_auth.authenticate(
+        auth_profile=ArkAuthProfile(
+            username=service_user,
+            auth_method=ArkAuthMethod.IdentityServiceUser,
+            auth_method_settings=IdentityServiceUserArkAuthMethodSettings(identity_authorization_application=application_name),
+        ),
+        secret=ArkSecret(secret=service_token),
+    )
+    print('Logged in successfully')
+    return isp_auth
+
+
+def construct_ssh_proxy_address(isp_auth: ArkISPAuth) -> str:
+    """
+    For a given authentication, construct the SSH proxy address
+    This'll grab from the ID token of the logged in user the name of the tenant (subdomain)
+    And the platform domain (cyberark.cloud)
+    And will concatenante everything to construct the SSH proxy address
+    will return the constructed ssh proxy address
+
+    Args:
+        isp_auth (ArkISPAuth): _description_
+
+    Returns:
+        str: _description_
+    """
+    token = isp_auth.token.token.get_secret_value()
+    return f'{ArkJWTUtils.get_subdomain_from_token(token)}.ssh.{ArkJWTUtils.get_platform_domain_from_token(token)}'
+
+
+def generate_mfa_caching_ssh_key(isp_auth: ArkISPAuth, folder: str) -> str:
+    """
+    This function will use the logged in user
+    And generate an SSH key into a given folder
+    Will return the path to the SSH key
+
+    Args:
+        isp_auth (ArkISPAuth): _description_
+        temp_folder (str): _description_
+
+    Returns:
+        str: _description_
+    """
+    print('Generating SSH MFA Caching Key')
+    sso_service = ArkSIASSOService(isp_auth=isp_auth)
+    path = sso_service.short_lived_ssh_key(get_ssh_key=ArkSIASSOGetSSHKey(folder=folder))
+    print(f'MFA Caching SSH Key generated to [{path}]')
+    return path
+
+
+def connect_and_validate_connection(ssh_key_path: str, proxy_address: str, connection_string: str, command: str) -> None:
+    """
+    This function will perform a connection via SSH and via SIA proxy to the target
+    For the given proxy address and connection string, a connection will be made with the ssh key
+    Once connected, the given command will be performed, expecting a return code of 0 as success
+
+    Args:
+        ssh_key_path (str): _description_
+        proxy_address (str): _description_
+        connection_string (str): _description_
+        command (str): _description_
+    """
+    print(f'Connecting to proxy [{proxy_address}] and connection string [{connection_string}]')
+    ssh_connection = ArkPTYSSHConnection()
+    ssh_connection.connect(
+        ArkConnectionDetails(
+            address=proxy_address,
+            credentials=ArkConnectionCredentials(
+                user=connection_string,
+                private_key_filepath=ssh_key_path,
+            ),
+        ),
+    )
+    print(f'Running test command [{command}]')
+    ssh_connection.run_command(
+        ArkConnectionCommand(command=command, expected_rc=0),
+    )
+    print('Finished Successfully!')
+
+
+if __name__ == '__main__':
+    # Construct an argument parser for CLI parameters for the script
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--service-user', required=True, help='Service user to login and perform the operation with')
+    parser.add_argument('--service-token', required=True, help='Service user token to use for logging in and connecting')
+    parser.add_argument(
+        '--service-application',
+        default='__idaptive_cybr_user_oidc',
+        help='Service application to login to, defaults to cyberark ISP application',
+    )
+    parser.add_argument(
+        '--connection-string',
+        required=True,
+        help='SSH connection string to use for the connection, without the proxy address.'
+        'A connection string may look like the following'
+        '<service-user>#<tenant_subdomain>@<target_user>@<target_address>#<optional_network_name>',
+    )
+    parser.add_argument('--test-command', default='ls -l', help='Test command to use once connected to the target, defaults to ls -l')
+
+    # Parse the CLI parameters
+    args = parser.parse_args()
+
+    # Construct a temporary folder to be used for the MFA Caching SSH key generation
+    # At the end of the execution, the temporary folder will be deleted alongside the SSH key
+    with tempfile.TemporaryDirectory() as temp_folder:
+        # Perform the flow:
+        # - Login to the tenant
+        # - Generate an MFA Caching SSH key
+        # - Construct the ssh proxy address
+        # - Connect in SSH to the proxy / target with the MFA Caching SSH Key and perform the command
+        isp_auth = login_to_identity_security_platform(args.service_user, args.service_token, args.service_application)
+        ssh_key_path = generate_mfa_caching_ssh_key(isp_auth, temp_folder)
+        proxy_address = construct_ssh_proxy_address(isp_auth)
+        connect_and_validate_connection(ssh_key_path, proxy_address, args.connection_string, args.test_command)
diff --git a/docs/examples/commands_examples.md b/docs/examples/commands_examples.md
@@ -125,6 +125,21 @@ ark_public exec sia secrets vm add-secret --secret-type ProvisionerUser --provis
 ark exec sia access connector-setup-script -ct onprem -co windows -cpi 588741d5-e059-479d-b4c4-3d821a87f012
 ```
 
+### Install a DPA Windows Connector Remotely
+```shell
+ark exec sia access install-connector --connector-pool-id abcd --connector-type onprem --connector-os windows --target-machine 1.2.3.4 --username myuser --password mypassword
+```
+
+### Install a DPA Linux Connector Remotely
+```shell
+ark exec sia access install-connector --connector-pool-id abcd --connector-type aws --connector-os linux --target-machine 1.2.3.4 --username ec2-user --private-key-path /path/to/key.pem
+```
+
+### Delete and uninstall a DPA Connector
+```shell
+ark exec sia access delete-connector --connector-id=CMSConnector_e9685e0d-a92e-4097-ad4d-b54eadb69bcb_81fa03c5-d0d3-4157-95f8-6a1903900fa0 --uninstall-connector --target-machine 1.2.3.4 --username ec2-user --private-key-path /path/to/key.pem
+```
+
 ### List All Session Monitoring sessions from the last 24 hours
 ```shell
 ark exec sm list-sessions
@@ -237,5 +252,15 @@ ark exec pcloud platforms list-platforms
 
 ### List CMGR connector pools
 ```shell
-ark exec exec cmgr list-pools
+ark exec cmgr list-pools
+```
+
+### Add CMGR network
+```shell
+ark exec cmgr add-network --name mynetwork
+```
+
+### Add CMGR connector pool
+```shell
+ark exec cmgr add-pool --name mypool --assigned-network-ids mynetwork_id
 ```
diff --git a/docs/howto/install_sia_connectors.md b/docs/howto/install_sia_connectors.md
@@ -0,0 +1,36 @@
+---
+title: Install SIA connectors
+description: Install SIA connectors
+---
+
+# Install SIA connectors
+Here is an example workflow for installing a connector on a linux / windows box:
+
+1. Install Ark SDK: `pip3 install ark-sdk-python`
+1. Create a profile:  
+    * Interactively:
+        ```shell linenums="0"
+        ark configure
+        ```
+    * Silently:
+        ```shell linenums="0"
+        ark configure --silent --work-with-isp --isp-username myuser
+        ```
+1. Log in to Ark:
+    ```shell linenums="0"
+    ark login --silent --isp-secret <my-ark-secret>
+    ```
+1. Create a network and connector pool:
+    ```shell linenums="0"
+    ark exec cmgr add-network --name mynetwork
+    ark exec cmgr add-pool --name mypool --assigned-network-ids mynetwork_id
+    ```
+1. Install a connector:
+    * Windows:
+        ```shell linenums="0"
+        ark exec sia access install-connector --connector-pool-id mypool_id --connector-type onprem --connector-os windows --target-machine 1.2.3.4 --username myuser --password mypassword
+        ```
+    * Linux:
+        ```shell linenums="0"
+        ark exec sia access install-connector --connector-pool-id mypool_id --connector-type aws --connector-os linux --target-machine 1.2.3.4 --username ec2-user --private-key-path /path/to/key.pem
+        ```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -16,6 +16,7 @@ nav:
       - End-user Kubernetes workflow: howto/enduser_kubernetes_workflow.md
       - End-user SSH workflow: howto/enduser_ssh_workflow.md
       - End-user RDP workflow: howto/enduser_rdp_workflow.md
+      - Install SIA connectors: howto/install_sia_connectors.md
       - Simple commands workflow: howto/simple_commands_workflow.md
       - Simple SDK workflow: howto/simple_sdk_workflow.md
       - Refresh authentication: howto/refreshing_authentication.md
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
