# paresh2806/pcap-analyzer architecture

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

- Interactive diagram: https://gitdiagram.com/paresh2806/pcap-analyzer
- Repository: https://github.com/paresh2806/pcap-analyzer

## Overview

##### Project type and purpose
- This is a single‐container, full-stack Python application with a Streamlit-based frontend and a modular backend for PCAP parsing and analysis.
- Its purpose is to load PCAP files, decode and filter network traffic, perform protocol‐level and geo-IP analysis, and present interactive visualizations.

##### File structure
- Top-level files:
- app.py – Streamlit app entry point (UI layer)
- main.py – secondary entry or orchestration script
- requirements.txt – Python dependencies
- .devcontainer/ – development environment config
- JupyterNotebook.ipynb – exploratory analysis notebook
- Directories:
- utils/ – core backend modules
– data_extract.py, file_extract.py – raw data ingestion
– pcap_decode.py, pcap_filter.py – decoding & filtering pipeline
– proto_analyzer.py, flow_analyzer.py – protocol/flow analysis
– ipmap_tools.py, GeoIP/GeoLite2-City.mmdb – geo-IP lookup
– packet_fake.py – synthetic packet generator
– upload_tools.py – file-upload handling
– protocol/ & warning/ – rule/config repositories for decoders and alerts
- images/ – demo assets and screenshots
- sample/ftp*.pcap – example PCAP files

##### README for additional insights
- Confirms use of Python 3.10 and Streamlit
- Highlights interactive loading, filtering, visualization, and support for many protocols
- No external microservices; all analysis is local

##### Components and relationships
a. Main components:
- Streamlit UI (app.py)
- Upload Service (utils/upload_tools.py)
- File Extraction & Ingestion (file_extract.py)
- Decode & Filter Pipeline (pcap_decode.py → pcap_filter.py)
- Analysis Modules (proto_analyzer.py, flow_analyzer.py, ipmap_tools.py + GeoIP DB)
- Rule Configs (utils/protocol/, utils/warning/)
- Visualization & Reporting (Streamlit components in app.py)
- Data Store (GeoLite2-City.mmdb)
- Example PCAP Data (sample.pcap, ftp-data.pcap)
b. Data flow & interactions:
1. User uploads PCAP via UI → upload_tools
2. file_extract reads raw bytes → pcap_decode parses packet headers/payloads
3. pcap_filter applies user-driven filters
4. proto_analyzer & flow_analyzer compute protocol stats and session flows
5. ipmap_tools queries GeoIP DB for locations
6. Warning engine consults warning rules to flag anomalies
7. Results are piped back to Streamlit for tables, charts, and geo-plots
c. Architectural patterns/design principles:
- Pipeline pattern: clear, linear stages of ingestion → decode → filter → analyze → display
- Modular layering: each analysis concern lives in its own module under utils/
- Configuration-as-code: protocol and warning definitions externalized in subfolders
- Single container deployment: all components run in the same Python process
d. Key technologies:
- Python 3.10, Streamlit
- pandas, scapy or pyshark (in requirements.txt) for PCAP handling
- MaxMind GeoLite2 (MMDB file)
- Custom rule-sets in utils/protocol and utils/warning

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (Streamlit)"
        UI["Streamlit UI"]:::frontend
        ORCH["Orchestration Script"]:::frontend
    end

    subgraph "Data Pipeline"
        UP["Upload Service"]:::pipeline
        EXTRACT["File Extraction & Ingestion"]:::pipeline
        DECODE["Decode Pipeline Stage"]:::pipeline
        FILTER["Filter Pipeline Stage"]:::pipeline
    end

    subgraph "Analysis Engine"
        PROTO["Protocol Analysis Module"]:::analysis
        FLOW["Flow Analysis Module"]:::analysis
        GEOIPTOOL["Geo-IP Lookup Tools"]:::analysis
        RULES["Warning Engine"]:::analysis
    end

    GEOIPDB["GeoLite2 Data Store"]:::datastore

    subgraph "Configurations"
        PROTCONF["Protocol Decoder Configurations"]:::config
        WARNCONF["Warning/Alert Rule Configurations"]:::config
    end

    subgraph "Sample PCAP Data"
        SAMP["sample.pcap"]:::external
        FTP1["ftp-data.pcap"]:::external
        FTP2["ftp3.pcap"]:::external
    end

    UI -->|uploads PCAP| UP
    ORCH -->|triggers pipeline| UP
    UP -->|raw bytes| EXTRACT
    EXTRACT -->|parsed data| DECODE
    DECODE -->|decoded packets| FILTER
    FILTER -->|filtered packets| PROTO
    FILTER -->|filtered packets| FLOW
    PROTO -->|protocol stats| RULES
    FLOW -->|flow sessions| RULES
    PROTO -->|requests geo lookup| GEOIPTOOL
    FLOW -->|requests geo lookup| GEOIPTOOL
    GEOIPTOOL -->|geo-enriched records| RULES
    RULES -->|warnings & analytics| UI

    SAMP --> UP
    FTP1 --> UP
    FTP2 --> UP

    PROTCONF --> PROTO
    WARNCONF --> RULES
    GEOIPDB --> GEOIPTOOL

    click UI "https://github.com/paresh2806/pcap-analyzer/blob/master/app.py"
    click ORCH "https://github.com/paresh2806/pcap-analyzer/blob/master/main.py"
    click UP "https://github.com/paresh2806/pcap-analyzer/blob/master/utils/upload_tools.py"
    click EXTRACT "https://github.com/paresh2806/pcap-analyzer/blob/master/utils/file_extract.py"
    click DECODE "https://github.com/paresh2806/pcap-analyzer/blob/master/utils/pcap_decode.py"
    click FILTER "https://github.com/paresh2806/pcap-analyzer/blob/master/utils/pcap_filter.py"
    click PROTO "https://github.com/paresh2806/pcap-analyzer/blob/master/utils/proto_analyzer.py"
    click FLOW "https://github.com/paresh2806/pcap-analyzer/blob/master/utils/flow_analyzer.py"
    click GEOIPTOOL "https://github.com/paresh2806/pcap-analyzer/blob/master/utils/ipmap_tools.py"
    click GEOIPDB "https://github.com/paresh2806/pcap-analyzer/blob/master/utils/GeoIP/GeoLite2-City.mmdb"
    click PROTCONF "https://github.com/paresh2806/pcap-analyzer/tree/master/utils/protocol/"
    click WARNCONF "https://github.com/paresh2806/pcap-analyzer/tree/master/utils/warning/"
    click SAMP "https://github.com/paresh2806/pcap-analyzer/blob/master/sample/sample.pcap"
    click FTP1 "https://github.com/paresh2806/pcap-analyzer/blob/master/sample/ftp-data.pcap"
    click FTP2 "https://github.com/paresh2806/pcap-analyzer/blob/master/sample/ftp3.pcap"

    classDef frontend fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef pipeline fill:#ABEBC6,stroke:#196F3D,color:#0B5345;
    classDef analysis fill:#F5B041,stroke:#B9770E,color:#6E2C00;
    classDef datastore fill:#A569BD,stroke:#6C3483,color:#512E5F,shape:cylinder;
    classDef config fill:#D5DBDB,stroke:#7F8C8D,color:#17202A;
    classDef external fill:#CACFD2,stroke:#566573,color:#1C2833;
```
