AI-Powered WiFi Security Tool with Reinforcement Learning
A samurai astronaut that learns to hunt WiFi handshakes
Features | Quick Start | Architecture | How It Works | Dashboard | Hardware
NeuroVulture is an autonomous WiFi security research tool that runs on a Raspberry Pi Zero 2W. It combines reinforcement learning (like Pwnagotchi), network scanning (like Bjorn), and AI-driven strategic planning (inspired by PicoClaw) to capture WPA/WPA2 handshakes while displaying a samurai astronaut personality on a Waveshare e-Paper HAT.
It learns. It adapts. It remembers. It hunts.
- Reinforcement Learning Brain — Contextual bandits with UCB exploration optimize 13 WiFi capture parameters (RSSI threshold, channel strategy, capture duration, deauth timing) based on real-time rewards
- Gene Strategy System — Proven parameter combinations are crystallized into "genes" with confidence scores. The system evolves new strategies by crossing top performers and prunes underperformers — a genetic algorithm for WiFi hunting
- Strategic AI Brain — LLM-powered reasoning layer that makes high-level decisions: passive mode at night, aggressive during peak hours, adapts to declining performance. Remembers what worked at each location across reboots
- Local LLM Personality — TinyLlama 1.1B runs on-device via llama.cpp, generating samurai-themed status comments. 60+ dynamic templates with live system data as fallback
- E-Paper Display — Waveshare 2.13" HAT shows samurai mascot (changes with emotion), live stats (APs, handshakes, channel, epoch, reward, RAM), and a pwned AP ticker
- Bjorn-Style Web Dashboard — Dark-themed, data-rich dashboard with network map, signal strength bars, RL brain stats, gene evolution table, strategic reasoning display, color-coded logs, and live mascot
- 10 Emotional States — Calm, hunting, excited, bored, sad, angry, intense, grateful, lonely, sleeping — each with unique display images and personality modifiers
- Zero-Internet Install — All dependencies bundled: ARM64 Python wheels, pre-built binaries, GGUF model. One
sudo bash install.shon a fresh Raspbian - Auto-Start Daemon — systemd service with crash recovery, PID management, clean shutdown with e-paper goodbye message
# SSH into your Pi Zero 2W running Raspbian Lite 64-bit
git clone https://github.com/ankurCES/NeuroVulture.git
cd NeuroVulture
sudo bash install.shThe installer handles everything: system packages, Python venv, SPI/I2C, swap, hostname, systemd service. NeuroVulture starts automatically on every boot.
Dashboard: http://neurovulture.local:8000
sudo systemctl start neurovulture # Start
sudo systemctl stop neurovulture # Stop
sudo systemctl status neurovulture # Status
tail -f data/logs/neurovulture.log # Live logs
# Or run directly
sudo python -m neurovulture # Foreground
sudo python -m neurovulture --daemon # Background
sudo python -m neurovulture --status # Check
sudo python -m neurovulture --stop # Stop daemon┌─────────────────────────────────────────────────────────────────┐
│ NeuroVulture │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────────┐ │
│ │ WiFi │ │ RL │ │ Strategic Brain │ │
│ │ Capture │───▶│ Brain │◀──▶│ (PicoClaw + LLM) │ │
│ │ │ │ │ │ │ │
│ │ hcxdump │ │ Bandits │ │ Time-aware decisions │ │
│ │ scanner │ │ 13 params│ │ Cross-session memory │ │
│ │ monitor │ │ UCB │ │ Location awareness │ │
│ └──────────┘ └────┬─────┘ └──────────────────────────┘ │
│ │ │
│ ┌────▼─────┐ ┌──────────────────────────┐ │
│ │ Gene │ │ Display │ │
│ │ Store │ │ │ │
│ │ │ │ E-Paper: mascot + stats │ │
│ │ Evolve │ │ Web: Bjorn-style dash │ │
│ │ Mutate │ │ LLM: samurai comments │ │
│ │ Prune │ │ Emotions: 10 states │ │
│ └──────────┘ └──────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
| Module | Purpose | RAM Usage |
|---|---|---|
wifi/ |
Monitor mode, AP scanning, hcxdumptool capture, PMKID/EAPOL validation | ~2MB |
brain/ |
Contextual bandits RL with 13 trainable parameters, 11-feature observation | ~5MB |
genes/ |
Gene store (JSONL), UCB1 selection, crossover/mutation evolution | ~3MB |
picoclaw/ |
Strategic brain: time-aware decisions, cross-session memory, gene naming | ~2MB |
llm/ |
TinyLlama 1.1B via llama-server (mmap, ~30MB active pages) | ~30MB |
display/ |
Waveshare e-Paper driver (lgpio), boot animation, samurai mascots | ~10MB |
personality/ |
State machine (7 states), emotional engine (10 emotions), event bus | ~2MB |
web/ |
HTTP dashboard with 8 REST API endpoints | ~5MB |
Total: ~245MB without LLM, ~445MB peak — fits in Pi Zero 2W's 512MB with swap
- Strategize — The strategic brain evaluates time of day, AP density, reward trend, and location memory to set approach (passive/active/balanced) and intensity (low/medium/high)
- Scan — Discovers nearby WiFi access points using
iw dev scan - Select — RL brain selects optimal capture parameters, or a proven gene is used if one matches the current environment
- Override — Strategic brain applies tactical adjustments (e.g., cap deauth rate at night)
- Capture — hcxdumptool runs a timed capture session targeting selected BSSIDs
- Validate — hcxpcapngtool extracts and validates PMKID/EAPOL handshakes
- Reward — Composite reward computed:
R = handshakes + activity + coverage - blindness - missed - inactivity - boredom - Learn — RL agent updates weights, gene confidence adjusted, new genes crystallized from high-reward discoveries
- Evolve — Every 10 epochs, top genes are crossed and mutated to create offspring
- Remember — Strategic decisions and location context persisted to JSONL for next session
| Time | Approach | Intensity | Reasoning |
|---|---|---|---|
| Night (11pm-6am) | Passive | Low | Few active devices, conserve resources |
| Morning (6am-9am) | Balanced | Medium | Devices waking up, steady discovery |
| Day (9am-5pm) | Active | High | Peak AP density, aggressive capture |
| Evening (5pm-11pm) | Active | High | Many active devices, good targets |
| Declining reward | Balanced | Medium | Current strategy failing, try new approach |
R = w1*handshakes + w2*activity + w3*coverage + w4*discovery
- w5*blindness - w6*missed - w7*inactivity - w8*boredom
Weights are configurable in config/reward_weights.yaml.
| Parameter | Range | Controls |
|---|---|---|
min_rssi |
-90 to -30 dBm | Signal strength filter |
capture_duration |
60-300s | How long to capture per epoch |
channel_strategy |
round-robin / weighted / focused | Channel selection method |
target_selection |
strongest / weakest / random | Which APs to target |
hop_recon_time |
5-120s | Channel hop interval |
max_interactions |
1-25 | Max capture attempts per epoch |
deauth_cooldown |
10-120s | Pause between deauth bursts |
ap_ttl / sta_ttl |
30-600s | Cache lifetime for APs and stations |
recon_time / min_recon_time |
1-60s | Reconnaissance windows |
max_inactive_scale |
3-10x | Inactivity multiplier |
recon_inactive_mult |
1-3x | Inactive recon scaling |
Bjorn-style dark-themed web dashboard at http://<pi-ip>:8000:
- Home — Stats bar (APs/Handshakes/Pwned/Epoch/Reward/RAM), samurai mascot with emotion-based switching, strategic brain card, LLM personality comments, WiFi overview, RL parameters, reward chart, handshake table, logs
- Network — AP table with signal strength bars, channel distribution chart, encryption breakdown, pwned status per AP
- Brain — RL epoch stats, current parameters, reward history chart, active gene
- Genes — Gene strategy table with confidence/uses/successes/total reward
- Logs — Color-coded log viewer (blue=INFO, yellow=WARNING, red=ERROR, green=handshake)
| Endpoint | Description |
|---|---|
GET /api/status |
Full system status with AP list and pwned networks |
GET /api/network |
AP details, channel/encryption distribution |
GET /api/brain |
RL stats, parameters, strategy, reward history |
GET /api/genes |
Gene store with confidence and usage stats |
GET /api/handshakes |
Captured handshakes with BSSID/SSID/type |
GET /api/llm |
LLM status, model info, comment source |
GET /api/logs |
Recent application logs |
GET /api/history |
Reward history for charting |
The Waveshare 2.13" e-Paper HAT shows:
┌──────────────────────────────────┐
│ ⚔ NEUROVULTURE HUNTING 0:15 │ Header (inverted)
├─────────┬────────────────────────┤
│ │ ◉ 12 APs ✡ 2 HS │ Stats with icons
│ SAMURAI │ ▶ CH6 ⚙ E:21 │
│ MASCOT │ ★ +0.35 ■ 184MB │
│ │ ☢ night_sweep_75db │ Active gene
│ │ ───────────────── │
│ │ [calm] Patience... │ Emotion + comment
├─────────┴────────────────────────┤
│ ⚔ PWNED: HomeNet | CafeWifi │ Pwned AP ticker
└──────────────────────────────────┘
Three samurai mascot characters rotate based on emotional state:
- Red Samurai (sword drawn) — aggressive states: hunting, angry, excited, bored
- Purple Samurai (dual swords + banner) — strategic states: hunting, intense, thinking
- Kitsune Fox (at torii gate) — calm states: calm, sad, lonely, grateful, sleeping
| Component | Model | Purpose |
|---|---|---|
| SBC | Raspberry Pi Zero 2W | Main computer (512MB RAM, ARM Cortex-A53) |
| Display | Waveshare 2.13" e-Paper HAT V2/V4 | Status display (250x122, 1-bit) |
| WiFi (monitor) | USB adapter with RTL8812AU | Handshake capture in monitor mode |
| WiFi (management) | Built-in BCM43438 | SSH access and connectivity |
| Power | Whispi battery backup | Portable operation |
| Storage | microSD 16GB+ | OS + NeuroVulture + model |
- Alfa AWUS036ACH (RTL8812AU) — recommended
- Alfa AWUS036AXML (MT7921AU)
- Panda PAU09 (RT5572)
- Any adapter supporting monitor mode on Linux
All settings in config/default.yaml, overridable via .env:
| Setting | Default | Description |
|---|---|---|
wifi.monitor_interface |
wlan1 |
USB WiFi adapter for capture |
wifi.management_interface |
wlan0 |
Built-in WiFi for SSH |
brain.algorithm |
contextual_bandits |
RL algorithm (or a2c with PyTorch) |
brain.epoch_length |
300 |
Seconds per learning epoch |
llm.enabled |
true |
Enable local TinyLlama LLM |
genes.max_genes |
100 |
Max strategies in gene store |
genes.exploitation_threshold |
0.7 |
Min confidence to use a gene |
picoclaw.enabled |
false |
Enable PicoClaw sidecar |
system.web_port |
8000 |
Dashboard port |
NeuroVulture/
├── config/ # YAML configuration
│ ├── default.yaml # All settings
│ └── reward_weights.yaml # RL reward function weights
├── neurovulture/ # Main Python package
│ ├── wifi/ # WiFi capture subsystem
│ ├── brain/ # Reinforcement learning
│ ├── genes/ # Gene strategy + orchestrator
│ ├── picoclaw/ # Strategic brain + MCP server
│ ├── llm/ # Local LLM engine
│ ├── display/ # E-paper driver + renderer
│ ├── personality/ # State machine + emotions
│ └── web/ # Dashboard + REST API
├── resources/images/ # Samurai mascot BMPs
├── models/ # TinyLlama GGUF (638MB)
├── bin/ # ARM64 binaries
├── wheels/ # ARM64 Python wheels
├── tests/ # 34 pytest tests
├── install.sh # One-command Pi installer
└── neurovulture.service # systemd unit file
Before deploying to Pi, download the binaries and model on a machine with internet:
# ARM64 Python wheels (already bundled in wheels/)
bash scripts/build_wheels.sh
# ARM64 binaries (llama-server, hcxdumptool) — requires Docker
bash scripts/build_binaries.sh
# Or download pre-built llama-server from GitHub releases
curl -L -o /tmp/llama.tar.gz \
https://github.com/ggml-org/llama.cpp/releases/latest/download/llama-*-bin-ubuntu-arm64.tar.gz
tar xzf /tmp/llama.tar.gz -C bin/
# TinyLlama model (638MB)
wget -O models/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf \
https://huggingface.co/TheBloke/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf
# PicoClaw (optional, for MCP orchestration)
curl -L -o /tmp/picoclaw.tar.gz \
https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
tar xzf /tmp/picoclaw.tar.gz -C bin/For a pre-configured SD card from macOS:
# 1. Flash Raspbian Lite 64-bit with Pi Imager / balenaEtcher
# 2. Re-insert SD card, then:
bash image/prepare_sd.sh
# 3. Eject, insert into Pi, power onOn power-up:
- Title card — "NEUROVULTURE - Samurai WiFi Hunter v0.1.0"
- Samurai mascot — Displayed on e-paper
- Progress bar — System initialization
- "READY TO HUNT" — Mascot reveal with armed status
- Live operation — Stats, mascot, ticker, LLM comments updating every 5 seconds
| Project | What NeuroVulture Takes |
|---|---|
| Pwnagotchi | RL-based WiFi parameter optimization, emotional states, epoch cycle |
| Bjorn | E-paper display layout, BMP status images, web dashboard style |
| PicoClaw | Gene strategy system, MCP tool integration, lightweight AI orchestration |
NeuroVulture is designed for authorized security testing, penetration testing engagements, and security research. It captures WPA/WPA2 handshakes (PMKID and EAPOL) which can be used to audit the strength of wireless network authentication.
Always obtain proper authorization before testing any network you do not own.
MIT
Built with reinforcement learning, evolutionary strategies, and the spirit of the samurai.
⚔ The hunt never ends. ⚔
This is a test project that has been created as a part of a long running Agent Developement based task