PineApple-Pi

A guided Raspberry Pi dashboard for wireless inventory, access-point administration, system visibility, and modular security tooling.

Important

PineApple-Pi is intended only for systems and networks you own or are explicitly authorized to administer or assess.

The operator is responsible for defining scope, following applicable law, protecting collected data, preventing unintended disruption, and handling all tools responsibly.

Project Status

Current build: v0.7.1-ap-enabled

Release stage: Prototype / pre-release

PineApple-Pi is a headless Raspberry Pi wireless toolkit built around a three-radio architecture and a browser-based dashboard.

The current release includes:

Branded startup and liability screens
Direct dashboard access without administrator setup
A modular tool catalog
Dashboard-based installation for approved tools
Authorization project records
Access-point configuration controls
AP client activity visibility
Network-interface role separation
A production installer
A persistent systemd service
Local rollback backups

PineApple-Pi is still under active development. Test new releases in a controlled environment before relying on the toolkit for regular operation.

Current Capabilities

Dashboard and Interface

Branded loading screen
Branded liability acknowledgment
Branded dashboard banner
Responsive desktop and mobile layout
No Create Administrator page
No login form
No Sign Out button
Direct transition from liability acknowledgment to the dashboard
Cache-busted frontend assets
Health endpoint
Production service on port 8000
Development server on port 8001

Radio Architecture

wlan1 host and Internet uplink
wlan2 PineApple-Pi toolkit access point
wlan0 network inventory interface
AP controls limited to wlan2
Host route kept on wlan1
Inventory role assigned to wlan0
Default AP channel set to 2.4 GHz channel 6

Access Point

Editable SSID
Open access-point mode
2.4 GHz channel selection
5 GHz channel selection
Client isolation
Shared IPv4 networking
Fixed AP address
AP start and stop controls
Explicit OPEN NETWORK confirmation
NetworkManager connection-profile integration

AP Activity

Client IP address
Client MAC address
Neighbor state
Online or offline status
Current client count
Activity refresh
Activity clearing
Dashboard client table

Tools

Tool catalog
Local executable detection
Installed and unavailable states
Dashboard Downloads page
One-time installation tokens
Fixed allowlisted installation recipes
No arbitrary browser-provided shell commands
Root helper isolated from the normal dashboard process

Authorization

Authorization project name
Authorizing owner
Exact project scope
Project state
Project expiration field
Persistent project records

Important Security Notice

PineApple-Pi v0.7.1 uses a no-login prototype workflow.

That means anyone who can reach the dashboard can view its pages and use enabled controls.

The current workflow is:

Loading screen
    ↓
Liability acknowledgment
    ↓
Dashboard

There is no administrator-login barrier in this release.

Because of that:

Restrict the dashboard to a trusted network.
Do not expose port 8000 to the public Internet.
Keep client isolation enabled on the toolkit AP.
Review AP clients regularly.
Do not run PineApple-Pi unattended in an untrusted location.
Add HTTPS and authentication before a stable public deployment.
Treat installation tokens as sensitive even though each token is temporary.

Network Layout

The recommended configuration uses three separate Wi-Fi interfaces.

Interface	Role	Purpose
`wlan1`	Host / uplink	SSH, Internet, Git, packages, updates, and Pi administration
`wlan2`	Toolkit AP	Broadcasts the PineApple-Pi access point
`wlan0`	Inventory	Reserved for authorized network inventory workflows

Why Separate the Interfaces?

A Wi-Fi radio normally operates in a specific mode.

A managed or client interface joins an existing network:

Raspberry Pi
    ↓
Existing wireless router

An access-point interface creates a network:

Phone or laptop
    ↓
PineApple-Pi access point

Using separate physical adapters avoids converting the management connection into an access point and accidentally losing SSH or Internet access.

The intended arrangement is:

Upstream router
    ↓
wlan1
    ↓
PineApple-Pi host and management

Phone or laptop
    ↓
wlan2
    ↓
PineApple-Pi toolkit AP

Authorized inventory target
    ↓
wlan0
    ↓
Inventory workflow

Current Development Hardware Mapping

The reference development system uses:

`wlan0`

Hardware: Raspberry Pi built-in wireless radio
Role: Network inventory

`wlan1`

