How samwafgo/samwaf works
Main high-level components
• User Interface: Represented by the “vue” folder (and public UI assets), which provides the web-based dashboard and configuration pages.
• API/Controller Layer: The “api”, “router”, and “middleware” directories contain RESTful endpoints and authentication/security middleware. They serve as the entry points for administrative and monitoring operations.
• Core WAF Engine: The “wafenginecore” folder (along with supporting modules in “wafproxy”, “wafqueue”, “waftask”, “wafinit”, etc.) represents the engine that performs request inspection, rule checking, load balancing, and other security logic.
• Configuration & Rules Management: The “conf”, “model”, “customtype”, “enums”, and “codetemplete” directories store configuration files, definitions of rules, and templates for generating or updating rules.
• Data Persistence and Logging: The “wafdb”, “model”, and “cache” directories point to how the project manages logs, attack records, and configuration data. This component can also include encrypted log storage features described in the README.
• Notification and External Integrations: The “wafnotify” directory (with subfolders for Kafka and RabbitMQ) and “utils/wechat” indicate channels for sending alerts and integration with external messaging systems.
• Auxiliary Tools: Other directories (like “wafbot”, “wafsec”, “wafowasp”, “wafupdate”) represent specialized functions such as bot detection, encryption utilities, and rule updates.
• Deployment & Build Infrastructure: The Dockerfile, “docker-compose.yml”, and CI/CD related directories (.github, .gitea) illustrate the build, release, and container orchestration aspects.
Relationships and interactions
• Incoming web traffic first reaches the deployed WAF; requests are intercepted and processed by the core engine (wafenginecore) via modules in “wafproxy” and “middleware”.
• The API layer (“api” and “router”) exposes administrative functions and collects data (attack logs, system status) from the engine.
• The Web UI (in “vue”) communicates with these APIs to display the management dashboard, configuration screens, and report logs/alerts.
• The engine uses configuration data (loaded from “conf” and “model”) and applies security rules for filtering and blocking malicious requests.
• Logs and events are stored in local databases (managed by “wafdb”) while also being processed for notifications through the “wafnotify” module.
• There are also scheduled tasks and background workers (under “waftask” and “wafqueue”) ensuring periodic operations like SSL certificate checks, cache updates, and system health monitoring.
Architectural patterns/design principles
• Separation of concerns: The system is clearly divided between the presentation layer (Vue-based UI), the API layer (controllers/middleware), the core WAF logic (wafenginecore and related modules), and persistence/logging.
• Modular design: With distinct folders for features (e.g., security rule processing, caching, notifications), the project encourages extension and isolation of concerns.
• Microservice/Cross-module communication: Even though it is a single project, components like wafnotify, waftask, and the database interactions indicate a loosely coupled structure where different subsystems interact via well-defined interfaces.
• Cross-platform deployment: Support for Windows, Linux, and containerized deployment (Dockerfiles and Compose scripts) is evident.
Relevant technologies/frameworks and libraries
• Programming Language: Go is used across the project.
• Web Framework: Likely using Gin (indicated by “middleware/gin_global_exception_middleware.go”) for handling HTTP requests.
• Frontend: A Vue-based front end is provided.
• Messaging: Kafka and RabbitMQ integrations are visible.
• Database: Interaction with local databases (using GORM, as seen in “wafdb/gormlogger.go”).
• Other libraries: libinjection-go for injection detection, and various utility libraries for encryption, logging, and HTTP handling.