qxshell
v1.0.7
Published
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
Downloads
148
Readme
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
Running the Client
qxshell --config path/to/client-config.json
Generate Credentials
qxshell --credentials
How It Works
- 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. - 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.
- 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.
- Connection Establishment: Clients and server communicate over the MQTT broker using the provided credentials, establishing a fully encrypted channel to ensure confidentiality.
- 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).