x4

Crates.io	x4
lib.rs	x4
version	0.1.0
source	src
created_at	2024-10-05 19:22:20.512521
updated_at	2024-10-05 19:22:20.512521
description	Execute shell commands to a server via ssh protocol
homepage	https://github.com/pwnwriter/x4
repository	https://github.com/pwnwriter/x4
max_upload_size
id	1398404
size	60,311

Nabeen Tiwaree (pwnwriter)

documentation

README

server image

A lightweight implementation of libssh2 to execute shell commands on remote servers with rich configuration via json.

Features and todos
Requirements
Installation
Usages
Configuration
- Options
  - Examples
Development
Support my work

Features and todos

retrieve the password from environment variables
retrieve the password by executing a shell command

usages pass password manager to get the user password and ssh's into the server

https://github.com/user-attachments/assets/2a85e2ab-c762-41e0-855d-fa8e6d15f5e0
format stderr and stdout outputs for better readability
check pipeline configuration
Implement file upload and download functionality
Allow connections through a proxy server
Implement unit tests for critical features
Current configuration is with json but with lua ? planned yes!!
Better code, docs and more
More ways to get the json value fields, like password ?
You tell more.

Requirements

ssh connection: must have ssh connections using one of the following authentication methods:
- password authentication: using the username and password.
- keypair: public key authentication.
- No extra deps will be required for runtime

Installation

Binary

manual: you can directly download the binary from releases of your arch and run it.
one liner: run this one liner script

wget -qo- "$(curl -qfssl "https://api.github.com/repos/pwnwriter/x4/releases/latest" | jq -r '.assets[].browser_download_url' | grep -ei "$(uname -m).*$(uname -s).*musl" | grep -v "\.sha")" | tar -xzf - --strip-components=1 && ./x4 -h

source

git clone --depth=1 https://github.com/pwnwriter/x4 --branch=main
cd x4
cargo build --release

then go to release dir and ./x4 or move the binary to your any $path for instant access from anywhere.

[!NOTE]
This requires a working setup of rust/cargo and binstall.

cargo

using crates.io
```
cargo install x4
```
using binstall
```
cargo binstall x4
```

on nix

Source build
```
nix run github:pwnwriter/x4
```
With flakes:
```
nix profile install nixpkgs#x4
```
Without flakes:
```
 nix-env -ia nixpkgs.x4
```

Usages

Usage: x4 [OPTIONS]

Options:
  -p, --pipeline <PIPELINE>              Path to your pipeline file
      --check-pipeline <CHECK_PIPELINE>  Check the configuration of the specified pipeline
  -h, --help                             Print help
  -V, --version                          Print version

Configuration

Options

The configuration JSON supports the following key values for server definitions:

Key	Description	Example Value
`description`	A brief description of the server's purpose or role.	My hot EC2 instance
`name`	A unique identifier for the server.	ec2
`host`	The hostname or IP address of the server.	fawn.pwnwriter.xyz
`port`	The SSH port to connect to the server. Defaults to `22`.	22
`user`	The username used for SSH authentication.	fawn
`password`	Method of authentication for SSH: use an environment variable (prefix with `env:`) or a command (prefix with `cmd:`). See Password Retrieval for details.	`env:wolf_pass` or `cmd:pass uni/server/wolf`
`commands`	An array of commands to execute once the SSH connection is established.	`[pnpm run build && pnpm start]`

Password Retrieval

The password field allows for secure handling of sensitive information using either environment variables or commands.

Using Environment Variables: To set your password as an environment variable in your shell, run:
```
export wolf_pass='my_secure_password'
```
You can then reference this variable in your configuration like so:
```
"password": "env:wolf_pass"
```
Using Commands: If you use the pass password manager, you can retrieve your password with a command. For instance:
```
"password": "cmd:pass uni/server/wolf"
```
This command will execute pass to get the password stored under uni/server/wolf.

Examples

Single server Configuration with cmd for password

{
  "servers": [
    {
      "description": "using a cmd to get password for SSH authentication and default 22 port",
      "name": "ec2",
      "host": "fawn.pwnwriter.xyz",
      "user": "wolf",
      "password": "cmd:pass personal/server/root",
      "commands": [
        "ping -c 3 google.com",
        "ls"
      ]
    }
  ]
}

More than one server configuration

{
  "servers": [
    {
      "description": "using a cmd to get password for SSH authentication and default 22 port",
      "name": "ec201",
      "host": "fawn.pwnwriter.xyz",
      "user": "wolf",
      "password": "cmd:pass personal/server/root",
      "commands": [
        "mkdir -p from_many_at_wolf",
        "cat /etc/os-release"
      ]
    },
    {
      "description": "using a private key for SSH authentication and default 22 port",
      "name": "ec2",
      "host": "fawn.pwnwriter.xyz",
      "user": "fawn",
      "private_key": "/Users/pwnwriter/.local/share/ssh/wynwood.pem",
      "commands": [
        "mkdir from_many_at_fawn",
        "mkdir from_manyyyy"
      ]
    }
  ]
}

Development

if you are using nix,

get into the development shell

nix develop or use

direnv allow to enter a shell with all required deps.

nix build/run to build and run the app.

nix run github:pwnwriter/x4 -- --help

Support my work

I do open source work in my free time, and I really enjoy it! If any of my applications have helped you in any way, please consider supporting me via Ko-fi. Your support enables me to continue developing and improving my projects.

Commit count: 74

x4