How 7h3ram/flowinspect works
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)