# bol-van/zapret2 architecture

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

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

## Overview

1. Core purpose and shape  
This repository is an autonomous anti-DPI toolkit called zapret2. Its center is a packet-processing engine that intercepts traffic from the OS, inspects packet dissections, and applies obfuscation/desynchronization strategies before forwarding, dropping, or splitting traffic.

2. Two main runtime engines  
There are two primary executables/engines: `nfq2/nfqws` for Linux/BSD-style packet interception through kernel queues/firewall hooks, and a Windows variant built around WinDivert (`nfq2/win.c`, `nfq2/windows/windivert/*`). Both share the same strategy model, but the interception boundary differs by OS.

3. Packet interception boundary  
Traffic enters the system from OS-level plumbing, not from a proxy layer. On Linux/OpenWrt the repo uses nftables/iptables-style NFQUEUE redirection and conntrack-aware filters; on Windows it uses WinDivert filters such as `--wf-tcp-out`, `--wf-udp-in`, and raw filter expressions. This interception layer is meant to keep most packets in the kernel and only hand relevant flows to user space.

4. Engine pipeline in `nfq2`  
The C engine receives packets, classifies them by L7 protocol and payload type, maintains flow state, and builds a structured “dissect” representation. That representation is then passed through one or more Lua desync instances. The engine decides whether to pass, modify, send fragmented variants, or drop the original packet.

5. Lua strategy layer as the main behavior boundary  
The major architectural split is between the C packet engine and the Lua strategy library. `lua/zapret-lib.lua`, `lua/zapret-antidpi.lua`, `lua/zapret-obfs.lua`, and related scripts contain the higher-level anti-DPI tactics, payload generation, and helper functions. The C side provides packet parsing, state tracking, blobs, and sending primitives; Lua expresses strategy logic.

6. Strategy composition model  
Instead of hard-coded “modes”, zapret2 uses chained `--lua-desync` instances inside profiles. Each instance can modify the current dissect, cut itself off after it is no longer useful, and contribute a verdict. Profiles are filtered by protocol, payload type, hostlist membership, and in/out range. This makes the strategy system the core architectural unit rather than a single monolithic firewall rule.

7. Data inputs for obfuscation  
The repo ships many binary payload templates in `files/fake/*` for TLS, HTTP, QUIC, WireGuard, STUN, Discord media discovery, and other protocol signatures. These are loaded as Lua blobs or referenced directly by strategy code. This asset layer is essential because the engine relies on realistic fake packets rather than abstract transforms only.

8. Hostlist and ipset integration  
The `ipset/` directory contains scripts for downloading, building, and maintaining domain/IP lists used for selective targeting or exclusion. These lists feed the engine’s filtering stage so strategies can be applied only to chosen destinations or classes of traffic. This is one of the main policy/data boundaries in the system.

9. OS/service integration and startup  
The `init.d/` tree contains service definitions for OpenWrt, OpenRC, systemd, sysvinit, runit, s6, pfSense, and Windows bundle examples. These are not just installers; they define how the packet engine is brought up, how filters are installed, and how list-update timers/services run. The repo is therefore both an engine and a deployment bundle.

10. Build and packaging architecture  
`Makefile`, `install_*.sh`, `docs/compile/*`, and the OpenWrt packaging subtree show that the project is built for multiple targets: Linux, embedded OpenWrt, and Windows. There is also some platform-specific support code in `nfq2/andr/` and `nfq2/windows/`, indicating cross-compilation and adapter layers rather than a single native target.

11. Protocol handling and support libraries  
Inside `nfq2/` the code is split into protocol parsing, conntrack, packet queues, filtering, timers, helpers, hostlists, ipset handling, gzip, crypto, and randomization. The crypto subdirectory suggests TLS/QUIC-related manipulation support, while `protocol.c`, `desync.c`, and `filter.c` likely form the core packet decision path.

12. External integration points  
The repo does not depend on external DPI services. Its only important external dependencies are OS packet filtering frameworks, WinDivert on Windows, and standard toolchains/libraries for building. That makes the architecture self-contained and primarily edge-deployed.

13. Operational flow to diagram  
A useful diagram would show: OS traffic → firewall/divert filter → engine queue → protocol/payload classification → Lua strategy chain → modified packets sent back to network stack. Side inputs feeding that flow are hostlists/ipsets, blobs/fake payload files, and init/service configuration.