Hardware: Realtek RTL8723BU USB adapter
Driver: rtl8xxxu
Role: Host and Internet uplink

`wlan2`

Hardware: Realtek RTL88x2BU AC1200 adapter
Driver: rtw88_8822bu
Role: PineApple-Pi access point

Interface names can change after:

Reinstalling the operating system
Replacing an adapter
Moving an adapter between USB ports
Changing a driver
Booting with an adapter disconnected
Adding another network interface

Always verify the current mapping before starting the AP.

Recommended Address Plan

Host interface:         wlan1
Host IPv4 address:      Assigned by upstream DHCP
Host dashboard:         http://pineapplepi.local:8000/

Toolkit AP interface:   wlan2
Toolkit AP address:     10.42.0.1/24
Toolkit AP subnet:      10.42.0.0/24
Toolkit AP SSID:        PineApplePi-Toolkit
Toolkit AP band:        2.4 GHz
Toolkit AP channel:     6
Toolkit dashboard:      http://10.42.0.1:8000/

Inventory interface:    wlan0

Default Access Point Configuration

SSID:                PineApplePi-Toolkit
Interface:           wlan2
Band:                2.4 GHz
Channel:             6
Address:             10.42.0.1/24
IPv4 mode:           Shared
Internet uplink:     wlan1
Client isolation:    Enabled
Wi-Fi security:      Open network
Wi-Fi password:      None

Warning

An open AP has no Wi-Fi password.

Anyone within radio range may attempt to connect. The web dashboard also has no login requirement in this prototype release.

Supported AP Channels

The dashboard limits channel choices to a small allowlist.

2.4 GHz

1
6
11

5 GHz

The default is:

2.4 GHz channel 6

Hardware Requirements

Minimum Hardware

Raspberry Pi capable of running a 64-bit operating system
Reliable microSD card or supported SSD
Appropriate Raspberry Pi power supply
Cooling suitable for continuous operation
One working management-network connection
SSH, local display, or Raspberry Pi Connect access

Recommended Hardware

Raspberry Pi 4 or newer
Built-in Wi-Fi for inventory or management fallback
One USB Wi-Fi adapter for host/uplink
One AP-capable USB Wi-Fi adapter for wlan2
Powered USB hub for multiple wireless adapters
Short, high-quality USB cables or extensions
Recovery microSD card stored separately
Case with heatsink and fan

Power Warning

Multiple USB Wi-Fi adapters can exceed the Raspberry Pi's available USB power.

Check the Pi power state:

vcgencmd get_throttled

Healthy result:

throttled=0x0

Do not start the AP or install large packages while active undervoltage is present.

A value such as:

throttled=0x50005

indicates active or recorded power problems and should be investigated before continuing.

Verify Connected Hardware

ip -brief link
iw dev
nmcli device status
lsusb
lsusb -t

Identify Adapter Drivers

ethtool -i wlan1
ethtool -i wlan2

Verify AP Capability

Identify the physical radio:

iw dev

Inspect the correct PHY. Replace phy3 when necessary:

iw phy phy3 info |
sed -n '/Supported interface modes:/,/Band 1:/p'

The output must include:

* AP

Software Requirements

PineApple-Pi v0.7.1 targets:

Debian 13 Trixie
Raspberry Pi OS 64-bit
ARM64
Python 3
NetworkManager
nmcli
iproute2
Avahi
Git
Python virtual environments
systemd

Install the base packages:

sudo apt update

sudo apt install -y \
  git \
  python3 \
  python3-venv \
  python3-pip \
  network-manager \
  iproute2 \
  iw \
  usbutils \
  ethtool \
  rfkill \
  avahi-daemon \
  libnss-mdns \
  curl \
  rsync \
  sudo

Enable mDNS:

sudo systemctl enable --now avahi-daemon

Verify:

systemctl is-active avahi-daemon
getent hosts pineapplepi.local

Download Options

GitHub Releases

Prepared builds are published on the PineApple-Pi Releases page.

The prepared release asset for this version should be named:

PineApple-Pi-v0.7.1-ap-enabled.zip

Clone the Repository

cd ~

git clone https://github.com/Ghost0Mod3/PineApple-Pi.git

cd PineApple-Pi

Verify:

