DOCSEARCHbyAlgolia
Submit Docs

RaspyJack Documentation

repository·main·Indexed 19 days ago

https://github.com/7h30th3r0n3/raspyjack

A portable Raspberry Pi-based offensive security toolkit for authorized testing and research. It features a handheld LCD interface, a remote WebUI, a browser-based Payload IDE, and a wide array of pre-built payloads covering WiFi, BLE, USB, network reconnaissance, credential capture, and exfiltration. The toolkit includes an Extensions API for payload authors and a vendored port of Responder for LLMNR, NBT-NS, and mDNS poisoning.

Tokens
14.9K
Snippets
43
Records
71
Agent score
77%

What's inside RaspyJack

  1. Understand Responder's Auth Servers and Modules

    main

    Responder includes several built-in authentication servers to capture credentials across different protocols:

    • SMB Auth Server: Supports NTLMv1, NTLMv2 (with ESS), and SMBv2. Supports LM hashing downgrade via --lm.
    • MSSQL Auth Server: Supports NTLMv1 and LMv2 hashes.
    • HTTP/HTTPS Auth Servers: Supports NTLMv1, NTLMv2, and Basic Authentication. Also supports WebDav NTLM authentication.
    • LDAP Auth Server: Supports NTLMSSP and Simple (clear text) authentication.
    • DCE-RPC Auth Server: Supports NTLMSSP hashes.
    • FTP, POP3, IMAP, SMTP Servers: Collect clear text credentials.
    • DNS Server: Answers SRV and A queries (effective when combined with ARP spoofing).
    • WPAD Proxy Server: Captures HTTP requests from clients with 'Auto-detect settings' enabled. Configure custom PAC scripts in Responder.conf.
    • Rogue DHCP: Uses python tools/DHCP.py to perform DHCP Inform Spoofing. Use -R to inject a DNS server, domain, or route.
    • Analyze Mode: Uses -A to passively map domains, MSSQL servers, and workstations without poisoning responses.

  2. Understand the WebUI Architecture (HTTPS/WSS)

    main

    The WebUI architecture relies on Caddy as a public entrypoint to proxy traffic to internal services:

    • Public Entrypoint: Caddy listening on :443 (https://<device-ip>/).
    • Web UI/API: Proxied from 127.0.0.1:8080.
    • Device WebSocket: Exposed as wss://<device-ip>/ws, which proxies to the upstream WebSocket at 127.0.0.1:8765.

    Note on Certificates: The installer uses tls internal (a self-signed local CA via Caddy). You may see a certificate warning on your first visit. You can either bypass the warning or install/trust Caddy's local CA on your client machine.

  3. Understand the RaspyJack WebUI Authentication Flow

    main

    The WebUI uses a multi-layered authentication mechanism:

    1. Initial Setup: On the first run, a blocking setup overlay requires an admin username and password.
    2. Session Management: After setup, a blocking login overlay is required for the WebUI and IDE. Successful login creates an HTTP-only session cookie used for subsequent API calls.
    3. WebSocket Security: WebSocket access is secured using a short-lived WS ticket issued by web_server.py.
    4. Emergency Access: Recovery token authentication remains supported for emergency fallback.

    When using HTTPS, session cookies are configured with Secure; HttpOnly; SameSite=Strict.

  4. Understand the RaspyJack project layout

    main

    RaspyJack is organized into several functional directories. The core engine and drivers reside in the root, while specialized offensive and utility tools are located in the payloads/ directory. Captured data is stored in loot/, and payload configurations are in config/.

    Raspyjack/
├── raspyjack.py          # Main UI engine
├── gui_conf.json          # Display type, colors, pins, lock
├── menu_icons.json        # FontAwesome icons for menus
├── LCD_1in44.py           # LCD driver (ST7735 + ST7789)
├── LCD_Config.py          # SPI/GPIO config
├── web_server.py          # WebUI HTTP server
├── device_server.py        # WebSocket device server
├── rj_input.py            # Input handler
├── install_raspyjack.sh   # Installer
├── web/                   # WebUI frontend
├── payloads/               # Tool categories (wifi, network, bluetooth, etc.)
├── loot/                  # Captured data
├── config/                # Payload configs
├── DNSSpoof/
├── Responder/
└── wifi/                  # WiFi manager

  5. Access the WebUI and Payload IDE

    main

    RaspyJack provides a remote management interface and a browser-based IDE via a web server. You can access these from another device on the same network using the device's IP address.

    • Main WebUI: https://<device-ip>/ (or http://<device-ip>:8080)
    • Payload IDE: https://<device-ip>/ide (or http://<device-ip>:8080/ide)

    To validate the JavaScript syntax for the WebUI components during development, use the provided sanity check script:

    ./scripts/check_webui_js.sh

  7. Access the RaspyJack WebUI

    main

    The RaspyJack WebUI provides a browser-based remote control for the device's LCD UI. It streams LCD frames to your browser and allows you to forward button inputs back to the device.

    Recommended Access (HTTPS):

    https://<device-ip>/

    Fallback Access (Direct HTTP): If the HTTPS proxy (Caddy) is unavailable or during troubleshooting, you can access the static frontend directly on port 8080:

    http://<device-ip>:8080

  8. Install RaspyJack on Raspberry Pi

    main

    To install RaspyJack, start with a fresh Raspberry Pi OS Lite installation. Run the following commands to update the system, clone the repository, and execute the installation script. A reboot is required after the installation completes.

    sudo apt update
sudo apt install -y git
sudo -i
git clone https://github.com/7h30th3r0n3/raspyjack.git Raspyjack
cd Raspyjack
chmod +x install_raspyjack.sh
./install_raspyjack.sh
reboot

  9. Run Responder for LLMNR/NBT-NS/mDNS Poisoning

    main

    Responder is a tool used to poison LLMNR, NBT-NS, and mDNS requests to capture NTLM hashes or relay authentication.

    Before running, you should review and tweak Responder.conf to suit your requirements.

    Typical Usage Example: To run Responder on interface eth0 with verbose output:

    ./Responder.py -I eth0 -Pv
    ./Responder.py -I eth0 -Pv

  10. Create a custom RaspyJack payload

    main

    To create a new payload, follow these steps:

    1. Template: Copy payloads/examples/_payload_template.py into the appropriate category folder.
    2. Display Logic: Use ScaledDraw and scaled_font() from payloads._display_helper to ensure compatibility across both 128x128 and 240x240 screens.
      • UI/tool payloads: Use ScaledDraw with 128-base coordinates (0-127). Do not use WIDTH/HEIGHT in draw calls.
      • Game payloads: Render at 128x128 using standard ImageDraw.Draw, then resize the image to (WIDTH, HEIGHT) before displaying.
    3. Exit Logic: Ensure KEY3 is mapped to an exit/cancel action.
    4. Menu Icon: Add an icon for your payload in menu_icons.json using FontAwesome 6 Solid unicode characters.
    5. Extensions: You can import shared helpers from EXTENSIONS.api (e.g., WAIT_FOR_PRESENT, REQUIRE_CAPABILITY) for reusable logic.
    #!/usr/bin/env python3
import os, sys, time
sys.path.append(os.path.abspath(os.path.join(__file__, '..', '..', '..')))

import RPi.GPIO as GPIO
import LCD_1in44, LCD_Config
from PIL import Image, ImageDraw, ImageFont
from payloads._display_helper import ScaledDraw, scaled_font
from payloads._input_helper import get_button

PINS = {"UP": 6, "DOWN": 19, "LEFT": 5, "RIGHT": 26,
        "OK": 13, "KEY1": 21, "KEY2": 20, "KEY3": 16}
GPIO.setmode(GPIO.BCM)
for pin in PINS.values():
    GPIO.setup(pin, GPIO.IN, pull_up_down=GPIO.PUD_UP)

LCD = LCD_1in44.LCD()
LCD.LCD_Init(LCD_1in44.SCAN_DIR_DFT)
WIDTH, HEIGHT = LCD.width, LCD.height
font = scaled_font()

try:
    while True:
        btn = get_button(PINS, GPIO)
        if btn == "KEY3":
            break
        img = Image.new("RGB", (WIDTH, HEIGHT), "black")
        d = ScaledDraw(img)
        d.text((6, 6), "Hello Payload", font=font, fill="#00FF00")
        LCD.LCD_ShowImage(img, 0, 0)
        time.sleep(0.05)
finally:
    LCD.LCD_Clear()
    GPIO.cleanup()

  11. Setup Responder on Ubuntu and OSX

    main

    Responder listens on many ports and may conflict with existing services.

    Ubuntu Setup

    If you are using Ubuntu, you must prevent dnsmasq from conflicting with Responder's DNS module:

    1. Edit /etc/NetworkManager/NetworkManager.conf and comment out the line: dns=dnsmasq.
    2. Kill the existing dnsmasq process as root:
      sudo killall dnsmasq -9

    OSX Setup

    Responder does not support native interface binding on OSX. You must specify a local IP using the -i flag.

    To ensure the best experience, unload the following services as root:

    launchctl unload /System/Library/LaunchDaemons/com.apple.Kerberos.kdc.plist
launchctl unload /System/Library/LaunchDaemons/com.apple.mDNSResponder.plist
launchctl unload /System/Library/LaunchDaemons/com.apple.smbd.plist
launchctl unload /System/Library/LaunchDaemons/com.apple.netbiosd.plist

  12. Best practices for payload authors using extensions

    main

    When integrating extensions into your payloads, follow these guidelines:

    • Do not replace the template: Extensions are helpers and should not replace the standard payload template.
    • Maintain UI standards: Interactive payloads should continue to use ScaledDraw, scaled_font(), and get_button.
    • Ensure cleanup: Always use the standard try/finally layout to guarantee that LCD.LCD_Clear() and GPIO.cleanup() are called, ensuring compatibility with supported screen sizes.