# prasro/security_log_analyzer architecture

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

- Interactive diagram: https://gitdiagram.com/prasro/security_log_analyzer
- Repository: https://github.com/prasro/security_log_analyzer

## Overview

##### Project type & purpose (what you’re diagramming)
This is a **single-process Python CLI tool** (not a distributed system) that:
##### Parses them into a structured representation,
3) Runs multiple **threat detectors** (brute force, SQLi, port scan, unauthorized access, etc.),
##### Aggregates findings and metrics,
5) **Generates an HTML report** using **Jinja2 templates**, likely with charts and tables (with **Pandas** used for analysis/aggregation).

##### File structure analysis (map folders → components)
From the tree:

- `main.py`
- Entry point / CLI orchestration. Accepts a log path and runs the pipeline.
- `wrappers/`
- “Glue” / orchestration layer (pipeline stages).
- `wrappers/log_parser.py`: log ingestion + parsing into structured events.
- `wrappers/event_analyzer.py`: likely runs detectors and aggregates results.
- `wrappers/report_gen.py`: prepares data for the report, renders HTML via template.
- `detectors/`
- Independent detection modules (core business logic).
- `access_detect.py`: unauthorized/sensitive resource access detection.
- `brute_force_detect.py`: brute-force & time-window brute-force patterns.
- `sql_injection_detect.py`: SQL injection pattern detection.
- `port_scan.py`: port scanning pattern detection.
- `ip_attack_counts.py`: shared aggregation utilities (counts per IP, etc.).
- `templates/report_template.html`
- Jinja2 HTML template used by report generator.
- `sample_logs/test_log.log`
- Example input.
- `requirements.txt`
- External dependencies (explicitly: Pandas, Jinja2; possibly chart libs).

Architecturally, the key boundary is:
**wrappers = pipeline & integration**, **detectors = pluggable analytical modules**, **templates = presentation**, **main = entrypoint**.

##### What the README implies (important runtime relationships)
- Multiple threat types → detectors likely run **in parallel conceptually** (or sequentially in code) over the same parsed event stream / dataframe.
- HTML report “interactive” with charts → there’s a **render stage** that transforms results into report-ready structures and injects them into `report_template.html`.
- Pandas → likely an internal canonical data structure is a **DataFrame** (or at least intermediate tabular data).

##### CLI / Entry Point
- `main.py`

##### Log Ingestion & Parsing
- `wrappers/log_parser.py`
- Input: `*.log` file path (e.g., `sample_logs/test_log.log`)
- Output: “Parsed Events” (list/dict) and/or **Pandas DataFrame**

##### Event Analysis Orchestrator
- `wrappers/event_analyzer.py`
- Responsibility: call detectors, merge/normalize outputs, compute summaries

##### Detection Modules (Pluggable Detectors)
- `detectors/brute_force_detect.py`
- `detectors/sql_injection_detect.py`
- `detectors/access_detect.py`
- `detectors/port_scan.py`
- `detectors/ip_attack_counts.py` (utility / shared aggregation)
- Output: findings (alerts), per-IP stats, time-series stats, etc.

##### Report Generation
- `wrappers/report_gen.py`
- Inputs: aggregated findings + metrics
- Uses: `templates/report_template.html` (Jinja2)
- Output: `report.html` (or similar) as an artifact

- **Pandas** (data manipulation)
- **Jinja2** (templating)

##### Output Artifact
- “HTML Security Report” (file)

A clean baseline flow:

##### `main.py`
→ calls **Log Parser** (`wrappers/log_parser.py`)
→ returns **Parsed Events / DataFrame**

##### Parsed Events / DataFrame
→ passed into **Event Analyzer** (`wrappers/event_analyzer.py`)

##### Event Analyzer
→ collects **Detector Findings** (alerts + metrics)

##### Aggregated Findings
→ passed to **Report Generator** (`wrappers/report_gen.py`)

##### Report Generator
→ reads **Jinja2 Template** (`templates/report_template.html`)
→ uses **Jinja2** to render
→ produces **HTML Report artifact**

Additionally:

##### Architectural patterns / design principles

- **Pipeline architecture**: Parse → Detect → Aggregate → Render.
- **Plugin-like modular detection**: each detector is an independent module under `detectors/` (easy to extend by adding a new detector file and wiring it in the analyzer).
- **Separation of concerns**:
- Parsing isolated from detection
- Detection isolated from presentation
- Presentation driven by a template

##### Relevant technologies
- Python 3.8+
- Pandas (tabular computation / grouping / aggregation)
- Jinja2 (HTML templating)
- (Optional) “Filesystem I/O” for logs + report output