git status
git remote -v
find . -maxdepth 3 -type f | sort

Repository Structure

PineApple-Pi/
├── backend/
│   ├── __init__.py
│   ├── cli.py
│   ├── config.py
│   ├── database.py
│   └── main.py
│
├── database/
│   └── schema.sql
│
├── data/
│   ├── artifacts/
│   └── backups/
│
├── frontend/
│   ├── assets/
│   │   ├── app.css
│   │   ├── app.js
│   │   ├── banner.jpg
│   │   └── login-logo.jpg
│   └── index.html
│
├── logs/
│
├── scripts/
│   ├── deploy-dev.sh
│   ├── install-tool-helper.sh
│   └── pineapple-tool-installer
│
├── systemd/
│   └── pineapple-pi-api.service
│
├── tests/
│   └── test_basic.py
│
├── .env.example
├── .gitignore
├── install.sh
├── LICENSE
├── pyproject.toml
├── README.md
├── requirements-dev.txt
└── requirements.txt

Quick Start

1. Enter the Project

cd ~/PineApple-Pi

Confirm:

pwd
ls -la

2. Create the Development Environment

python3 -m venv .venv
source .venv/bin/activate

3. Install Dependencies

python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt

4. Create Local Configuration

cp .env.example .env
chmod 600 .env

5. Initialize SQLite

python -m backend.cli

Expected:

Database initialized

6. Run Tests

pytest -q

7. Start the Development Server

python -m uvicorn backend.main:app \
  --host 0.0.0.0 \
  --port 8001

Open:

http://PI-IP-ADDRESS:8001/

Example:

http://192.168.4.30:8001/

Development Helper

The included development helper creates the virtual environment, installs requirements, initializes the database, and starts port 8001.

chmod +x scripts/deploy-dev.sh
./scripts/deploy-dev.sh

Production Installation

The production installer deploys PineApple-Pi into:

/opt/pineapple-pi

Run:

cd ~/PineApple-Pi

sudo bash install.sh

The installer:

Installs required Debian packages.
Creates a production directory.
Copies the source files.
Creates /opt/pineapple-pi/.env.
Creates a production Python virtual environment.
Installs Python requirements.
Initializes SQLite.
Installs the systemd service.
Enables PineApple-Pi at boot.
Installs the dashboard tool helper.
Starts the production dashboard on port 8000.

After installation, open:

http://pineapplepi.local:8000/

IP fallback:

http://PI-IP-ADDRESS:8000/

Configuration

PineApple-Pi reads configuration from .env.

The default v0.7.1 configuration is:

APP_VERSION=0.7.1-ap-enabled
DATABASE_PATH=database/pineapple_pi.db
FRONTEND_PATH=frontend

HOST_INTERFACE=wlan1
ACCESS_POINT_INTERFACE=wlan2
INVENTORY_INTERFACE=wlan0

ENABLE_AP_CHANGES=true
AP_CONNECTION_NAME=PineApple-AP

`APP_VERSION`

Version shown by the health endpoint:

APP_VERSION=0.7.1-ap-enabled

`DATABASE_PATH`

SQLite database path:

DATABASE_PATH=database/pineapple_pi.db

`FRONTEND_PATH`

Static frontend directory:

FRONTEND_PATH=frontend

`HOST_INTERFACE`

Primary management and Internet interface:

HOST_INTERFACE=wlan1

`ACCESS_POINT_INTERFACE`

Dedicated AP interface:

ACCESS_POINT_INTERFACE=wlan2

`INVENTORY_INTERFACE`

Network inventory interface:

INVENTORY_INTERFACE=wlan0

`ENABLE_AP_CHANGES`

Controls whether the dashboard can configure, start, or stop the AP:

ENABLE_AP_CHANGES=true

`AP_CONNECTION_NAME`

NetworkManager connection name:

AP_CONNECTION_NAME=PineApple-AP

Verify Production Configuration

sudo grep -E \
  '^(APP_VERSION|HOST_INTERFACE|ACCESS_POINT_INTERFACE|INVENTORY_INTERFACE|ENABLE_AP_CHANGES|AP_CONNECTION_NAME)=' \
  /opt/pineapple-pi/.env

Expected:

