start writing manual.md

docs/manual.md

@@ -0,0 +1,113 @@
+# МАНУАЛ В ПРОЦЕССЕ НАПИСАНИЯ
+
+
+# Введение
+
+zapret2 является пакетным манипулятором, основная задача которого - совершение различных автономных атак на DPI в реальном времени
+с целью преодоления ограничений (блокировок) ресурсов или сетевых протоколов.
+Однако, этим возможности zapret2 не ограничиваются. Архитектура позволяет выполнять и другие виды пакетных манипуляций.
+Например, двусторонняя (клиент+сервер) обфускация протоколов с целью их сокрытия от DPI. Возможны и иные применения.
+
+# Структура проекта
+
+Главный компонент zapret2 - программа nfqws2 (dvtws2 на BSD, winws2 на Windows), написанная на C, которая и является пакетным манипулятором.
+Содержит функции по перехвату пакетов, базовой фильтрации, рапознавания основных протоколов и пейлоадов, поддержки хост и IP листов, автоматических хостлистов
+с распознаванием блокировок, систему множественных профилей (стратегий), возможности по отсылке raw пакетов и другие сервисные функции.
+Однако, там нет никаких возможностей собственно для воздействия на трафик. Это вынесено в код на языке LUA, вызываемый из nfqws2.
+
+Поэтому следующая по важности часть проекта - LUA код. В базовый комплект входит библиотека функций-хелперов `zapret-lib.lua`,
+библиотека программ автономных атак на DPI `zapret-antidpi.lua`, библиотека функций принятия динамических решений (оркестрации) `zapret-auto.lua`.
+Дополнительно присутствует набор тестов C функций `zapret-tests.lua`, средство обфускации wireguard протокола `zapret-wgobfs.lua` и средство записи дампа пакетов в cap файлы `zapret-pcap.lua`.
+
+Функции перенаправления трафика из ядра в Linux возложены на iptables и nftables, в FreeBSD - на ipfw, в OpenBSD - на pf, в Windows - встроены в сам процесс winws2 посредством драйвера windivert.
+Схема перехвата трафика из ядра , nfqws2 и lua код составляют минимально рабочее ядро проекта. Все остальное является дополнительным, второстепенным и опциональным.
+
+Из второстепенных компонент - скрипты запуска под Linux - `init.d`, `common`, `ipset`, `install_easy.sh`, `uninstall_easy.sh` и средство автоматизации тестирования стратегий `blockcheck2`.
+Цель скриптов запуска - согласовать процесс поднятия таблиц и запуск инстансов nfqws2, учесть особенности интеграции в различные дистрибутивы (openwrt, systemd, openrc).
+Дополнительная функция - обеспечить поддержку и согласованное обновление различных листов и загрузку IP листов в пространство ядра - ipset.
+Все это можно сделать при желании и собственными средствами, если так удобнее или функционал скриптов запуска не подходит.
+Скрипты запуска выносят все настройки в файл config, лежащий в корне проекта. Этот конфиг относится только к ним, nfqws2 ничего о нем не знает.
+
+Для обработки листов предусмотрены 2 программы, написанные на C. mdig - многопоточный ресолвер хостлистов неограниченного обьема.
+ip2net - программа для группировки отдельных IP адресов в подсети с целью сокращения их обьема.
+Эти программы испльзуются в скриптах запуска и в blockcheck2.
+
+Скрипты запуска и инсталятор поддерживает установку на любые классические дистрибутивы Linux с systemd или openrc , из прошивок - на openwrt.
+Если система не удовлетворяет указанным требованиям - возможна самостоятельная "доприкрутка" к системе.
+
+MacOS не поддерживается по причине отсутствия подходящего средства перехвата и управления пакетами. Стандартное для BSD средство ipdivert было убрано из ядра производителем.
+
+# Схема обработки трафика
+
+Сети работают с IP пакетами. Поэтому единицей обработки являются именно они. Приемом и отправкой пакетов занимается сетевая подсистема в ядре ОС.
+nfqws2 работает не в ядре (kernel mode), а является процессом пространства пользователя (user mode). Поэтому первая часть процесса обработки состоит
+в передаче пакетов из ядра ОС в процесс nfqws2. Все 4 средства перехвата обладают некоторыми возможностями фильтрации пакетов. Максимальные возможности - в Linux.
+Чем больше на этом этапе будет отсечено ненужного трафика, тем меньше будет нагрузка на процессор, поскольку передача пакетов из ядра в user mode и обратно сопряжена со значительными накладными расходами.
+
+Пакет пришел в nfqws2. Первое, что он делает, это разбирает его по уровням OSI модели - выделяет ip , ipv6, tcp, udp заголовки и поле данных. Это называется диссекцией.
+Результатом диссекции является диссект - представление пакета в виде структур, которые можно адресовать по полям.
+
+Далее задействуется встроенная в nfqws2 подсистема conntrack - система отслеживания потоков поверх отдельно взятых пакетов. 
+Ищется уже имеющаяся запись о соединении на основании данных L3/L4 пакета. Если ее нет - создается. Старые записи, по которым давно нет активности, удаляются.
+conntrack отслеживание логическое направление пакетов в потоке (входящее/исходящее), ведет подсчет количество прошедших пакетов и байт в обе стороны,
+следит за sequence numbers для tcp. Он же используется в случае необходимости сборки сообщений, передаваемых несколькими пакетами.
+
+Сигнатурно определяется тип пейлоада - содержимого отдельно взятого пакета или группы пакетов. На основании типа пейлоада определяется тип протокола
+всего потока, который сохраняется за потоком до конца его существования. В рамках одного соединения могут проходить разные типы пейлоадов.
+Например, протокол потока xmpp обычно несет несколько видов специфических для xmpp сообщений и сообщения, связанные с tls.
+Тип протокола потока xmpp остается, но последующие пакеты получают различные типы пейлоада - как известные, так и неизвестные. Неизвестные пейлоады определяются как тип "unknown".
+
+Если для конкретного пейлоада и типа протокола потока выясняется необходимость реконструкции сообщения из нескольких пакетов, nfqws2 начинает их накапливать в связи с записью в conntrack
+и запрещает их немедленную отправку. После приема всех пакетов сообщения происходит реконструкция и при необходимости дешифровка составного пейлоада.
+Дальнейшие решения принимаются уже на базе полностью собранного пейлоада - reasm или результата сборки и дешифровки - decrypt.
+
+Когда необходимая информация о пейлоаде получена, наступает очередь системы классификации по профилям.
+Профили содержат систему фильтров и команды действия внутри профиля.
+Профили фильтруются по L3 - версия IP протокола, ipset-ы - списки IP адресов, L4 - порты tcp или udp, L6/L7 - тип протокола потока, списки доменов (хостлисты).
+Профили сканируются строго в порядке от первого к последнему. При первом совпадении условий фильтра профиля выбирается этот профиль, а сканирование прекращается.
+Если ни одно из условий не выполнено, выбирается профиль по умолчанию, в котором нет никаких действий.
+
+Все дальнейшие действия выполняются уже в рамках выбранного профиля. Выбранный профиль кэшируется в записи conntrack, поэтому для каждого пакета поиск заново не выполняется.
+Повторный поиск выполняется в случае изменения исходных данных - при обнаружении L7 протокола и при обнаружении имени хоста. В последних случаях производится повторный поиск
+и при необходимости переключение профиля. Таких переключений может быть за соединение до двух, поскольку есть лишь 2 изменяемых параметра.
+
+Профиль выбран. Из чего состоит его содержание, отвечающее за действия ?
+За действия отвечают LUA функции. В профиле их может быть произвольное количество. 
+Каждый вызов LUA функции из профиля называется инстансом. Функция может быть одна, вызовов несколько - с разными параметрами.
+Поэтому и применяется понятие инстанса - экземпляра вызываемой функции, который идентифицируется номером профиля и порядковым номером вызова внутри профиля.
+Инстансы вызываются через параметры `--lua-desync`. Каждый инстанс получает набор произвольных параметров, задаваемых в `--lua-desync`.
+Порядок вызовов имеет принципиальное значение для логики стратегии и выполняется строго в порядке задания параметров `--lua-desync`.
+
+Присутствуют и внутипрофильные фильтры. Их 3 типа - фильтр `--payload` - список принимаемых инстансом пейлоадов, и 2 диапазонных фильтра `--in-range` и `--out-range`,
+позволяющих задать диапазон позиций внутри потока, который интересен для инстанса. Внутрипрофильные фильтры после их определения действуют на все последующие инстансы
+до их переопределения. Главный смысл наличия внутрипрофильных фильтров - сократить число относительно медленных вызовов LUA , принимая максимум решений на стороне C кода.
+
+Пакет пришел в LUA инстанс. Функция имеет 2 параметра - ctx и desync. ctx - это контекст для связи с некоторыми функциями на стороне C кода.
+desync - таблица, содержащая множество параметров обрабатываемого пакета. Прежде всего это диссект - подтаблица `dis`.
+Информация из записи conntrack - подтаблица `track`. Еще целый ряд параметров, который можно увидеть, выполнив `var_debug(desync)` или просто вызвав готовый инстанс `pktdebug`.
+
+Если идет перепроигрывание задержанных пакетов (replay), LUA инстанс получает информацию о номере части, количестве частей исходного сообщения, позиции текущей части,
+reasm или decrypt при наличии.
+
+LUA код может использовать глобальное пространство переменных для хранения данных, не относящихся к конкретному обрабатываемому пакету. Ему доступна таблица `desync.track.lua_state`,
+в которой он может хранить любую информацию, связанную с записью conntrack. При каждом новом пакете потока в LUA выдается одна и та же таблица.
+Таблицу desync можно использовать для генерации и хранения временных данных, актуальных в цепочке обработки текущего пакета.
+Следующие LUA инстансы получают ту же таблицу desync и тем самым могут принимать данные от предыдущих инстансов.
+
+LUA инстанс может создавать копии текущего диссекта, вносить в них изменения, генерировать собственные диссекты, отправлять их через вызовы C кода.
+Итогои работы каждого инстанса является вердикт - VERDICT_PASS - не делать ничего с текущим диссектом, VERDICT_MODIFY - в конце всей цепочки отослать модифицированное содержимое диссекта,
+VERDICT_DROP - дропнуть текущий диссект. Вердикты всех инстансов аггрегируются - MODIFY замещает PASS, а DROP замещает и PASS, и MODIFY.
+
+LUA инстанс может сам себя отключить от получения дальнейших пакетов потока по направлению in/out - это назвается instance cutoff.
+Может отключить направление in/out текущего потока от всей LUA обработки - lua cutoff.
+Может запросить отмену всей дальнейшей цепочки вызовов LUA инстансов по текущему диссекту. Инстанс, принимающий такое решение, берет на себя функцию координации дальнейших действий.
+Такой инстанс называется оркестратором. Он получает от C кода план дальнейшего выполнения со всеми фильтрами профиля и параметрами вызова всех оставшихся инстансов
+и сам принимает решения когда и при каких условиях их вызывать или не вызывать, менять их параметры. Так реализуются динамические сценарии без модификации основных составлящих кода стратегии.
+Например, определение блокировки ресурса и смена стратегии, если предыдущая не сработала.
+
+Если все инстансы текущего профиля вошли в состояние cutoff по текущему потоку, либо текущая позиция потока находится за верхней границей range фильтров, значит по этому потоку больше не будет LUA
+вызовов. C код помечает такие потоки специальным признаком "lua cutoff", который проверяется максимально быстро без вызовов кода LUA. Тем самым экономятся ресурсы процессора.
+
+После выполнения всей цепочки инстансов профиля C код получает итоговый вердикт - что делать с текущим диссектом. Отправить как есть, отправить модифицированный вариант или дропнуть.
+
+В конце nfqws2 переходит к ожиданию следующего пакета, и цикл повторяется вновь.