qxshell v1.0.15

QX Shell

QX Shell is a secure, end-to-end encrypted shell system that leverages MQTT for real-time data exchange. It allows users to run a remote shell session over an MQTT broker with end-to-end encryption, ensuring that all communications remain confidential and protected from unauthorized access.

Installation

Install qx-shell globally via NPM to access the command-line tools:

npm install -g qx-shell

This will install the following command:

• qxshell

Prerequisites

• Node.js (version 20 or higher recommended)
• A working MQTT broker (e.g., HiveMQ, Mosquitto, self-hosted)

Usage

Generating Credentials

To generate a new set of credentials (ID and Secret Key), use the --credentials option:

qxshell --credentials

Example Output:

ID: your-generated-id
SK: your-generated-secret-key

Running as Server or Client

Use the --config option to specify a configuration file. The configuration file must include a role attribute to determine whether to run as a server or client.

Configuration File Structure

• Server Configuration (server-config.json):

{
  "role": "server",
  "id": "server-id",
  "sk": "server-secret-key",
  "heartbeat": 5000,
  "peerIds": ["client-id-1", "client-id-2"],
  "mqtt": {
    "host": "mqtt://broker.hivemq.com",
    "options": {
      // MQTT options (username, password, etc.)
    }
  },
  "shell": "bash" // Optional, defaults to the system shell
}

• Client Configuration (client-config.json):

{
  "role": "client",
  "id": "client-id",
  "sk": "client-secret-key",
  "heartbeat": 5000,
  "peerIds": ["server-id"],
  "mqtt": {
    "host": "mqtt://broker.hivemq.com",
    "options": {
      // MQTT options (username, password, etc.)
    }
  }
}

Running the Server

qxshell --config path/to/server-config.json

To run in pm2: pm2 start qxshell -- -c path/to/server-config.json

Running the Client

qxshell --config path/to/client-config.json

Generate Credentials

qxshell --credentials

How It Works

1. Credential Generation: Users generate unique credentials (ID and Secret Key) for both server and clients, which act as cryptographic keys. These credentials are used to facilitate end-to-end encryption through the NaCl library provided by the qxbot library.
2. Server Setup: The server is configured with its credentials and the list of authorized client IDs. These credentials ensure secure communication between the server and authorized clients.
3. Client Setup: Each client is configured with its own credentials, along with the server's ID. The NaCl-based encryption guarantees that only authorized clients can communicate with the server.
4. Connection Establishment: Clients and server communicate over the MQTT broker using the provided credentials, establishing a fully encrypted channel to ensure confidentiality.
5. Shell Interaction: Users can securely execute shell commands on the remote server through the client interface, with all communications protected by end-to-end encryption.

Security

QX Shell uses NaCl-based encryption provided by the qxbot library for end-to-end security. It’s essential to keep your generated credentials private and never share your secret key publicly.

Best practices:

• Use strong and unique credentials.
• Regularly update your secret keys.
• Ensure that the MQTT broker you use supports encrypted connections (TLS/SSL).