https://github.com/bytehunt/x4
💭 Execute shell commands to server(s) via ssh protocol
https://github.com/bytehunt/x4
cicd-json-pipeline libssh2 rustlang ssh ssh-commands
Last synced: 10 months ago
JSON representation
💭 Execute shell commands to server(s) via ssh protocol
- Host: GitHub
- URL: https://github.com/bytehunt/x4
- Owner: bytehunt
- License: mit
- Created: 2024-09-17T20:14:34.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-28T20:54:46.000Z (about 1 year ago)
- Last Synced: 2025-04-15T01:04:59.245Z (10 months ago)
- Topics: cicd-json-pipeline, libssh2, rustlang, ssh, ssh-commands
- Language: Rust
- Homepage: https://crates.io/crates/x4
- Size: 144 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
A lightweight implementation of libssh2 to execute shell commands on remote servers with rich configuration via json.
- [Features and todos](#features-and-todos)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usages](#usages)
- [Configuration](#configuration)
- [Options](#options)
- [Examples](#examples)
- [Development](#development)
- [Support my work](#support-my-work)
---
> [!TIP]
> Here's a blogpost on how i use [**x4 to deploy a website on aws ec2 instance**](/.github/guide.md)
## Features and todos
- [x] retrieve the password from environment variables
- [x] 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
- [x] format `stderr` and `stdout` outputs for better readability
- [x] 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**](https://github.com/pwnwriter/x4/releases) of your arch and run it.
- **one liner**: run this one liner script
```bash
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
```bash
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](https://crates.io/crates/x4)
```bash
cargo install x4
```
- using [binstall](https://github.com/cargo-bins/cargo-binstall)
```bash
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
```yaml
Usage: x4 [OPTIONS]
Options:
-p, --pipeline Path to your pipeline file
--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](#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:
```bash
export wolf_pass='my_secure_password'
```
You can then reference this variable in your configuration like so:
```json
"password": "env:wolf_pass"
```
- **Using Commands**:
If you use the `pass` password manager, you can retrieve your password with a command. For instance:
```json
"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`
```json
{
"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
```json
{
"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 🍃