cloudx-proxy 0.4.7__tar.gz → 0.4.9__tar.gz

cloudx_proxy-0.4.9/.clinerules

@@ -0,0 +1,103 @@
+# cloudX-proxy
+
+CloudX is a development environment consisting of 
+
+- a local VSCode installation
+- a remote development server (EC2 instance) running with auto-shutdown
+
+The AWS side consists of the following components:
+
+- an CloudX-environment
+- a CloudX-user
+- a CloudX-instance
+
+The CloudX-environment is a set of resources that are used to run the CloudX-instance. 
+Most importantly, it defines the VPC subnet where the instances are launched.
+
+A CloudX-user is an IAM user with the necessary permissions to manage their CloudX-instance(s) based on a ABAC tag defined in the cloudX-environment.
+
+A CloudX-instance is an EC2 instance that is launched in the CloudX-environment.
+It's most important feature is that it is automatically stopped after a certain period of inactivity.
+
+The AWS components are deployed from AWS Service Catalog.
+
+The cloudX-proxy is a tool that allows you to access the remote development server from your local VSCode installation over an ssh connection established by the cloudX-proxy. The cloudX-proxy takes care of starting the instance should it be stopped. Also, it pushes an ssh key to the instance to allow you to connect to it. Given that the proxy uses AWS Systems Manager to initiate the connection, you don't need to open any inbound ports in the security group of the instance.
+
+## Architecture
+
+### SSH Configuration Structure
+
+CloudX-proxy uses a hierarchical three-tier SSH configuration approach:
+
+1. **Generic Configuration (cloudx-*)**: Common settings for all environments
+   - User settings (ec2-user)
+   - TCP keepalive
+   - SSH multiplexing configuration
+
+2. **Environment Configuration (cloudx-{env}-*)**: Environment-specific settings
+   - Authentication configuration (identity settings)
+   - ProxyCommand with environment-specific parameters
+
+3. **Host Configuration (cloudx-{env}-hostname)**: Instance-specific settings
+   - HostName (instance ID)
+   - Optional overrides for incompatible settings
+
+This tiered approach minimizes configuration duplication and makes it clear which settings apply broadly and which are specific to an environment or host.
+
+### Security Model
+
+The primary security boundary is enforced through AWS IAM via Systems Manager (SSM) and EC2 Instance Connect:
+- Only authenticated AWS users with appropriate IAM permissions can establish SSM sessions
+- EC2 Instance Connect allows temporary injection of SSH public keys
+- No inbound SSH ports need to be exposed, as all connections are through AWS SSM's secure tunneling
+- All connection attempts and key pushes are logged in AWS CloudTrail
+
+## Operating Modes
+
+CloudX-proxy runs in either of two modes:
+
+- setup
+- connect
+
+### Setup Mode
+
+With setup mode, the config files and directories for the connect mode are established. The setup mode is typically only run once per CloudX-instance. When running setup, the user is asked for their AWS AK/SK of the IAM user created as CloudX-user. This will be stored in ~/.aws/credentials. Alternatively the user can store this data themselves in ~/.aws/credentials. The profile name is 'vscode' by default, but can be overruled with the --profile option. When multiple instances are used, it is recommended to use a profile cloudx-env-user where env is the environment and user the username.
+
+By default an ssh key named vscode will be used - and created if not available in the configuration directory (~/.ssh/vscode). The user can specify a different key with the --ssh-key option.
+
+A 'Host cloudx-{env}-*' entry will be created in the ~/.ssh/vscode/config file for each environment. A user can potentially have multiple instances in a single environment as well as multiple environments.
+
+#### Setup Options
+
+- **--profile**: AWS profile to use (default: 'vscode')
+- **--ssh-key**: SSH key name to use (default: 'vscode')
+- **--ssh-config**: SSH config file to use (default: ~/.ssh/vscode/config)
+- **--aws-env**: AWS environment directory (default: ~/.aws)
+- **--1password**: Use 1Password SSH agent for SSH authentication
+- **--instance**: EC2 instance ID to set up connection for
+- **--hostname**: Hostname to use for SSH configuration (without this, hostname will be generated from instance ID or prompted)
+- **--yes**: Non-interactive mode, use default values for all prompts
+
+### Connect Mode
+
+In connect mode, the actual connection is established. This is not used by the user directly, but in the ssh configuration as a proxy command. The command is run using uvx.
+
+### 1Password Integration
+
+When the --1password option is used:
+1. CloudX-proxy first checks if any SSH key with the specified name exists in any 1Password vault
+2. If the key exists, it's reused (the public key is exported to the filesystem)
+3. If the key doesn't exist, the user selects which vault to store the newly created key in
+4. The SSH configuration uses the 1Password SSH agent socket and the public key
+
+### Automation Support
+
+The --yes option enables non-interactive mode for use in scripts and automated processes:
+- All prompts use default values
+- Hostname is automatically generated based on instance ID
+- AWS profile must already be configured
+- EC2 instance ID must be provided with the --instance option
+
+## Future Considerations
+
+[Potential Breaking Change] Replacing all default values from 'vscode' to 'cloudx' would align the naming but would be a breaking change. This would affect default profile names, SSH key names, and configuration directories.

