Концепции и архитектура

Рабочие пространства, сессии, Go-бэкенд и взаимодействие компонентов.

Traffic Jam — это три взаимодействующих процесса и одна база данных. Понимание этого разделения — что где выполняется и где хранится состояние — облегчает навигацию по остальной документации.

Три слоя

Слой	Технология	Зона ответственности
Десктопная оболочка	Electron (`electron/main.cjs`)	Запускает Go API и управляет им, выделяет loopback-порт, генерирует capability-токен, отдаёт фронтенд по схеме `traffic-jam://app`
Фронтенд	React + Vite (TypeScript)	Весь UI: библиотека захватов, вкладки анализа, API-лаборатория, диалоги replay. Общается с бэкендом только по HTTP
API-бэкенд	Go (`server/`, сборка через `uber-go/fx`)	Разбор, расшифровка TLS, replay, хранение. Предоставляет JSON REST API по пути `/api`

В упакованном macOS-приложении оболочка запускает встроенный бинарник traffic-jam-api на свободном порту 127.0.0.1. В режиме разработки вы запускаете обе части самостоятельно: npm run dev:api стартует Go на 127.0.0.1:8790, а npm run dev:web — Vite, который проксирует /api на http://127.0.0.1:8790. См. /docs/ru/getting-started/installation/.

Рабочие пространства, сессии и запросы

Модель данных представляет собой небольшую иерархию:

Папка захватов (рабочее пространство) — каталог, который вы регистрируете для организации материалов. Папки могут быть вложенными; сессии размещаются внутри них. Управление — через PUT/PATCH/DELETE /api/folders.
Сессия захвата — один импортированный захват: файл pcap/pcapng (с опциональным TLS keylog) или HAR-файл. Сессия содержит статистику разбора, предупреждения, TLS-отпечатки и восстановленные сертификаты.
Обмен запрос/ответ — одна HTTP-транзакция, восстановленная из захвата: с упорядоченными заголовками, телами, таймингами и TLS-отпечатком соединения (JA3/JA4, шифры, ALPN, SNI).

Фронтенд получает список сессий через GET /api/sessions (только краткие сводки) и лениво подгружает полные детали через GET /api/sessions/{id}. Вкладки рабочего пространства в десктопной оболочке — Captures, Browser capture, Android, API lab, Timeline, Compare, TLS, Workbench — это представления тех же самых данных.

Как фронтенд общается с бэкендом

Каждый вызов проходит через src/shared/api/client.ts, который добавляет префикс apiBaseUrl и, если задан токен, один заголовок:

X-Traffic-Jam-Token: <capability token>

Базовый URL и токен бэкенда берутся из preload-моста Electron (window.trafficJam) в десктопных сборках или из VITE_TRAFFIC_JAM_API_BASE_URL / VITE_TRAFFIC_JAM_API_TOKEN в веб-сборке.

Middleware безопасности API (withAPISecurity в handler.go) выполняет две независимые проверки для каждого запроса:

Белый список origin. Запрос с заголовком Origin должен приходить с разрешённого origin, иначе он отклоняется с HTTP 403. Всегда разрешены: десктопный origin traffic-jam://app, localhost и loopback-адреса (127.0.0.1, ::1). Дополнительные точные origin можно добавить через переменную окружения TRAFFIC_JAM_ALLOWED_ORIGINS со значениями через запятую.
Capability-токен. Если задана TRAFFIC_JAM_API_TOKEN, запрос должен содержать то же значение в X-Traffic-Jam-Token (сравнение выполняется за константное время), иначе он отклоняется с HTTP 401. Автономный dev-API по умолчанию работает без токена; десктопная оболочка при каждом запуске генерирует криптографически случайный 32-байтный токен и передаёт его только своему бэкенду и рендереру.

Переменная окружения (бэкенд)	По умолчанию	Назначение
`TRAFFIC_JAM_ADDR`	`127.0.0.1:8790`	Адрес прослушивания
`TRAFFIC_JAM_API_TOKEN`	не задана (токен не требуется)	Capability-токен; пустое значение отключает проверку
`TRAFFIC_JAM_ALLOWED_ORIGINS`	не задана	Дополнительные точные браузерные origin помимо loopback/десктопных
`TRAFFIC_JAM_DB_PATH`	`.traffic-jam/traffic-jam-v2.sqlite3`	Файл базы данных SQLite
`TRAFFIC_JAM_CAPTURE_DIR`	`.traffic-jam/live-captures`	Каталог артефактов захвата в реальном времени
`TRAFFIC_JAM_MAX_UPLOAD_BYTES`	4 GiB	Ограничение размера загрузки

