# 7h3ram/flowinspect architecture

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

- Interactive diagram: https://gitdiagram.com/7h3ram/flowinspect
- Repository: https://github.com/7h3ram/flowinspect

## Overview

##### Project type and purpose
- This is an open-source, command-line network traffic inspection tool (“flowinspect”) written in Python.
- It captures or reads packets (via libnids/pynids), reassembles IP/TCP flows, and runs them through one or more inspection engines (regex, fuzzy matching, shellcode emulation, Yara) to detect patterns, malware, exploits, etc.

##### File structure
- Top-level script:
- flowinspect.py – the CLI entry point, argument parsing, orchestrates the pipeline
- Core package:
- core/globals.py – global configuration & constants
- core/functions.py, core/utils.py – shared helper functions
- core/inspector.py – the “flow inspector” module that applies the configured inspection modes in order
- core/iphandler.py – IP defragmentation logic (wrapper around pynids)
- core/tcphandler.py – TCP stream reassembly & flow tracking
- core/udphandler.py – per-packet UDP inspection
- docs/tasks: issues/, todo/ – backlog and contribution pointers

##### README for technical stack
- Packet capture & reassembly: libnids (via Python bindings pynids)
- Inspection modes & libraries:
- RegexEngine: Google RE2 via pyre2 (fallback to Python re)
- FuzzyEngine: fuzzywuzzy
- ShellcodeEmulation: libemu via pylibemu
- YaraEngine: yara-python bindings
- Output modes: console (print, hex, raw, meta), log files, pcap dumps
- CLI options allow BPF filters, match direction (CTS/STC/ANY), multi-match, kill TCP streams, linemode, etc.

##### Main components
a. CLI / Orchestrator (flowinspect.py)
- Parses arguments, selects input (live device or pcap), configures BPF filter, inspection modes, output options.
b. & Preprocessor (pynids/libnids)
- Raw packet sniffing → IP fragmentation → TCP stream reassembly → hands off to IPHandler/TCPHandler/UDPHandler
c. Handlers
- IPHandler: defrag & dispatch to transport layer
- TCPHandler: reassemble streams into flows, manage state, close/reset detection
- UDPHandler: per-packet buffering, flow tracking until exit
d. Flow Inspector (core.inspector)
- Central pipeline: for each flow or packet buffer, apply in order: RegexEngine → FuzzyEngine → LibemuEngine → YaraEngine
- Honors CLI order, directions (CTS/STC/ANY), optimistic first-match or multi-match (–j), limits, offsets/depth
e. Inspection Engines (External Libraries)
- pyre2 (or re), fuzzywuzzy, pylibemu, yara-python
f. Output Manager
- Console dumper (various modes), log writer, optional pcap dumper per flow

##### Relationships and interactions
- Configuration flows from CLI into all downstream modules (handlers, inspector, engines, output)
- Error & status reporting (verbose, statistics) flows back upstream to CLI/console

##### Architectural patterns & design principles
- Modular pipeline / layered architecture: capture → pre-process → inspect → output
- Separation of concerns: each module focuses on one responsibility
- Pluggable inspection engines: easy to add new mode by conforming to an engine interface in core/inspector.py
- Single process, event-driven style (pynids callback model)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Configuration Layer
    subgraph "CLI & Configuration"
        CLI["flowinspect.py"]:::internal
        Globals["Globals & Config"]:::internal
        Functions["Helper Functions"]:::internal
        Utils["Utilities"]:::internal
    end

    %% Capture Layer
    subgraph "Capture Layer"
        Input["Network Interface / PCAP"]:::io
        Libnids["libnids / pynids"]:::external
    end

    %% Handlers Layer
    subgraph "Preprocessor & Handlers"
        IPH["IPHandler (Defragmentation)"]:::internal
        TCPH["TCPHandler (Reassembly)"]:::internal
        UDPH["UDPHandler (UDP Tracking)"]:::internal
    end

    %% Inspection Pipeline
    subgraph "Flow Inspector Pipeline"
        Inspector["Flow Inspector"]:::internal
    end

    %% Engines
    subgraph "Inspection Engines"
        RE["RegexEngine (pyre2)"]:::external
        FZ["FuzzyEngine (fuzzywuzzy)"]:::external
        EMU["ShellcodeEmulation (pylibemu)"]:::external
        YARA["YaraEngine (yara-python)"]:::external
    end

    %% Output Layer
    subgraph "Output Manager"
        Console["Console / Log Output"]:::io
        LogFile["Log Files"]:::io
        PCAPDump["PCAP Dump Files"]:::io
    end

    %% Data & Control Flows
    CLI -->|"configures"| Libnids
    Input -->|"raw packets"| Libnids
    Libnids -->|"IP fragments"| IPH
    IPH -->|"IP packets"| TCPH
    IPH -->|"IP packets"| UDPH
    TCPH -->|"streams (flows)"| Inspector
    UDPH -->|"packet buffers"| Inspector

    Inspector -->|"apply Regex"| RE
    RE -->|"pass to next"| FZ
    FZ -->|"pass to next"| EMU
    EMU -->|"pass to next"| YARA
    YARA -->|"match events"| Inspector

    Inspector -->|"console output"| Console
    Inspector -->|"log entries"| LogFile
    Inspector -->|"pcap dump"| PCAPDump

    Globals --> IPH
    Globals --> TCPH
    Globals --> UDPH
    Globals --> Inspector
    Globals --> Console

    Functions --> IPH
    Functions --> TCPH
    Functions --> UDPH
    Functions --> Inspector
    Functions --> Console

    Utils --> IPH
    Utils --> TCPH
    Utils --> UDPH
    Utils --> Inspector
    Utils --> Console

    %% Click Events
    click CLI "https://github.com/7h3ram/flowinspect/blob/master/flowinspect.py"
    click Globals "https://github.com/7h3ram/flowinspect/blob/master/core/globals.py"
    click Functions "https://github.com/7h3ram/flowinspect/blob/master/core/functions.py"
    click Utils "https://github.com/7h3ram/flowinspect/blob/master/core/utils.py"
    click Inspector "https://github.com/7h3ram/flowinspect/blob/master/core/inspector.py"
    click IPH "https://github.com/7h3ram/flowinspect/blob/master/core/iphandler.py"
    click TCPH "https://github.com/7h3ram/flowinspect/blob/master/core/tcphandler.py"
    click UDPH "https://github.com/7h3ram/flowinspect/blob/master/core/udphandler.py"

    %% Styles
    classDef internal fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef external fill:#ccccff,stroke:#333,stroke-width:1px
    classDef io fill:#ffddaa,stroke:#333,stroke-width:1px
```