##### “Separate into as many components as possible” (without overthinking)
To be maximally detailed for this repo, split into these subcomponents inside the pipeline:

- **Log Parser**
- “Reader” (filesystem open/read)
- “Tokenizer/Regex parser” (extract IP, timestamp, endpoint, status, port, etc.)
- “Normalizer” (standard event schema)

- **Analyzer**
- “Detector runner” (invokes detectors)
- “Result normalizer” (common schema for alerts)
- “Aggregator” (summary tables, per-IP counts, time buckets)

- **Detectors**
- Brute force detection
- Time-window brute force detection (if distinct from brute force; README implies both)
- SQL injection detection
- Unauthorized access detection
- Port scanning detection
- Shared IP metrics utility (`ip_attack_counts.py`)

- **Report Generator**
- “Data preparation for template” (tables + chart series)
- “Template render” (Jinja2)
- “Write HTML output”

- Shows runtime pipeline from log file to HTML report, with detectors branching off the analyzer stage.

- `main.py` depends on `wrappers/*`
- `wrappers/event_analyzer.py` depends on `detectors/*`
- `wrappers/report_gen.py` depends on `templates/report_template.html`, Jinja2, and possibly Pandas

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========
    %% Inputs
    %% =========
    LogFile["InputLogFile\n*.log\n(e.g.,test_log.log)"]:::io

    %% =========
    %% CLI / Entry
    %% =========
    subgraph "CLI Layer (single-process Python)"
        Main["CLIEntryPoint\nmain.py\norchestrates pipeline"]:::entry
    end

    %% =========
    %% Wrappers / Pipeline Orchestration
    %% =========
    subgraph "Wrappers (pipeline stages)"
        subgraph "Log Ingestion & Parsing"
            LP["LogParser\nwrappers/log_parser.py\nraw->structured events"]:::stage
            Reader["Reader\nfilesystem open/read\nraw lines"]:::substage
            Tokenizer["Tokenizer/Regex Parser\nextract fields\n(ip,time,endpoint,etc.)"]:::substage
            Normalizer["Normalizer\nstandard event schema\n(DataFrame-ready)"]:::substage
        end

        subgraph "Event Analysis & Aggregation"
            EA["EventAnalyzer\nwrappers/event_analyzer.py\nruns detectors + aggregates"]:::stage
            Runner["DetectorRunner\ninvokes detectors\nfan-out"]:::substage
            ResNorm["ResultNormalizer\ncommon alert schema\nmerge outputs"]:::substage
            Agg["Aggregator\nsummaries + per-IP + time buckets"]:::substage
        end

        subgraph "Report Generation"
            RG["ReportGenerator\nwrappers/report_gen.py\nprepare + render HTML"]:::stage
            Prep["DataPreparation\nreport tables + chart series\ncontext dict"]:::substage
            Render["TemplateRender\nJinja2 render\nHTML string"]:::substage
            WriteOut["WriteOutput\nfilesystem write\nreport.html"]:::substage
        end
    end

    %% =========
    %% Detectors (pluggable modules)
    %% =========
    subgraph "Detectors (pluggable analytical modules)"
        DRoot["DetectorsPackage\ndetectors/\nindependent modules"]:::detectorGroup
        BF["BruteForceDetector\ndetectors/brute_force_detect.py\nlogin bursts/time-window"]:::detector
        SQLi["SQLInjectionDetector\ndetectors/sql_injection_detect.py\npattern-based findings"]:::detector
        Access["AccessDetector\ndetectors/access_detect.py\nunauthorized/sensitive access"]:::detector
        PS["PortScanDetector\ndetectors/port_scan.py\nscan-like behavior"]:::detector
        IPUtil["IPAttackCountsUtil\ndetectors/ip_attack_counts.py\nshared per-IP metrics"]:::utility
    end

    %% =========
    %% Templates & Outputs
    %% =========
    Template["Jinja2Template\ntemplates/report_template.html\nHTML layout"]:::template
    Report["OutputArtifact\nHTML Security Report\nreport.html"]:::io

    %% =========
    %% External Dependencies
    %% =========
    subgraph "External Libraries / Dependencies"
        Pandas["Pandas\nDataFrames + aggregation"]:::lib
        Jinja2["Jinja2\nHTML templating"]:::lib
        Req["Dependencies List\nrequirements.txt"]:::meta
    end

    %% =========
    %% Dataflow (solid)
    %% =========
    LogFile -->|"log_path"| Main
    Main -->|"read+parse"| LP
    LP -->|"raw_log_lines"| Reader
    Reader -->|"tokens/fields"| Tokenizer
    Tokenizer -->|"normalized events"| Normalizer
    Normalizer -->|"parsed_events (DataFrame/list)"| EA

    EA -->|"fan-out events"| Runner
    Runner -->|"events"| BF
    Runner -->|"events"| SQLi
    Runner -->|"events"| Access
    Runner -->|"events"| PS

    BF -->|"findings+metrics"| ResNorm
    SQLi -->|"findings+metrics"| ResNorm
    Access -->|"findings+metrics"| ResNorm
    PS -->|"findings+metrics"| ResNorm

    ResNorm -->|"normalized alerts"| Agg
    Agg -->|"aggregated findings+tables"| RG

    RG -->|"report context"| Prep
    Prep -->|"context dict"| Render
    Template -->|"template source"| Render
    Render -->|"rendered HTML"| WriteOut
    WriteOut -->|"write report"| Report

    %% =========
    %% Internal dependencies (solid for module calls)
    %% =========
    DRoot -->|"contains"| BF
    DRoot -->|"contains"| SQLi
    DRoot -->|"contains"| Access
    DRoot -->|"contains"| PS
    DRoot -->|"contains"| IPUtil

    BF -->|"uses"| IPUtil
    SQLi -->|"uses"| IPUtil
    Access -->|"uses"| IPUtil
    PS -->|"uses"| IPUtil

    %% =========
    %% Library dependencies (dashed)
    %% =========
    LP -.->|"uses"| Pandas
    EA -.->|"uses"| Pandas
    RG -.->|"uses"| Pandas
    Render -.->|"uses"| Jinja2
    Template -.->|"rendered_by"| Jinja2

    Req -.->|"declares"| Pandas
    Req -.->|"declares"| Jinja2

    %% =========
    %% Legend (vertical)
    %% =========
    subgraph "Legend"
        L1["Blue rounded = pipeline stage"]:::stage
        L2["Light-blue = stage subcomponent"]:::substage
        L3["Orange = detector module"]:::detector
        L4["Yellow = shared utility"]:::utility
        L5["Green = template file"]:::template
        L6["Gray doc = filesystem I/O artifact"]:::io
        L7["Purple = external library"]:::lib
        L8["Dark = entry/meta"]:::entry
    end

    %% =========
    %% Click Events (from component_mapping)
    %% =========
    click Main "https://github.com/prasro/security_log_analyzer/blob/main/main.py"
    click LP "https://github.com/prasro/security_log_analyzer/blob/main/wrappers/log_parser.py"
    click EA "https://github.com/prasro/security_log_analyzer/blob/main/wrappers/event_analyzer.py"
    click RG "https://github.com/prasro/security_log_analyzer/blob/main/wrappers/report_gen.py"
    click DRoot "https://github.com/prasro/security_log_analyzer/tree/main/detectors/"
    click BF "https://github.com/prasro/security_log_analyzer/blob/main/detectors/brute_force_detect.py"
    click SQLi "https://github.com/prasro/security_log_analyzer/blob/main/detectors/sql_injection_detect.py"
    click Access "https://github.com/prasro/security_log_analyzer/blob/main/detectors/access_detect.py"
    click PS "https://github.com/prasro/security_log_analyzer/blob/main/detectors/port_scan.py"
    click IPUtil "https://github.com/prasro/security_log_analyzer/blob/main/detectors/ip_attack_counts.py"
    click Template "https://github.com/prasro/security_log_analyzer/blob/main/templates/report_template.html"
    click LogFile "https://github.com/prasro/security_log_analyzer/blob/main/sample_logs/test_log.log"
    click Req "https://github.com/prasro/security_log_analyzer/blob/main/requirements.txt"

    %% =========
    %% Styles
    %% =========
    classDef entry fill:#0B3A5B,stroke:#06263B,stroke-width:2px,color:#FFFFFF
    classDef stage fill:#1F77B4,stroke:#124B73,stroke-width:2px,color:#FFFFFF
    classDef substage fill:#7FBCEB,stroke:#2C6FA1,stroke-width:1.5px,color:#0B1C2A
    classDef detectorGroup fill:#D35400,stroke:#8A3A00,stroke-width:2px,color:#FFFFFF
    classDef detector fill:#F39C12,stroke:#A96500,stroke-width:2px,color:#1D1300
    classDef utility fill:#F7DC6F,stroke:#B7950B,stroke-width:2px,color:#2A2100
    classDef template fill:#2ECC71,stroke:#1E8449,stroke-width:2px,color:#07240F
    classDef io fill:#E5E7EB,stroke:#6B7280,stroke-width:2px,color:#111827
    classDef lib fill:#8E44AD,stroke:#5B2C6F,stroke-width:2px,color:#FFFFFF
    classDef meta fill:#374151,stroke:#111827,stroke-width:2px,color:#FFFFFF
```
