# openappsec/waf-comparison-project architecture

> Architecture diagram of the GitHub repository openappsec/waf-comparison-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openappsec/waf-comparison-project
- Repository: https://github.com/openappsec/waf-comparison-project

## Overview

##### Project type and purpose
- This is a Python-based test automation tool whose purpose is to compare the efficacy of multiple Web Application Firewalls (WAFs). It ingests large sets of legitimate and malicious HTTP request data, sends them to configured WAF endpoints, records responses in a database, and computes security metrics (true positive/false positive rates).

##### File structure
- Top-level files and directories:
- Data/ – contains “Legitimate” and “Malicious” subfolders of HTTP request files
- config_template.py – blueprint for WAF URLs, database credentials, thread counts
- runner.py – main entry point that orchestrates the pipeline
- analyzer.py – computes performance metrics from logged results
- helper.py – utility functions for HTTP requests, threading, health checks
- analyzer.py, helper.py, runner.py, analyzer.py – form the core modules
- requirements.txt – third-party libraries (e.g., requests, psycopg2)
- No frontend; purely a backend automation pipeline.

##### README for additional insights
- Workflow:
1. Copy config_template.py → config.py (enter WAF URLs + DB settings)
2. Health-check each WAF (connectivity + prevention mode)
3. Load two datasets and dispatch each request in multi-threaded fashion via requests library
4. Log every WAF response to an external PostgreSQL (AWS RDS)
5. Post-processing via analyzer.py to generate balanced scores
- External dependencies: WAF endpoints, optional upstream nginx, AWS RDS Postgres, datasets on disk.

##### Final pointers
- Configuration as a first-class component.
- Make the multithreading dispatch step explicit so reviewers understand performance scaling.
- Optional nginx upstream if used in certain test scenarios.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Project Documentation
    Readme["README.md"]:::docs
    Requirements["requirements.txt"]:::docs
    DataRead["Data/README.md"]:::docs

    %% Configuration
    Config["config_template.py"]:::code

    %% Dataset Files
    DataFolder["Data/ (Legitimate & Malicious)"]:::storage

    %% Core Modules
    subgraph "Core Modules"
        Runner["runner.py"]:::code
        Helper["helper.py"]:::code
        Analyzer["analyzer.py"]:::code
    end

    %% External Services
    subgraph "External Services"
        direction TB
        WAFs["WAF Endpoints"]:::external
        Nginx["Optional Nginx Upstream"]:::external
    end

    %% Database
    Postgres["PostgreSQL RDS"]:::storage

    %% Report Output
    Report["Metrics Report"]:::code

    %% Data Flow
    Readme -->|“setup instructions”| Runner
    Requirements -->|“dependencies”| Runner
    Config -->|“load configuration”| Runner
    DataFolder -->|“read HTTP requests”| Runner

    Runner -->|“health check”| Helper
    Helper -->|“HTTP health checks”| WAFs
    Helper -->|“multi-threaded dispatch”| WAFs
    WAFs -->|“responses”| Postgres

    Nginx -->|“optional proxy”| Helper

    Runner -->|“invoke analysis”| Analyzer
    Analyzer -->|“read results”| Postgres
    Analyzer -->|“compute metrics”| Report

    %% Click Events
    click Config "https://github.com/openappsec/waf-comparison-project/blob/main/config_template.py"
    click DataFolder "https://github.com/openappsec/waf-comparison-project/tree/main/Data/"
    click Runner "https://github.com/openappsec/waf-comparison-project/blob/main/runner.py"
    click Helper "https://github.com/openappsec/waf-comparison-project/blob/main/helper.py"
    click Analyzer "https://github.com/openappsec/waf-comparison-project/blob/main/analyzer.py"
    click Requirements "https://github.com/openappsec/waf-comparison-project/blob/main/requirements.txt"
    click Readme "https://github.com/openappsec/waf-comparison-project/blob/main/README.md"
    click DataRead "https://github.com/openappsec/waf-comparison-project/blob/main/Data/README.md"

    %% Styles
    classDef code fill:#CCE5FF,stroke:#333,stroke-width:1px;
    classDef external fill:#FFDD99,stroke:#333,stroke-width:1px;
    classDef storage fill:#C8E6C9,stroke:#333,stroke-width:1px;
    classDef docs fill:#EEEEEE,stroke:#333,stroke-width:1px;
```
