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

---

Tip

Here's a blogpost on how i use x4 to deploy a website on aws ec2 instance

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

  x4-with-gpg-pass.mov

• 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.me
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.me",
      "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.me",
      "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.me",
      "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.

copyright © 2024 pwnwriter.me 🍃