gmab 0.1.1__tar.gz

gmab-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Steve Cannivy (steve at roudeleiw dot lu)
+
+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.

gmab-0.1.1/PKG-INFO

@@ -0,0 +1,350 @@
+Metadata-Version: 2.2
+Name: gmab
+Version: 0.1.1
+Summary: Give Me A Box - CLI tool to spawn, list, and manage temporary cloud boxes
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/gmab
+Project-URL: Bug Tracker, https://github.com/yourusername/gmab/issues
+Keywords: cloud,cli,devops,aws,linode,hetzner
+Classifier: Development Status :: 3 - Alpha
+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.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: boto3>=1.26.0
+Requires-Dist: pathlib>=1.0.1
+Requires-Dist: typing-extensions>=4.0.0
+
+# GMAB (Give Me A Box) v0.1.1
+
+A CLI tool to spawn, list, and manage temporary cloud boxes.
+
+#### Why?
+
+- Need a quick VPS for pentesting, bug bounty, or scanning?
+- Want to run commands from a different IP without using your local machine?
+- No need for manual cloud console interaction—just **gmab spawn**, and you're in!
+
+
+## Features
+
+- Spawn temporary cloud instances that automatically expire
+- List active instances across providers
+- Terminate instances individually or in bulk
+- Support for multiple cloud providers (Linode, AWS, Hetzner)
+- Provider-agnostic command interface
+- SSH key management
+
+## Installation
+
+### Using pip
+
+The easiest way to install GMAB is directly from PyPI:
+
+```bash
+pip install gmab
+```
+
+### From Source
+
+You can also install directly from the source code:
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/gmab.git
+cd gmab
+
+# Install the package
+pip install .
+
+# For development (editable mode)
+pip install -e .
+```
+
+## Configuration
+Before you can use GMAB, you need to configure it with your provider credentials and preferences. You must run the `configure` command before using any other functionality.
+
+### Interactive Configuration
+
+Use the configure command to set up or modify your configuration:
+
+```bash
+# Configure all settings and providers
+gmab configure
+
+# Configure a specific provider
+gmab configure -p linode
+```
+
+> **Note:** GMAB will only use providers that you've explicitly configured. If you don't configure a provider, GMAB will not attempt to use it, preventing any unnecessary API calls or errors.
+
+### Viewing Configuration
+
+You can view your current configuration using the `--print` flag:
+
+```bash
+gmab configure --print
+```
+
+This will display:
+- The location of your config files
+- The contents of your configuration (with sensitive data masked)
+- The current settings for all configured providers
+
+## Usage
+
+### Spawn a new instance
+```bash
+# Using default provider
+gmab spawn
+
+# Specify a provider
+gmab spawn --provider linode
+gmab spawn --provider aws
+gmab spawn --provider hetzner
+
+# Override defaults
+gmab spawn -p linode -r us-east -i linode/ubuntu22.04 -t 120
+```
+
+### List instances
+```bash
+# List all instances
+gmab list
+
+# List instances for specific provider
+gmab list --provider linode
+```
+
+### Terminate instances
+```bash
+# Terminate by ID or label
+gmab terminate instance-123
+gmab terminate my-instance-label
+
+# Terminate multiple instances
+gmab terminate instance-1 instance-2
+
+# Terminate all instances
+gmab terminate all
+
+# Terminate expired instances
+gmab terminate expired
+```
+
+## Provider-Specific Notes
+
+### Linode
+- Requires API key with full access
+- Default instance type: Nanode 1GB
+- Supports all regions
+
+### AWS
+- Requires access key and secret key
+- Default instance type: t2.micro
+- Creates VPC and security group if needed
+- Supports all regions
+
+### Hetzner
+- Requires API token
+- Default instance type: CPX11
+- Supports all Hetzner Cloud regions
+- Uses label-based instance tracking
+
+## Best Practices
+
+1. **SSH Key**: Use an ed25519 key pair for better security
+```bash
+ssh-keygen -t ed25519 -C "your_email@example.com"
+```
+
+2. **Instance Lifetime**: Set reasonable expiration times and automatic cleanup
+```bash
+# Set lifetime when spawning
+gmab spawn -t 60  # 60 minutes lifetime
+
+# Set up automatic cleanup with cron (Linux/Mac)
+# Run every hour to clean up expired instances
+0 * * * * gmab terminate expired -y
+
+# For Windows, use Task Scheduler to run:
+# gmab.exe terminate expired -y
+```
+
+3. **Regular Cleanup**: Periodically check and terminate expired instances
+```bash
+gmab terminate expired
+```
+
+4. **Provider Organization**:
+- AWS: Create a dedicated IAM user for GMAB
+- Linode: Use a dedicated API key
+- Hetzner: Create a dedicated project named "gmab" and generate the API token specifically for this project
+
+5. **Security**:
+- Store configuration files securely
+- Don't commit provider credentials to version control
+- Regularly rotate API keys and tokens
+
+## Example Commands and Outputs
+
+### List Command
+```bash
+$ gmab list
+Provider    Instance ID            Label                IP Address        Status              Region        Image                     Time Left
+=====================================================================================================================
+linode      12345678              gmab-abc123def456    192.168.1.100    running             us-east       linode/ubuntu22.04        45m
+aws         i-0abc123def456789    gmab-def456abc789    10.0.1.100       running             us-west-2     ami-123456789abc         30m
+hetzner     98765432              gmab-ghi789jkl012    10.0.0.100       running             nbg1          ubuntu-22.04             15m
+aws         i-0xyz987wvu654321    gmab-mno345pqr678    10.0.2.200       running (expired)   us-east-1     ami-987654321xyz         expired
+```
+
+### Terminate Command
+```bash
+$ gmab terminate gmab-abc123def456 i-0abc123def456789
+Are you sure you want to terminate instances: 'gmab-abc123def456', 'i-0abc123def456789'? [y/N]: y
+Terminated instance 'gmab-abc123def456' on 'linode'.
+Terminated instance 'i-0abc123def456789' on 'aws'.
+Successfully terminated 2 instance(s).
+
+$ gmab terminate all
+The following instances will be terminated:
+- 98765432 (hetzner: gmab-ghi789jkl012)
+- i-0xyz987wvu654321 (aws: gmab-mno345pqr678)
+Do you want to proceed? [y/N]: y
+Successfully terminated 2 instance(s).
+```
+
+### Terminate Expired Command
+```bash
+$ gmab terminate expired
+The following expired instances will be terminated:
+- i-0xyz987wvu654321 (aws: gmab-mno345pqr678)
+Do you want to proceed? [y/N]: y
+Successfully terminated 1 instance(s).
+
+$ gmab terminate expired
+No expired instances found.
+```
+
+## Configuration Storage
+GMAB follows platform-specific standards for storing configuration:
+
+- Linux/macOS: `~/.config/gmab/` or `$XDG_CONFIG_HOME/gmab/`
+- Windows: `%APPDATA%\gmab\`
+- Override: Set `GMAB_CONFIG_DIR` environment variable
+
+Two main configuration files are used:
+1. `config.json` - General settings (SSH key, default lifetime, default provider)
+2. `providers.json` - Provider-specific credentials and defaults
+
+
+### AWS Resources Created
+When using AWS as a provider, GMAB automatically creates and manages the following resources:
+
+1. **VPC (Virtual Private Cloud)**
+   - Named: 'gmab-vpc'
+   - CIDR: 10.0.0.0/16
+   - DNS hostnames enabled
+
+2. **Internet Gateway**
+   - Named: 'gmab-igw'
+   - Attached to gmab-vpc
+
+3. **Subnet**
+   - Named: 'gmab-subnet'
+   - CIDR: 10.0.1.0/24
+   - Auto-assign public IP enabled
+
+4. **Route Table**
+   - Named: 'gmab-rt'
+   - Routes all traffic (0.0.0.0/0) through the internet gateway
+   - Associated with gmab-subnet
+
+5. **Security Group**
+   - Named: 'gmab-sg'
+   - Inbound rules: SSH (port 22) from anywhere
+   - All resources are tagged with 'gmab=true'
+
+### Provider Recommendations
+While GMAB supports multiple cloud providers, it has been primarily developed and tested with Linode in mind. Linode typically offers:
+
+- Faster instance provisioning times
+- Simpler setup (no VPC/networking configuration needed)
+- More straightforward API and authentication
+- Lower costs for basic instances
+- Consistent image names across regions (e.g., "linode/ubuntu22.04" works everywhere)
+
+Hetzner Cloud provides similar ease of use and speed to Linode, with:
+- Simple API and quick instance provisioning
+- Consistent image names across regions
+- Automatic network configuration
+- Competitive pricing
+
+AWS on the other hand adds some complexity due to:
+- Network setup (VPC, subnet, security groups) required per region
+- AMI IDs (image IDs) are different between regions
+- Instance types may not be available in all regions
+- Slower API responses and instance provisioning
+- More complex authentication setup
+
+For these reasons, when using GMAB with AWS we recommend:
+- Stick to one region for all your instances
+- Make sure your chosen AMI ID exists in your region
+- Use modern instance types (t3.micro instead of t2.micro) for better region compatibility
+- Configure your AWS credentials properly with sufficient permissions for VPC/networking
+- Be patient as instance creation takes longer than other providers
+
+If you're just getting started with GMAB, we recommend beginning with Linode or Hetzner for the simplest experience.
+
+## Example configuration session:
+```bash
+$ gmab configure
+Using config directory: /home/user/.config/gmab
+
+Configuring general settings:
+SSH public key path [~/.ssh/id_ed25519.pub]: 
+Default instance lifetime (minutes) [60]: 
+Default provider (linode, aws, hetzner) [linode]: 
+
+Do you want to configure linode? [Y/n]: y
+
+Configuring linode provider:
+API Key: your-api-key-here
+Default region [nl-ams]: 
+Default instance type [g6-nanode-1]: 
+Default image [linode/ubuntu22.04]: 
+Default root password: your-root-password
+
+Do you want to configure aws? [Y/n]: y
+
+Configuring aws provider:
+Access Key: your-access-key
+Secret Key: your-secret-key
+Default region [eu-west-1]: 
+Default image [ami-12345678]: 
+Default instance type [t2.micro]: 
+
+Do you want to configure hetzner? [Y/n]: n
+
+Configuration completed successfully!
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

