styx-os

A network access point to capture and analyze network traffic data for review in Augmented and Virtual Reality

In Greek mythology the River Styx was the boundary between the world of the living and Hades

The Styx project provides a boundary between your devices and the Underworld of the Internet

Features

• Wireless Access Point (via hostapd)
• Ad blocking for all connected devices (via Pi-hole/dnsmasqd)
• Deep Packet Inspection for connected devices (via tcpdump)
• API for accessing reports on monitored network traffic
• Web service with auto-generated HTTPS self-signed certificate
• UDP relay for access to API across WLAN as an alternative to HTTPS
• Visualize and interact with network data in Mixed Reality and on touchscreen devices using styx-godot

Requirements

• Raspberry Pi 3, 4, or 5
• Ethernet network connection
• MicroSD card (4 GB minimum, 8 GB+ recommended)
• Base Raspberry Pi OS installation
  • 64 bit version
  • "Lite" image preferred

Instructions

• Install Raspberry Pi OS (see below)

• Log into console directly or via SSH

• Automated installation:

  • Install dependencies
  • Build software
  • Deploy containers
  • Start services

• Documentation is available for accessing the Styx API

Default Automated Installation

curl -sL setup.styx.jigsaw.studio | sh

Custom Automated Installation

The following optional command line arguments can be used to customize your styx-os installation:

• --user: The username under which to run the various styx-os software services (default: "styx")
• --ssid: The SSID broadcast name for the wireless access point (default: "Styx")
• --wpa: The WPA passphrase for the wireless access point (default: [hidden])
• --web: The password for the Pi-hole administrative web interface (default: [hidden])
• --branch: An alternative branch for installing development versions of styx-os (default: "main")

Example (custom SSID name):

curl -sL setup.styx.jigsaw.studio | sh -s -- --ssid Styx

Example (All custom settings demonstrated):

curl -sL setup.styx.jigsaw.studio | sh -s -- \
  --user styx \
  --ssid Styx \
  --wpa "StyxWiFiPassword" \
  --web "Pi-holeWebAdmin"
  --branch v1.1.1

Access (Defaults)

• Wireless Access Point
  • SSID: Styx
  • Password: (hidden)
• Pi-hole
  • Web Interface: http://172.16.100.1/admin (replace 172.16.100.1 with your Raspberry Pi's IP address)
  • Password: (hidden)
• API
  • Documentation: http://172.16.100.1/redoc (replace 172.16.100.1 as necessary)
  • Swagger: http://172.16.100.1/docs (replace 172.16.100.1 as necessary)

OS Installation

• Raspberry Pi Imager is an easy way to perform an OS installation
  • Download link
• Select your model of Raspberry Pi Device
• Choose "Lite" version of Operating System to minimum storage usage
  • Scroll down to "Raspberry Pi OS (other)"
  • Choose Raspberry Pi OS Lite (64-bit)
• Insert Micro SD card into your system using a SD or USB adapter
• Under "Storage" choose your device
• Click Next
• When prompted, "Edit Settings" to save time post-installation.
  • Enter the following settings under "General"
    • Hostname (choose any name)
    • Username (choose any name, a "styx" user will be created for running services)
    • Timezone
    • Keyboard layout
    • (NOTE: it is not necessary to configure wireless LAN for this step)
  • Under "Services" make sure to "Enable SSH" for remote access
  • For privacy reasons, you may wish to disable "Enable telemetry" under "Options"
  • Click "Save" to confirm your changes
  • Click "Yes" to apply your customizations
• Click "Yes" to begin writing the OS image to your device
• Raspberry Pi Imager will write the image, verify it, and notify you when finished

Credits

• Pi-hole: GitHub | Donate
• AutoWLAN by Guille Hartek