How safing/portmaster works
Project Type and Purpose
Project Type:
Portmaster is a full-stack application that functions as an open-source application firewall. It integrates deeply with the operating system's network stack to provide privacy controls, monitoring, and blocking capabilities for both Windows and Linux desktops.
Purpose:
Portmaster aims to enhance user privacy by monitoring all network activity, blocking unwanted trackers and malware, managing secure DNS settings, recording network history, and utilizing the Safing Privacy Network (SPN) for enhanced privacy through encrypted routing.
File Structure
Top-Level Directories:
• desktop
• Contains the frontend built with Angular and integrates with Tauri for cross-platform desktop functionality.
• service
• Houses the backend services written in Go, managing network interception, configurations, and interactions with the OS.
• spn
• Manages the Safing Privacy Network, including modules for network routing and privacy enhancements.
• windows_kext & windows_core_dll
• Contain Windows kernel extensions and DLLs necessary for deep integration with the Windows network stack.
• base, cmds, packaging, runtime
• Support various aspects of the application, including core functionalities, command-line tools, packaging scripts for different OS environments, and runtime configurations.
Architectural Indicators:
• Modular Structure: Clear separation between frontend (desktop/angular), backend (service, base), and specialized modules (spn).
• Configuration and Build Scripts: Presence of .github, Earthfile, and various Makefile and Dockerfile scripts indicate a robust CI/CD pipeline and environment setup.
• Kernel Integration: Directories like windows_kext suggest deep OS-level integration for network packet interception.
README for Additional Insights
The README outlines the following key architectural and technological aspects:
• Integration with Network Stack: Uses nfqueue on Linux and Windows Filtering Platform (WFP) drivers on Windows for packet interception.
• Local Processing: Emphasizes that all processing is done locally, enhancing privacy.
• Update Mechanisms: Automatic, signed updates ensure security and ease of maintenance.
• User Interface: Utilizes Electron (with plans to transition away) and Tauri for the desktop UI, providing both user-friendly and browser-based interfaces.
• SPN Integration: Incorporates the Safing Privacy Network for encrypted routing, positioned between traditional VPNs and Tor.
a. Main Components
• Frontend/UI:
• Angular Application: Located in desktop/angular, serving the user interface.
• Tauri/Electron Integration: Facilitates cross-platform desktop functionalities.
• Backend Services:
• Go Services: Located in service and base, handling business logic, network interception, and configuration management.
• Kernel Extensions/Drivers:
• Windows Kexts: Found in windows_kext and windows_core_dll, enabling low-level network packet interception on Windows.
• eBPF Modules: For Linux network interception.
• Safing Privacy Network (SPN):
• SPN Modules: Located in the spn directory, managing encrypted routing and privacy features.
• Database:
• Local Databases: For storing network activity logs, configurations, and usage data.
• Configuration & Update Mechanisms:
• Earthly & Docker: For build and deployment workflows.
• Automatic Update Services: Ensuring the application and its components remain up-to-date securely.
b. Relationships and Interactions
• UI ↔ Backend Services:
• The Angular frontend communicates with Go backend services via RESTful APIs or WebSockets for real-time updates.
• Backend ↔ Kernel Extensions:
• Backend services interact with kernel drivers (WFP on Windows, eBPF on Linux) to intercept and manage network packets.
• Backend ↔ SPN:
• Services route traffic through the SPN modules for encrypted and privacy-enhanced communication.
• Backend ↔ Database:
• All configuration settings, network logs, and usage data are stored and retrieved from local databases.
• Update Mechanism ↔ All Components:
• Automatic update services ensure that the frontend, backend, kernel drivers, and SPN modules receive the latest updates.
c. Architectural Patterns or Design Principles
• Modular Architecture:
• Separation of concerns with distinct modules for frontend, backend, kernel integration, and privacy networking.
• Microservices:
• Backend services are likely structured as microservices, each handling specific functionalities like network interception, configuration management, and SPN routing.
• Local-First Design:
• Emphasis on all processing being local enhances privacy and security.
• Extensibility:
• Modular components allow for future enhancements, such as transitioning away from Electron to more lightweight UI frameworks.
d. Relevant Technologies, Frameworks, or Libraries
• Frontend:
• Angular: For building dynamic and responsive user interfaces.
• Tauri/Electron: For cross-platform desktop application capabilities.
• Backend:
• Go (Golang): For efficient and concurrent backend services.
• eBPF (Linux) & WFP (Windows): For deep network packet interception and manipulation.
• Kernel Extensions:
• Rust/C/C++: Likely used in windows_kext and related directories for building secure and performant kernel drivers.
• Databases:
• Local Databases: Possibly using embedded databases like SQLite for storing logs and configurations.
• CI/CD & Build Tools:
• Earthly, Docker: For consistent build environments and deployment workflows.
• GitHub Workflows: For automated testing, building, and deployment processes.
Elements
• Clear Labels for Each Component:
• Frontend (Angular UI)
• Backend Services (Go Modules)
• Kernel Extensions (WFP Drivers, eBPF Modules)
• SPN Network
• Databases
• Configuration & Update Services
• From UI to Backend via APIs
• From Backend to Kernel Extensions for packet interception
• From Backend to SPN for encrypted routing
• Data storage flows between Backend and Databases
• Update flows from Update Services to all components
Detail and Essential Architectural Elements
• Comprehensive Coverage:
• Critical components are represented, including lesser-known modules and services.
• Avoid Overcomplication:
• While detail is essential, maintain clarity by grouping related components and using hierarchical structuring.
• Scalability:
• Consistency:
Final Recommendations
• Tool Selection:
• Iterative Refinement:
• Collaborative Review:
• Documentation: