# leohearts/awd-watchbird architecture

> Architecture diagram of the GitHub repository leohearts/awd-watchbird, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leohearts/awd-watchbird
- Repository: https://github.com/leohearts/awd-watchbird

## Overview

##### Core Components
- Main WAF Module (watchbird-source.php)
- Kernel-level Protection Module (waf.c/waf.so)
- Web Console UI
- Installation/Management Script (pack.py)

##### Architecture Layers

Layer 1: Web Application Layer
- Protected PHP application (represented as an external component)
- Connection to the WAF integration points

Layer 2: WAF Processing Layer
- Request Interceptor
- Defense Modules:
- Basic Protection:
- SQL Injection Detection
- File Upload Protection
- LFI Protection
- Flag Keyword Detection
- Unserialize Protection
- RCE Protection
- DDoS Protection
- Request Header/Parameter Analysis
- Deep Protection:
- Response Detection
- Reverse Proxy
- Flag Response Protection
- LD_PRELOAD Protection
- open_basedir Protection

Layer 3: Management Layer
- Web Console
- Configuration Management
- Real-time Logging
- Traffic Replay System
- Alert System

##### Flow Directions
- Incoming web requests
- Inspection points
- Response paths
- Management interactions

##### Component Relationships
- Data flow between protection modules
- Monitoring connections to the management console

##### Special Elements
- A proxy server component with configurable settings
- Flag detection and replacement mechanism
- Installation/deployment process

##### Technical Details
- PHP integration points
- Kernel-level protection mechanisms
- Configuration storage
- Log flow
- Alert pathways

Specific Implementation Notes:

##### Use a hexagonal architecture pattern
- Input adapters (request processing)
- Core security logic
- Output adapters (response processing)

##### A separate section for the installation process
- Relationship between pack.py and deployment
- Integration with the web server

- Reverse proxy flow
- Where LD_PRELOAD protection operates
- Flag detection and replacement mechanism

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Web Traffic"
        Client(("Client"))
        WebTraffic["HTTP/HTTPS Requests"]
    end

    subgraph "Web Application Layer"
        PHPApp["Protected PHP Application"]
        WAFIntegration["WAF Integration Point"]:::security
    end

    subgraph "Watchbird WAF Core"
        MainWAF["Main WAF Module"]:::core
        KernelProtect["Kernel Protection Module"]:::security
        
        subgraph "Defense Modules"
            BasicProtect["Basic Protection"]:::security
            DeepProtect["Deep Protection"]:::security
            LDProtect["LD_PRELOAD Protection"]:::security
            BasedirProtect["open_basedir Protection"]:::security
        end
        
        RequestInt["Request Interceptor"]:::core
        ResponseMon["Response Monitor"]:::core
    end

    subgraph "Management Layer"
        WebConsole["Web Console UI"]:::ui
        ConfigMgmt["Configuration Management"]:::management
        LogSystem["Logging System"]:::management
        TrafficReplay["Traffic Replay System"]:::management
    end

    subgraph "Special Features"
        FlagProtect["Flag Detection & Replacement"]:::feature
        DDoSProtect["DDoS Protection"]:::feature
        Broadcast["Broadcasting System"]:::feature
        Notify["Notification System"]:::feature
    end

    %% Connections
    Client --> WebTraffic
    WebTraffic --> WAFIntegration
    WAFIntegration --> RequestInt
    RequestInt --> MainWAF
    MainWAF --> KernelProtect
    
    MainWAF --> BasicProtect
    MainWAF --> DeepProtect
    MainWAF --> LDProtect
    MainWAF --> BasedirProtect
    
    BasicProtect --> PHPApp
    DeepProtect --> PHPApp
    LDProtect --> PHPApp
    BasedirProtect --> PHPApp
    
    PHPApp --> ResponseMon
    ResponseMon --> FlagProtect
    
    WebConsole --> ConfigMgmt
    ConfigMgmt --> MainWAF
    LogSystem --> WebConsole
    TrafficReplay --> Broadcast
    
    %% Click Events
    click MainWAF "https://github.com/leohearts/awd-watchbird/blob/master/watchbird-source.php"
    click KernelProtect "https://github.com/leohearts/awd-watchbird/blob/master/waf.c"
    
    %% Styling
    classDef core fill:#2374f7,stroke:#fff,stroke-width:2px,color:#fff
    classDef security fill:#ff6b6b,stroke:#fff,stroke-width:2px,color:#fff
    classDef management fill:#4ecdc4,stroke:#fff,stroke-width:2px,color:#fff
    classDef ui fill:#ffbe0b,stroke:#fff,stroke-width:2px,color:#fff
    classDef feature fill:#95d5b2,stroke:#fff,stroke-width:2px,color:#fff

    %% Legend
    subgraph Legend
        L1["Core Component"]:::core
        L2["Security Component"]:::security
        L3["Management Component"]:::management
        L4["User Interface"]:::ui
        L5["Special Feature"]:::feature
    end
```
