# orange-cyberdefense/grepmarx architecture

> Architecture diagram of the GitHub repository orange-cyberdefense/grepmarx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/orange-cyberdefense/grepmarx
- Repository: https://github.com/orange-cyberdefense/grepmarx

## Overview

##### Project Type & Purpose
- This is a full‐stack, Flask-based web application (“Grepmarx”) for security scanning (SAST & SCA).
- It provides a web UI (AdminLTE) to configure repositories, scan code, manage rules, view results and generate SBOMs.

##### High-Level Architecture Components
a. **Client (Browser)**
- HTML/CSS/JS (AdminLTE templates + custom assets under `app/base/static`)
- Interacts over HTTP(S).
b. **Edge Layer**
- Optional NGINX reverse proxy (docker nginx/grepmarx.conf)
- Routes requests to Gunicorn.
c. **Web Server**
- Gunicorn WSGI server (configured via `gunicorn-cfg.py` & `supervisord.conf`).
- Serves the Flask application (`run.py`).
d. **Flask Application**
- Blueprints under `app/`:
- base (login, nav, dashboard)
- administration (LDAP, user/repos management)
- analysis (scan submission, workbench, occurrence views)
- projects & rules (project dashboards, rule packs)
- ORM/models + forms + routes + templates/util.
- Configuration in `app/config.py`.
e. **Database**
- Relational DB (SQLite, MySQL or PostgreSQL via `requirements-*.txt`)
- Migrations via Alembic (`migrations/`).
f. **Task Queue & Workers**
- Redis (broker)
- Celery worker (`app/celery_worker.py`) scheduled by supervisor or Docker.
- Executes long‐running scan tasks asynchronously.
g. **Third-Party Analysis Engines**
- Semgrep (SAST)
- CycloneDX cdxgen & OWASP dep-scan (SCA/SBOM)
- scc (LOC counter)
- Application Inspector (feature discovery)
- Invoked by worker processes as CLI tools under `app/third-party/`.
h. **Storage for Artifacts**
- Scan outputs (reports, logs) written to DB or file‐system (e.g., `media/`).

##### Component Interactions & Data Flow
1. User submits scan request via Web UI →
HTTP POST → Gunicorn → Flask route (analysis blueprint)
2. Flask enqueues scan task → Celery (Redis broker)
3. Celery worker pulls task → invokes third‐party CLIs → processes results
4. Worker stores findings in Database + file storage
5. User refreshes/view results → Flask reads DB → renders templates