gmab-0.1.1/README.md

@@ -0,0 +1,322 @@
+# GMAB (Give Me A Box) v0.1.1
+
+A CLI tool to spawn, list, and manage temporary cloud boxes.
+
+#### Why?
+
+- Need a quick VPS for pentesting, bug bounty, or scanning?
+- Want to run commands from a different IP without using your local machine?
+- No need for manual cloud console interaction—just **gmab spawn**, and you're in!
+
+
+## Features
+
+- Spawn temporary cloud instances that automatically expire
+- List active instances across providers
+- Terminate instances individually or in bulk
+- Support for multiple cloud providers (Linode, AWS, Hetzner)
+- Provider-agnostic command interface
+- SSH key management
+
+## Installation
+
+### Using pip
+
+The easiest way to install GMAB is directly from PyPI:
+
+```bash
+pip install gmab
+```
+
+### From Source
+
+You can also install directly from the source code:
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/gmab.git
+cd gmab
+
+# Install the package
+pip install .
+
+# For development (editable mode)
+pip install -e .
+```
+
+## Configuration
+Before you can use GMAB, you need to configure it with your provider credentials and preferences. You must run the `configure` command before using any other functionality.
+
+### Interactive Configuration
+
+Use the configure command to set up or modify your configuration:
+
+```bash
+# Configure all settings and providers
+gmab configure
+
+# Configure a specific provider
+gmab configure -p linode
+```
+
+> **Note:** GMAB will only use providers that you've explicitly configured. If you don't configure a provider, GMAB will not attempt to use it, preventing any unnecessary API calls or errors.
+
+### Viewing Configuration
+
+You can view your current configuration using the `--print` flag:
+
+```bash
+gmab configure --print
+```
+
+This will display:
+- The location of your config files
+- The contents of your configuration (with sensitive data masked)
+- The current settings for all configured providers
+
+## Usage
+
+### Spawn a new instance
+```bash
+# Using default provider
+gmab spawn
+
+# Specify a provider
+gmab spawn --provider linode
+gmab spawn --provider aws
+gmab spawn --provider hetzner
+
+# Override defaults
+gmab spawn -p linode -r us-east -i linode/ubuntu22.04 -t 120
+```
+
+### List instances
+```bash
+# List all instances
+gmab list
+
+# List instances for specific provider
+gmab list --provider linode
+```
+
+### Terminate instances
+```bash
+# Terminate by ID or label
+gmab terminate instance-123
+gmab terminate my-instance-label
+
+# Terminate multiple instances
+gmab terminate instance-1 instance-2
+
+# Terminate all instances
+gmab terminate all
+
+# Terminate expired instances
+gmab terminate expired
+```
+
+## Provider-Specific Notes
+
+### Linode
+- Requires API key with full access
+- Default instance type: Nanode 1GB
+- Supports all regions
+
+### AWS
+- Requires access key and secret key
+- Default instance type: t2.micro
+- Creates VPC and security group if needed
+- Supports all regions
+
+### Hetzner
+- Requires API token
+- Default instance type: CPX11
+- Supports all Hetzner Cloud regions
+- Uses label-based instance tracking
+
+## Best Practices
+
+1. **SSH Key**: Use an ed25519 key pair for better security
+```bash
+ssh-keygen -t ed25519 -C "your_email@example.com"
+```
+
+2. **Instance Lifetime**: Set reasonable expiration times and automatic cleanup
+```bash
+# Set lifetime when spawning
+gmab spawn -t 60  # 60 minutes lifetime
+
+# Set up automatic cleanup with cron (Linux/Mac)
+# Run every hour to clean up expired instances
+0 * * * * gmab terminate expired -y
+
+# For Windows, use Task Scheduler to run:
+# gmab.exe terminate expired -y
+```
+
+3. **Regular Cleanup**: Periodically check and terminate expired instances
+```bash
+gmab terminate expired
+```
+
+4. **Provider Organization**:
+- AWS: Create a dedicated IAM user for GMAB
+- Linode: Use a dedicated API key
+- Hetzner: Create a dedicated project named "gmab" and generate the API token specifically for this project
+
+5. **Security**:
+- Store configuration files securely
+- Don't commit provider credentials to version control
+- Regularly rotate API keys and tokens
+
+## Example Commands and Outputs
+
+### List Command
+```bash
+$ gmab list
+Provider    Instance ID            Label                IP Address        Status              Region        Image                     Time Left
+=====================================================================================================================
+linode      12345678              gmab-abc123def456    192.168.1.100    running             us-east       linode/ubuntu22.04        45m
+aws         i-0abc123def456789    gmab-def456abc789    10.0.1.100       running             us-west-2     ami-123456789abc         30m
+hetzner     98765432              gmab-ghi789jkl012    10.0.0.100       running             nbg1          ubuntu-22.04             15m
+aws         i-0xyz987wvu654321    gmab-mno345pqr678    10.0.2.200       running (expired)   us-east-1     ami-987654321xyz         expired
+```
+
+### Terminate Command
+```bash
+$ gmab terminate gmab-abc123def456 i-0abc123def456789
+Are you sure you want to terminate instances: 'gmab-abc123def456', 'i-0abc123def456789'? [y/N]: y
+Terminated instance 'gmab-abc123def456' on 'linode'.
+Terminated instance 'i-0abc123def456789' on 'aws'.
+Successfully terminated 2 instance(s).
+
+$ gmab terminate all
+The following instances will be terminated:
+- 98765432 (hetzner: gmab-ghi789jkl012)
+- i-0xyz987wvu654321 (aws: gmab-mno345pqr678)
+Do you want to proceed? [y/N]: y
+Successfully terminated 2 instance(s).
+```
+
+### Terminate Expired Command
+```bash
+$ gmab terminate expired
+The following expired instances will be terminated:
+- i-0xyz987wvu654321 (aws: gmab-mno345pqr678)
+Do you want to proceed? [y/N]: y
+Successfully terminated 1 instance(s).
+
+$ gmab terminate expired
+No expired instances found.
+```
+
+## Configuration Storage
+GMAB follows platform-specific standards for storing configuration:
+
+- Linux/macOS: `~/.config/gmab/` or `$XDG_CONFIG_HOME/gmab/`
+- Windows: `%APPDATA%\gmab\`
+- Override: Set `GMAB_CONFIG_DIR` environment variable
+
+Two main configuration files are used:
+1. `config.json` - General settings (SSH key, default lifetime, default provider)
+2. `providers.json` - Provider-specific credentials and defaults
+
+
+### AWS Resources Created
+When using AWS as a provider, GMAB automatically creates and manages the following resources:
+
+1. **VPC (Virtual Private Cloud)**
+   - Named: 'gmab-vpc'
+   - CIDR: 10.0.0.0/16
+   - DNS hostnames enabled
+
+2. **Internet Gateway**
+   - Named: 'gmab-igw'
+   - Attached to gmab-vpc
+
+3. **Subnet**
+   - Named: 'gmab-subnet'
+   - CIDR: 10.0.1.0/24
+   - Auto-assign public IP enabled
+
+4. **Route Table**
+   - Named: 'gmab-rt'
+   - Routes all traffic (0.0.0.0/0) through the internet gateway
+   - Associated with gmab-subnet
+
+5. **Security Group**
+   - Named: 'gmab-sg'
+   - Inbound rules: SSH (port 22) from anywhere
+   - All resources are tagged with 'gmab=true'
+
+### Provider Recommendations
+While GMAB supports multiple cloud providers, it has been primarily developed and tested with Linode in mind. Linode typically offers:
+
+- Faster instance provisioning times
+- Simpler setup (no VPC/networking configuration needed)
+- More straightforward API and authentication
+- Lower costs for basic instances
+- Consistent image names across regions (e.g., "linode/ubuntu22.04" works everywhere)
+
+Hetzner Cloud provides similar ease of use and speed to Linode, with:
+- Simple API and quick instance provisioning
+- Consistent image names across regions
+- Automatic network configuration
+- Competitive pricing
+
+AWS on the other hand adds some complexity due to:
+- Network setup (VPC, subnet, security groups) required per region
+- AMI IDs (image IDs) are different between regions
+- Instance types may not be available in all regions
+- Slower API responses and instance provisioning
+- More complex authentication setup
+
+For these reasons, when using GMAB with AWS we recommend:
+- Stick to one region for all your instances
+- Make sure your chosen AMI ID exists in your region
+- Use modern instance types (t3.micro instead of t2.micro) for better region compatibility
+- Configure your AWS credentials properly with sufficient permissions for VPC/networking
+- Be patient as instance creation takes longer than other providers
+
+If you're just getting started with GMAB, we recommend beginning with Linode or Hetzner for the simplest experience.
+
+## Example configuration session:
+```bash
+$ gmab configure
+Using config directory: /home/user/.config/gmab
+
+Configuring general settings:
+SSH public key path [~/.ssh/id_ed25519.pub]: 
+Default instance lifetime (minutes) [60]: 
+Default provider (linode, aws, hetzner) [linode]: 
+
+Do you want to configure linode? [Y/n]: y
+
+Configuring linode provider:
+API Key: your-api-key-here
+Default region [nl-ams]: 
+Default instance type [g6-nanode-1]: 
+Default image [linode/ubuntu22.04]: 
+Default root password: your-root-password
+
+Do you want to configure aws? [Y/n]: y
+
+Configuring aws provider:
+Access Key: your-access-key
+Secret Key: your-secret-key
+Default region [eu-west-1]: 
+Default image [ami-12345678]: 
+Default instance type [t2.micro]: 
+
+Do you want to configure hetzner? [Y/n]: n
+
+Configuration completed successfully!
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

gmab-0.1.1/gmab/__init__.py

@@ -0,0 +1,7 @@
+# gmab/__init__.py
+
+"""
+GMAB (Give Me A Box) - CLI tool to spawn, list, and manage temporary cloud boxes.
+"""
+
+__version__ = "0.1.1"