 |
 |
Ragnar is a fork of the awesome Bjorn project — a Tamagotchi-like autonomous network scanning, vulnerability assessment, and offensive security tool. It runs on a Raspberry Pi with a 2.13-inch e-Paper HAT, as a headless server on Debian-based systems (AMD64/ARM/ARM64) with Ethernet-first connectivity, or on the WiFi Pineapple Pager with full-color LCD display. On servers with 8GB+ RAM, Ragnar unlocks advanced capabilities including enhanced vulnerability scanning and parallel scanning.
Important
For educational and authorized testing purposes only.
This README is a map, not a manual — each feature gets a couple of sentences and a link to its full guide in docs/. Start with the documentation index if you'd rather browse.
wget https://raw.githubusercontent.com/PierreGode/Ragnar/main/install_ragnar.sh
sudo chmod +x install_ragnar.sh && sudo ./install_ragnar.sh
# On Raspberry Pi: choose e-Paper HAT, TFT LCD, server/headless, Pineapple Pager, or Docker container.
# On other hardware: choose server install, Pineapple Pager, or Docker container.
# It may take a while as many packages and modules will be installed. Reboot when it finishes.Prefer containers? Run the headless web UI on any Linux host with docker compose up -d --build, then open http://:8000. Pi-only hardware (e-Paper, GPS, SDR, Wi-Fi monitor mode) isn't available in a container — see the Docker Guide.
Don't want to run the installer at all? Flash Ragnar OS — a prebuilt Raspberry Pi image with Ragnar already installed and enabled. Write it with Raspberry Pi Imager, boot, open the web UI. For an offensive/red-team build with onboard-Wi-Fi monitor mode and the full toolset, flash Ragnar OS Ulfberht (built on a Kali ARM base).
More: Install Guide · Ragnar OS image · Ragnar OS Ulfberht · AP Mode / getting on a network · Updating Ragnar · Releases (per-PR log) · Release Notes.
Access Ragnar's dashboard at http://<ragnar-ip>:8000 — real-time discovery and vulnerability scanning, a multi-source threat-intel dashboard, file management, system monitoring, and hardware profile auto-detection (Pi Zero 2W, Pi 4, Pi 5).
WiFi Configuration Portal — when Ragnar can't reach a known network it raises a hotspot: connect to WiFi Ragnar (password ragnarconnect), open http://192.168.4.1:8000, and enter your credentials via the mobile-friendly portal. It supports scanning with signal strength, hidden-SSID entry, known-network management, and one-tap reconnection, then exits AP mode once configured. (The web UI is down during a wardrive with no AP or WiFi connection.)
Every feature below has a full guide in docs/. Short version here, details behind the link.
- Network scanning, vulnerability assessment & attacks — the autonomous scan-and-act loop : host/port discovery (with a per-host Ignore blacklist), Nmap-based vulnerability assessment Every nmap run is logged. See Scanning & Actions.
- Advanced vulnerability scanning — the Adv Scan tab: Nuclei, Nikto, SQLMap, WhatWeb and Nmap vuln scripts run on any board with
nmap; OWASP ZAP and parallel scanning need 8GB+ RAM. RAM-gated scanners are delegated to a capable mesh peer instead of dead-ending. See Advanced Vulnerability Scanning. - Multi-source threat intelligence — real-time fusion from CISA KEV, NVD CVE, AlienVault OTX, and MITRE, used to prioritize findings. See Scanning & Actions.
- AI-powered analysis — security summaries, vulnerability prioritization and remediation advice, with support for self-hosted / OpenAI-compatible endpoints (Ollama, LocalAI, vLLM, LM Studio) so inference can stay on your hardware. See AI Integration.
- Traffic analysis — live
tcpdumpcapture with top-talkers, protocol mix, DNS logging, and detection of port scans, DNS tunnelling and C2 beacons; also drives passive host discovery. Detection-only; runs on any board (Pi Zero 2W included). See Traffic Analysis.
- Authority Verification across the stack — is the claimed root bridge / gateway / DNS resolver / DHCP server / routing neighbour / SMB server genuine or an impostor? A network engineer's toolbox (Diagnostics — every module sorted by OSI layer, L7 to L1 — and Interfaces) plus a detection-only passive watcher suite spanning L2→L7 (STP/DTP/CDP/VTP/MRP/LACP/BFD/PTP/SR-MPLS/IPsec-IKE/DNS-Watch/FHRP/OSPF/EIGRP/IS-IS/BGP/SMB/Relay/RPC/LDAP/SSH/Telnet/IGMP-MLD/NDP/ICMP/NTP/SNMP/TLS/Cert — most dual-stack IPv4+IPv6, with cross-protocol D(HE)at / SWEET32 crypto-attack coverage), passive vendor CVE guards (Cisco, Juniper, Arista, Comware, MikroTik, Aruba, APC / Schneider NMC Ripple20, Vertiv Liebert power cards, and a Dell OS10 daemon), a scheduled Network Integrity Monitor, and IPv6 RA Guard. Co-authored by Solarflere. Full details in the Authority Verification Guide.
- Watchtower — unifies the standalone watcher daemons into one normalized, deduped alert feed with a single push-notification path. See Watchtower.
- Push Notifications — alerts delivered via Pushover and/or Slack (incoming webhook). See Push Notifications.
- Asset Inventory & SIEM forwarding — turns the flat hosts table into a change-aware inventory (new device / IP move / OUI change / offline, with owner/criticality/authorized tags and rogue-device signatures), lets you permanently ignore noisy devices, and ships every alert to syslog/CEF/LEEF, Splunk HEC, Elasticsearch/OpenSearch, or a JSON/Slack webhook. Host liveness unions an
arp-scansweep on the LAN interface (wired or wireless) with the kernel neighbour table, so a single missed broadcast never flaps the whole target list Offline. See Asset Inventory and SIEM Forwarding. - Incident correlation — fuses the alert stream into named cross-site attack-chain incidents. See Incident Correlation.
- WiFi Spectrum Analyzer — a passive tri-band (2.4/5/6 GHz, up to Wi-Fi 7) RF troubleshooter: interactive spectrum graph, per-AP inspector, interference/DFS flags, coverage rings, a walk-around heatmap, printable survey report, plus Bluetooth/Zigbee overlays and a HackRF true-RF waterfall. See WiFi Analyzer and the RoomScan floor-plan tracer.
- Sub-GHz RF instrument (RTL-SDR / HackRF / ESP-SDR) — a real spectrum analyser in the browser: real-time IQ waterfall with adjustable display range, wheel/drag zoom, markers with Δ and peak search, band-plan labels and signal identification, dBm calibration, noise-print subtraction, limit lines with pass/fail alerts into Watchtower, unattended band surveys with reports, RSSI direction finding across mesh units, mesh/LPWAN band overlays (Z-Wave, Meshtastic, MeshCore, LoRaWAN, Wi-Fi HaLow, Zigbee Suzi), CSV/SigMF export and a listen bar (FM/NFM/AM/SSB/CW). An ESP-SDR node — any ESP32 flashed with the ESP-SDR firmware — adds a third live panel over USB (on-chip FFT spectra, ~2.2–2.7 GHz on an ESP32-S3), no dedicated SDR hardware needed; its TCXO-less crystal is trimmed by having a nearby HackRF briefly transmit a known pilot tone the ESP locks onto (sub-ppm, spur-proof). See RF Waterfall, the capability guide and SDR / Sub-GHz. Detectors (peak/RMS/avg), the RTL-SDR centre spike hidden by offset tuning, overload and image checks, mask-triggered capture with a pre-trigger buffer, ACPR/spur/harmonic measurements, geotagged SigMF recordings, an on-box Signal Analyzer that opens any recording for spectrogram/measurement/demod/decode plus a whole-capture Spectrum Survey (occupancy heatmap + a measured carrier inventory with duty cycle, burst count, SNR and CSV/annotation export), and the whole instrument is scriptable over HTTP (API). A self-healing watcher recovers a stuck or silent dongle by power-cycling its USB port and resuming the sweep, and says so plainly when the dongle, cable or port is at fault.
- Meshtastic mesh — read a USB Meshtastic node (node DB, positions, messages, send over LoRa) and/or the public MQTT Internet feed with no node, on a node list and a full-screen map; a Region picker narrows the MQTT feed to one region (EU, US, ANZ, …) or a custom topic. The node list filters/sorts the roster and each node has actions — message it, focus it on the map, and trace route to see the LoRa hops (the jumps) with per-link SNR. See SDR / Sub-GHz.
- WiFi Defense (802.11 WIDS) — passive wireless intrusion detection: deauth/disassoc & beacon floods, rogue APs / evil twins, KARMA/MANA, Wi-Fi Pineapple / PineAP-family rogue APs (Mark VII/Enterprise/Pager), and a client-isolation observer, with a printable WIDS incident report. The continuous monitor is receive-only; an opt-in PineAP active-probe test is the one action that transmits, and only when you run it. Its daemon sibling wifiwatch extends this to the WPA handshake layer (PMKID, downgrade, PNL leakage). See WiFi Defense.
- BLE Watch (Bluetooth Low Energy monitor) — the BLE counterpart to the WIDS: passive, detection-only, driven by an external nRF51 / nRF52 sniffer (Adafruit Bluefruit LE Sniffer, nRF52840 dongle), found by the firmware answering on the port, so a look-alike Bluefruit LE Friend, or an nRF52840 dongle still on Nordic's Connectivity firmware, is named with the fix rather than silently ignored. Live capture uses the bundled Nordic nRF Sniffer extcap, so there is nothing extra to install. Flags advertising-layer impersonation (device & beacon clones, two radios sharing one address), beacon spoofing and GATT service masquerade, advertising floods and BLE-spam tooling (Flipper / "Sour Apple" / Fast-Pair / Swift-Pair), and the connection-layer abuse the sniffer can see when it follows a link (CONNECT_IND races, version swaps, Just-Works pairing downgrade, forced re-pair). Device-gated in the web UI; HIGH/CRITICAL findings reach Watchtower. See blewatch.
- Wardriving with GPS recovery — logs WiFi/BLE/cell with GPS positions, exports WiGLE CSV / KML and a printable A–F security-graded survey, uploads sessions (manually or automatically once back online) to WiGLE, WDGWars and Wardrift, and backfills missing positions with speed-aware interpolation. Battery-less u-blox pucks get an assisted start (last-known position, NTP time and their own saved almanac/ephemeris) so a cold boot fixes like a warm one. Solo drives on a Piglet come in over USB: plug it in and every finished drive on its SD card is pulled and imported as a session (Piglet firmware v2.60+). Includes a deep Diagnostics panel (radios/power/GPS sky view + Starview observatory), cellular modem capture, and a power badge — the System tab adds a load power test and a one-click fix for the Pi 5's 600 mA USB current cap (also applied by the installer on Pi 5). The System tab also shows the cooling fan — connected or not, rpm, duty, curve step — with manual speed control, a spin test and an editable fan curve. The ADS-B radar can likewise feed Wardrift's Aircraft Watch — Ragnar logs the unique aircraft heard each UTC day and uploads them (manually or automatically) for aircraft influence and XP. See Wardriving.
- RuSense — camera-free surveillance — ESP32 nodes read WiFi Channel State Information (CSI) to report presence, motion, people-count, and (with a trained model) coarse pose and resting vital signs — in the dark, through walls, no images. Browser flashing, calibration wizard, offline mesh. Powered by RuView (ruvnet). See RuSense.
- Home Assistant integration — a HACS custom integration (in-repo under
custom_components/ragnar/) surfacing RuSense presence/vitals, Watchtower alerts + incidents, connectivity, and mesh fleet health as native HA entities. Read-only local polling. See Home Assistant.
- Device Console — plug a USB console cable into a Ragnar and a switch, router or firewall console port, and the dashboard streams what the device prints: boot banners with the exact firmware version, ROMMON, crash dumps and console logging. Read-only by default (
O_RDONLY); enable Allow write to send commands or run pre-made console scripts (reboot, monitor logs, show version, configure VLANs, interface status — install more from the shared RagnarScripts library, or add your own JSON scripts with the console card's Upload button or via Files > console_scripts). Passive auto-baud, port reserved from every other component — and it works across the mesh, so you can watch a console cabled to a Ragnar in another rack. See Device Console. - Ragnar Mesh — a Viking army, not a box — links units over Tailscale with no controller: each unit is born with a Viking name, publishes its own report and reads its peers', and is reachable by a stable private address through any NAT. The Mesh tab shows per-unit health, undervoltage, worst alert and a "degraded" state — filter/search/sort the fleet and, on a unit's node page, see the tailnet path (direct vs. DERP relay), run a live trace route or ping, and start a bounded packet capture whose
.pcapstreams back over the tailnet for Wireshark; peer API calls are authenticated by WireGuard identity (no shared secret). Includes Fleet Config export/import and unit-to-unit file transfer. See the Ragnar Mesh Guide and Mesh Share & File Transfer.
- Displays — 2.13" e-Paper HAT; color TFT/OLED (GC9A01 1.28" round, ST7735S 1.44" HAT with keys + joystick, 3.5" SPI TFT ILI9486/9488, SSD1306 OLED); and MAX7219 8×8 LED matrix arrays. The 1.44" HAT's joystick drives On-Screen Network Diagnostic Mode and a wardriving carousel. Full mappings: Display Buttons & Joystick Reference.
- On-Screen Kiosk (Pi server only) — drives an attached HDMI/DSI screen as a fullscreen Chromium dashboard, with a handheld escape hatch (Hackberry Pi CM5). Needs 2GB+ RAM. See Kiosk Mode.
- WiFi Pineapple Pager — deploy Ragnar to the Pager as a native payload with a full-color LCD, buttons and LED status. Based on brAinphreAk's PagerBjorn / Loki. See Pager Guide.
- PiSugar 3 button — physical button to swap between Ragnar and Pwnagotchi modes (see below).
- LAN-first connectivity & smart WiFi — prefers Ethernet when present, manages WiFi as fallback, auto-connects to known networks and falls back to AP mode with a captive portal.
- Cellular uplink fallback — plug a USB-tethered hotspot (Orbic Speed, MiFi, Nighthawk…), a phone or an LTE modem into a Ragnar and it becomes a backup internet path. No extra drivers are needed. Heartbeats through each uplink to several public targets detect a WAN that's dead upstream, not just a lost link. Failback waits for several consecutive good heartbeats, so a flapping WAN doesn't bounce it. It is never scanned, and push alerts cover both failover and restore (with the outage window), so a leave-behind unit stays reachable over the mesh. See Cellular Uplink Fallback.
- Hardware-bound authentication — optional login with full database encryption at rest. See Security & Authentication.
- Vault — encrypted file store — a password-protected, AES-256-GCM store in the Files tab (contents and index are ciphertext on disk; scrypt-derived key; auto-locks; no recovery). See Vault.
- In-browser file editor — open any text file (JSON, Python, shell, YAML, config, etc.) in the Files tab and edit it directly from the dashboard. Changes save back to disk — useful for tweaking console scripts, configs and scan results without SSH.
- Web Terminal — optional in-dashboard shell (xterm.js ↔ PTY over Socket.IO) as the non-root
ragnaruser; off by default and login-gated — enable only on trusted networks. - Kill Switch —
/api/killwipes all databases, logs and data. See Kill Switch.
- 64-bit Raspberry Pi OS (Debian Trixie, kernel 6.12+)
- Username and hostname set to
ragnar - 2.13-inch e-Paper HAT connected to GPIO pins (for display mode)
- For 32-bit systems, use Ragnar's predecessor Bjorn
Recommendation: Edit ~/.config/labwc/autostart and comment out /usr/bin/lwrespawn /usr/bin/wf-panel-pi & to free up resources, or run sudo pkill wf-panel-pi temporarily.
The compact, self-contained reference node: a headless Pi Zero 2 W with an on-board status display, wired networking, and a Wi-Fi 6E monitor-mode radio. In collaboration with Solarflere — Raspberry Pi Zero 2 W + Waveshare 1.44" LCD Display HAT (ST7735S) + Waveshare Ethernet/USB HAT + Alfa AWUS036AXM (Wi-Fi 6E, mt7921u). See Gen 2 Hardware Requirements for the full BOM, assembly, and setup notes.
- Debian 11+ or Ubuntu 20.04+ (AMD64, ARM64, or ARMv7)
- Minimum: 2GB RAM, 2 CPU cores, 10GB free disk
- Recommended: 8GB+ RAM for the heaviest features (OWASP ZAP and parallel scanning). The rest of the Adv Scan tab and Traffic Analysis run on any board — the CLI scanners just need
nmap, Traffic Analysis needs onlytcpdump.
Firmware 1.0.7+, PAGERCTL payload, SSH access, Python3 + nmap. See Pager Guide.
A community wrapper runs Ragnar in headless/server mode on the Hackberry Pi CM5 handheld cyberdeck — a 720×720 touch panel with a BlackBerry-style keyboard. It installs Ragnar unmodified (vendored as a dependency), adds a touch dashboard and keyboard control panel, and keeps everything off system Python via an isolated virtualenv. See DezusAZ/ragnar-cyberdeck.
The Flipper One is an ARM64 Linux multi-tool — the same class of aarch64 host Ragnar already supports, so the headless / web-UI configuration looks highly feasible with little core change. Still a community-development project with no shipping hardware to validate against yet. See the Flipper One feasibility & porting notes.
The installer auto-detects your platform and configures everything — distro detection (apt/dnf/pacman/zypper), architecture support (AMD64/ARM64/ARMv7/ARMv8), install profiles (Pi + e-Paper, Server/Headless, Pineapple Pager, Docker), automatic advanced tools on 8GB+ boards, and smart resource management that skips heavy tools on a Pi Zero 2W. Full walkthrough: Install Guide; updating an existing box: Updating Ragnar. Installed headless and added a screen later (e.g. the 1.44" LCD HAT)? Run sudo ./installhead.sh to pick and enable it — see Adding a screen to a headless install.
On 8GB+ systems Ragnar automatically unlocks OWASP ZAP and parallel scanning. The rest of the Adv Scan tab (Nuclei, Nikto, SQLMap, WhatWeb, Nmap vuln scripts) and Traffic Analysis run on any board — see Advanced Vulnerability Scanning for the full breakdown of what runs where, RAM gating, and mesh delegation. Fresh 8GB+ installs get the advanced tools automatically; on an existing box:
cd /home/ragnar/Ragnar
sudo ./scripts/install_advanced_tools.sh
sudo systemctl restart ragnarRuSense turns ordinary 2.4 GHz WiFi into a no-camera surveillance system. ESP32 nodes read WiFi Channel State Information (CSI) — the tiny distortions a moving body imprints on radio waves — and a bundled engine reports presence, motion, people-count, and (with a trained model) coarse pose and resting vital signs. No images are ever captured; it works in the dark and through walls.
- Flash a node from your browser — no toolchain: RuSense Flasher (ESP32-S3 DevKitC / Seeed XIAO ESP32S3 & Plus / AMOLED / C6, Chrome/Edge).
- Install the backend:
sudo ./scripts/install_sensing.sh(runs asragnar-sensing.service). - View it under the RuSense tabs at
http://<ragnar-ip>:8000.
Powered by RuView (by ruvnet). Full details: RuSense Guide.
A bundled helper (sudo ./scripts/install_pwnagotchi.sh) plus dashboard controls make swapping between Ragnar and Pwnagotchi painless — the script clones pwnagotchiworking, installs dependencies, and drops a disabled pwnagotchi.service. Switch from the web UI (Config → Pwnagotchi Bridge), the PiSugar 3 button, or a reboot-recovery script. Pwnagotchi web UI: http://<same-ip>:8080 (ragnar/ragnar). Needs a monitor-mode USB adapter (wlan1) and a Waveshare 2.13" e-Paper HAT V4. Full setup, config, mode-switching and troubleshooting: Pwnagotchi Bridge Guide.
Ragnar deploys to the WiFi Pineapple Pager as a native payload with a full-color 480×222 LCD, button controls and LED status indicators. The pager port is based on the original work of brAinphreAk (PagerBjorn / Loki) — full credit and thanks for making pager hardware support possible. Install it from the main installer (option 3) or ./scripts/install_pineapple_pager.sh [pager-ip]. Full prerequisites, features and usage: Pager Guide.
The project welcomes contributions in new attack modules, bug fixes, documentation, and feature improvements.
See Contributing Docs and Code of Conduct.
- Report Issues: Via GitHub Issues
- Author: PierreGode — PierreGode/Ragnar
Ragnar is built on the shoulders of great work by others:
CREDITS.md — Solarflere identified and curated the CVE corpus behind Ragnar's passive detection suite — 342 CVEs detected from the wire, 405 named (CVE-1999-0113 → CVE-2026-102019). See the full writeup and numbers there, and the CVE Index for every CVE with its detector and status.
2025- - Ragnar is distributed under the MIT License. See the LICENSE file for details.