GitMiner3

• Autor: UnkL4b
• Сайт: bravul.com
• Блог: unkl4b.github.io
• Github: UnkL4b
• X: @UnkL4b

ПРЕДУПРЕЖДЕНИЕ

 +---------------------------------------------------+
 | РАЗРАБОТЧИКИ НЕ НЕСУТ НИКАКОЙ ОТВЕТСТВЕННОСТИ И   |
 | НЕ ОТВЕЧАЮТ ЗА ЛЮБОЕ НЕПРАВИЛЬНОЕ ИСПОЛЬЗОВАНИЕ   |
 | ИЛИ УЩЕРБ, ПРИЧИНЁННЫЙ ЭТОЙ ПРОГРАММОЙ            |
 +---------------------------------------------------+

GITMINER 3

GitMiner v3 — это модульный инструмент, предназначенный для обнаружения конфиденциальной информации в публичных репозиториях GitHub. Он использует расширенные dork-запросы, сопоставление с регулярными выражениями и генерирует комплексные отчёты по киберразведке.

Этот проект представляет собой полный рефакторинг оригинального скрипта Gitminer, с упором на поддерживаемость, масштабируемость и принципы профессиональной программной архитектуры.

Содержание

• Возможности
• Структура проекта
• Предварительные требования
• Установка
• Конфигурация
• Использование
• Результаты
• Расширение GitMiner
• Лицензия

Возможности

• Объектно-ориентированный дизайн: Полностью рефакторизован в модульную архитектуру на основе классов для лучшей поддерживаемости и расширяемости.
• Многодорковое сканирование: Обработка нескольких GitHub дорков из файла или одного дорка из командной строки.
• Расширенное сопоставление с образцом: Использует настраиваемый набор регулярных выражений для обнаружения широкого спектра секретов, включая API-ключи, токены, пароли и закрытые ключи.
• Конфигурация на основе YAML: Простое управление путями, настройками API и шаблонами обнаружения через простые YAML-файлы.
• Отчёты по киберразведке: Автоматическая генерация подробных отчётов в формате Markdown для каждого дорка, включая исполнительное резюме, анализ серьёзности и технические детали.
• База данных истории SQLite: Отслеживает все операции поиска, загруженные файлы и находки для исторического анализа и постоянного хранения.
• Соответствие PEP 8: Написан с чистым, читаемым и профессиональным кодом, соответствующим стандартам Python.
• Надёжная обработка ошибок: Реализована правильная обработка ошибок и управление ограничениями скорости для стабильного выполнения.

Структура проекта

Проект организован в модульную структуру для разделения задач и улучшения ясности.

gitminer_v3/
├── config/                 # Файлы конфигурации
│   ├── paths.yaml          # Пути к каталогам, файлам и API
│   ├── labels.yaml         # Сопоставления регулярных выражений с метками для параметров
│   └── patterns.yaml       # Регулярные выражения для обнаружения секретов
├── data/                   # Постоянное хранилище данных
│   └── gitminer_history.sqlite # База данных SQLite для истории
├── gitminer/               # Основной пакет Python
│   ├── __init__.py
│   ├── config_manager.py   # Загружает и управляет всеми конфигурациями
│   ├── github_client.py    # Обрабатывает все взаимодействия с GitHub API
│   ├── file_manager.py     # Управляет загрузкой и хранением файлов
│   ├── pattern_analyzer.py # Сканирует файлы на наличие секретов
│   ├── database.py         # Управляет операциями с базой данных SQLite
│   ├── report_generator.py # Генерирует отчёты в формате Markdown
│   └── utils.py            # Общие служебные функции
├── raw/                    # Хранит загруженные файлы с GitHub
├── reports/                # Хранит сгенерированные отчёты по киберразведке
├── gitminer_v3.py          # Основной исполняемый скрипт
├── requirements.txt        # Зависимости Python
└── README.md               # Этот файл 

Предварительные требования

• Python 3.11+
• Персональный токен доступа GitHub (PAT) с областью действия public_repo.

Установка

1. Клонируйте репозиторий или загрузите исходный код.

2. Настройте свой GitHub-токен: Для взаимодействия с API GitMiner требуется GitHub-токен. Вы должны задать его как переменную окружения.

   root@kitploit:~

   export GITHUB_TOKEN="your_github_personal_access_token_here"
   

