How evilsocket/pwnagotchi works
Main Components
• AI/Agent & Learning Core
– Located under the “pwnagotchi/ai” directory with modules such as epoch.py, featurizer.py, train.py, etc.
– Contains the policy network implementation (using an LSTM-MLP architecture) and adapts key parameters over time.
• Core Engine & Orchestration
– Modules like agent.py, automata.py, and grid.py coordinate the operation of the tool.
– The main “pwnagotchi” package encapsulates configuration (defaults.toml), logging (log.py), and identity handling.
• Plugins
– Found in “pwnagotchi/plugins”, these extend or modify core functionality (for example, web configuration, system monitoring, auto-update, etc.).
• Hardware/Display Integration
– Located in “pwnagotchi/ui/hw” and associated “libs” directories for various hardware types (Adafruit, DFRobot, Waveshare, etc).
– This layer supports the various display configurations and peripheral controls.
• Web and UI Interface
– Under “pwnagotchi/ui” there are components for display and a web interface (e.g., “web/server.py”, “web/templates”).
– This includes both portable UI hardware as well as a browser-based "status" or configuration panel.
• Mesh Networking
– Found under “pwnagotchi/mesh”, handling peer discovery and communication between multiple units.
• Build/Deployment & Scripts
– The “builder” folder contains configuration files, systemd service definitions, and network settings.
– The “scripts” and “bin” folders manage deployment and auxiliary operations (e.g., backups, connection shares).
Relationships and Interactions
• The AI/Agent module interacts with:
– The learning infrastructure (e.g., training routines, parameter adjustments) to tune its “pwning” algorithm.
– The mesh/networking modules to share information with nearby units.
– The plugins to add or override behaviors.
• The Core Engine calls on the hardware layer to display status information and control the interface – for example, sending output to LCDs or OLED displays.
• The Web UI module integrates with the core engine to provide remote status viewing and configuration, utilizing its built-in web server and static assets.
• The builder and system configuration files ensure that on startup (via systemd services defined in the builder/data/etc/systemd), the tool initializes with the correct network, hardware, and AI configurations.
Architectural Patterns and Design Principles
• Modular design: The project is organized into separate logical areas (agent, AI, plugins, UI, networking) so that components can be developed, tested, and maintained nearly independently.
• Plugin architecture: The plugins directory signifies an extensibility point, allowing additional functionality to be integrated without changing the core system.
• Separation of Concerns: There is a distinct split between learning logic (AI), hardware integration (UI/hw and supporting libs), and I/O/communication (mesh and web modules).
• Use of configuration and initialization files (e.g., defaults.toml, pwnagotchi.yml) to abstract runtime parameters from code.
Relevant Technologies, Frameworks, and External Tools
• Reinforcement Learning and AI: Uses an A2C-based agent with an LSTM and MLP policy network.
• Networking: Integrates with bettercap for WiFi interactions and likely uses standard Linux networking for interface modification (see builder/data/etc/network).
• System Deployment: Contains Makefile, setup.py, and systemd unit files to facilitate installation and service management.
• Hardware libraries: Supports various peripheral hardware via interfacing libraries, many of which are included in the “ui/hw/libs” directory.
• Web technologies: HTML templates, CSS, and JavaScript for status and remote management interfaces.