APP_VERSION=0.7.1-ap-enabled
HOST_INTERFACE=wlan1
ACCESS_POINT_INTERFACE=wlan2
INVENTORY_INTERFACE=wlan0
ENABLE_AP_CHANGES=true
AP_CONNECTION_NAME=PineApple-AP

AP Configuration Workflow

Open Settings.
Confirm the displayed interfaces.
Enter the desired SSID.
Select channel 6 or another allowed channel.
Type:

OPEN NETWORK

Select Save AP.
Select Start.
Connect a test device.
Verify the client receives an address in 10.42.0.0/24.
Open the dashboard through 10.42.0.1:8000.

Stop the AP

Use Stop in Settings or run:

sudo nmcli connection down PineApple-AP

Manual Status Check

nmcli device status
ip -4 -brief address show wlan2
iw dev wlan2 info

Expected:

type AP
channel 6
10.42.0.1/24

AP Activity

The Settings page displays clients observed through wlan2.

Current data includes:

IP address
MAC address
Neighbor state
Online status

Manual check:

ip -4 neigh show dev wlan2

Example:

10.42.0.20 lladdr aa:bb:cc:dd:ee:ff REACHABLE

This means:

IP:       10.42.0.20
MAC:      aa:bb:cc:dd:ee:ff
Status:   REACHABLE

Privacy Boundary

The AP activity page does not intentionally collect:

Passwords
Browser history
Message contents
Account credentials
Client files
Full traffic content

Toolkit

The Toolkit page lists:

Wireshark / TShark
tcpdump
Nmap
arp-scan
Lynis
Recon-ng
SpiderFoot
theHarvester
Meshtastic
RTL-SDR
Node-RED
Docker

Each tool is displayed as:

Installed

or:

Not installed

Dashboard Tool Installation

The Downloads page can install tools with reviewed recipes.

Supported Dashboard Installation

TShark
tcpdump
Nmap
arp-scan
Lynis
RTL-SDR
Meshtastic CLI
Docker

Dedicated Recipe Required

The following remain visible but are not installed automatically:

Recon-ng
SpiderFoot
theHarvester
Node-RED

Generate an Installation Token

From an SSH terminal:

sudo pineapple-tool-installer issue-token

Example output:

Installation token: A1B2C3D4

The token is:

Short-lived
Single-use
Generated locally
Required for one installation request

Do not post the real token publicly.

Install from the Dashboard

Open Downloads.
Choose a supported tool.
Click Install.
Enter the one-time token.
Wait for the installation to finish.
Refresh the Downloads page.

Why a Token Is Required

The dashboard itself does not receive arbitrary root shell access.

The browser submits:

{
  "tool_id": "nmap",
  "confirmation_token": "A1B2C3D4"
}

The helper maps nmap to a fixed package command.

The browser cannot provide:

A custom package name
An arbitrary shell command
A custom URL
A custom Git repository
Extra package-manager arguments

Verify Tool Installation

command -v tshark
command -v tcpdump
command -v nmap
command -v arp-scan
command -v lynis
command -v rtl_test
command -v meshtastic
command -v docker

Restart PineApple-Pi after installing tools:

sudo systemctl restart pineapple-pi-api.service

Authorization Projects

Authorization Projects record the purpose and boundaries of approved work.

Each project includes:

Project name
Owner
Exact scope
Active status
Optional expiration value

A useful scope should identify:

Included systems
Included networks
Excluded systems
Permitted actions
Prohibited actions
Testing window
Data handling expectations

Example:

Inventory is limited to the privately owned lab network.

Permitted activity includes device discovery, address inventory,
service identification, and configuration review.

Disruption, credential collection, denial of service,
and testing against third-party systems are excluded.

Production Service

Check the service:

sudo systemctl status \
  pineapple-pi-api.service \
  --no-pager \
  --full

Check enablement:

sudo systemctl is-enabled pineapple-pi-api.service

Check runtime state:

sudo systemctl is-active pineapple-pi-api.service

Expected:

enabled
active

Health Check

curl -fsS http://127.0.0.1:8000/healthz
echo

Expected:

{"status":"ok","version":"0.7.1-ap-enabled"}

Check Port 8000

sudo ss -ltnp 'sport = :8000'

Dashboard Entry Points

