Как перехватить HTTPS-трафик и начать работу с Microkoi

01 Установка

Бета-версия работает на macOS 13 и новее, Windows 10 и 11 и на Linux. Регистрация и ключ не нужны.

Бета собрана без платных сертификатов подписи, поэтому при первом запуске система предупредит о неизвестном разработчике. На macOS откройте приложение через правую кнопку и «Открыть», на Windows нажмите «Подробнее» и «Выполнить в любом случае».

02 Рабочее пространство

Всё, что относится к проекту, Microkoi хранит в папке рабочего пространства: запросы, окружения, моки, заметки и перехваченный трафик. При первом запуске откроется приветственный экран.

Удобнее всего открыть папку внутри репозитория проекта: коллекции, окружения, моки, мок-серверы, мониторы и заметки попадут в git, а база с трафиком будет исключена автоматически.

Те же действия есть в меню «Файл»: там же подменю недавних пространств и «Закрыть пространство» (⌘⇧W). Пространство, которое на этом компьютере открывают впервые, показывает полосу с кнопкой «Доверять»: до этого мок-серверы и мониторы из него не запускаются сами.

03 Запуск прокси

Откройте раздел «Трафик» и нажмите «Запустить». Прокси поднимется на адресе 127.0.0.1 и порту 9090 — порт меняется в настройках. Чтобы прокси запускался сам, включите в настройках «Запускать при открытии пространства».

Весь трафик компьютера

Не забудьте выключить системный прокси после отладки: пока Microkoi не запущен, программы, которые идут через него, не смогут выйти в сеть.

Только одна программа

Многие инструменты командной строки и среды разработки читают адрес прокси из переменных окружения. Задайте их в терминале перед запуском программы:

export HTTP_PROXY=http://127.0.0.1:9090
export HTTPS_PROXY=http://127.0.0.1:9090

Программам со своим списком доверенных сертификатов укажите файл сертификата Microkoi явно. Например, для curl:

curl --proxy http://127.0.0.1:9090 \
  --cacert "$HOME/Library/Application Support/Microkoi/Certificates/microkoi-ca.pem" \
  https://api.example.com/v1/users/me

04 Корневой сертификат для HTTPS

Чтобы видеть содержимое защищённых соединений, нужен корневой сертификат. Microkoi создаёт его при первом обращении к прокси, и он уникален для вашей установки. Пока сертификат не установлен, HTTPS-запросы видны только по узлу, времени и размеру.

1. На экране трафика нажмите «Установить сертификат».
2. Подтвердите действие так, как просит ваша система: паролем, окном подтверждения или правами администратора.
3. Сертификат Microkoi Root CA появится в хранилище доверенных сертификатов, и программы начнут ему доверять.

На Linux Microkoi дополнительно добавляет сертификат в хранилище браузеров ~/.pki/nssdb, если в системе есть certutil из libnss3-tools. Если доверие нужно на уровне всей системы — например, для служб от другого пользователя, — приложение покажет готовую команду для терминала и кнопку проверки результата.

Удалить сертификат можно в настройках, раздел «Корневой сертификат»: кнопка «Удалить» убирает его из хранилища системы. Соединения с настоящими серверами Microkoi всегда проверяет полностью — режима «доверять всему» нет.

05 Телефон, планшет и эмуляторы

Кнопка «Устройство» на экране трафика открывает пошаговую настройку. Устройство отправляет трафик в Microkoi по Wi-Fi, а обмены появляются в том же списке.

1. Включите «Подключения из локальной сети» в диалоге или в настройках прокси. Пока они разрешены, у прокси на экране трафика стоит пометка «в сети».
2. В настройках Wi-Fi телефона укажите ручной прокси: адрес компьютера в сети и порт из диалога — их можно скопировать.
3. Отсканируйте QR-код или откройте на телефоне http://microkoi.cert: на странице — сертификат и инструкции для iOS и Android.
4. Установите сертификат и включите доверие к нему в настройках телефона. Диалог в Microkoi покажет, что устройство подключилось.

Прокси без авторизации доступен любому устройству этой сети, поэтому включайте подключения из сети только в доверенной сети и на время отладки, а сертификат удаляйте с телефона после отладки.

• Эмулятор Android обращается к компьютеру по адресу 10.0.2.2.
• Симулятор iOS использует сетевые настройки самого компьютера.
• На Android приложения доверяют установленному пользователем сертификату, только если это разрешено в network_security_config их отладочной сборки.

06 Фильтр перехвата

Кнопка с воронкой на панели инструментов трафика открывает фильтр текущего пространства. Узел вне фильтра не расшифровывается: соединение идёт сквозным туннелем, а обмены не записываются. Так банки, почта и приложения с привязкой к сертификату продолжают работать во время отладки.

• api.example.com — только этот узел
• *.example.com — сам домен и все его поддомены
• Можно вставить адрес целиком: https://api.example.com/v1/users превратится в api.example.com

07 Разбор перехваченного