3. Установите необходимые пакеты Python:

   root@kitploit:~

   pip install -r requirements.txt
   

Конфигурация

Поведение GitMiner управляется файлами в каталоге config/.

paths.yaml

Этот файл определяет все важные пути и настройки API.

• directories: Указывает, где хранить необработанные файлы, отчёты и данные.
• files: Определяет имена для базы данных и вывода CSV по умолчанию.
• github: Содержит настройки для GitHub API, такие как URL-адреса, тайм-ауты и лимиты результатов по умолчанию.

labels.yaml

Этот файл сопоставляет регулярные выражения с понятными человеку метками. В основном используется для идентификации имён параметров (например, ftp_user, api_key) в коде.

# Формат: "regex_pattern": "LABEL_NAME"
"(?i)(api[_\\- ]?key|apikey)": "API_KEY"
"(?i)(password|passwd)": "PASSWORD"

patterns.yaml

Этот файл содержит основные регулярные выражения, используемые для обнаружения конфиденциальных значений, таких как ключи, токены и учётные данные.

# Формат: PATTERN_NAME: "regex_pattern"
GITHUB_TOKEN: "ghp_[A-Za-z0-9_]{36,255}"
AWS_ACCESS_KEY_ID: "AKIA[0-9A-Z]{16}"

Использование

Основной скрипт gitminer_v3.py является точкой входа для всех операций.

Аргументы командной строки

Примеры

1. Поиск с использованием одного дорка и генерация отчёта:

   root@kitploit:~

   python3 gitminer_v3.py -d "filename:.env DB_PASSWORD" --report
   

2. Поиск с использованием файла, содержащего несколько дорков: Создайте файл с именем dorks.txt:

   root@kitploit:~

   filename:wp-config.php DB_PASSWORD
   filename:settings.py SECRET_KEY
   extension:pem private
   

   Затем выполните команду:

   root@kitploit:~

   python3 gitminer_v3.py -d dorks.txt -m 500 --report
   

3. Экспорт списка всех загруженных файлов в CSV:

   root@kitploit:~

   python3 gitminer_v3.py -d dorks.txt -o downloaded_files.csv
   

4. Загрузка файлов без выполнения какого-либо анализа:

   root@kitploit:~

   python3 gitminer_v3.py -d dorks.txt --no-analyze
   

Результаты

GitMiner создаёт несколько типов результатов, хранящихся в каталогах raw/, reports/ и data/.

Необработанные файлы

Все файлы, загруженные с GitHub, хранятся в каталоге raw/, организованные по ключевому слову дорка и имени репозитория.

raw/
└── DB_PASSWORD/
    └── someuser_some-repo/
        └── .env

Отчёты по киберразведке

Если используется флаг --report, для каждого дорка генерируется подробный отчёт в формате Markdown и сохраняется в каталоге reports/. Эти отчёты включают:

• Исполнительное резюме с ключевой статистикой.
• Находки по серьёзности (Высокая, Средняя, Низкая).
• Раздел Технический анализ с фрагментами кода и ссылками на исходные файлы.
• Рекомендации по устранению.

База данных SQLite

Файл data/gitminer_history.sqlite содержит полную историю всех операций, включая:

• search_history: Записи о каждом выполненном поиске дорков.
• downloaded_files: Метаданные для каждого загруженного файла.
• findings: Подробные записи о каждом найденном секрете.

Эта база данных может использоваться для долгосрочного отслеживания и расширенной аналитики.

Расширение GitMiner

GitMiner v3 спроектирован так, чтобы его можно было легко расширять.

• Чтобы добавить новые шаблоны обнаружения: Просто добавьте новую запись в config/patterns.yaml.
• Чтобы добавить новые метки параметров: Добавьте новую пару регулярное выражение-метка в config/labels.yaml.
• Чтобы изменить поведение: Модульный объектно-ориентированный код в пакете gitminer/ хорошо документирован и может быть легко изменён или расширен.

Лицензия

Этот проект является открытым исходным кодом и доступен для личного и образовательного использования. Пожалуйста, используйте его ответственно и этично. Автор не несёт ответственности за любое неправильное использование этого инструмента.