Local Hostname

http://pineapplepi.local:8000/

Host IP

http://PI-IP-ADDRESS:8000/

Direct AP Address

http://10.42.0.1:8000/

Development Server

http://PI-IP-ADDRESS:8001/

Database

PineApple-Pi uses SQLite.

Default path:

database/pineapple_pi.db

Current record types include:

Liability acknowledgments
Authorization projects
AP client records
AP o cp
/opt/pineapple-pi/database/pineapple_pi.db
~/pineapple-pi-backup.sqlite

sudo systemctl start pineapple-pi-api.service


Protect database backups because they may contain:

- Client IP addresses
- Client MAC addresses
- Authorization scope
- Connection timestamps

---

## Updating from GitHub

Back up local state first:

```bash
sudo cp \
  /opt/pineapple-pi/.env \
  ~/pineapple-pi-production.env

sudo cp \
  /opt/pineapple-pi/database/pineapple_pi.db \
  ~/pineapple-pi-production.db

Update the repository:

cd ~/PineApple-Pi

git pull

Reinstall:

sudo bash install.sh

Replacing Repository Files with a Release ZIP

When replacing the GitHub repository through drag and drop:

Extract the release ZIP.
Open the extracted project folder.
Select everything inside the project folder.
Upload the files to the GitHub repository root.
Replace existing files when prompted.
Commit the changes.
Pull the changes onto the Pi.
Run the installer.

The GitHub repository root should immediately contain:

backend/
database/
frontend/
scripts/
systemd/
tests/
.env.example
.gitignore
install.sh
README.md
requirements.txt
requirements-dev.txt

Avoid creating this incorrect nested structure:

PineApple-Pi/
└── PineApple-Pi-v0.7.1-ap-enabled/
    ├── backend/
    └── frontend/

Troubleshooting

Git Is Missing

sudo apt update
sudo apt install -y git

Virtual Environment Cannot Be Created

sudo apt install -y python3-venv
python3 -m venv .venv

`.env.example` Is Missing

ls -la

Make sure the repository root contains:

.env.example

Dashboard Will Not Start

sudo systemctl status \
  pineapple-pi-api.service \
  --no-pager \
  --full

View logs:

sudo journalctl \
  -u pineapple-pi-api.service \
  -n 100 \
  --no-pager

Port 8000 Is Closed

sudo systemctl enable --now pineapple-pi-api.service
sudo ss -ltnp 'sport = :8000'

AP Controls Show Disabled

Check:

sudo grep '^ENABLE_AP_CHANGES=' \
  /opt/pineapple-pi/.env

Expected:

ENABLE_AP_CHANGES=true

Restart:

sudo systemctl restart pineapple-pi-api.service

AP Does Not Start

nmcli device status
iw dev
sudo journalctl \
  -u NetworkManager \
  -n 100 \
  --no-pager

Channel Is Wrong

iw dev wlan2 info

Expected:

channel 6

AP Clients Do Not Get Addresses

ip -4 -brief address show wlan2

Expected:

10.42.0.1/24

Check NetworkManager:

sudo journalctl \
  -u NetworkManager \
  -n 100 \
  --no-pager

USB Adapter Repeatedly Disconnects

sudo dmesg --ctime |
grep -Ei \
  'usb|wlan2|rtw88|disconnect|reset|error'

Check power:

vcgencmd get_throttled

If active undervoltage is present:

Stop the AP.
Shut down cleanly.
Use a powered hub.
Verify the Pi power supply.
Retest before starting the AP.

Tool Installation Fails

Check helper installation:

ls -la \
  /usr/local/sbin/pineapple-tool-installer

Check sudoers:

sudo visudo -cf \
  /etc/sudoers.d/pineapple-pi-installer

Issue a fresh token:

sudo pineapple-tool-installer issue-token

Tokens are single-use.

Security Boundaries

Implemented

Fixed AP interface
Fixed AP channel allowlist
Explicit open-network confirmation
Tool installation allowlist
One-time installation tokens
No browser-provided arbitrary shell command
No browser-provided package name
No browser-provided installation URL
Database excluded from Git
.env excluded from Git
Client isolation control
Authorization project records

Recommended Before a Stable Release

Restore administrator authentication
Add HTTPS
Add CSRF protection
Add login rate limiting
Add a complete administrator audit log
Add firewall-management controls
Add database migrations
Add release signatures
Add published checksums
Add automated dependency checks
Add automated backup and restore
Add role-based dashboard permissions

Development Checks

Before committing changes:

python3 -m py_compile backend/*.py

bash -n install.sh
bash -n scripts/deploy-dev.sh
bash -n scripts/install-tool-helper.sh
bash -n scripts/pineapple-tool-installer

pytest -q

Never Commit

.env
.venv/
database/*.db
database/*.db-wal
database/*.db-shm
__pycache__/
*.pyc
Wi-Fi passwords
API keys
Session tokens
Private keys
Private assessment artifacts

Roadmap

Potential future work:

Guided Nmap interface
Guided arp-scan inventory
TShark capture profiles
tcpdump capture profiles
Lynis report viewer
RTL-SDR device page
Docker service manager
Dedicated SpiderFoot installer
Dedicated Recon-ng installer
Dedicated theHarvester installer
Dedicated Node-RED installer
Inventory reports
AP client labels
AP client history
Hostname collection
Exportable JSON and CSV reports
HTTPS deployment
Authentication restoration
Database migration system
Automated backups

Responsible Use

Appropriate uses include:

Inventorying a privately owned network
Operating a personal networking lab
Reviewing systems covered by explicit authorization
Troubleshooting local network configuration
Learning defensive network administration
Testing a controlled access point

PineApple-Pi does not create authorization.

The operator remains responsible for obtaining permission and defining scope.

License

Review the repository's LICENSE file before redistributing, modifying, or packaging PineApple-Pi.

Support and Issue Reports

When reporting an issue, include:

PineApple-Pi version
Raspberry Pi model
Operating-system version
Kernel version
Python version
Wi-Fi adapter chipset
Wi-Fi driver
Relevant service status
Relevant sanitized logs
Steps needed to reproduce the issue

Do not include:

Wi-Fi passwords
API keys
Private keys
Installation tokens
Session data
Sensitive client data
Private assessment results

Name		Name	Last commit message	Last commit date
backend		backend
database		database
frontend		frontend
scripts		scripts
systemd		systemd
tests		tests
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

PineApple-Pi

Project Status

Current Capabilities

Dashboard and Interface

Radio Architecture

Access Point

AP Activity

Tools

Authorization

Important Security Notice

Network Layout

Why Separate the Interfaces?

Current Development Hardware Mapping

wlan0

wlan1

wlan2

Recommended Address Plan

Default Access Point Configuration

Supported AP Channels

2.4 GHz

5 GHz

Hardware Requirements

Minimum Hardware

Recommended Hardware

Power Warning

Verify Connected Hardware

Identify Adapter Drivers

Verify AP Capability

Software Requirements

Download Options

GitHub Releases

Clone the Repository

Repository Structure

Quick Start

1. Enter the Project

2. Create the Development Environment

3. Install Dependencies

4. Create Local Configuration

5. Initialize SQLite

6. Run Tests

7. Start the Development Server

Development Helper

Production Installation

Configuration

APP_VERSION

DATABASE_PATH

FRONTEND_PATH

HOST_INTERFACE

ACCESS_POINT_INTERFACE

INVENTORY_INTERFACE

ENABLE_AP_CHANGES

AP_CONNECTION_NAME

Verify Production Configuration

AP Configuration Workflow

Stop the AP

Manual Status Check

AP Activity

Privacy Boundary

Toolkit

Dashboard Tool Installation

Supported Dashboard Installation

Dedicated Recipe Required

Generate an Installation Token

Install from the Dashboard

Why a Token Is Required

Verify Tool Installation

Authorization Projects

Production Service

Health Check

Check Port 8000

Dashboard Entry Points

Local Hostname

Host IP

Direct AP Address

Development Server

Database

`wlan0`

`wlan1`

`wlan2`

`APP_VERSION`

`DATABASE_PATH`

`FRONTEND_PATH`

`HOST_INTERFACE`

`ACCESS_POINT_INTERFACE`

`INVENTORY_INTERFACE`

`ENABLE_AP_CHANGES`

`AP_CONNECTION_NAME`

`.env.example` Is Missing