s-b-repo-rustsploit/docs

🛠️ Developer Documentation: RouterSploit-Rust Framework

This document details the internal architecture, auto-dispatch system, proxy retry logic, and step-by-step guide to writing modules for the Rust rewrite of RouterSploit.

---

🧠 Framework Philosophy

RouterSploit-Rust is a modular, async-capable, Rust-based rewrite of RouterSploit. Each module is standalone, invoked via:

• 📟 CLI (cargo run -- --command ...)
• 🖥️ Shell (rsf> prompt)

Goals:

• 🔒 Safe-by-default
• 📦 Cleanly separated modules
• ⚡ Async concurrency
• 🌐 Proxy-aware execution

---

🗂️ Directory Structure

routersploit_rust/
├── Cargo.toml
├── build.rs
└── src/
    ├── main.rs              # Entrypoint
    ├── cli.rs               # CLI argument parser
    ├── shell.rs             # Interactive shell logic
    ├── commands/            # Module dispatch logic
    │   ├── mod.rs
    │   ├── scanner.rs
    │   ├── scanner_gen.rs
    │   ├── exploit.rs
    │   ├── exploit_gen.rs
    │   ├── creds_gen.rs
    │   └── creds.rs
    ├── modules/             # All attack modules
    │   ├── mod.rs
    │   ├── exploits/
    │   ├── scanners/
    │   └── creds/
    └── utils.rs             # Common utilities

---

🔗 Module System

Each module is a Rust file with a required run() entry point:

pub async fn run(target: &str) -> anyhow::Result<()>

Optional:

pub async fn run_interactive(target: &str) -> anyhow::Result<()> {
    // internal prompts or logic
}

Placement:

• Exploits: src/modules/exploits/
• Scanners: src/modules/scanners/
• Credentials: src/modules/creds/

Subfolders are supported:

• exploits/routers/tplink.rs → tplink or routers/tplink
• scanners/http/title.rs → title or http/title

---

✅ Adding a New Module

1. Create File

// src/modules/scanners/ftp_weak_login.rs
use anyhow::Result;

pub async fn run(target: &str) -> Result<()> {
    run_interactive(target).await
}

pub async fn run_interactive(target: &str) -> Result<()> {
    println!("[*] Checking FTP on {}", target);
    Ok(())
}

2. Register in mod.rs

pub mod ftp_weak_login;

---

🧠 Auto-Dispatch System

The CLI/shell can call:

cargo run -- --command scanner --module ftp_weak_login --target 192.168.1.1

Or in the shell:

rsf> use scanners/ftp_weak_login
rsf> set target 192.168.1.1
rsf> run

Behind the scenes:

1. build.rs scans src/modules/ recursively
2. Detects files with pub async fn run(...)
3. Generates:
   • exploit_dispatch.rs
   • scanner_dispatch.rs
   • creds_dispatch.rs
4. Registers short + full names (e.g., ftp_weak_login + scanners/ftp_weak_login)

---

❌ What Not To Do

• ❌ No run() → won’t dispatch
• ❌ Don’t name multiple functions run() in one file
• ❌ Don’t use mod.rs as a module — ignored by generator
• ❌ Don’t forget to update mod.rs when adding modules

---

⚙️ CLI Usage

cargo run -- --command exploit --module my_exploit --target 10.0.0.1

Args:

• --command: exploit | scanner | creds
• --module: file name of module
• --target: IP or host

---

🖥️ Shell Usage

cargo run

Then:

rsf> help
rsf> modules
rsf> use scanners/port_scanner
rsf> set target 192.168.0.1
rsf> run

Maintains internal state:

• current_module
• current_target
• proxy_list
• proxy_enabled

---

🔁 Proxy Retry Logic (Shell Only)

Proxy logic only applies in shell mode (rsf>).

Flow:

1. User types run
2. Shell checks:
   • Module is selected?
   • Target is set?
   • Proxy enabled?

---

Case 1: Proxy ON, Proxies LOADED

• Create HashSet<String> → tried_proxies

• Loop:

  • Pick random untried proxy
  • Set ALL_PROXY using:

    env::set_var("ALL_PROXY", proxy);
    

  • Call commands::run_module(...)
  • On success: stop
  • On error: mark proxy as failed, try another

• If all proxies fail:

  • Clear proxy env:

    env::remove_var("ALL_PROXY");
    

  • Try once directly

---

Case 2: Proxy ON, No Proxies Loaded

• Show warning
• Clear ALL_PROXY
• Run once directly

---

Case 3: Proxy OFF

• Clear proxy vars
• Run module once

---

Summary Flow:

If proxy_enabled:
    while untried proxies:
        pick → set env → run → if fail → mark tried
    if none work → clear env → try direct
else:
    clear env → try direct

---

🧪 Module Execution Flow

Whether via CLI or shell:

1. commands::run_module(...)
2. Determines type: exploit, scanner, or cred
3. Calls correct dispatcher
4. Dispatcher calls run(target).await
5. Output shown to user

---

🛑 Error Handling

• All modules must return anyhow::Result<()>
• Errors are caught and shown cleanly in CLI or shell

---

⚡ Async Features

• Entire framework is powered by tokio
• All I/O modules are async
• Use tokio::spawn, FuturesUnordered, etc. for concurrency

---

📡 Making Requests

Use reqwest:

let resp = reqwest::get(&url).await?.text().await?;

Or with client:

let client = reqwest::Client::new();
let resp = client.post(&url).json(&data).send().await?;

✅ All requests respect ALL_PROXY

---

🧪 Example Use Cases

CLI

cargo run -- --command creds --module ftp_weak_login --target 192.168.1.100

Shell

rsf> use creds/ftp_weak_login
rsf> set target 192.168.1.100
rsf> run

---

🧼 Shell Reset

No session data persists. When restarted, shell forgets all settings — no saved targets or modules (by design).

---

🔐 Adapting CVEs

To build a real-world exploit:

• Convert PoC to async Rust logic
• Validate by checking known response headers/content
• Place it in the right folder and wire run()

TCP/UDP logic:

use tokio::net::{TcpStream, UdpSocket};

---

💡 Feature Roadmap

add more exploits etc

---

👥 Contributors

• Main Developer: me.
• Language: 100% Rust.
• Inspired by: RouterSploit, Metasploit, pwntools.

Would you like this exported as a DEVELOPER_GUIDE.md file now? I can generate it for you in exact GitHub-flavored markdown.