mitmproxy-plugin

mitmproxy-plugin – это плагин для mitmproxy, позволяющий в реальном времени изменять HTTP-ответы на основе заданных правил (моков). Плагин считывает настройки из файла mocks.json, сопоставляет URL запроса с заданными шаблонами и изменяет ответ (как полностью, так и выборочно) – включая возможность выполнения динамического кода прямо внутри JSON.

---

Содержание

• Особенности
• Структура репозитория
• Установка
• Запуск
• Конфигурация и формат mocks.json
• Динамическое выполнение кода
• Как это работает
• Безопасность

---

Особенности

• Перехват и изменение HTTP-ответов согласно заданным правилам.
• Гибкая настройка – можно как полностью заменить тело ответа, так и аккуратно изменить его, объединяя с оригинальными данными (опция «soft»).
• Поддержка динамического выполнения Python-кода в JSON (через специальный префикс code::), что позволяет, например, генерировать случайные значения прямо при обработке ответа.
• Нормализация URL. Плагин заменяет цифровые значения в частях URL на специальный символ (ID), что упрощает сопоставление и именование сохранённых файлов.
• Опциональное сохранение перехваченных ответов в виде файлов JSON для последующего анализа (папка responses_collection).

---

Структура репозитория

Репозиторий имеет следующую структуру:

mitmproxy-plugin/
├── responses_collection/   # Папка для сохранения ответов (если включена опция COLLECT_RESPONSES)
├── default_mocks.json      # Пример (демо) файла с настройками моков
├── mocks.json              # Файл с актуальными данными моков, используемый плагином
└── mocker.py               # Исходный код плагина для mitmproxy

---

Установка

1. Убедитесь, что установлена версия Python 3.9 или выше.

2. Установите mitmproxy с помощью pip:

   (на Windows или Linux)

   pip install mitmproxy

   или

   ---

   pip3 install mitmproxy

---

Запуск

Чтобы запустить mitmproxy с данным плагином, выполните следующую команду в терминале:

---

mitmproxy --scripts /путь/к/mitmproxy-plugin/mocker.py

При необходимости можно добавить опцию для ограничения прослушиваемых хостов, например:

---

mitmproxy --allow-hosts "example.com" --scripts /путь/к/mitmproxy-plugin/mocker.py

После запуска плагин автоматически будет отслеживать HTTP-запросы и ответы, изменяя ответы согласно правилам, заданным в файле mocks.json.

---

Конфигурация и формат mocks.json

Файл mocks.json содержит основную конфигурацию для работы плагина и состоит из двух частей:

1. variables – глобальные переменные для настройки поведения
2. folders – набор папок, каждая из которых может содержать один или несколько моков

Пример структуры mocks.json

{
  "variables": {
    "globalUseNormalizedIds": true,
    "globalFindExactPath": false,
    "globalSkippedMocksLoggingEnabled": true
  },
  "folders": {
    "my_mocks_folder": {
      "isFolderActive": true,
      "mocks": {
        "my-first-mock-data": {
          "isMockActive": true,
          "url": "/api/path/method?param1=foo&param2=123",
          "statusCode": 200,
          "useNormalizedIds": true,
          "findExactPath": true,
          "shouldApplyChangesSoftly": false,
          "changes": {
            "data": {
              "userInfo": {
                "id": 1,
                "username": "test_user_123"
              },
              "anotherUsefulData": {
                "egg": "foo",
                "important": true
              }
            }
          }
        },
        "disabled-example-mock-data": {
          "isMockActive": false,
          "url": "/api/path/anotherMethod",
          "statusCode": 200,
          "useNormalizedIds": false,
          "findExactPath": true,
          "shouldApplyChangesSoftly": false,
          "changes": {
            "data": {
              "userInfo": {
                "id": 2,
                "username": "test_user_123456"
              },
              "anotherUsefulData": {
                "egg": "foo2",
                "important": false
              }
            }
          }
        }
      }
    },
    "my-next-folder": {
      "isFolderActive": false,
      "mocks": {}
    },
    "namingStyle-is_your_choice": {
      "isFolderActive": false,
      "description": "this description key will be ignored",
      "mocks": {}
    }
  }
}

Параметры моков

Для каждого мок-объекта можно задавать следующие параметры:

• isMockActive
– включение/выключение конкретного мока;
• url
– URL или его часть, по которой производится срабатывание мока. Если включена опция useNormalizedIds, числовые сегменты URL будут заменены на ID.
• statusCode
– статус-код, который будет установлен для изменённого ответа.
• useNormalizedIds
– если true, то для сопоставления URL будут заменены цифровые части на ID.
• findExactPath
– если true, требуется полное соответствие URL; если false, достаточно, чтобы URL содержал подстроку, указанную в url.
• shouldApplyChangesSoftly
– если true, изменения из mock будут применены «мягко», то есть существующие значения будут обновлены, а отсутствующие добавлены; если false, оригинальный ответ полностью заменяется на заданные данные из changes.
• changes
– объект с изменениями, которые будут внедрены в тело ответа. Возможна поддержка динамического выполнения кода.

Обратите внимание, что файл default_mocks.json приведён лишь как демонстрация примера – фактически используется файл mocks.json.

---

Динамическое выполнение кода

В любое строковое значение внутри раздела changes можно вставить специальный префикс "code::". Если такое значение обнаружено, плагин выполнит указанный за префиксом Python код с помощью функции exec и подставит результат (значение переменной result).

Пример:

"amount": "code::import random; result = random.randint(20, 1000)"

После обработки данный параметр будет заменён на числовое значение, сгенерированное функцией random.randint.

Важно: выполнение кода происходит через exec, поэтому используйте эту возможность только с доверенными данными, чтобы избежать выполнения нежелательного кода.

---

Как это работает

1. При возникновении HTTP-ответа плагин проверяет заголовок content-type. Если значение не входит в список поддерживаемых (например, application/json, text/plain), ответ игнорируется.
2. Для запроса формируется “нормализованный” URL – последние элементы пути, где числовые значения заменены на ID (если это настроено).
3. Плагин загружает настройки из mocks.json и перебирает активные моки, сверяя параметр url (с учетом флагов findExactPath и useNormalizedIds).
4. Если найден подходящий мок: – Изменяется статус-код ответа (на параметр statusCode из конфига).
   – В зависимости от shouldApplyChangesSoftly: • Если false, оригинальный ответ очищается и заменяется на данные из changes. • Если true, данные из changes рекурсивно сливаются с оригинальным JSON. – Обрабатываются все значения (в том числе вложенные), содержащие "code::", – выполняется код, и его результат подставляется вместо исходной строки.
5. Если включена опция COLLECT_RESPONSES, плагин сохраняет JSON-ответы в папку responses_collection с именем, составленным из последних частей URL и кода ответа (например, user_ID__200.json).

---

Безопасность

• Использование динамического выполнения кода через exec может привести к выполнению потенциально опасного кода.
• Рекомендуется использовать данную функцию только с проверенными и доверенными файлами конфигурации.
• Перед использованием в production-среде обязательно проведите аудит мока и протестируйте все сценарии.

---

Вклад и лицензия

Если вы хотите внести изменения или улучшения в проект – буду рад вашим pull request’ам или issues.