Testing distributed systems is hard. But what if the system you need to test has no official documentation? That's where reverse engineering comes in. The Pwnagotchi Generator started as a deep dive into understanding how opwngrid's authentication and reporting protocols work under the hood.
The Challenge: Understanding opwngrid
The Pwnagotchi ecosystem relies on opwngrid to share captured WiFi handshakes across devices. But to build effective testing tools, I needed to understand:
- How does authentication actually work?
- What cryptographic signing scheme is used?
- How are access points reported and validated?
- What rate limiting or anti-abuse mechanisms exist?
- Can the protocol handle extreme edge cases?
The only way to answer these questions was to reverse engineer the protocol itself.
Reverse Engineering the Authentication Flow
Initial Discovery
My first step was examining how real Pwnagotchi devices communicate with the grid. Using packet capture and API inspection, I identified the enrollment endpoint:
POST /api/v1/unit/enroll
But what data format did it expect? Time to dig deeper.
Understanding the Cryptographic Requirements
Through analysis of the open-source Pwnagotchi codebase and network traffic, I discovered the authentication uses:
RSA-2048 keypairs - Each unit needs a persistent identity
SHA-256 fingerprints - Computed from the public key
PKCS1-PSS signatures - Signsname@fingerprintwith the private key
The server validates this signature to ensure the enrollment request comes from someone who controls the private key. This prevents impersonation attacks.
Implementing Authentic Signing
Getting the signature format right was critical. The grid expects:
def generate_signature(name: str, fingerprint: str, private_key) -> str:
message = f"{name}@{fingerprint}".encode('utf-8')
signature = private_key.sign(
message,
padding.PSS(
mgf=padding.MGF1(hashes.SHA256()),
salt_length=padding.PSS.MAX_LENGTH
),
hashes.SHA256()
)
return base64.b64encode(signature).decode('utf-8')
Any deviation from this exact format and the server rejects the enrollment. This taught me how serious the authentication is - you can't fake it without the private key.
Discovering API Endpoints Through Testing
With authentication working, I needed to understand the full API surface. Through systematic testing and endpoint discovery, I mapped out:
Enrollment Flow
POST /api/v1/unit/enroll
Body: { identity, public_key, signature, data }
Returns: JWT token for subsequent requests
AP Reporting
POST /inbox
Headers: { X-Unit-Name, X-Unit-Fingerprint, X-Unit-Signature }
Body: Access point data with encryption info
Unit Data Endpoint
GET /api/v1/unit/{fingerprint}/data
Returns: Current statistics for the unit
Each endpoint taught me something about the protocol design and security model.
Stress Testing at Scale
Once I understood the protocol, I could properly stress test it. But this revealed interesting challenges:
The Million AP Problem
What happens when a unit has 1,000,000 pwned networks? Reporting them individually would take hours. Through testing different approaches, I discovered:
- The server can handle batch uploads efficiently
- Intelligent sampling maintains statistical accuracy
- Multi-threading is essential for performance
This led to the multi-threaded architecture:
# Single-threaded: ~8 minutes
python3 pwnagotchi-gen.py --count 1 --name mega --pwned 1000000
# 20 threads: ~30 seconds
python3 pwnagotchi-gen.py --count 1 --name mega --pwned 1000000 --threads 20
| Pwned Count | Threads | Time | Discovery |
|---|---|---|---|
| 1,000,000 | 1 | ~8 min | Connection timeout issues |
| 1,000,000 | 10 | ~60 sec | Improved but still slow |
| 1,000,000 | 20 | ~30 sec | Optimal performance |
| 1,000,000 | 50 | ~12 sec | Diminishing returns |
Rate Limiting Discovery
By gradually increasing request volume, I found the grid has soft rate limits around:
- 50 concurrent connections per IP
- ~1000 AP reports per minute per unit
- Exponential backoff on repeated failures
Understanding these limits helped design respectful testing that won't impact production grids.
Protocol Edge Cases and Security
Edge Case: Unicode SSIDs
Testing revealed interesting handling of non-ASCII SSIDs:
# These all needed proper handling:
ssid = "café" # UTF-8 encoding
ssid = "测试网络" # Chinese characters
ssid = "🔥WiFi" # Emoji (yes, really)
The grid properly handles UTF-8 encoding, but URL encoding in API calls required careful attention.
Edge Case: Signature Replay
What happens if you reuse a signature? Testing showed:
- Signatures are time-sensitive (implicitly via JWT)
- But the enrollment signature can be cached
- Token refresh is handled gracefully
Edge Case: Extreme Statistics
Can units report billions of epochs or impossible uptime? Testing revealed:
- The server validates reasonable ranges
- But allows for very high-uptime units
- Statistics are stored as appropriate integer types
Building the Testing Framework
Understanding the protocol enabled building a comprehensive testing suite:
Authentic Simulation
Every synthetic unit:
- Generates real RSA-2048 keypairs
- Computes proper SHA-256 fingerprints
- Signs enrollment exactly like real devices
- Cannot be distinguished from genuine Pwnagotchi units
Fleet Management
The CLI and web interface provide:
- Real-time monitoring of synthetic units
- Bulk operations (boot all, stop all)
- Per-unit Tor circuit management
- Persistent state across restarts
Performance Testing
Multi-threading enables:
- High-volume AP reporting (millions of networks)
- Concurrent unit enrollment
- Database connection pool stress testing
- API rate limit verification
Real-World Applications
Security Research
Understanding the authentication protocol helps identify:
- Potential attack vectors (all mitigated by design)
- Rate limiting effectiveness
- DoS resistance under load
- Token handling security
Protocol Documentation
This project serves as unofficial documentation for:
- Enrollment flow and requirements
- AP reporting format and validation
- Expected HTTP headers and responses
- Error handling and retry logic
Grid Deployment Testing
Before deploying your own opwngrid:
- Test database performance under load
- Verify API server scaling
- Validate connection pooling
- Confirm rate limiting works
Technical Deep Dive
Authentication Internals
# Key generation
private_key = rsa.generate_private_key(
public_exponent=65537,
key_size=2048,
backend=default_backend()
)
# Fingerprint computation
public_der = public_key.public_bytes(
encoding=serialization.Encoding.DER,
format=serialization.PublicFormat.SubjectPublicKeyInfo
)
fingerprint = hashlib.sha256(public_der).hexdigest()
# Signature generation
signature = private_key.sign(
f"{name}@{fingerprint}".encode(),
padding.PSS(
mgf=padding.MGF1(hashes.SHA256()),
salt_length=padding.PSS.MAX_LENGTH
),
hashes.SHA256()
)
AP Reporting Strategy
Intelligent sampling based on total count:
def calculate_sample_size(total_pwned: int) -> int:
if total_pwned <= 100:
return total_pwned # Report all
elif total_pwned <= 1000:
return min(500, total_pwned) # Up to 500
elif total_pwned <= 100000:
return int(total_pwned * 0.01) # 1%
else:
return min(5000, int(total_pwned * 0.005)) # 0.5%, max 5K
This maintains statistical accuracy while respecting API limits.
Installation & Usage
Quick Start
git clone https://github.com/4ngel2769/pwnagotchi-generator.git
cd pwnagotchi-generator
pip3 install -r requirements.txt
Generate Test Units
# Create a test unit with realistic stats
python3 pwnagotchi-gen.py --count 1 --name test --pwned 10000 --yes
# Create multiple units through Tor
python3 pwnagotchi-gen.py --count 10 --tor --pwned random
# High-performance testing
python3 pwnagotchi-gen.py --count 1 --name mega --pwned 1000000 --threads 20 --yes
Fleet Management
# Launch CLI interface
python3 pwnie-manager.py
# Or use the web dashboard
python3 pwnie-manager.py --webui
# Browse to http://localhost:5000
Lessons Learned
Protocol Design Insights
The opwngrid protocol is well-designed:
- Proper cryptographic authentication prevents impersonation
- JWT tokens enable stateless validation
- Rate limiting protects against abuse
- Graceful error handling aids debugging
Reverse Engineering Ethics
This project demonstrates responsible reverse engineering:
Purpose: Build testing tools for legitimate infrastructure
Documentation: Share knowledge to help the ecosystem
Respect: Follow rate limits and don't abuse production grids
Open Source: All code is public for review and improvement
Performance Optimization
Key optimizations discovered through testing:
- Thread pooling dramatically improves throughput
- Intelligent sampling maintains accuracy
- Tor circuit reuse reduces overhead
- State persistence enables resumability
Future Enhancements
Planned improvements include:
- Enhanced web dashboard with analytics
- Real-time log streaming
- Statistical analysis and graphing
- Configuration templates and profiles
- SQLite persistence for historical data
See readmes/WEB-DASHBOARD-PLAN.md for detailed roadmap.
Conclusion
Reverse engineering opwngrid wasn't about breaking it - it was about understanding it deeply enough to build proper testing tools. The authentication is solid, the protocol is well-designed, and stress testing reveals how robust the system really is.
Whether you're deploying your own grid, developing new features, or studying distributed system security, understanding the protocol at this level is invaluable. The Generator provides a practical tool while demonstrating responsible reverse engineering practices.
Want to explore the protocol yourself? Check out the GitHub repository and start experimenting.
Found this useful? Star the repo and share your findings with the community!
Note: Always use this tool responsibly against your own infrastructure or with explicit permission. Respect rate limits and don't abuse public grids.