mirror of
https://github.com/s-b-repo/rustsploit
synced 2026-06-27 09:54:12 +00:00
S.B
201 lines
5.8 KiB
Markdown
201 lines
5.8 KiB
Markdown
# Getting Started
|
||
|
||
Rustsploit is a modular offensive tooling framework for embedded targets, written in Rust and inspired by RouterSploit/Metasploit. It ships an interactive shell, a CLI runner, a WebSocket API server with post-quantum encryption, and an ever-growing library of exploits, scanners, and credential modules.
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
### System Dependencies
|
||
|
||
**Debian / Ubuntu / Kali:**
|
||
```bash
|
||
sudo apt update && sudo apt install -y build-essential pkg-config libssl-dev libdbus-1-dev cmake clang lld mold
|
||
```
|
||
|
||
> `clang`, `lld`, and `mold` are optional but strongly recommended — the repo's `.cargo/config.toml` is preconfigured to use a fast linker (see [Faster Builds](#faster-builds) below).
|
||
|
||
**Arch Linux:**
|
||
```bash
|
||
sudo pacman -S base-devel pkgconf openssl dbus cmake
|
||
```
|
||
|
||
**Gentoo:**
|
||
```bash
|
||
sudo emerge dev-libs/openssl dev-util/pkgconf sys-apps/dbus dev-build/cmake
|
||
```
|
||
|
||
**Fedora / RHEL:**
|
||
```bash
|
||
sudo dnf install gcc make pkgconf-pkg-config openssl-devel dbus-devel cmake
|
||
```
|
||
|
||
### Rust & Cargo
|
||
|
||
```bash
|
||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||
source $HOME/.cargo/env
|
||
```
|
||
|
||
> Rust 1.85+ is required (edition 2024). Run `rustup update` to stay current.
|
||
|
||
---
|
||
|
||
## Clone & Build
|
||
|
||
```bash
|
||
git clone https://github.com/s-b-repo/rustsploit.git
|
||
cd rustsploit
|
||
cargo build
|
||
```
|
||
|
||
For a release-optimized binary:
|
||
```bash
|
||
cargo build --release
|
||
# Binary written to target/release/rustsploit
|
||
```
|
||
|
||
---
|
||
|
||
## Faster Builds
|
||
|
||
The repository ships with build-performance tuning already applied:
|
||
|
||
- **`.cargo/config.toml`** — uses `clang` + `lld` as the linker on Linux and enables the sparse crates.io registry protocol.
|
||
- **`Cargo.toml` `[profile.dev]`** — `debug = "line-tables-only"` and `codegen-units = 256` for fast incremental builds with usable backtraces.
|
||
- **`[profile.dev.package."*"]`** — dependencies are still compiled at `opt-level = 2` so runtime stays fast.
|
||
- **`[profile.fast-release]`** — `cargo build --profile fast-release` for release-like binaries with thin LTO and parallel codegen (much faster than `--release`).
|
||
|
||
### Recommended optional tooling
|
||
|
||
**1. Install `mold` (fastest linker on Linux).** It's already in the apt install line above. To switch from `lld` to `mold`, edit `.cargo/config.toml` and replace `-fuse-ld=lld` with `-fuse-ld=mold`.
|
||
|
||
**2. `cargo check` instead of `cargo build`** during iteration — skips codegen entirely:
|
||
```bash
|
||
cargo check
|
||
# or auto-rerun on save:
|
||
cargo install cargo-watch
|
||
cargo watch -x check
|
||
```
|
||
|
||
**3. `sccache` for cross-project caching:**
|
||
```bash
|
||
cargo install sccache
|
||
export RUSTC_WRAPPER=sccache # add to ~/.zshrc or ~/.bashrc
|
||
```
|
||
|
||
**4. Share a target directory across projects** to reuse compiled deps:
|
||
```bash
|
||
export CARGO_TARGET_DIR="$HOME/.cargo-target"
|
||
```
|
||
|
||
### Reducing memory / CPU usage
|
||
|
||
If `cargo build` thrashes RAM or pegs all cores, cap parallelism:
|
||
```bash
|
||
cargo build -j 4 # limit parallel compile jobs
|
||
CARGO_BUILD_JOBS=4 cargo build # or via env
|
||
```
|
||
A good rule of thumb: `-j $(($(nproc) / 2))` on memory-constrained machines. Each rustc job can use 1–2 GiB on heavy crates.
|
||
|
||
### Quick reference
|
||
|
||
| Goal | Command |
|
||
|------|---------|
|
||
| Type-check only (fastest) | `cargo check` |
|
||
| Dev build | `cargo build` |
|
||
| Release-like, fast to compile | `cargo build --profile fast-release` |
|
||
| Fully optimized release | `cargo build --release` |
|
||
| Limit RAM/CPU | `cargo build -j 4` |
|
||
|
||
---
|
||
|
||
## Run
|
||
|
||
### Interactive Shell
|
||
```bash
|
||
cargo run
|
||
```
|
||
|
||
### CLI (non-interactive)
|
||
```bash
|
||
cargo run -- -m exploits/heartbleed -t 192.168.1.1
|
||
```
|
||
|
||
See [CLI Reference](CLI-Reference.md) for all flags.
|
||
|
||
### API Server
|
||
```bash
|
||
cargo run -- --api
|
||
```
|
||
|
||
This starts the PQ-encrypted API server on port 8080. On first run it generates a host key pair at `~/.rustsploit/pq_host_key` and prints its fingerprint. Clients must be listed in `~/.rustsploit/pq_authorized_keys` to connect. No TLS or API keys — authentication uses SSH-style post-quantum identity keys. See [API Server](API-Server.md) and [API Usage Examples](API-Usage-Examples.md) for details.
|
||
|
||
---
|
||
|
||
## Docker Deployment
|
||
|
||
Rustsploit ships a provisioning script that builds and launches the API inside Docker.
|
||
|
||
### Requirements
|
||
|
||
- Docker Engine 24+ (or Docker Desktop)
|
||
- Docker Compose plugin (`docker compose`) or legacy `docker-compose`
|
||
- Python 3.8+
|
||
|
||
### Interactive Setup
|
||
|
||
```bash
|
||
python3 scripts/setup_docker.py
|
||
```
|
||
|
||
The helper will:
|
||
1. Confirm you are in the repository root (`Cargo.toml` present).
|
||
2. Ask how the API should bind (`127.0.0.1`, `0.0.0.0`, detected LAN IP, or custom `host:port`).
|
||
3. Generate or configure PQ identity keys for the API server.
|
||
4. Toggle hardening mode and tune the IP limit.
|
||
5. Generate:
|
||
- `docker/Dockerfile.api`
|
||
- `docker/entrypoint.sh`
|
||
- `.env.rustsploit-docker`
|
||
- `docker-compose.rustsploit.yml`
|
||
6. Optionally run `docker compose up -d --build` with BuildKit enabled.
|
||
|
||
Existing files are never overwritten without confirmation.
|
||
|
||
### Non-Interactive / CI
|
||
|
||
```bash
|
||
python3 scripts/setup_docker.py \
|
||
--bind 0.0.0.0:8443 \
|
||
--generate-key \
|
||
--enable-hardening \
|
||
# PQ identity keys auto-generated on first run
|
||
--skip-up \
|
||
--force \
|
||
--non-interactive
|
||
```
|
||
|
||
To start the stack later:
|
||
```bash
|
||
docker compose -f docker-compose.rustsploit.yml up -d --build
|
||
```
|
||
|
||
---
|
||
|
||
## Privacy / VPN
|
||
|
||
The built-in proxy system has been removed in favor of system-level VPN solutions.
|
||
|
||
We recommend **[Mullvad VPN](https://mullvad.net)**:
|
||
- No registration — account numbers generated without email or personal data
|
||
- Proven no-logs policy with audited infrastructure
|
||
- WireGuard support for high-performance, low-latency tunneling
|
||
- Excellent Linux CLI for headless setups
|
||
|
||
Connect the VPN on your host before running Rustsploit and all traffic routes through the tunnel automatically.
|
||
|
||
---
|
||
|
||
> ⚠️ For authorized security testing and research only. Obtain explicit written permission before targeting any system you do not own.
|