# bol-van/zapret architecture

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

- Interactive diagram: https://gitdiagram.com/bol-van/zapret
- Repository: https://github.com/bol-van/zapret

## Overview

##### Main Project Type and Purpose
- The project is a network-level DPI circumvention toolset. Its purpose is to “fool” or desynchronize deep packet inspection devices by modifying packet streams.
- It supports embedded devices (e.g., routers running OpenWrt), conventional Linux systems, Windows, and even BSD/macOS. The README details advanced methods (fake packets, segmentation, TCP sequence manipulation, etc.) that make it clear the project is about actively “dodging” censorship and DPI tactics.

##### Recognize the Main Components from the File Structure
- Daemons and core utilities:
– nfqws: The daemon using NFQUEUE to intercept and modify packets in real time using multiple desynchronization modes.
– tpws: A transparent TCP proxy daemon that also applies segmentation and various “tampering” techniques on TCP flows.
– ip2net: A utility written in C for summarizing individual IP addresses into aggregated network prefixes (to optimize IP list sizes).
– mdig: A multi-threaded DNS resolver that supports bulk resolution for host-based filtering.
- Common Scripts and Libraries:
– The “common” directory holds shared shell scripts (for logging, configuration, process elevation, etc.) that underpin the operation of both nfqws and tpws.
- Configuration & Initialization:
– Files such as “config.default”, “Makefile”, and various init.d folders (with examples for different platforms like linux (sysv, systemd), OpenWrt, macOS) indicate that the project is intended to be deployed in a variety of environments. These scripts not only start/stop the daemons but also set up the underlying network interception rules (using iptables or nftables).
- Documentation:
– The extensive README (multilanguage version) and additional docs (bsd.*, windows.*, quick_start.md) provide details on usage, configuration options and technical strategies.

##### Relationships and Flows
- Data Flow:
– Incoming network traffic from clients is intercepted by firewall rules (either iptables or nftables) and steered toward one of the two daemons.
▸ nfqws functions by hooking into the NFQUEUE to modify packets (applying DPI desynchronization techniques) before the rest of the networking stack processes them.
▸ tpws works as a transparent proxy on TCP streams by “splitting” requests and manipulating TCP segments.
– After processing, these modified packets are released back into the normal network path, with the aim being that DPI devices see modified (or “desynchronized”) traffic that does not trigger censorship.
- Control Flow:
– Configuration files (e.g., config.default) and custom initialization scripts determine which strategies are active (for example, which combination of fake packet injection, TCP split, and header modifications are used).
– Host- and IP-based filtering is supported by additional utilities (mdig for DNS resolutions; ip2net for summarizing IP lists) which feed into firewall rules and into the daemons via parameters like “--hostlist”.
- External Dependencies:
– The system depends on underlying kernel capabilities and networking subsystems: NFQUEUE, iptables/nftables, and conntrack.
▸ The design clearly maps out the separation between user mode daemons (nfqws and tpws), the firewall interception layer, and supporting utilities that prepare host/IP lists.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Network Layer
    A["Clients & External Network"]:::external

    %% Firewall / Network Interception Layer
    F["Firewall (iptables/nftables)"]:::firewall

    %% Configuration & Initialization Layer
    subgraph "Configuration & Initialization"
        CF["config.default"]:::config
        MF["Makefile"]:::config
        ID["init.d"]:::config
        CConfig["Config & Init Scripts"]:::config
    end

    %% Common Scripts & Libraries
    CS["Common Scripts & Libraries"]:::common

    %% Supporting Utilities Layer
    subgraph "Supporting Utilities"
        I2["ip2net"]:::utility
        MD["mdig"]:::utility
    end

    %% User-space Daemons Layer
    subgraph "User-space Daemons"
        N["nfqws"]:::daemon
        T["tpws"]:::daemon
    end

    %% nfqws Source Files (internal details)
    N1["nfqws.c"]:::daemon
    N2["nfqws.h"]:::daemon
    N --> N1
    N --> N2

    %% tpws Source Files (internal details)
    T1["tpws.c"]:::daemon
    T2["tpws.h"]:::daemon
    T --> T1
    T --> T2

    %% mdig Source File detail
    MD1["mdig.c"]:::utility
    MD --> MD1

    %% Data Flow Connections
    A -->|"TrafficIntercepted"| F

    %% Firewall directs traffic to Daemons
    F -->|"NFQUEUEhook"| N
    F -->|"TCPintercept"| T

    %% Configuration flows to Firewall and Daemons
    CConfig -->|"SetsRules"| F
    CConfig -->|"ConfigsDaemon"| N
    CConfig -->|"ConfigsDaemon"| T

    %% Common Scripts support Daemons
    CS -->|"SharedCode"| N
    CS -->|"SharedCode"| T

    %% Supporting Utilities provide data to Config
    I2 -->|"IPLists"| CConfig
    MD -->|"DNSInfo"| CConfig

    %% Click Events
    click N "https://github.com/bol-van/zapret/tree/master/docs/compile/openwrt/package/zapret/nfqws/"
    click N1 "https://github.com/bol-van/zapret/blob/master/nfq/nfqws.c"
    click N2 "https://github.com/bol-van/zapret/blob/master/nfq/nfqws.h"

    click T "https://github.com/bol-van/zapret/tree/master/docs/compile/openwrt/package/zapret/tpws/"
    click T1 "https://github.com/bol-van/zapret/blob/master/tpws/tpws.c"
    click T2 "https://github.com/bol-van/zapret/blob/master/tpws/tpws.h"

    click I2 "https://github.com/bol-van/zapret/blob/master/ip2net/ip2net.c"
    click MD "https://github.com/bol-van/zapret/tree/master/docs/compile/openwrt/package/zapret/mdig/"
    click MD1 "https://github.com/bol-van/zapret/blob/master/mdig/mdig.c"

    click CS "https://github.com/bol-van/zapret/tree/master/common/"
    click CF "https://github.com/bol-van/zapret/blob/master/config.default"
    click MF "https://github.com/bol-van/zapret/tree/master/Makefile"
    click ID "https://github.com/bol-van/zapret/tree/master/init.d/"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef firewall fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef daemon fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef utility fill:#FFA07A,stroke:#CD5C5C,stroke-width:2px;
    classDef config fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef common fill:#DDA0DD,stroke:#800080,stroke-width:2px;
```
