GitMiner3

• Autor: UnkL4b
• Sitio: bravul.com
• Blog: unkl4b.github.io
• Github: UnkL4b
• X: @UnkL4b

ADVERTENCIA

 +---------------------------------------------------+
 | LOS DESARROLLADORES NO ASUMEN NINGUNA              |
 | RESPONSABILIDAD Y NO SON RESPONSABLES DE CUALQUIER |
 | USO INDEBIDO O DAÑO CAUSADO POR ESTE PROGRAMA      |
 +---------------------------------------------------+

GITMINER 3

GitMiner v3 es una herramienta modular diseñada para descubrir información sensible en repositorios públicos de GitHub. Utiliza consultas dork avanzadas, coincidencia de patrones regex y genera informes completos de inteligencia de amenazas.

Este proyecto es una refactorización completa del script original Gitminer, centrada en la mantenibilidad, la escalabilidad y los principios de arquitectura de software profesional.

Tabla de Contenidos

• Características
• Estructura del Proyecto
• Requisitos Previos
• Instalación
• Configuración
• Uso
• Salida
• Extender GitMiner
• Licencia

Características

• Diseño Orientado a Objetos: Refactorizado completamente a una arquitectura modular basada en clases para una mejor mantenibilidad y extensibilidad.
• Escaneo Multi-Dork: Procesa múltiples dorks de GitHub desde un archivo o un solo dork desde la línea de comandos.
• Coincidencia Avanzada de Patrones: Utiliza un conjunto configurable de patrones regex para detectar una amplia gama de secretos, incluyendo claves API, tokens, contraseñas y claves privadas.
• Configuración Basada en YAML: Gestiona fácilmente rutas, ajustes de API y patrones de detección mediante archivos YAML simples.
• Informes de Inteligencia de Amenazas: Genera automáticamente informes Markdown detallados para cada dork, incluyendo un resumen ejecutivo, análisis de severidad y detalles técnicos.
• Base de Datos de Historial SQLite: Registra todas las operaciones de búsqueda, archivos descargados y hallazgos para análisis histórico y persistencia.
• Conforme a PEP 8: Escrito con código limpio, legible y profesional que cumple con los estándares de Python.
• Manejo Robusto de Errores: Implementa un manejo adecuado de errores y gestión de límites de tasa para una ejecución estable.

Estructura del Proyecto

El proyecto está organizado en una estructura modular para separar responsabilidades y mejorar la claridad.

gitminer_v3/
├── config/                 # Archivos de configuración
│   ├── paths.yaml          # Rutas de directorios, archivos y API
│   ├── labels.yaml         # Mapeos de regex a etiquetas para parámetros
│   └── patterns.yaml       # Patrones regex para detección de secretos
├── data/                   # Almacenamiento de datos persistente
│   └── gitminer_history.sqlite # Base de datos SQLite para el historial
├── gitminer/               # Paquete principal de Python
│   ├── __init__.py
│   ├── config_manager.py   # Carga y gestiona todas las configuraciones
│   ├── github_client.py    # Maneja todas las interacciones con la API de GitHub
│   ├── file_manager.py     # Gestiona descargas y almacenamiento de archivos
│   ├── pattern_analyzer.py # Escanea archivos en busca de secretos
│   ├── database.py         # Gestiona las operaciones de la base de datos SQLite
│   ├── report_generator.py # Genera informes Markdown
│   └── utils.py            # Funciones de utilidad compartidas
├── raw/                    # Almacena archivos descargados de GitHub
├── reports/                # Almacena informes de inteligencia de amenazas generados
├── gitminer_v3.py          # Script ejecutable principal
├── requirements.txt        # Dependencias de Python
└── README.md               # Este archivo 

Requisitos Previos

• Python 3.11+
• Un Token de Acceso Personal (PAT) de GitHub con el alcance public_repo.

Instalación

1. Clona el repositorio o descarga el código fuente.

