# certsocietegenerale/fir architecture

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

- Interactive diagram: https://gitdiagram.com/certsocietegenerale/fir
- Repository: https://github.com/certsocietegenerale/fir

## Overview

##### Project type and purpose
- FIR is a full-stack, monolithic Django web application (Python) for cybersecurity incident management.
- It comprises many loosely coupled “apps” (fir_abuse, fir_alerting, fir_api, fir_artifacts, fir_auth_2fa, etc.) that each implement a distinct feature set (abuse handling, alerting, REST API, artifacts management, 2FA, etc.).
- It’s deployed via Docker (docker-compose), uses Nginx as a reverse proxy, Gunicorn (WSGI) or Django’s wsgi module to serve Python code, MySQL (or any Django-compatible RDBMS) for data persistence, and Celery for asynchronous tasks.

##### File structure for architectural cues
- Top-level “fir” folder: Django project settings, URL routing, WSGI entry-point.
- A set of directories each named fir_<feature>: each is a Django app containing models, views, templates, static assets (js/css), migrations, URLs.
- “fir_api”: the REST API module (serializers, permissions, authentication).
- “fir_celery”: Celery configuration and task definitions (celeryconf.py).
- Docker folder: Dockerfile, docker-compose.yml, environment files, Nginx config.
- “incidents”: the core incident-tracking app with its own URL space, forms, custom authorization backends.
- “uploads”: filesystem storage for user-uploaded files (artifacts).
- requirements.txt for Python dependencies.

##### README for additional insights
- Confirms Django + Bootstrap + Ajax stack.
- Recommends MySQL, but any Django-supported driver works.
- Deployment modes: Docker for quick start; production installation via the wiki.
- Non-greedy resource usage: small VM footprint.

a. Main components
- Client (browser)
- Nginx reverse proxy (docker/nginx.conf)
- Django application (Gunicorn or uWSGI serving the fir WSGI module)
- Django apps modules (e.g., fir_abuse, fir_alerting, fir_api, incidents, etc.)
- Celery worker
- Message broker (Redis or RabbitMQ)
- Database (MySQL)
- Filesystem storage (uploads directory)
- External services: SMTP server for email, LDAP/ OIDC provider for authentication, optional 2FA services

b. Relationships and interactions
- Browser → Nginx (HTTP/HTTPS)
- Nginx → Gunicorn/Wsgi → Django apps
- Django ORM → MySQL
- Django → Celery (enqueue tasks via broker)
- Celery worker ↔ broker ↔ Django tasks → MySQL or file storage
- Django (or Celery) → SMTP (email notifications via fir_email, fir_notifications)
- Django → External auth providers (LDAP, OIDC)
- Static file requests → Nginx directly serves /static and /uploads

c. Architectural patterns / design principles
- Monolithic, modular Django “app” pattern (each feature as an independent app).
- MVC (Django’s MTV) architecture: Models (database schemas), Templates (UI), Views (business logic).
- Plugin/extension pattern: core “fir_plugins” app uses hooks, signals, management commands — enables third-party extensions.
- Asynchronous processing via Celery to offload long-running tasks (email sending, artifact enrichment tasks, notifications).
- Configuration separation: local (base.py, production.py), multiple environments via composeprod.