[!NOTE] API привязывается только к loopback. Это локальный инструмент анализа, а не сетевой сервис; не направляйте TRAFFIC_JAM_ADDR на публичный интерфейс.

Конвейер обработки захватов

Импорт захвата (POST /api/import или /api/import-har для HAR) выполняется целиком внутри процесса — TShark не требуется:

Чтение пакетов. gopacket/pcapgo перебирает содержимое файла pcap/pcapng.
Восстановление TCP-потоков. Сегменты группируются по потокам и переупорядочиваются; пробелы в захвате отмечаются как предупреждения. UDP на портах 443/8443 помечается как QUIC/HTTP3 — такие сессии невозможно расшифровать с помощью TLS keylog.
Расшифровка TLS. Записи TLS 1.2/1.3 расшифровываются ключами из внешнего NSS keylog-файла или из блока Decryption Secrets Block в pcapng. ClientHello/ServerHello разбираются для извлечения JA3/JA4 и сертификатов.
Разбор HTTP. Открытый поток разбирается на обмены запрос/ответ.
Сохранение. Сессия, обмены, отпечатки и сертификаты записываются в SQLite.

При захвате в реальном времени вместо этого запускаются дочерние процессы mitmdump (и tshark для захвата на уровне пакетов); см. /docs/ru/capture/.

Хранение в SQLite

Всё постоянное состояние хранится в одной базе данных SQLite (modernc.org/sqlite, единственное пишущее соединение). Импортированные сессии переживают перезапуски API. Таблицы:

Таблица	Содержимое
`capture_sessions`, `capture_folders`	Импортированные захваты и иерархия их папок
`traffic_exchanges`	Восстановленные пары запрос/ответ
`tls_fingerprints`, `tls_certificates`	Отпечатки ClientHello и восстановленные сертификаты
`replay_history`	Отправленные replay и их ответы
`endpoint_annotations`	Статус проверки, теги и заметки по каждому эндпоинту
`client_certs`	Загруженные клиентские сертификаты mTLS (PEM/PKCS#12)
`decode_scripts`, `decode_pipelines`	Пользовательские скрипты декодирования/кодирования и конвейеры для эндпоинтов
`fingerprint_profiles`, `canary_checks`, `canary_runs`	Версионируемые снимки отпечатков и canary-проверки дрейфа
`protobuf_schemas`, `protobuf_bindings`	Загруженные `.proto`-схемы и привязки к эндпоинтам
`route_model_rules`	Правила моделирования каталога маршрутов

API-лаборатория

API-лаборатория (фича api-re, вкладка рабочего пространства API lab) — это поверхность для реверс-инжиниринга. Она читает выбранные сессии захватов и добавляет поверх них каталог маршрутов, глобальный поиск, анализ сигнатур, конвейеры декодирования, одиночный и массовый replay (бэкенд ограничивает его 50 запросами на пакет), переменные цепочек replay и инструменты для JWT. Replay и его модель безопасности описаны в /docs/ru/replay/; рабочий процесс исследования и находок — в /docs/ru/analysis/ и /docs/ru/security/; экспорт автономного Go-коллектора — в /docs/ru/collector/.

[!WARNING] Такие возможности, как тестовые токены alg=none, A/B replay учётных данных и зондирующие мутации, предназначены для авторизованного тестирования систем, которые вам разрешено оценивать.

Где данные хранятся на диске

Веб/dev: .traffic-jam/traffic-jam-v2.sqlite3 в рабочем каталоге; артефакты захвата в реальном времени — в .traffic-jam/live-captures (или рядом с пользовательской базой данных).
Десктопное приложение: база данных SQLite находится в пользовательском каталоге данных Electron (traffic-jam-v2.sqlite3); открыть его можно через Capture → Open Traffic Jam Data Folder.

Переменные окружения и форматы файлов собраны в /docs/ru/reference/.