gcli-control 0.1.0__tar.gz

gcli_control-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: gcli-control
+Version: 0.1.0
+Summary: Remote access tool via npoint.io - encrypted command relay using AES-256-GCM
+Author: gcli contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gcli-control/gcli
+Project-URL: Repository, https://github.com/gcli-control/gcli
+Project-URL: Issues, https://github.com/gcli-control/gcli/issues
+Keywords: remote-access,npoint,encrypted,ssh,aes256
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+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: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0
+
+# gcli
+
+Remote access tool via [npoint.io](https://npoint.io) — encrypted command relay using AES-256-GCM.
+
+## How It Works
+
+```
+┌──────────┐     commands     ┌─────────────┐     commands     ┌──────────┐
+│ gcli ssh │ ───────────────> │ npoint.io   │ ───────────────> │gcli host │
+│ (client) │ <─────────────── │ (JSON bin)  │ <─────────────── │ (daemon) │
+└──────────┘     results      └─────────────┘     results      └──────────┘
+```
+
+1. **`gcli host`** starts a background daemon that polls npoint.io for encrypted commands
+2. **`gcli ssh`** connects interactively, sends encrypted commands, and polls for results
+3. All payloads are encrypted with **AES-256-GCM** — the password never leaves your machine
+
+## Quick Start
+
+### Install
+
+```bash
+pip install cryptography
+```
+
+### Host (on the remote machine)
+
+```bash
+# Start the daemon (runs in background)
+python -m gcli host --password MySecret123
+
+# Or run in foreground for debugging
+python -m gcli host --password MySecret123 --foreground
+```
+
+### Client (on your local machine)
+
+```bash
+# Connect to the host
+python -m gcli ssh --password MySecret123
+```
+
+### Stop the host
+
+```bash
+python -m gcli stop
+```
+
+## SSH Commands
+
+Once connected, you have a full interactive REPL:
+
+| Command | Description |
+|---------|-------------|
+| Any text | Execute shell command on remote host |
+| `:help` | Show available commands |
+| `:info` | Show remote system info (hostname, OS, user, IP) |
+| `:ping` | Ping remote host and show latency |
+| `:upload <local> <remote>` | Upload a file to the remote host |
+| `:download <remote> <local>` | Download a file from the remote host |
+| `:timeout <seconds>` | Set exec command timeout |
+| `:history` | Show recent command history |
+| `:exit` | Disconnect and close session |
+
+## Security
+
+- **AES-256-GCM** encryption with PBKDF2 key derivation (600K iterations)
+- Password is never transmitted — only encrypted payloads flow through npoint.io
+- Each message gets a unique random nonce (prevents identical plaintext detection)
+- Built-in tamper detection (GCM authentication tag)
+
+## Cross-Platform
+
+| Platform | Background Detach | Process Management |
+|----------|-------------------|-------------------|
+| Windows  | `CREATE_NO_WINDOW` subprocess | `tasklist` / `taskkill` |
+| Linux    | Double-fork + `setsid` | `kill` / `os.kill` |
+| macOS    | Double-fork + `setsid` | `kill` / `os.kill` |
+
+## Configuration
+
+```bash
+# Custom npoint bin (both host and client must use the same bin)
+python -m gcli host --password MySecret --bin YOUR_NPOINT_BIN_ID
+python -m gcli ssh --password MySecret --bin YOUR_NPOINT_BIN_ID
+
+# Adjust polling speed (default: 2s host, 1s client)
+python -m gcli host --password MySecret --poll-interval 1.0
+```
+
+## Architecture
+
+```
+gcli/
+├── __main__.py      # CLI entry point (argparse)
+├── __init__.py
+├── crypto.py        # AES-256-GCM encrypt/decrypt (PBKDF2 key derivation)
+├── npoint.py        # npoint.io API wrapper with retry logic
+├── protocol.py      # Document structure, read/write, race-condition safe appends
+├── host.py          # Daemon: poll → decrypt → execute → encrypt → respond
+├── client.py        # SSH REPL: send → poll → display (tab completion)
+├── utils.py         # PID management, process detach, command execution
+└── colors.py        # Cross-platform terminal colours (Win/Linux/macOS)
+```
+
+## Requirements
+
+- Python 3.8+
+- `cryptography` package
+- Internet connection (for npoint.io)
+
+## License
+
+MIT

gcli_control-0.1.0/README.md

@@ -0,0 +1,114 @@
+# gcli
+
+Remote access tool via [npoint.io](https://npoint.io) — encrypted command relay using AES-256-GCM.
+
+## How It Works
+
+```
+┌──────────┐     commands     ┌─────────────┐     commands     ┌──────────┐
+│ gcli ssh │ ───────────────> │ npoint.io   │ ───────────────> │gcli host │
+│ (client) │ <─────────────── │ (JSON bin)  │ <─────────────── │ (daemon) │
+└──────────┘     results      └─────────────┘     results      └──────────┘
+```
+
+1. **`gcli host`** starts a background daemon that polls npoint.io for encrypted commands
+2. **`gcli ssh`** connects interactively, sends encrypted commands, and polls for results
+3. All payloads are encrypted with **AES-256-GCM** — the password never leaves your machine
+
+## Quick Start
+
+### Install
+
+```bash
+pip install cryptography
+```
+
+### Host (on the remote machine)
+
+```bash
+# Start the daemon (runs in background)
+python -m gcli host --password MySecret123
+
+# Or run in foreground for debugging
+python -m gcli host --password MySecret123 --foreground
+```
+
+### Client (on your local machine)
+
+```bash
+# Connect to the host
+python -m gcli ssh --password MySecret123
+```
+
+### Stop the host
+
+```bash
+python -m gcli stop
+```
+
+## SSH Commands
+
+Once connected, you have a full interactive REPL:
+
+| Command | Description |
+|---------|-------------|
+| Any text | Execute shell command on remote host |
+| `:help` | Show available commands |
+| `:info` | Show remote system info (hostname, OS, user, IP) |
+| `:ping` | Ping remote host and show latency |
+| `:upload <local> <remote>` | Upload a file to the remote host |
+| `:download <remote> <local>` | Download a file from the remote host |
+| `:timeout <seconds>` | Set exec command timeout |
+| `:history` | Show recent command history |
+| `:exit` | Disconnect and close session |
+
+## Security
+
+- **AES-256-GCM** encryption with PBKDF2 key derivation (600K iterations)
+- Password is never transmitted — only encrypted payloads flow through npoint.io
+- Each message gets a unique random nonce (prevents identical plaintext detection)
+- Built-in tamper detection (GCM authentication tag)
+
+## Cross-Platform
+
+| Platform | Background Detach | Process Management |
+|----------|-------------------|-------------------|
+| Windows  | `CREATE_NO_WINDOW` subprocess | `tasklist` / `taskkill` |
+| Linux    | Double-fork + `setsid` | `kill` / `os.kill` |
+| macOS    | Double-fork + `setsid` | `kill` / `os.kill` |
+
+## Configuration
+
+```bash
+# Custom npoint bin (both host and client must use the same bin)
+python -m gcli host --password MySecret --bin YOUR_NPOINT_BIN_ID
+python -m gcli ssh --password MySecret --bin YOUR_NPOINT_BIN_ID
+
+# Adjust polling speed (default: 2s host, 1s client)
+python -m gcli host --password MySecret --poll-interval 1.0
+```
+
+## Architecture
+
+```
+gcli/
+├── __main__.py      # CLI entry point (argparse)
+├── __init__.py
+├── crypto.py        # AES-256-GCM encrypt/decrypt (PBKDF2 key derivation)
+├── npoint.py        # npoint.io API wrapper with retry logic
+├── protocol.py      # Document structure, read/write, race-condition safe appends
+├── host.py          # Daemon: poll → decrypt → execute → encrypt → respond
+├── client.py        # SSH REPL: send → poll → display (tab completion)
+├── utils.py         # PID management, process detach, command execution
+└── colors.py        # Cross-platform terminal colours (Win/Linux/macOS)
+```
+
+## Requirements
+
+- Python 3.8+
+- `cryptography` package
+- Internet connection (for npoint.io)
+
+## License
+
+MIT

gcli_control-0.1.0/gcli/__init__.py

@@ -0,0 +1,6 @@
+"""
+gcli — remote access tool via npoint.io.
+Encrypted command relay using AES-256-GCM over npoint.io JSON bins.
+"""
+__version__ = "0.1.0"
+__author__ = "gcli"

gcli_control-0.1.0/gcli/__main__.py

@@ -0,0 +1,104 @@
+"""
+gcli — remote access tool via npoint.io.
+
+Commands:
+    gcli host [--password P] [--bin ID] [--poll-interval N]
+    gcli ssh  [--password P] [--bin ID]
+    gcli stop [--bin ID]
+"""
+import argparse
+import sys
+import getpass
+import logging
+
+from .host import start_daemon, stop_daemon, DEFAULT_BIN_ID, DEFAULT_POLL
+from .client import SSHSession
+from .colors import banner, info, error
+
+logger = logging.getLogger("gcli")
+
+
+def cmd_host(args):
+    """Start the gcli host daemon."""
+    password = args.password
+    if not password:
+        password = getpass.getpass("Password: ")
+
+    print(info(f"[gcli] Starting host daemon (bin={args.bin})..."))
+    start_daemon(
+        password=password,
+        bin_id=args.bin,
+        poll_interval=args.poll_interval,
+        foreground=args.foreground,
+    )
+
+
+def cmd_ssh(args):
+    """Connect to a remote gcli host."""
+    password = args.password
+    if not password:
+        password = getpass.getpass("Password: ")
+
+    print(banner())
+    session = SSHSession(
+        password=password,
+        bin_id=args.bin,
+    )
+    session.repl()
+
+
+def cmd_stop(args):
+    """Stop a running gcli daemon."""
+    stop_daemon(bin_id=args.bin)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="gcli",
+        description="Remote access tool via npoint.io — encrypted command relay",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # ---- gcli host ----
+    host_parser = subparsers.add_parser("host", help="Start the background host daemon")
+    host_parser.add_argument("-p", "--password", default=None, help="Encryption password")
+    host_parser.add_argument("-b", "--bin", default=DEFAULT_BIN_ID, help="npoint.io bin ID")
+    host_parser.add_argument("--poll-interval", type=float, default=DEFAULT_POLL,
+                             help="Poll interval in seconds (default: 2.0)")
+    host_parser.add_argument("--foreground", action="store_true",
+                             help="Run in foreground (don't detach)")
+
+    # ---- gcli ssh ----
+    ssh_parser = subparsers.add_parser("ssh", help="Connect to a remote gcli host")
+    ssh_parser.add_argument("-p", "--password", default=None, help="Encryption password")
+    ssh_parser.add_argument("-b", "--bin", default=DEFAULT_BIN_ID, help="npoint.io bin ID")
+
+    # ---- gcli stop ----
+    stop_parser = subparsers.add_parser("stop", help="Stop the host daemon")
+    stop_parser.add_argument("-b", "--bin", default=DEFAULT_BIN_ID, help="npoint.io bin ID")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        print(banner())
+        parser.print_help()
+        sys.exit(1)
+
+    try:
+        if args.command == "host":
+            print(banner())
+            cmd_host(args)
+        elif args.command == "ssh":
+            cmd_ssh(args)
+        elif args.command == "stop":
+            cmd_stop(args)
+    except KeyboardInterrupt:
+        print(f"\n{error('[gcli] Interrupted.')}")
+        sys.exit(130)
+    except Exception as e:
+        logger.error("Fatal error: %s", e)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()