chrismaddalena/goreportСкрипт на Python для сбора данных о кампаниях из Gophish и формирования отчёта
Этот скрипт принимает идентификатор(ы) вашей кампании Gophish в качестве параметра, а затем собирает результаты кампании для отображения статистики, парсинга user-agent и геолокации IP-адресов. Goreport формирует списки IP-адресов, операционных систем, типов и версий браузеров, а также местоположений с указанием количества, сколько раз каждый из них был замечен в ходе кампании.
Замечание по статистике: Goreport сообщает общее количество событий и количество получателей электронной почты, принявших участие в каждом событии. Иными словами, Goreport покажет, сколько раз Gophish зафиксировал событие «Clicked Link» (переход по ссылке) и сколько получателей перешли по ссылке. Это существенно разные числа. Кампания, отправленная 10 людям, может иметь 9 событий Clicked Link, когда только 3 получателя перешли по ссылке. Знание того, что получатели переходили по ссылке или отправляли данные более одного раза, является ценной информацией, но следите за тем, чтобы не путать эти числа.
Для работы скрипта требуется сервер Gophish, активная или завершенная кампания и API-ключ вашего приложения Gophish. Получите этот ключ, перейдя на вкладку Settings. API-ключ находится на первой странице. Каждая учетная запись пользователя Gophish имеет свой собственный API-ключ, который служит методом аутентификации этого пользователя для Gophish API. Если вы используете несколько учетных записей с Gophish, убедитесь, что вы взяли правильный API-ключ пользователя.
Также необходимы следующие библиотеки Python:
Чтобы начать, вам нужно выполнить несколько действий:
pip install -r requirements.txt.В этом примере предполагается, что Gophish находится на другом сервере и используется HTTPS. Для доступа к API-эндпоинту вам потребуется использовать SSH-туннелирование с перенаправлением порта 3333 (или любого другого локального порта по вашему выбору):
[Gophish]
gp_host: https://127.0.0.1:3333
api_key: <YOUR_API_KEY>
[ipinfo.io]
ipinfo_token: <IPINFO_API_KEY>
[Google]
geolocate_key: <GEOLOCATE_API_KEY>
python3 Goreport.py --id 26 --format excel
Эта команда получит результаты кампании 26 с https://localhost:3333/api/campaigns/26/?api_key=<Your_API_Key> и сохранит их в файл xlsx.
Можно указать несколько идентификаторов одновременно для получения нескольких отчетов. Идентификаторы можно передавать через запятую, в виде диапазона или комбинировать оба способа.
Пример: python3 Goreport.py --id 26,29-33,54 --format csv
Если вы используете несколько учетных записей пользователей Gophish или серверов, у вас будет несколько API-ключей. Чтобы упростить переключение между ключами, опция --config в Goreport позволяет переопределить файл конфигурации по умолчанию (gophish.config) на другой файл с именем, которое вы укажете. Если этот аргумент указан с существующим, читаемым файлом конфигурации, Goreport использует его вместо gophish.config для настройки API-подключений.
Вы можете использовать эту опцию, если у вас, например, три сервера фишинга с запущенным Gophish. Вы можете создать три конфигурационных файла, каждый с разным API-ключом Gophish, и использовать их по мере необходимости.
Пример: python3 Goreport.py --id 26,29-33,54 --format csv --config phish_server_2.config
Если вы запустили несколько кампаний с одинаковыми настройками для разных целевых групп, вы можете запустить Goreport для всех этих кампаний одновременно, а затем объединить результаты в один отчет. Это можно сделать с помощью флага --combine.
Пример: python3 Goreport.py --id 26,29-33,54 --format excel --combine
Эта команда соберет результаты для кампаний 26, 29, 30, 31, 32, 33 и 54. Обычно Goreport вывел бы семь файлов xlsx, но добавление --combine указывает Goreport объединить результаты и вывести только один отчет, как если бы все они были одной большой кампанией.
Goreport может выводить отчет в виде электронной таблицы Excel (xlsx) или документа Word (docx). Также есть опция «быстрого» отчета. Просто выберите предпочитаемый формат с помощью аргумента командной строки --format, как показано выше в разделе «Пример использования». О формате csv говорить особо нечего.
Документ Word создается на основе шаблона template.docx. Поместите файл шаблона с именем template.docx в каталог Goreport вместе с основным скриптом. Ваш шаблон должен содержать стиль таблицы, который вы хотите использовать, и стили заголовков «Heading 1» и «Heading 2». Назовите предпочитаемый стиль таблицы «Goreport» и настройте стили заголовков 1 и 2 уровней.
Вы можете создать собственный стиль или использовать существующий. Единственное, что важно — чтобы файл template.docx существовал и в нём был стиль таблицы «Goreport».
Чтобы переименовать стиль, щелкните правой кнопкой мыши стиль, выберите «Изменить стиль таблицы» и задайте новое имя.
Опция Excel создает аккуратно отформатированную книгу Excel с несколькими листами для различных наборов результатов и статистики. Это удобный вариант, если вы хотите легко сортировать или фильтровать таблицы результатов.
Наконец, есть опция «quick» (быстрый). Она не создает отчетный документ. Вместо отчета она выводит базовую информацию о кампании в терминал. Это удобно для быстрой проверки хода кампании или просмотра результатов после её завершения.
Если вы хотите установить статус кампании «Complete» (Завершена) при запуске отчета, Goreport может сделать это автоматически с помощью флага --complete. Если указать этот флаг, Goreport через API изменит статус каждого идентификатора кампании на «Complete», чтобы завершить кампанию и обновить её статус в Gophish.
Gophish выполняет собственное геолокационное определение по IP-адресам и возвращает широту и долготу. Это работает неплохо, но может давать сбои и возвращать координаты 0,0 или устаревшую информацию.
Goreport имеет две опции, которые могут улучшить результаты определения местоположения. Первая (рекомендуемая) — это API ipinfo.io. Доступ к API бесплатен при условии, что вы делаете менее 1 000 запросов за 24 часа. Для фишинговой кампании это не должно быть проблемой.
Если в конфигурационный файл добавлен API-ключ ipinfo.io, Goreport автоматически использует ipinfo.io для получения актуальной геолокационной информации для каждого уникального IP-адреса.
Вторая опция — это Google Maps API. Goreport v1.0 использовал Maps API, когда он был бесплатным. Сейчас Google взимает плату в размере $0,005 за запрос к API Geolocate (теперь он так называется). Если вы предпочитаете не использовать ipinfo.io, активируйте Maps Geolocate API в учетной записи Google и добавьте API-ключ в конфигурационный файл Goreport. Затем добавьте флаг --google в команду Goreport, когда захотите, чтобы Goreport использовал API для преобразования координат Gophish в форматированный адрес.
Если вы хотите ознакомиться с кодом, вот базовое описание процесса:
Goreport.py использует Python 3 и библиотеку CLICK (Command Line Interface Creation Kit). При запуске скрипта создается новый объект Goreport. Функция __init__ класса Goreport устанавливает соединение с вашим сервером Gophish, используя предоставленный API-ключ для аутентификации. Затем вызывается функция run().
Функция Run() использует параметры командной строки для запуска построения отчетов. Цикл For проходит по всем идентификаторам кампаний, переданным с помощью --id. Ваш сервер Gophish опрашивается на предмет деталей кампании для каждого отдельного идентификатора.
Сначала вызывается collect_all_campaign_info() для сохранения базовой информации о кампании в переменные. Это включает такие данные, как название кампании, время её запуска, статус, используемый SMTP-сервер, название шаблона и другое.
Во-вторых, вызывается process_timeline_events() для получения модели временной шкалы Gophish для идентификатора. Это включает события, записанные Gophish. Эта функция выполняется второй, потому что она заполняет некоторые списки, которые просматриваются функцией process_results().
В-третьих, вызывается process_results() для получения модели результатов Gophish для идентификатора. Это предоставляет такие данные, как количество целей в кампании.
Goreport использует эти шаги для настройки некоторых списков с целью определения базовых результатов кампании, например, кому было успешно отправлено письмо, какие получатели перешли по ссылке и какие получатели предоставили данные.
Имея такую основу, Goreport может различными способами упорядочивать данные для отчета. В любой момент можно запросить списки, чтобы проверить, присутствует ли определенный адрес электронной почты из модели результатов в списке targets_clicked и, тем самым, подтвердить, перешел ли данный получатель по ссылке. Это затем может инициировать просмотр модели временной шкалы для сбора деталей. Gophish хранит такие детали, как IP-адрес и user-agent, в модели временной шкалы, а базовую информацию — в модели результатов.