• Поиск работает по адресу, заголовкам и текстовым телам запросов и ответов, фильтры — по классам кода ответа от 2xx до 5xx.
• Кнопка паузы останавливает список, а новые обмены копятся в буфере — их число видно на кнопке.
• Дерево узлов справа фильтрует список щелчком по ветке; повторный щелчок снимает фильтр.
• Панель обмена внизу показывает запрос и ответ рядом. Двойной щелчок по её краю разворачивает панель, Esc возвращает обычную высоту и затем закрывает её.
• Тело ответа копируется одной кнопкой или сохраняется в файл через системный диалог — целиком, даже если на экране показано начало.
• Кнопка «cURL» копирует перехваченный запрос командой для терминала.

08 Точки останова

Точка останова задерживает обмен: запрос — перед отправкой на сервер, ответ — перед отдачей приложению. Пока он стоит, его можно поправить.

1. Нажмите «Остановка» в панели обмена — точка встанет на этот метод, узел и путь, сразу на запрос и ответ. Или добавьте правило в списке «Остановки».
2. Повторите действие в приложении. Когда обмен остановится, поверх экрана откроется редактор.
3. Поправьте метод, адрес, заголовки и тело запроса или код, заголовки и тело ответа.
4. Нажмите «Продолжить» (⌘Enter), «Без изменений» или «Прервать» — тогда приложение получит ответ 502.

Обмен ждёт решения не больше 10 минут, потом продолжается без изменений. Общий выключатель «Останавливать обмены» отключает все точки и отпускает всё, что стоит.

09 Первый запрос в API-клиенте

1. В разделе «Запросы» нажмите «+» на полосе вкладок.
2. Выберите метод и введите адрес. Схему можно не писать: внешние узлы уйдут по HTTPS, localhost — по HTTP.
3. Заполните параметры, заголовки, тело и авторизацию на вкладках редактора.
4. Нажмите ⌘↩, чтобы отправить; повторное нажатие отменяет выполнение.
5. Нажмите ⌘S, чтобы сохранить запрос в коллекцию.

Любой перехваченный обмен открывается в клиенте кнопкой «В запросы», а целую ветку дерева узлов можно сохранить коллекцией кнопкой, которая появляется при наведении.

Команду cURL можно вставить прямо в строку адреса — вкладка заполнится методом, адресом, заголовками и телом. «Импорт cURL» открывает команду новой вкладкой, а «Копировать cURL» собирает команду из запроса с подставленными переменными активного окружения.

10 Окружения и переменные

Окружение — именованный набор переменных. Создайте его в редакторе «Окружения» и выберите на полосе вкладок. Запись {{name}} подставляется в адрес, параметры, заголовки, тело и авторизацию, а переменные могут ссылаться друг на друга.

baseUrl   = {{scheme}}://{{host}}
scheme    = https
host      = api.example.com

GET {{baseUrl}}/v1/orders?requestId={{$uuid}}

Флаг «секрет» скрывает значение в интерфейсе, но не шифрует его на диске. Если окружение лежит в репозитории, значение попадёт в git вместе с ним.

11 Моки

1. Выберите обмен на экране трафика и нажмите «Сделать мок» — или нажмите «+» в разделе «Моки».
2. Проверьте метод, узел и путь. Мок из трафика создаётся выключенным.
3. Задайте код ответа, задержку, заголовки и тело, сохраните ⌘S.
4. Включите мок переключателем. Подменённые обмены помечаются в трафике.

Если подходят несколько моков, срабатывает самый точный: путь без масок важнее пути с масками, указанные узел и метод важнее «любого». Моки работают только для узлов, которые перехватывает фильтр пространства.

12 Мок-серверы

Мок-сервер — отдельный API на своём порту, к которому приложение обращается напрямую, как к бэкенду. В отличие от мока, он работает без прокси.

1. Наведите на узел или ветку пути в дереве трафика и нажмите «Создать мок-сервер из ветки» — или «+» в разделе «Мок-серверы».
2. Проверьте ручки: каждое сочетание метода и пути стало ручкой с последним перехваченным ответом.
3. Включите переключатель «Работает». Сервер поднимется на свободном порту начиная с 9091.
4. Укажите в приложении адрес сервера, например http://127.0.0.1:9091, вместо адреса настоящего API.

• HTTPS работает на том же порту: устройство должно доверять корневому сертификату Microkoi.
• Для телефона включите «Доступ из локальной сети» и используйте адрес компьютера в сети.
• На запрос без подходящей ручки сервер отвечает 404, а во вкладке «Журнал» у такого запроса есть кнопка «Создать ручку».

13 Мониторинг

1. Нажмите значок мониторинга у запроса или папки в дереве коллекций, «В мониторинг» в редакторе запроса или «Мониторинг» в панели обмена.
2. Задайте интервал — от 20 секунд до суток — и условия успеха: код ответа, значение по пути в JSON, текст в теле или заголовок.
3. Пока приложение открыто, монитор проверяется сам. О падении и восстановлении придёт системное уведомление.

«Проверить все» и кнопка проверки у папки опрашивают сразу много мониторов — удобно после выкладки. У неудачной проверки есть кнопка «Обмен»: она открывает полный запрос и ответ.

14 Заметки

В разделе «Заметки» кнопки «Заметка» и «Папка» создают элементы в корне, а кнопки при наведении на папку — внутри неё. Заметки — обычные файлы .md в папке notes, они сохраняются сами.

15 Если что-то не работает