s-b-repo-rustsploit/docs/Getting-Started.md

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 REST API server, and an ever-growing library of exploits, scanners, and credential modules.

---

Requirements

System Dependencies

Debian / Ubuntu / Kali:

sudo apt update
sudo apt install pkg-config libssl-dev rustc libdbus-1-dev 

Arch Linux:

sudo pacman -S pkgconf openssl freerdp rustc

Gentoo:

sudo emerge dev-libs/openssl dev-util/pkgconf net-misc/freerdp

Fedora / RHEL:

sudo dnf install pkgconf-pkg-config openssl-devel freerdp rustc

Rust & Cargo

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

The minimum supported Rust version tracks stable. Run rustup update to stay current.

---

Clone & Build

git clone https://github.com/s-b-repo/rustsploit.git
cd rustsploit
cargo build

For a release-optimized binary:

cargo build --release
# Binary written to target/release/rustsploit

Quick install

sudo su

sudo bash -c 'apt update -y && apt upgrade -y && apt install -y pkg-config libssl-dev rustc libdbus-1-dev git && curl --proto '"'"'=https'"'"' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && source $HOME/.cargo/env && git clone https://github.com/s-b-repo/rustsploit.git && cd rustsploit && cargo build && cargo run'

---

Run

Interactive Shell

cargo run

CLI (non-interactive)

cargo run -- -m exploits/heartbleed -t 192.168.1.1

See CLI Reference for all flags.

API Server

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 and API Usage Examples for details.

MCP Integration

cargo run -- --mcp

This starts the MCP (Model Context Protocol) server over stdio using JSON-RPC 2.0 transport. It exposes 30 tools and 7 resources for integration with Claude Desktop and other MCP-compatible clients. No network listener is opened — communication is over stdin/stdout.

To use with Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "rustsploit": {
      "command": "/path/to/rustsploit",
      "args": ["--mcp"]
    }
  }
}

See MCP Integration for the full tool and resource reference.

---

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

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

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:

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:

• 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.