burterm/NOTES.md

Заметки по разработке burterm

Чистое описание архитектуры — в ARCHITECTURE.ru.md.

Этот файл — то, что не годится в ARCHITECTURE, потому что описывает не «как устроено», а «почему так вышло» и «на что обратить внимание». Весь код писался в среде без сети и без установленного Go — ни разу не проходил через компилятор.

Реальные баги, найденные и исправленные по ходу разработки

Не гипотетические — конкретные, с объяснением, как нашлись.

• UTF-8 в §маркерах§. Маркер § (U+00A7) — два байта в UTF-8 (0xC2 0xA7). Самая ранняя версия ParseMarkers сравнивала байты напрямую и детектила маркер только по второму байту, оставляя первый (0xC2) мусором в очищенной строке. Баг жил с первого черновика, найден при разработке DetectParamName (умные заготовки payload'ов). Исправлено: сканирование через range по рунам.
• O(N²) в Results. resultsModel на каждый входящий результат атаки заново парсил текст всех полей фильтра и пересобирал весь список отфильтрованных строк через strings.Join. На словаре в миллион строк это останавливало TUI намертво. Исправлено тремя механизмами: кэшированные предикаты (парсятся один раз при изменении текста поля, а не на каждый результат), инкрементальный strings.Builder вместо пересборки списка, дросселированный рендер во viewport по таймеру раз в 300мс — и только для той атаки, что видна на экране.
• MaxIdleConnsPerHost — баг с самого начала, не только для больших словарей. Голый http.Transport даёт дефолт 2 соединения на хост. При Concurrency > 2 (а дефолт формы — 10) большинство воркеров закрывало и переоткрывало TCP/TLS-соединение на каждый запрос вместо переиспользования из пула. Исправлено в engine.New и в spider.New (там клиент был вообще голый — Transport==nil, то есть неявно общий пакетный http.DefaultTransport).
• Прокси не читал тело ответа. Изначальная версия сохраняла только заголовки/статус — без тела полнотекстовый поиск по Project был бы пустым обещанием. Исправлено: io.ReadAll полного тела, капированная копия (8КБ) для хранения, resp.Body восстанавливается через io.NopCloser перед resp.Write() (тело можно прочитать только один раз).
• Утечка горутин при параллельных атаках. Изначально Model хранила один resultsCh/cancel на всё приложение — вторая атака без дожидания первой тихо переключала отслеживание, а горутины первой оставались писать в канал, который больше никто не читает (небуферизованный канал — блокировка навечно). Исправлено переходом на []*attackRun (независимые атаки) и на select с ctx.Done() при записи в out внутри engine.send().
• proxyModel.SetSize вообще не резервировал место под собственные заголовок/футер. View() всегда рисует "Перехвачено: N" + пустую строку сверху и пустую строку + строку подсказки снизу — 4 строки сверх viewport, а SetSize отдавал viewport.Height всю переданную высоту без остатка. Из-за этого вкладка Proxy стабильно вылезала за экран независимо от того, сколько высоты ей давал model.go — сам бюджет внутри файла никогда не учитывал собственный хром. Найдено построчным разбором View(), а не подбором чисел снаружи. Исправлено вычитанием фиксированных 4 строк внутри SetSize.
• comparerModel: SetSize считал раскладку A/B side-by-side (делит ширину пополам через halfWidth), а View() рисовал их друг под другом. Из-за этого реальная высота была примерно вдвое больше того, что закладывал бюджет diff.Height — вкладка Comparer вылезала за экран независимо от общего бюджета высоты. Исправлено не подгонкой чисел, а починкой самого рассинхрона: View() теперь реально кладёт A и B рядом через lipgloss.JoinHorizontal, как и предполагала раскладка ширины с самого начала.
• Футер Dashboard врал про pgup/pgdn. Подсказка гласила "pgup/pgdn — прокрутка", хотя после того как эти клавиши стали перехватываться глобально под переключение вкладок (см. раздел решений ниже), до viewport они больше не доходят и ничего не прокручивают. Текст поправлен на "↑/↓ — прокрутка".
• Бюджет высоты был неверен на 10 из 12 вкладок одновременно — и по двум независимым причинам. Первая: строки-подсказки в футере доходили до 200+ символов (targetview.go — 425 символов исходно с учётом экранирования, repeater.go — 219) — терминал переносил их сам, а высота этого переноса нигде не учитывалась. Исправлено разбиением каждого длинного футера на гарантированные 2 (иногда 3) строки: специфичные подсказки вкладки отдельно, общая навигация f1-f12, pgup — вкладки отдельно — так поместится в одну физическую строку почти на любом терминале, а не будет угадывания, перенесётся или нет. Вторая причина — независимая от первой: у нескольких вкладок константа вычитания была просто арифметически неверна с самого начала, до всей этой истории с футерами (Fuzzer: -12 вместо нужных -20, Repeater: -2 вместо -8, Decoder/Sequencer: -4 вместо -8/-6, Spider/Project: -6/-8 вместо -11). Обе причины нашлись только построчным подсчётом каждого View() — при этом подсчёте я сам дважды ошибся на лету (Decoder сначала посчитал 5 вместо верных 8) и пересчитывал заново. Итоговые числа для всех 12 файлов сведены в одну таблицу для сверки:

  comparerview.go:  diff.Height = height - inputHeight - 6
  dashboardview.go: vh = height - 3
  decoderview.go:   output.Height = height - inHeight - 8
  fuzzerview.go:    vh = height - 20  (минимум для "чистого" состояния)
  projectview.go:   vh = height - 11
  proxyview.go:     vh = height - 6  (плюс ещё -5 снаружи, в model.go, под "Прокси:...CA:...")
  repeater.go:      response.Height = height - reqHeight - 8
  results.go:       vh = height - 11  (плюс ещё -6 снаружи, в model.go, под заголовок атаки)
  scannerview.go:   vh = height - taHeight - 15 - len(scanner.AllCheckNames())
  sequencerview.go: output.Height = height - inHeight - 6
  spiderview.go:    vh = height - 11
  targetview.go:    vh = height - 13
  

  Request Builder сюда не входит — он не считает высоту viewport по фиксированному бюджету (сайзинг пропорциональный, height/3), так что этот класс бага его не касается, хотя длинный футер разбил и там для единообразия.
• Comparer вылезал за экран ещё дважды после починки JoinHorizontal (сначала -5, потом -6 — оба раза построчный подсчёт по коду казался верным, но на практике не сходилось). Рабочая гипотеза: textarea.View() (компонент bubbles), возможно, рендерит не ровно столько строк, сколько задано через SetHeight — то есть у неё есть какой-то собственный оверхед (рамка/индикатор/что-то ещё), которого нет в исходниках, доступных мне без реального терминала. Это касается не только Comparer — Decoder, Repeater, Scanner, Request Builder тоже используют textarea и МОГЛИ пострадать той же проблемой, просто не в такой явной форме (или ещё не протестированы так тщательно). Для Comparer вместо третьей попытки точного подсчёта поставлен солидный запас (-12 вместо расчётных 6, inputHeight урезан до height/4) — если и остальные текстовые вкладки продолжат вылезать за экран после всех починок из записи выше, это будет подтверждением гипотезы, и той же логике (запас вместо точного числа) нужно последовать и там.

Непроверенные места (порядок — от вероятных проблем к маловероятным)

1. go.mod: modernc.org/sqlite v1.34.4 — версия по памяти, go mod tidy может подтянуть другую, go.sum пересоберётся с нуля.
2. bubbles/bubbletea API — Focus() у textinput/textarea в некоторых версиях возвращает tea.Cmd, в некоторых — нет; сигнатуры spinner.Tick могли измениться между версиями.
3. exitErr.Sys().(syscall.WaitStatus) в internal/fuzzer/fuzzer.go — platform-specific type assertion, работает только на Unix.
4. Гонки данных, не проверенные race detector'ом. Весь проект писался с оглядкой на конкурентный доступ (sync.RWMutex в proxy.Server, независимые снапшоты sitemap.Scope, atomic в счётчиках фаззера), но ни разу не прогонялся под go test -race.
5. pgup (вкладка Fuzzer, единственная за пределами F1-F12 после выделения Steganography/аудио в отдельный проект stegterm) — четвёртая попытка навигации на вкладку, не влезающую в F1-F12 (история первых трёх — в разделе решений ниже). PageUp кодируется терминалом так же атомарно, как F-клавиши (в отличие от Alt+буква, которая на практике расщепляется на ESC+символ) — по конструкции должен быть надёжнее, но конкретно в связке с Zellij ещё не подтверждён.

Сознательно отложенные и оставленные как есть решения

• Навигация на Fuzzer — четыре попытки подряд, есть разобранная причина третьего провала. У физической клавиатуры нет F13/F14, а 13 вкладок в F1-F12 не помещаются (изначально этой проблеме были подвержены сразу две вкладки — Fuzzer и Steganography, — но Steganography с тех пор выделена в отдельный проект stegterm, и сейчас в лишней клавише нуждается только Fuzzer). История:
  1. f13/f14 — не существуют физически, отпало сразу.
  2. shift+f1 — по историческому терминальному соглашению это и есть F13 (kf13 в terminfo), но подтверждённо не сработало в связке с Zellij.
  3. alt+f — подтверждённо не сработало, и в этот раз причина найдена: терминал расщепляет Alt+буква на два отдельных байта (ESC, затем сама буква) вместо единой комбинации. Если между ними случается задержка (обычное дело через мультиплексор/SSH), bubbletea не успевает склеить их обратно и видит одинокую букву — а раз в фокусе текстовое поле (что почти всегда так по умолчанию), эта буква просто печатается как обычный ввод, а не распознаётся как комбинация. F-клавиши от этой болезни не страдают: кодируются терминалом атомарно, не могут расщепиться в печатный символ.
  4. pgup — та же атомарная категория кодирования, что и у F-клавиш, поэтому по конструкции не должен страдать той же болезнью, что Alt-комбинации. Компромисс: viewport (Results, Proxy, Scanner и т.д.) по умолчанию тоже вешает постраничную прокрутку на PageUp — раз эта клавиша перехватывается глобально на уровне корневой модели раньше, чем дойдёт до конкретной вкладки, постраничная прокрутка пропадает везде, остаются только стрелки (построчно). Осознанный выбор: надёжный доступ к вкладке важнее удобства постраничной прокрутки. Не проверено на практике конкретно в связке с Zellij.
• Единая рамка вокруг тела каждой вкладки — откачена. Была попытка обернуть body любой вкладки (кроме Dashboard) в panel() для визуальной консистентности со всем приложением. Дважды подряд не смог вслепую подобрать для неё правильный бюджет высоты: сначала меню обрезалось снизу на нескольких вкладках, потом (после первой попытки исправить) сама рамка вылезала за край экрана на вкладках с длинным содержимым (Comparer, Scanner). Без реального терминала под рукой это угадывание, а не расчёт — после второго провала откатил саму обёртку, а не в третий раз стал подбирать числа. Остались только подтверждённо рабочие вещи: Dashboard со своими собственными панелями и стилизованный таб-бар. Если понадобится вернуться к идее единой рамки на каждой вкладке — делать это нужно с реальным терминалом под рукой для итеративной проверки, не вслепую.
• Плагины. Обсуждалась возможность подключения внешних модулей. Решение: не строить сейчас, направление на будущее — подпроцессы поверх JSON Lines по stdin/stdout (не Go plugin-пакет — хрупкий, требует точного совпадения версии Go; не встроенный Lua — новая непроверяемая зависимость с тем же риском, что и sqlite). Подпроцесс живёт весь прогон (атаку/скан), не спавнится на каждый вызов. Три типа плагинов на будущее: payload-generator, scanner-check, decoder. В коде не реализовано ничего.
• Побочный эффект рекурсии Intruder. У Model изначально было заложено поведение «после старта атаки переключиться на Results» — рекурсия тоже шлёт attackStartedMsg на каждую находку, значит при активной рекурсии с несколькими совпадениями пользователя может несколько раз подряд дёрнуть на вкладку Results. Решение неочевидно (нужно различать «юзер нажал ctrl+r» от «рекурсия сама что-то нашла»), оставлено как есть.
• drainGenerator для Pitchfork/ClusterBomb вычитывает генератор целиком в память перед стартом. Для словарей на миллионы строк — разовая пауза и всплеск памяти перед первым запросом. Не исправлено: риск сломать корректность одометра выше выигрыша.
• Только WAV, не MP3/FLAC. Сознательный выбор, не недоделка: сжатие с потерями убивает мелкую структуру спектра, в которую в CTF прячут сообщения — задачи почти всегда именно в PCM WAV.
• Поля "второе изображение"/"длина LSB" видны и в аудио-режиме вкладки Steganography, хотя там ничего не делают. Условный layout ради их сокрытия усложнил бы View() заметнее, чем стоит того.
• ASCII-логотип не в блочном стиле (как у референсных TUI-инструментов вроде Burp) — сознательно: точная посимвольная геометрия блочных букв без реального терминала для проверки выравнивания легко разъезжается на один символ. Вместо этого — разрядка текста акцентным цветом.
• Заголовки панелей — не врезаны в саму рамку (┌─ TITLE ─┐), а первая строка жирным текстом внутри неё — по той же причине: точная ширина без права на ошибку.

Порядок отладки при первой сборке

1. go mod tidy — разберётся с зависимостями и go.sum.
2. go build ./... — почти наверняка всплывут точечные несовпадения сигнатур bubbles/bubbletea. Правятся по месту, по тексту ошибки.
3. go vet ./... — статический анализ.
4. go run -race ./cmd/burterm — особенно при активном Proxy + одновременной смене scope-правил.
5. Дальше — по вкладкам, от простых к сложным: Decoder/Comparer/Sequencer (чистая логика, без сети) → Repeater (один запрос) → Intruder на маленьком словаре → Proxy → Scanner/Fuzzer последними — там наибольшая оставшаяся неопределённость.