##### Architectural Patterns & Principles
- **MVC**-style separation: Blueprints for Controller (routes), Jinja templates for View, SQLAlchemy models as Model.
- **Asynchronous Processing**: Offload heavy scans to Celery workers.
- **Modularization**: Each feature in its own blueprint.
- **Externalization of Config**: `.env`, `config.py`, `docker-compose.yml`.
- **Infrastructure as Code**: Docker + Compose + supervisor configs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        StaticAssets["Static Assets"]:::frontend
        Templates["Templates"]:::frontend
    end

    %% Edge Layer
    NGINX["NGINX Reverse Proxy"]:::server

    %% Web Server
    subgraph "Web Server"
        direction TB
        Gunicorn["Gunicorn WSGI"]:::server
        Procfile["Procfile"]:::server
        Entrypoint["entrypoint.sh"]:::server
        Dockerfile["Dockerfile"]:::server
        Runtime["runtime.txt"]:::server
        GunicornCfg["gunicorn-cfg.py"]:::server
        Supervisor["supervisord.conf"]:::server
        SupervisorDocker["supervisord-docker.conf"]:::server
    end

    %% Application Layer
    subgraph "Flask Application" 
        direction TB
        CoreRun["run.py"]:::server
        Init["__init__.py"]:::server
        Config["config.py"]:::server
        Constants["constants.py"]:::server

        subgraph "Blueprints"
            direction TB
            BaseBP["Base"]:::server
            AdminBP["Administration"]:::server
            AnalysisBP["Analysis"]:::server
            ProjectsBP["Projects"]:::server
            RulesBP["Rules"]:::server
        end
    end

    %% Data Stores
    subgraph "Database & Migrations"
        direction TB
        DB["Relational Database"]:::datastore
        MigrationsDir["migrations"]:::datastore
        AlembicIni["alembic.ini"]:::datastore
        Versions["versions"]:::datastore
    end

    subgraph "Task Queue & Worker"
        direction TB
        Redis["Redis (Broker)"]:::datastore
        Celery["Celery Worker"]:::server
    end

    %% Third-Party Tools
    subgraph "Third-Party Analysis Engines"
        direction TB
        AppInspector["Application Inspector"]:::external
        SCC["SCC (LOC Counter)"]:::external
    end

    %% Artifact Storage
    Storage["Scan Outputs (media/)"]:::datastore

    %% Deployment Orchestration
    DockerCompose["docker-compose.yml"]:::server

    %% Connections
    StaticAssets -->|"Serves UI"| NGINX
    Templates -->|"Serves UI"| NGINX
    NGINX -->|"HTTP"| Gunicorn
    Gunicorn -->|"WSGI"| CoreRun
    CoreRun -->|"Loads"| Init
    CoreRun -->|"Loads"| Config
    CoreRun -->|"Loads"| Constants

    CoreRun -->|"Controller Calls"| BaseBP
    CoreRun -->|"Controller Calls"| AdminBP
    CoreRun -->|"Controller Calls"| AnalysisBP
    CoreRun -->|"Controller Calls"| ProjectsBP
    CoreRun -->|"Controller Calls"| RulesBP

    AnalysisBP -->|"Enqueue Task (AMQP/Redis)"| Redis
    Redis -->|"Pull Task"| Celery
    Celery -->|"CLI Call"| AppInspector
    Celery -->|"CLI Call"| SCC
    Celery -->|"Store Results (SQL)"| DB
    Celery -->|"Store Files"| Storage

    CoreRun -->|"Query/Write (SQL)"| DB
    CoreRun -->|"Read Results"| DB

    DockerCompose --> NGINX
    DockerCompose --> Gunicorn
    DockerCompose --> Redis
    DockerCompose --> DB
    DockerCompose --> Celery

    %% Click Events
    click StaticAssets "https://github.com/orange-cyberdefense/grepmarx/tree/main/app/base/static"
    click Templates "https://github.com/orange-cyberdefense/grepmarx/tree/main/app/base/templates"
    click NGINX "https://github.com/orange-cyberdefense/grepmarx/blob/main/nginx/grepmarx.conf"
    click GunicornCfg "https://github.com/orange-cyberdefense/grepmarx/blob/main/gunicorn-cfg.py"
    click Supervisor "https://github.com/orange-cyberdefense/grepmarx/blob/main/supervisord.conf"
    click SupervisorDocker "https://github.com/orange-cyberdefense/grepmarx/blob/main/supervisord-docker.conf"
    click Procfile "https://github.com/orange-cyberdefense/grepmarx/tree/main/Procfile"
    click Entrypoint "https://github.com/orange-cyberdefense/grepmarx/blob/main/entrypoint.sh"
    click Dockerfile "https://github.com/orange-cyberdefense/grepmarx/tree/main/Dockerfile"
    click Runtime "https://github.com/orange-cyberdefense/grepmarx/blob/main/runtime.txt"
    click CoreRun "https://github.com/orange-cyberdefense/grepmarx/blob/main/run.py"
    click Init "https://github.com/orange-cyberdefense/grepmarx/blob/main/app/__init__.py"
    click Config "https://github.com/orange-cyberdefense/grepmarx/blob/main/app/config.py"
    click Constants "https://github.com/orange-cyberdefense/grepmarx/blob/main/app/constants.py"
    click BaseBP "https://github.com/orange-cyberdefense/grepmarx/tree/main/app/base"
    click AdminBP "https://github.com/orange-cyberdefense/grepmarx/tree/main/app/administration"
    click AnalysisBP "https://github.com/orange-cyberdefense/grepmarx/tree/main/app/analysis"
    click ProjectsBP "https://github.com/orange-cyberdefense/grepmarx/tree/main/app/projects"
    click RulesBP "https://github.com/orange-cyberdefense/grepmarx/tree/main/app/rules"
    click MigrationsDir "https://github.com/orange-cyberdefense/grepmarx/tree/main/migrations"
    click AlembicIni "https://github.com/orange-cyberdefense/grepmarx/blob/main/migrations/alembic.ini"
    click Versions "https://github.com/orange-cyberdefense/grepmarx/tree/main/migrations/versions"
    click Celery "https://github.com/orange-cyberdefense/grepmarx/blob/main/app/celery_worker.py"
    click AppInspector "https://github.com/orange-cyberdefense/grepmarx/tree/main/app/third-party/app-inspector"
    click SCC "https://github.com/orange-cyberdefense/grepmarx/tree/main/app/third-party/scc"
    click Storage "https://github.com/orange-cyberdefense/grepmarx/tree/main/media"
    click DockerCompose "https://github.com/orange-cyberdefense/grepmarx/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef server fill:#90EE90,stroke:#333,stroke-width:1px
    classDef datastore fill:#F4A460,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