d. Key technologies/frameworks
- Python 3.x, Django
- Gunicorn or uWSGI (WSGI server)
- Nginx (reverse proxy / static files)
- MySQL (or any Django-compatible RDBMS)
- Celery + broker (Redis/RabbitMQ)
- Docker & Docker Compose
- Bootstrap, jQuery/vanilla Ajax for UI
- LDAP/OIDC backends, 2FA library for authentication

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client"
        Browser["Browser (UI)"]:::frontend
    end

    %% Docker Compose Environment
    subgraph "Docker Compose"
        subgraph "web (Nginx + Gunicorn)"
            Nginx["Nginx Reverse Proxy"]:::backend
            Gunicorn["Gunicorn/WSGI Server"]:::backend
            Nginx -->|"WSGI"| Gunicorn
            click Nginx "https://github.com/certsocietegenerale/fir/blob/master/docker/nginx.conf"
            click Gunicorn "https://github.com/certsocietegenerale/fir/blob/master/fir/wsgi.py"
        end

        subgraph "db (MySQL)"
            MySQL["MySQL Database"]:::datastore
        end

        subgraph "broker (RabbitMQ/Redis)"
            Broker["Message Broker"]:::datastore
            click Broker "https://github.com/certsocietegenerale/fir/blob/master/docker/docker-compose.yml"
        end

        subgraph "worker (Celery)"
            Celery["Celery Worker"]:::backend
            click Celery "https://github.com/certsocietegenerale/fir/blob/master/fir_celery/celeryconf.py"
        end
    end

    %% Core Django Application
    subgraph "Django Application"
        Settings["Project Settings"]:::backend
        URLs["URL Routing"]:::backend
        Manage["manage.py CLI"]:::backend
        Settings --> URLs
        click Settings "https://github.com/certsocietegenerale/fir/blob/master/fir/config/base.py"
        click URLs "https://github.com/certsocietegenerale/fir/blob/master/fir/urls.py"
        click Manage "https://github.com/certsocietegenerale/fir/blob/master/manage.py"

        subgraph "Django Apps"
            incidents["incidents"]:::backend
            abuse["fir_abuse"]:::backend
            alerting["fir_alerting"]:::backend
            artifacts["fir_artifacts"]:::backend
            artifacts_enrich["Artifact Enrichment"]:::backend
            api["fir_api"]:::backend
            auth2fa["fir_auth_2fa"]:::backend
            auth_ldap["fir_auth_ldap"]:::backend
            auth_oidc["fir_auth_oidc"]:::backend
            email["fir_email"]:::backend
            notifications["fir_notifications"]:::backend
            plugins["fir_plugins"]:::backend
            relations["fir_relations"]:::backend
            stats["fir_stats"]:::backend
            threat["fir_threatintel"]:::backend
            todos["fir_todos"]:::backend

            click incidents "https://github.com/certsocietegenerale/fir/tree/master/incidents/"
            click abuse "https://github.com/certsocietegenerale/fir/tree/master/fir_abuse/"
            click alerting "https://github.com/certsocietegenerale/fir/tree/master/fir_alerting/"
            click artifacts "https://github.com/certsocietegenerale/fir/tree/master/fir_artifacts/"
            click artifacts_enrich "https://github.com/certsocietegenerale/fir/blob/master/fir_artifacts_enrichment/tasks.py"
            click api "https://github.com/certsocietegenerale/fir/tree/master/fir_api/"
            click auth2fa "https://github.com/certsocietegenerale/fir/tree/master/fir_auth_2fa/"
            click auth_ldap "https://github.com/certsocietegenerale/fir/blob/master/fir_auth_ldap/backend.py"
            click auth_oidc "https://github.com/certsocietegenerale/fir/tree/master/fir_auth_oidc/"
            click email "https://github.com/certsocietegenerale/fir/tree/master/fir_email/"
            click notifications "https://github.com/certsocietegenerale/fir/tree/master/fir_notifications/"
            click plugins "https://github.com/certsocietegenerale/fir/tree/master/fir_plugins/"
            click relations "https://github.com/certsocietegenerale/fir/tree/master/fir_relations/"
            click stats "https://github.com/certsocietegenerale/fir/tree/master/fir_stats/"
            click threat "https://github.com/certsocietegenerale/fir/tree/master/fir_threatintel/"
            click todos "https://github.com/certsocietegenerale/fir/tree/master/fir_todos/"
        end
    end

    %% Storage and External Services
    subgraph "Storage"
        Uploads["File Upload Storage"]:::datastore
        click Uploads "https://github.com/certsocietegenerale/fir/tree/master/uploads/"
    end

    subgraph "External Services"
        SMTP["SMTP Email Server"]:::external
        LDAP_OIDC["LDAP / OIDC Provider"]:::external
    end

    %% Data Flows
    Browser -->|"HTTP/HTTPS"| Nginx
    Gunicorn -->|"Loads WSGI Module"| Settings
    Gunicorn -->|"Routes Requests"| URLs
    Gunicorn -->|"Invokes Django"| incidents

    incidents -->|"SQL"| MySQL
    abuse -->|"SQL"| MySQL
    alerting -->|"SQL"| MySQL
    artifacts -->|"SQL"| MySQL
    api -->|"SQL"| MySQL
    stats -->|"SQL"| MySQL

    artifacts -->|"Store Files"| Uploads
    Browser -->|"Static/Media Requests"| Nginx

    Gunicorn -->|"Enqueue Tasks (AMQP)"| Broker
    incidents -->|"Enqueue Tasks (AMQP)"| Broker
    alerting -->|"Enqueue Tasks (AMQP)"| Broker
    artifacts_enrich -->|"Process Tasks"| Celery

    Celery -->|"AMQP"| Broker
    Celery -->|"SQL"| MySQL
    Celery -->|"File I/O"| Uploads
    Celery -->|"SMTP"| SMTP

    alerting -->|"SMTP"| SMTP
    email -->|"SMTP"| SMTP
    notifications -->|"SMTP"| SMTP

    auth_ldap -->|"LDAP Auth"| LDAP_OIDC
    auth_oidc -->|"OIDC Auth"| LDAP_OIDC

    %% Styles
    classDef frontend fill:#D6E9FE,color:#000;
    classDef backend fill:#CEE5D0,color:#000;
    classDef datastore fill:#F0E68C,color:#000;
    classDef external fill:#FDEBD3,color:#000;
```
