cloudx-proxy 2025.3.0__py3-none-any.whl

cloudx_proxy/__init__.py

@@ -0,0 +1,6 @@
+"""CloudX Client - Connect to EC2 instances via SSM for VSCode Remote SSH."""
+
+from .core import CloudXClient
+from ._version import __version__
+
+__all__ = ["CloudXClient", "__version__"]

cloudx_proxy/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '2025.3.0'
+__version_tuple__ = version_tuple = (2025, 3, 0)

cloudx_proxy/cli.py

@@ -0,0 +1,41 @@
+import os
+import sys
+import click
+from .core import CloudXClient
+
+@click.command()
+@click.argument('instance_id')
+@click.argument('port', type=int, default=22)
+@click.option('--profile', default='vscode', help='AWS profile to use (default: vscode)')
+@click.option('--region', help='AWS region (default: from profile, or eu-west-1 if not set)')
+@click.option('--key-path', help='Path to SSH public key (default: ~/.ssh/vscode/vscode.pub)')
+@click.option('--aws-env', help='AWS environment directory (default: ~/.aws, use name of directory in ~/.aws/aws-envs/)')
+def main(instance_id: str, port: int, profile: str, region: str, key_path: str, aws_env: str):
+    """CloudX Client - Connect to EC2 instances via SSM for VSCode Remote SSH.
+    
+    INSTANCE_ID is the EC2 instance ID to connect to (e.g., i-0123456789abcdef0)
+    
+    Example usage:
+        uvx cloudx-client i-0123456789abcdef0 22
+        uvx cloudx-client i-0123456789abcdef0 22 --profile myprofile --region eu-west-1
+        uvx cloudx-client i-0123456789abcdef0 22 --aws-env prod
+    """
+    try:
+        client = CloudXClient(
+            instance_id=instance_id,
+            port=port,
+            profile=profile,
+            region=region,
+            public_key_path=key_path,
+            aws_env=aws_env
+        )
+        
+        if not client.connect():
+            sys.exit(1)
+            
+    except Exception as e:
+        print(f"Error: {str(e)}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

cloudx_proxy/core.py

@@ -0,0 +1,189 @@
+import os
+import sys
+import time
+from pathlib import Path
+import boto3
+from botocore.exceptions import ClientError
+
+class CloudXClient:
+    def __init__(self, instance_id: str, port: int = 22, profile: str = "vscode", 
+                 region: str = None, public_key_path: str = None, aws_env: str = None):
+        """Initialize CloudX client for SSH tunneling via AWS SSM.
+        
+        Args:
+            instance_id: EC2 instance ID to connect to
+            port: SSH port number (default: 22)
+            profile: AWS profile to use (default: "vscode")
+            region: AWS region (default: from profile)
+            public_key_path: Path to SSH public key (default: ~/.ssh/vscode/vscode.pub)
+            aws_env: AWS environment directory (default: None, uses ~/.aws)
+        """
+        self.instance_id = instance_id
+        self.port = port
+        self.profile = profile
+        
+        # Configure AWS environment
+        if aws_env:
+            aws_env_dir = os.path.expanduser(f"~/.aws/aws-envs/{aws_env}")
+            os.environ["AWS_CONFIG_FILE"] = os.path.join(aws_env_dir, "config")
+            os.environ["AWS_SHARED_CREDENTIALS_FILE"] = os.path.join(aws_env_dir, "credentials")
+        
+        # Set up AWS session with eu-west-1 as default region
+        if not region:
+            # Try to get region from profile first
+            session = boto3.Session(profile_name=profile)
+            region = session.region_name or 'eu-west-1'
+        
+        self.session = boto3.Session(profile_name=profile, region_name=region)
+        self.ssm = self.session.client('ssm')
+        self.ec2 = self.session.client('ec2')
+        self.ec2_connect = self.session.client('ec2-instance-connect')
+        
+        # Default public key path if not provided
+        if not public_key_path:
+            public_key_path = os.path.expanduser("~/.ssh/vscode/vscode.pub")
+        self.public_key_path = Path(public_key_path)
+
+    def log(self, message: str) -> None:
+        """Log message to stderr to avoid interfering with SSH connection."""
+        print(message, file=sys.stderr)
+
+    def get_instance_status(self) -> str:
+        """Check if instance is online in SSM."""
+        try:
+            response = self.ssm.describe_instance_information(
+                Filters=[{'Key': 'InstanceIds', 'Values': [self.instance_id]}]
+            )
+            if response['InstanceInformationList']:
+                return response['InstanceInformationList'][0]['PingStatus']
+            return 'Offline'
+        except ClientError:
+            return 'Offline'
+
+    def start_instance(self) -> bool:
+        """Start the EC2 instance if it's stopped."""
+        try:
+            self.ec2.start_instances(InstanceIds=[self.instance_id])
+            return True
+        except ClientError as e:
+            self.log(f"Error starting instance: {e}")
+            return False
+
+    def wait_for_instance(self, max_attempts: int = 30, delay: int = 3) -> bool:
+        """Wait for instance to come online.
+        
+        Args:
+            max_attempts: Maximum number of status checks
+            delay: Seconds between checks
+        
+        Returns:
+            bool: True if instance came online, False if timeout
+        """
+        for _ in range(max_attempts):
+            if self.get_instance_status() == 'Online':
+                return True
+            time.sleep(delay)
+        return False
+
+    def push_ssh_key(self) -> bool:
+        """Push SSH public key to instance via EC2 Instance Connect."""
+        try:
+            with open(self.public_key_path) as f:
+                public_key = f.read()
+            
+            self.ec2_connect.send_ssh_public_key(
+                InstanceId=self.instance_id,
+                InstanceOSUser='ec2-user',
+                SSHPublicKey=public_key
+            )
+            return True
+        except (ClientError, FileNotFoundError) as e:
+            self.log(f"Error pushing SSH key: {e}")
+            return False
+
+    def start_session(self) -> None:
+        """Start SSM session with SSH port forwarding.
+        
+        Uses AWS CLI directly to ensure proper stdin/stdout handling for SSH ProxyCommand.
+        The session manager plugin will automatically handle the data transfer.
+        
+        When used as a ProxyCommand, we need to:
+        1. Pass through stdin/stdout directly to AWS CLI
+        2. Only use stderr for logging
+        3. Let the session manager plugin handle the actual data transfer
+        """
+        import subprocess
+        import platform
+        
+        try:
+            # Build environment with AWS credentials configuration
+            env = os.environ.copy()
+            if 'AWS_CONFIG_FILE' in os.environ:
+                env['AWS_CONFIG_FILE'] = os.environ['AWS_CONFIG_FILE']
+            if 'AWS_SHARED_CREDENTIALS_FILE' in os.environ:
+                env['AWS_SHARED_CREDENTIALS_FILE'] = os.environ['AWS_SHARED_CREDENTIALS_FILE']
+            
+            # Determine AWS CLI command based on platform
+            aws_cmd = 'aws.exe' if platform.system() == 'Windows' else 'aws'
+            
+            # Build command as list (works for both Windows and Unix)
+            cmd = [
+                aws_cmd, 'ssm', 'start-session',
+                '--target', self.instance_id,
+                '--document-name', 'AWS-StartSSHSession',
+                '--parameters', f'portNumber={self.port}',
+                '--profile', self.profile,
+                '--region', self.session.region_name
+            ]
+            
+            # Start AWS CLI process with direct stdin/stdout pass-through
+            process = subprocess.Popen(
+                cmd,
+                env=env,
+                stdin=sys.stdin,
+                stdout=sys.stdout,
+                stderr=subprocess.PIPE,  # Capture stderr for our logging
+                shell=platform.system() == 'Windows'  # shell=True only on Windows
+            )
+            
+            # Monitor stderr for logging while process runs
+            while True:
+                err_line = process.stderr.readline()
+                if not err_line and process.poll() is not None:
+                    break
+                if err_line:
+                    self.log(err_line.decode().strip())
+            
+            if process.returncode != 0:
+                raise subprocess.CalledProcessError(process.returncode, cmd)
+            
+        except subprocess.CalledProcessError as e:
+            self.log(f"Error starting session: {e}")
+            raise
+
+    def connect(self) -> bool:
+        """Main connection flow:
+        1. Check instance status
+        2. Start if needed and wait for online
+        3. Push SSH key
+        4. Start SSM session
+        """
+        status = self.get_instance_status()
+        
+        if status != 'Online':
+            self.log(f"Instance {self.instance_id} is {status}, starting...")
+            if not self.start_instance():
+                return False
+            
+            self.log("Waiting for instance to come online...")
+            if not self.wait_for_instance():
+                self.log("Instance failed to come online")
+                return False
+        
+        self.log("Pushing SSH public key...")
+        if not self.push_ssh_key():
+            return False
+        
+        self.log("Starting SSM session...")
+        self.start_session()
+        return True

cloudx_proxy-2025.3.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 easytocloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cloudx_proxy-2025.3.0.dist-info/METADATA

@@ -0,0 +1,258 @@
+Metadata-Version: 2.2
+Name: cloudx-proxy
+Version: 2025.3.0
+Summary: SSH proxy command to connect VSCode with Cloud9/CloudX instance using AWS Systems Manager
+Author-email: easytocloud <info@easytocloud.com>
+License: MIT License
+        
+        Copyright (c) 2025 easytocloud
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/easytocloud/cloudX-proxy
+Project-URL: Repository, https://github.com/easytocloud/cloudX-proxy.git
+Project-URL: Issues, https://github.com/easytocloud/cloudX-proxy/issues
+Project-URL: Changelog, https://github.com/easytocloud/cloudX-proxy/blob/main/CHANGELOG.md
+Keywords: aws,vscode,cloud9,cloudX,ssm,ssh,proxy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3>=1.34.0
+Requires-Dist: click>=8.1.0
+
+# cloudX-proxy
+
+A cross-platform SSH proxy command for connecting VSCode to CloudX/Cloud9 EC2 instances using AWS Systems Manager Session Manager.
+
+## Overview
+
+cloudX-proxy enables seamless SSH connections from VSCode to EC2 instances using AWS Systems Manager Session Manager, eliminating the need for direct SSH access or public IP addresses. It handles:
+
+- Automatic instance startup if stopped
+- SSH key distribution via EC2 Instance Connect
+- SSH tunneling through AWS Systems Manager
+- Cross-platform support (Windows, macOS, Linux)
+
+## Prerequisites
+
+1. **AWS CLI v2** - [Installation Guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+2. **AWS Session Manager Plugin** - [Installation Guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
+3. **OpenSSH Client**
+   - Windows: [Microsoft's OpenSSH Installation Guide](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=gui)
+   - macOS/Linux: Usually pre-installed
+4. **uv** - Python package installer and resolver
+   ```bash
+   pip install uv
+   ```
+5. **VSCode with Remote SSH Extension** installed
+
+## AWS Credentials Setup
+
+The proxy expects to find AWS credentials in a profile named 'vscode' by default. These credentials should be the Access Key and Secret Key that were created by deploying the cloudX-user stack in your AWS account. The cloudX-user stack creates an IAM user with the minimal permissions required for:
+- Starting/stopping EC2 instances
+- Establishing SSM sessions
+- Pushing SSH keys via EC2 Instance Connect
+
+Once the SSH session is established, the user has to further configure the instance using `generate-sso-config` tool. This is a one-time setup unless the user's access to AWS accounts changes, in which case the user should re-run the `generate-sso-config` tool.
+
+It is recommended to use  --generate-directories and --use-ou-structure to create working directories for each account the user has access to.
+
+Everytime the user connects to the instance, `ssostart` will authenticate the user with AWS SSO and generate temporary credentials. 
+
+This ensures you have the appropriate AWS access both for connecting to the instance and for working within it.
+
+The proxy also supports easytocloud's AWS profile organizer. If you use multiple AWS environments, you can store your AWS configuration and credentials in `~/.aws/aws-envs/<environment>` directories and use the `--aws-env` option to specify which environment to use.
+
+## Setup
+
+1. Deploy the cloudX-user stack in your AWS account to create the necessary IAM user
+2. Configure the 'vscode' AWS profile with the credentials from the cloudX-user stack
+3. Install uv if you haven't already:
+   ```bash
+   pip install uv
+   ```
+
+The `uvx` command, part of the uv package manager, makes running cloudX-proxy seamless. When you run `uvx cloudx-proxy`, it automatically:
+- Pulls the latest version from PyPI
+- Creates an isolated virtual environment
+- Installs all dependencies
+- Runs the code
+
+All of this happens in a single, fast operation without any manual setup required.
+
+## SSH Configuration
+
+### 1. Generate SSH Key Pair
+
+If you don't already have an SSH key pair for VSCode:
+
+```bash
+# Create .ssh/vscode directory
+mkdir -p ~/.ssh/vscode
+
+# Generate key pair
+ssh-keygen -t rsa -b 4096 -f ~/.ssh/vscode/vscode
+```
+
+### 2. Configure SSH
+
+#### Unix-like Systems (macOS/Linux)
+
+1. Create or edit `~/.ssh/config`:
+   ```bash
+   # Include VSCode-specific config
+   Include vscode/config
+   ```
+
+2. Create `~/.ssh/vscode/config`:
+   ```
+   Host cloudx-*
+       ProxyCommand uvx cloudx-proxy %h %p
+       User ec2-user
+       IdentityFile ~/.ssh/vscode/vscode
+       StrictHostKeyChecking no
+       UserKnownHostsFile /dev/null
+
+   # Example host configuration
+   Host cloudx-dev
+       HostName i-0123456789abcdef0  # Your EC2 instance ID
+   ```
+
+#### Windows
+
+1. Create or edit `%USERPROFILE%\.ssh\config`:
+   ```
+   Include vscode/config
+   ```
+
+2. Create `%USERPROFILE%\.ssh\vscode\config`:
+   ```
+   Host cloudx-*
+       ProxyCommand uvx cloudx-proxy %h %p
+       User ec2-user
+       IdentityFile %USERPROFILE%\.ssh\vscode\vscode
+       StrictHostKeyChecking no
+       UserKnownHostsFile /dev/null
+
+   # Example host configuration
+   Host cloudx-dev
+       HostName i-0123456789abcdef0  # Your EC2 instance ID
+   ```
+
+### 3. VSCode Configuration
+
+1. Install the "Remote - SSH" extension in VSCode
+2. Configure VSCode settings:
+   ```json
+   {
+       "remote.SSH.configFile": "~/.ssh/vscode/config",
+       "remote.SSH.connectTimeout": 90
+   }
+   ```
+
+## Usage
+
+### Command Line
+
+```bash
+# Basic usage (uses default vscode profile, port 22, and eu-west-1 region)
+uvx cloudx-proxy i-0123456789abcdef0
+
+# With custom port
+uvx cloudx-proxy i-0123456789abcdef0 2222
+
+# With custom profile
+uvx cloudx-proxy i-0123456789abcdef0 --profile myprofile
+
+# With different region (overrides eu-west-1 default)
+uvx cloudx-proxy i-0123456789abcdef0 --region us-east-1
+
+# With AWS profile organizer environment
+uvx cloudx-proxy i-0123456789abcdef0 --aws-env prod
+
+# With custom SSH key
+uvx cloudx-proxy i-0123456789abcdef0 --key-path ~/.ssh/custom_key.pub
+```
+
+### VSCode
+
+1. Click the "Remote Explorer" icon in the VSCode sidebar
+2. Select "SSH Targets" from the dropdown
+3. Your configured hosts will appear (e.g., cloudx-dev)
+4. Click the "+" icon next to a host to connect
+5. VSCode will handle the rest, using cloudX-proxy to establish the connection
+
+## AWS Permissions
+
+The AWS user/role needs these permissions:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "ec2:StartInstances",
+                "ec2:DescribeInstances",
+                "ssm:StartSession",
+                "ssm:DescribeInstanceInformation",
+                "ec2-instance-connect:SendSSHPublicKey"
+            ],
+            "Resource": "*"
+        }
+    ]
+}
+```
+
+## Troubleshooting
+
+1. **Connection Timeout**
+   - Ensure the instance has the SSM agent installed and running
+   - Check that your AWS credentials have the required permissions
+   - Verify the instance ID is correct
+   - Increase the VSCode SSH timeout if needed
+
+2. **SSH Key Issues**
+   - Ensure the key pair exists in the correct location
+   - Check file permissions (600 for private key, 644 for public key)
+   - Verify the public key is being successfully pushed to the instance
+
+3. **AWS Configuration**
+   - Confirm AWS CLI is configured with valid credentials (default profile name is 'vscode')
+   - Default region is eu-west-1 if not specified in profile or command line
+   - If using AWS profile organizer, ensure your environment directory exists at `~/.aws/aws-envs/<environment>/`
+   - Verify the Session Manager plugin is installed correctly
+   - Check that the instance has the required IAM role for SSM
+
+## License
+
+MIT License - see LICENSE file for details

cloudx_proxy-2025.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+cloudx_proxy/__init__.py,sha256=YfZd1x9PT_aGA4FGsNw1WwvWkfRKLy_9O93a_W2wtiE,187
+cloudx_proxy/_version.py,sha256=fWRR5Orqc8dqtVKNeAfCqsDhc30HwoGblv4fyeGnKoY,417
+cloudx_proxy/cli.py,sha256=bBcvqiKpsLY6cYt-OG8282RZuoSDwDgEdyehTAeeec0,1502
+cloudx_proxy/core.py,sha256=j6CUKdg2Ikcoi-05ceXMGA_c1aGWBhN9_JevbkLkaUY,7383
+cloudx_proxy-2025.3.0.dist-info/LICENSE,sha256=i7P2OR4zsJYsMWcCUDe_B9ZfGi9bU0K5I2nKfDrW_N8,1068
+cloudx_proxy-2025.3.0.dist-info/METADATA,sha256=I-ImXVJrHCT-tnl26xPK94FrtVwxZ-dgc7290pzp0rs,9527
+cloudx_proxy-2025.3.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+cloudx_proxy-2025.3.0.dist-info/entry_points.txt,sha256=BugqsX1eJtZGC6b5ONbieB9To9go2RCQVXuzdN79lZQ,55
+cloudx_proxy-2025.3.0.dist-info/top_level.txt,sha256=2wtEote1db21j-VvkCJFfT-dLlauuG5indjggYh3xDg,13
+cloudx_proxy-2025.3.0.dist-info/RECORD,,

cloudx_proxy-2025.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cloudx_proxy-2025.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cloudx-proxy = cloudx_proxy.cli:main

cloudx_proxy-2025.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cloudx_proxy