Pwnagotchi Generator: Understanding opwngrid Through Reverse Engineering

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:

1. RSA-2048 keypairs - Each unit needs a persistent identity
2. SHA-256 fingerprints - Computed from the public key
3. PKCS1-PSS signatures - Signs name@fingerprint with 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.