2. Configura tu Token de GitHub: GitMiner requiere un token de GitHub para interactuar con la API. Debes configurarlo como una variable de entorno.

   root@kitploit:~

   export GITHUB_TOKEN="tu_token_de_acceso_personal_de_github_aqui"
   

3. Instala los paquetes de Python requeridos:

   root@kitploit:~

   pip install -r requirements.txt
   

Configuración

El comportamiento de GitMiner está controlado por los archivos en el directorio config/.

paths.yaml

Este archivo define todas las rutas importantes y los ajustes de API.

• directories: Especifica dónde almacenar archivos raw, informes y datos.
• files: Define los nombres para la base de datos y la salida CSV predeterminada.
• github: Contiene ajustes para la API de GitHub, como URLs, tiempos de espera y límites de resultados predeterminados.

labels.yaml

Este archivo mapea patrones regex a etiquetas legibles por humanos. Se utiliza principalmente para identificar nombres de parámetros (por ejemplo, ftp_user, api_key) en el código.

# Formato: "patron_regex": "NOMBRE_ETIQUETA"
"(?i)(api[_\\- ]?key|apikey)": "API_KEY"
"(?i)(password|passwd)": "PASSWORD"

patterns.yaml

Este archivo contiene los patrones regex principales utilizados para detectar valores sensibles como claves, tokens y credenciales.

# Formato: NOMBRE_PATRON: "patron_regex"
GITHUB_TOKEN: "ghp_[A-Za-z0-9_]{36,255}"
AWS_ACCESS_KEY_ID: "AKIA[0-9A-Z]{16}"

Uso

El script principal gitminer_v3.py es el punto de entrada para todas las operaciones.

Argumentos de Línea de Comandos

Ejemplos

1. Buscar usando un solo dork y generar un informe:

   root@kitploit:~

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

2. Buscar usando un archivo que contenga múltiples dorks: Crea un archivo llamado dorks.txt:

   root@kitploit:~

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

   Luego ejecuta el comando:

   root@kitploit:~

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

3. Exportar una lista de todos los archivos descargados a CSV:

   root@kitploit:~

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

4. Descargar archivos sin realizar ningún análisis:

   root@kitploit:~

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

Salida

GitMiner produce varios tipos de salida, almacenados en los directorios raw/, reports/ y data/.

Archivos Raw

Todos los archivos descargados de GitHub se almacenan en el directorio raw/, organizados por palabra clave del dork y nombre del repositorio.

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

Informes de Inteligencia de Amenazas

Si se utiliza la bandera --report, se genera un informe Markdown detallado para cada dork y se guarda en el directorio reports/. Estos informes incluyen:

• Un Resumen Ejecutivo con estadísticas clave.
• Hallazgos por Severidad (Alta, Media, Baja).
• Una sección de Análisis Técnico con fragmentos de código y enlaces a los archivos fuente.
• Recomendaciones para la remediación.

Base de Datos SQLite

El archivo data/gitminer_history.sqlite contiene un historial completo de todas las operaciones, incluyendo:

• search_history: Registros de cada búsqueda de dork realizada.
• downloaded_files: Metadatos de cada archivo descargado.
• findings: Registros detallados de cada secreto encontrado.

Esta base de datos puede utilizarse para seguimiento a largo plazo y análisis avanzados.

Extender GitMiner

GitMiner v3 está diseñado para ser fácilmente extensible.

• Para añadir nuevos patrones de detección: Simplemente añade una nueva entrada a config/patterns.yaml.
• Para añadir nuevas etiquetas de parámetros: Añade un nuevo par regex-etiqueta a config/labels.yaml.
• Para modificar el comportamiento: El código modular y orientado a objetos en el paquete gitminer/ está bien documentado y puede modificarse o extenderse fácilmente.

Licencia

Este proyecto es de código abierto y está disponible para uso personal y educativo. Úsalo de manera responsable y ética. El autor no es responsable de ningún uso indebido de esta herramienta.