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.

   export GITHUB_TOKEN="tu_token_de_acceso_personal_de_github_aqui"
   

3. Instala los paquetes de Python requeridos:

   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

Argumento	Corto	Descripción	Requerido
--dorks	-d	Archivo con dorks (uno por línea) o una cadena de dork única.	Sí
--token	-t	Token de GitHub (anula la variable de entorno GITHUB_TOKEN).	No
--max-results	-m	Máximo de resultados a obtener por dork. (Predeterminado: 200)	No
--per-page	-p	Resultados por página para la API. (Predeterminado: 30, Máx: 100)	No
--output-csv	-o	Exporta un resumen de los archivos descargados a un archivo CSV.	No
--report		Genera un informe detallado de inteligencia de amenazas en Markdown.	No
--no-analyze		Omite el paso de análisis de archivos locales (solo descarga archivos).	No

Ejemplos

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

   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:

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

   Luego ejecuta el comando:

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

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

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

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

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