14. What is intentionally not centralized  
There is no single “configuration server” or “policy backend.” Strategy behavior is distributed across Lua scripts, lists, service wrappers, and OS-specific filter definitions. That decentralization is central to the repo’s architecture and is what makes it portable across Linux, embedded routers, BSD, and Windows.

Main entry points: [`nfq2/protocol.c`](https://github.com/bol-van/zapret2/blob/master/nfq2/protocol.c) (Packet core), [`nfq2/win.c`](https://github.com/bol-van/zapret2/blob/master/nfq2/win.c) (win entry), [`nfq2/nfqws.c`](https://github.com/bol-van/zapret2/blob/master/nfq2/nfqws.c) (nfqws), [`Makefile`](https://github.com/bol-van/zapret2/tree/master/Makefile) (Build system)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime engines"]
  node_nfqws["nfqws<br/>C packet engine<br/>[nfqws.c]"]
  node_win["win entry<br/>Windows entry<br/>[win.c]"]
  node_windivert["WinDivert<br/>divert backend<br/>[windivert.h]"]
  node_nfq2_core["Packet core<br/>engine core<br/>[protocol.c]"]
  node_desync["Desync<br/>strategy executor<br/>[desync.c]"]
  node_filter["Flow filter<br/>match engine<br/>[filter.c]"]
end

subgraph group_strategy["Strategy layer"]
  node_lua_bridge["Lua bridge<br/>Lua runtime<br/>[lua.c]"]
  node_lua_lib["Lua lib<br/>Lua helpers<br/>[zapret-lib.lua]"]
  node_lua_antidpi["Anti-DPI<br/>Lua tactics<br/>[zapret-antidpi.lua]"]
  node_lua_obfs["Obfs<br/>Lua payloads<br/>[zapret-obfs.lua]"]
end

subgraph group_policy["Policy inputs"]
  node_hostlist[("Hostlists<br/>target lists")]
  node_listscript["List scripts<br/>list maintenance"]
end

subgraph group_assets["Payload assets"]
  node_fake_assets[("Fake packets<br/>binary templates")]
end

subgraph group_deployment["Deployment"]
  node_init_openwrt["OpenWrt init<br/>service config<br/>[zapret2]"]
  node_init_systemd["systemd units<br/>service config<br/>[zapret2.service]"]
  node_init_windows["Windows filters<br/>service config"]
end

subgraph group_tooling["Tooling"]
  node_makefile["Build system<br/>build config"]
  node_compile_docs["Compile docs<br/>build guidance"]
  node_blockcheck["Blockcheck<br/>diagnostic suite<br/>[blockcheck2.sh]"]
end

node_win -->|"captures traffic"| node_windivert
node_nfqws -->|"drives core"| node_nfq2_core
node_win -->|"shares core"| node_nfq2_core
node_nfq2_core -->|"classifies flows"| node_filter
node_nfq2_core -->|"applies tactics"| node_desync
node_desync -->|"invokes lua"| node_lua_bridge
node_lua_bridge -->|"loads helpers"| node_lua_lib
node_lua_lib -->|"supports"| node_lua_antidpi
node_lua_lib -->|"supports"| node_lua_obfs
node_lua_antidpi -->|"consumes blobs"| node_fake_assets
node_lua_obfs -->|"consumes blobs"| node_fake_assets
node_hostlist -->|"selects targets"| node_filter
node_listscript -->|"updates lists"| node_hostlist
node_init_openwrt -->|"starts engine"| node_nfqws
node_init_systemd -->|"runs service"| node_nfqws
node_init_systemd -.->|"refreshes lists"| node_listscript
node_init_windows -->|"configures filters"| node_win
node_makefile -->|"builds"| node_nfqws
node_makefile -->|"builds"| node_win
node_makefile -.->|"documents"| node_compile_docs
node_blockcheck -.->|"tests engine"| node_nfq2_core
node_blockcheck -.->|"tests tactics"| node_lua_antidpi

click node_nfqws "https://github.com/bol-van/zapret2/blob/master/nfq2/nfqws.c"
click node_win "https://github.com/bol-van/zapret2/blob/master/nfq2/win.c"
click node_windivert "https://github.com/bol-van/zapret2/blob/master/nfq2/windows/windivert/windivert.h"
click node_nfq2_core "https://github.com/bol-van/zapret2/blob/master/nfq2/protocol.c"
click node_desync "https://github.com/bol-van/zapret2/blob/master/nfq2/desync.c"
click node_filter "https://github.com/bol-van/zapret2/blob/master/nfq2/filter.c"
click node_lua_bridge "https://github.com/bol-van/zapret2/blob/master/nfq2/lua.c"
click node_lua_lib "https://github.com/bol-van/zapret2/blob/master/lua/zapret-lib.lua"
click node_lua_antidpi "https://github.com/bol-van/zapret2/blob/master/lua/zapret-antidpi.lua"
click node_lua_obfs "https://github.com/bol-van/zapret2/blob/master/lua/zapret-obfs.lua"
click node_hostlist "https://github.com/bol-van/zapret2/tree/master/ipset"
click node_listscript "https://github.com/bol-van/zapret2/blob/master/ipset/get_antizapret_domains.sh"
click node_fake_assets "https://github.com/bol-van/zapret2/tree/master/files/fake"
click node_init_openwrt "https://github.com/bol-van/zapret2/blob/master/init.d/openwrt/zapret2"
click node_init_systemd "https://github.com/bol-van/zapret2/blob/master/init.d/systemd/zapret2.service"
click node_init_windows "https://github.com/bol-van/zapret2/blob/master/init.d/windivert.filter.examples"
click node_makefile "https://github.com/bol-van/zapret2/tree/master/Makefile"
click node_compile_docs "https://github.com/bol-van/zapret2/blob/master/docs/compile/build_howto_windows.txt"
click node_blockcheck "https://github.com/bol-van/zapret2/blob/master/blockcheck2.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_nfqws,node_win,node_windivert,node_nfq2_core,node_desync,node_filter toneBlue
class node_lua_bridge,node_lua_lib,node_lua_antidpi,node_lua_obfs toneAmber
class node_hostlist,node_listscript toneMint
class node_fake_assets toneRose
class node_init_openwrt,node_init_systemd,node_init_windows toneIndigo
class node_makefile,node_compile_docs,node_blockcheck toneTeal
```

## Components

### Runtime engines

OS-specific packet interception and packet-processing executables.

- [nfqws](https://github.com/bol-van/zapret2/blob/master/nfq2/nfqws.c): C packet engine · Linux/BSD-style engine that receives queued packets, classifies flows, and applies desync actions. · `nfq2/nfqws.c`
- [win entry](https://github.com/bol-van/zapret2/blob/master/nfq2/win.c): Windows entry · Windows-side entrypoint that bridges the shared engine model to WinDivert. · `nfq2/win.c`
- [WinDivert](https://github.com/bol-van/zapret2/blob/master/nfq2/windows/windivert/windivert.h): divert backend · Windows packet interception backend and filter integration. · `nfq2/windows/windivert/windivert.h`
- [Packet core](https://github.com/bol-van/zapret2/blob/master/nfq2/protocol.c): engine core · Shared packet-processing internals: queueing, protocol detection, state tracking, and send/drop decisions. · `nfq2/protocol.c`
- [Desync](https://github.com/bol-van/zapret2/blob/master/nfq2/desync.c): strategy executor · Core decision point that applies obfuscation, fragmentation, and verdict selection. · `nfq2/desync.c`
- [Flow filter](https://github.com/bol-van/zapret2/blob/master/nfq2/filter.c): match engine · Filters flows by protocol, host, payload type, and other profile constraints. · `nfq2/filter.c`

### Strategy layer

Lua-driven anti-DPI behavior and packet obfuscation tactics.

- [Lua bridge](https://github.com/bol-van/zapret2/blob/master/nfq2/lua.c): Lua runtime · Embeds Lua and passes dissected flow state between C packet logic and strategy scripts. · `nfq2/lua.c`
- [Lua lib](https://github.com/bol-van/zapret2/blob/master/lua/zapret-lib.lua): Lua helpers · Shared Lua helpers and blob handling used by strategies. · `lua/zapret-lib.lua`
- [Anti-DPI](https://github.com/bol-van/zapret2/blob/master/lua/zapret-antidpi.lua): Lua tactics · Main anti-DPI strategy scripts that compose desync instances and payload transforms. · `lua/zapret-antidpi.lua`
- [Obfs](https://github.com/bol-van/zapret2/blob/master/lua/zapret-obfs.lua): Lua payloads · Obfuscation-oriented Lua tactics and payload generation helpers. · `lua/zapret-obfs.lua`

### Policy inputs

Hostlists, ipsets, and flow-selection data used to target traffic.

- [Hostlists](https://github.com/bol-van/zapret2/tree/master/ipset): target lists · Domain and IP lists used for inclusion, exclusion, and selective targeting. · `ipset`
- [List scripts](https://github.com/bol-van/zapret2/blob/master/ipset/get_antizapret_domains.sh): list maintenance · Scripts that fetch, build, and refresh ipset and domain lists. · `ipset/get_antizapret_domains.sh`

### Payload assets

Binary templates used to impersonate realistic protocol traffic.

- [Fake packets](https://github.com/bol-van/zapret2/tree/master/files/fake): binary templates · Protocol-shaped binary blobs for TLS, QUIC, WireGuard, HTTP, STUN, and other signatures. · `files/fake`

### Deployment

Service wrappers, init scripts, and platform packaging.

- [OpenWrt init](https://github.com/bol-van/zapret2/blob/master/init.d/openwrt/zapret2): service config · OpenWrt firewall hooks and startup scripts for installing filters and launching the engine. · `init.d/openwrt/zapret2`
- [systemd units](https://github.com/bol-van/zapret2/blob/master/init.d/systemd/zapret2.service): service config · systemd service and timer units for the engine and list updates. · `init.d/systemd/zapret2.service`
- [Windows filters](https://github.com/bol-van/zapret2/blob/master/init.d/windivert.filter.examples): service config · Windows filter examples and bundle guidance for WinDivert-based deployment. · `init.d/windivert.filter.examples`

### Tooling

Build, compile, and diagnostic support utilities.

- [Build system](https://github.com/bol-van/zapret2/tree/master/Makefile): build config · Top-level build orchestration for native, embedded, and Windows targets. · `Makefile`
- [Compile docs](https://github.com/bol-van/zapret2/blob/master/docs/compile/build_howto_windows.txt): build guidance · Platform-specific build instructions and cross-compilation notes. · `docs/compile/build_howto_windows.txt`
- [Blockcheck](https://github.com/bol-van/zapret2/blob/master/blockcheck2.sh): diagnostic suite · Scripted traffic tests and protocol probes used to validate DPI behavior. · `blockcheck2.sh`

## Connections

- win entry → WinDivert: captures traffic · Windows entry uses WinDivert to intercept packets before user-space processing.
- nfqws → Packet core: drives core · The main executable drives the shared packet-processing pipeline.
- win entry → Packet core: shares core · Windows entry reuses the same shared packet engine logic.
- Packet core → Flow filter: classifies flows · Packets are matched against protocol and profile filters before strategy execution.
- Packet core → Desync: applies tactics · Dissected packets are handed to desync logic for modification or drop decisions.
- Desync → Lua bridge: invokes lua · C engine passes dissect state into Lua strategy instances.
- Lua bridge → Lua lib: loads helpers · Lua runtime depends on shared helper functions and blob utilities.
- Lua lib → Anti-DPI: supports · Anti-DPI scripts build on common Lua helpers.
- Lua lib → Obfs: supports · Obfuscation scripts reuse shared Lua primitives.
- Anti-DPI → Fake packets: consumes blobs · Strategies reference realistic fake packet templates for protocol impersonation.
- Obfs → Fake packets: consumes blobs · Obfuscation tactics use binary payload templates and signatures.
- Hostlists → Flow filter: selects targets · Host and IP lists constrain which flows receive anti-DPI treatment.
- List scripts → Hostlists: updates lists · Maintenance scripts fetch and build the policy lists used by the engine.
- OpenWrt init → nfqws: starts engine · OpenWrt service scripts launch the packet engine and install firewall hooks.
- systemd units → nfqws: runs service · systemd units supervise the engine runtime.
- systemd units → List scripts: refreshes lists · Timer/service pair updates targeting lists on a schedule.
- Windows filters → win entry: configures filters · Windows deployment examples define divert filter expressions and startup behavior.
- Build system → nfqws: builds · Top-level build orchestration compiles the Linux/BSD engine.
- Build system → win entry: builds · Top-level build orchestration compiles the Windows entry and related objects.
- Build system → Compile docs: documents · Build instructions describe cross-compilation and packaging targets.
- Blockcheck → Packet core: tests engine · Diagnostic scripts exercise packet handling and desync behavior.
- Blockcheck → Anti-DPI: tests tactics · Protocol probes validate the strategy layer against representative traffic.