{cloudx_proxy-0.4.7 → cloudx_proxy-0.4.9}/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [0.4.9](https://github.com/easytocloud/cloudX-proxy/compare/v0.4.8...v0.4.9) (2025-03-12)
+
+
+### Bug Fixes
+
+* added list command ([76e43e4](https://github.com/easytocloud/cloudX-proxy/commit/76e43e449ec2f704475014f95d0a345e322be8e8))
+
+## [0.4.8](https://github.com/easytocloud/cloudX-proxy/compare/v0.4.7...v0.4.8) (2025-03-07)
+
 ## [0.4.7](https://github.com/easytocloud/cloudX-proxy/compare/v0.4.6...v0.4.7) (2025-03-07)
 
 

{cloudx_proxy-0.4.7 → cloudx_proxy-0.4.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: cloudx-proxy
-Version: 0.4.7
+Version: 0.4.9
 Summary: SSH proxy command to connect VSCode with Cloud9/CloudX instance using AWS Systems Manager
 Author-email: easytocloud <info@easytocloud.com>
 License: MIT License
@@ -119,6 +119,9 @@ uvx cloudx-proxy setup --ssh-config ~/.ssh/cloudx/config
 # Setup with 1Password integration
 uvx cloudx-proxy setup --1password
 
+# Setup with non-interactive automation
+uvx cloudx-proxy setup --instance i-0123456789abcdef0 --hostname myserver --yes
+
 # Combine options
 uvx cloudx-proxy setup --profile myprofile --ssh-key mykey --ssh-config ~/.ssh/cloudx/config --1password --aws-env prod
 ```
@@ -274,6 +277,9 @@ Options:
 - `--ssh-config` (optional): Path to the SSH config file to use. If specified, configuration and keys will be stored in this location. Default is ~/.ssh/vscode/config.
 - `--1password` (flag): Enable 1Password SSH agent integration. Creates keys directly in 1Password and configures SSH to use the 1Password SSH agent.
 - `--aws-env` (optional): AWS environment directory to use. If specified, AWS configuration and credentials will be read from ~/.aws/aws-envs/{env}/.
+- `--instance` (optional): EC2 instance ID to set up connection for. If provided, skips the instance ID prompt.
+- `--hostname` (optional): Hostname to use for SSH configuration. If not provided, a hostname will be generated from the instance ID in non-interactive mode or prompted for in interactive mode.
+- `--yes` (flag): Non-interactive mode, use default values for all prompts. Requires sufficient defaults or explicit parameters for all required values.
 
 Example usage:
 ```bash
@@ -323,6 +329,33 @@ uvx cloudx-proxy connect i-0123456789abcdef0 22 --profile myprofile --aws-env pr
 
 Note: The connect command is typically used through the SSH ProxyCommand configuration set up by the setup command. You rarely need to run it directly unless testing the connection.
 
+#### List Command
+```bash
+uvx cloudx-proxy list [OPTIONS]
+```
+
+Options:
+- `--ssh-config` (optional): Path to the SSH config file to use. If not specified, uses ~/.ssh/vscode/config.
+- `--environment` (optional): Filter hosts by environment (e.g., dev, prod). If not specified, shows all environments.
+- `--detailed` (flag): Show detailed information including instance IDs.
+
+Example usage:
+```bash
+# List all configured hosts
+uvx cloudx-proxy list
+
+# List hosts in a specific environment
+uvx cloudx-proxy list --environment dev
+
+# List hosts with detailed information
+uvx cloudx-proxy list --detailed
+
+# List hosts from a custom SSH config
+uvx cloudx-proxy list --ssh-config ~/.ssh/cloudx/config
+```
+
+The list command displays all configured cloudx-proxy hosts, grouped by environment. It provides a quick overview of available connections and can help troubleshoot SSH configuration issues.
+
 ### VSCode
 
 1. Click the "Remote Explorer" icon in the VSCode sidebar

{cloudx_proxy-0.4.7 → cloudx_proxy-0.4.9}/README.md

@@ -69,6 +69,9 @@ uvx cloudx-proxy setup --ssh-config ~/.ssh/cloudx/config
 # Setup with 1Password integration
 uvx cloudx-proxy setup --1password
 
+# Setup with non-interactive automation
+uvx cloudx-proxy setup --instance i-0123456789abcdef0 --hostname myserver --yes
+
 # Combine options
 uvx cloudx-proxy setup --profile myprofile --ssh-key mykey --ssh-config ~/.ssh/cloudx/config --1password --aws-env prod
 ```
@@ -224,6 +227,9 @@ Options:
 - `--ssh-config` (optional): Path to the SSH config file to use. If specified, configuration and keys will be stored in this location. Default is ~/.ssh/vscode/config.
 - `--1password` (flag): Enable 1Password SSH agent integration. Creates keys directly in 1Password and configures SSH to use the 1Password SSH agent.
 - `--aws-env` (optional): AWS environment directory to use. If specified, AWS configuration and credentials will be read from ~/.aws/aws-envs/{env}/.
+- `--instance` (optional): EC2 instance ID to set up connection for. If provided, skips the instance ID prompt.
+- `--hostname` (optional): Hostname to use for SSH configuration. If not provided, a hostname will be generated from the instance ID in non-interactive mode or prompted for in interactive mode.
+- `--yes` (flag): Non-interactive mode, use default values for all prompts. Requires sufficient defaults or explicit parameters for all required values.
 
 Example usage:
 ```bash
@@ -273,6 +279,33 @@ uvx cloudx-proxy connect i-0123456789abcdef0 22 --profile myprofile --aws-env pr
 
 Note: The connect command is typically used through the SSH ProxyCommand configuration set up by the setup command. You rarely need to run it directly unless testing the connection.
 
+#### List Command
+```bash
+uvx cloudx-proxy list [OPTIONS]
+```
+
+Options:
+- `--ssh-config` (optional): Path to the SSH config file to use. If not specified, uses ~/.ssh/vscode/config.
+- `--environment` (optional): Filter hosts by environment (e.g., dev, prod). If not specified, shows all environments.
+- `--detailed` (flag): Show detailed information including instance IDs.
+
+Example usage:
+```bash
+# List all configured hosts
+uvx cloudx-proxy list
+
+# List hosts in a specific environment
+uvx cloudx-proxy list --environment dev
+
+# List hosts with detailed information
+uvx cloudx-proxy list --detailed
+
+# List hosts from a custom SSH config
+uvx cloudx-proxy list --ssh-config ~/.ssh/cloudx/config
+```
+
+The list command displays all configured cloudx-proxy hosts, grouped by environment. It provides a quick overview of available connections and can help troubleshoot SSH configuration issues.
+
 ### VSCode
 
 1. Click the "Remote Explorer" icon in the VSCode sidebar

{cloudx_proxy-0.4.7 → cloudx_proxy-0.4.9}/cloudx_proxy/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.4.7'
-__version_tuple__ = version_tuple = (0, 4, 7)
+__version__ = version = '0.4.9'
+__version_tuple__ = version_tuple = (0, 4, 9)

{cloudx_proxy-0.4.7 → cloudx_proxy-0.4.9}/cloudx_proxy/cli.py

@@ -1,5 +1,7 @@
 import os
 import sys
+import re
+from pathlib import Path
 import click
 from . import __version__
 from .core import CloudXProxy
@@ -123,5 +125,104 @@ def setup(profile: str, ssh_key: str, ssh_config: str, aws_env: str, use_1passwo
         print(f"\n\033[91mError: {str(e)}\033[0m", file=sys.stderr)
         sys.exit(1)
 
+@cli.command()
+@click.option('--ssh-config', help='SSH config file to use (default: ~/.ssh/vscode/config)')
+@click.option('--environment', help='Filter hosts by environment (e.g., dev, prod)')
+@click.option('--detailed', is_flag=True, help='Show detailed information including instance IDs')
+def list(ssh_config: str, environment: str, detailed: bool):
+    """List configured cloudx-proxy SSH hosts.
+    
+    This command parses the SSH configuration file and displays all configured cloudx-proxy hosts.
+    Hosts are grouped by environment for easier navigation.
+    
+    Example usage:
+        cloudx-proxy list
+        cloudx-proxy list --environment dev
+        cloudx-proxy list --ssh-config ~/.ssh/cloudx/config
+        cloudx-proxy list --detailed
+    """
+    try:
+        # Determine SSH config file path
+        if ssh_config:
+            config_file = Path(os.path.expanduser(ssh_config))
+        else:
+            config_file = Path(os.path.expanduser("~/.ssh/vscode/config"))
+        
+        if not config_file.exists():
+            print(f"SSH config file not found: {config_file}")
+            print("Run 'cloudx-proxy setup' to create a configuration.")
+            sys.exit(1)
+        
+        # Read SSH config file
+        config_content = config_file.read_text()
+        
+        # Parse hosts using regex
+        # Match Host entries for cloudx hosts
+        host_pattern = r'Host\s+(cloudx-[^\s]+)(?:\s*\n(?:(?!\s*Host\s+).)*?HostName\s+([^\s]+))?'
+        hosts = re.finditer(host_pattern, config_content, re.DOTALL)
+        
+        # Group hosts by environment
+        environments = {}
+        generic_hosts = []
+        
+        for match in hosts:
+            hostname = match.group(1)
+            instance_id = match.group(2) if match.group(2) else "N/A"
+            
+            # Skip generic patterns like cloudx-* or cloudx-dev-*
+            if hostname.endswith('*'):
+                generic_hosts.append((hostname, instance_id))
+                continue
+                
+            # Extract environment from hostname (format: cloudx-{env}-{name})
+            parts = hostname.split('-')
+            if len(parts) >= 3:
+                env = parts[1]
+                name = '-'.join(parts[2:])
+                
+                # Filter by environment if specified
+                if environment and env != environment:
+                    continue
+                    
+                if env not in environments:
+                    environments[env] = []
+                    
+                environments[env].append((hostname, name, instance_id))
+        
+        # Display results
+        if not environments and not generic_hosts:
+            print("No cloudx-proxy hosts configured.")
+            print("Run 'cloudx-proxy setup' to configure a host.")
+            return
+            
+        # Print header
+        print(f"\n\033[1;95m=== cloudx-proxy Configured Hosts ===\033[0m\n")
+        
+        # Print generic patterns if any and detailed mode
+        if generic_hosts and detailed:
+            print("\033[1;94mGeneric Patterns:\033[0m")
+            for hostname, instance_id in generic_hosts:
+                print(f"  {hostname}")
+            print()
+            
+        # Print environments and hosts
+        for env, hosts in sorted(environments.items()):
+            print(f"\033[1;94mEnvironment: {env}\033[0m")
+            for hostname, name, instance_id in sorted(hosts, key=lambda x: x[1]):
+                if detailed:
+                    print(f"  {name} \033[90m({hostname})\033[0m -> \033[93m{instance_id}\033[0m")
+                else:
+                    print(f"  {name} \033[90m({hostname})\033[0m")
+            print()
+            
+        # Print usage hint
+        print("\033[1;93mUsage:\033[0m")
+        print("  Connect with SSH:  \033[96mssh <hostname>\033[0m")
+        print("  Connect with VSCode: Use Remote Explorer in VSCode")
+        
+    except Exception as e:
+        print(f"Error: {str(e)}", file=sys.stderr)
+        sys.exit(1)
+
 if __name__ == '__main__':
     cli()

{cloudx_proxy-0.4.7 → cloudx_proxy-0.4.9}/cloudx_proxy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: cloudx-proxy
-Version: 0.4.7
+Version: 0.4.9
 Summary: SSH proxy command to connect VSCode with Cloud9/CloudX instance using AWS Systems Manager
 Author-email: easytocloud <info@easytocloud.com>
 License: MIT License
@@ -119,6 +119,9 @@ uvx cloudx-proxy setup --ssh-config ~/.ssh/cloudx/config
 # Setup with 1Password integration
 uvx cloudx-proxy setup --1password
 
+# Setup with non-interactive automation
+uvx cloudx-proxy setup --instance i-0123456789abcdef0 --hostname myserver --yes
+
 # Combine options
 uvx cloudx-proxy setup --profile myprofile --ssh-key mykey --ssh-config ~/.ssh/cloudx/config --1password --aws-env prod
 ```
@@ -274,6 +277,9 @@ Options:
 - `--ssh-config` (optional): Path to the SSH config file to use. If specified, configuration and keys will be stored in this location. Default is ~/.ssh/vscode/config.
 - `--1password` (flag): Enable 1Password SSH agent integration. Creates keys directly in 1Password and configures SSH to use the 1Password SSH agent.
 - `--aws-env` (optional): AWS environment directory to use. If specified, AWS configuration and credentials will be read from ~/.aws/aws-envs/{env}/.
+- `--instance` (optional): EC2 instance ID to set up connection for. If provided, skips the instance ID prompt.
+- `--hostname` (optional): Hostname to use for SSH configuration. If not provided, a hostname will be generated from the instance ID in non-interactive mode or prompted for in interactive mode.
+- `--yes` (flag): Non-interactive mode, use default values for all prompts. Requires sufficient defaults or explicit parameters for all required values.
 
 Example usage:
 ```bash
@@ -323,6 +329,33 @@ uvx cloudx-proxy connect i-0123456789abcdef0 22 --profile myprofile --aws-env pr
 
 Note: The connect command is typically used through the SSH ProxyCommand configuration set up by the setup command. You rarely need to run it directly unless testing the connection.
 
+#### List Command
+```bash
+uvx cloudx-proxy list [OPTIONS]
+```
+
+Options:
+- `--ssh-config` (optional): Path to the SSH config file to use. If not specified, uses ~/.ssh/vscode/config.
+- `--environment` (optional): Filter hosts by environment (e.g., dev, prod). If not specified, shows all environments.
+- `--detailed` (flag): Show detailed information including instance IDs.
+
+Example usage:
+```bash
+# List all configured hosts
+uvx cloudx-proxy list
+
+# List hosts in a specific environment
+uvx cloudx-proxy list --environment dev
+
+# List hosts with detailed information
+uvx cloudx-proxy list --detailed
+
+# List hosts from a custom SSH config
+uvx cloudx-proxy list --ssh-config ~/.ssh/cloudx/config
+```
+
+The list command displays all configured cloudx-proxy hosts, grouped by environment. It provides a quick overview of available connections and can help troubleshoot SSH configuration issues.
+
 ### VSCode
 
 1. Click the "Remote Explorer" icon in the VSCode sidebar

{cloudx_proxy-0.4.7 → cloudx_proxy-0.4.9}/cloudx_proxy.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+.clinerules
 .gitignore
 .releaserc
 CHANGELOG.md