GitMiner3

• Autore: UnkL4b
• Sito: bravul.com
• Blog: unkl4b.github.io
• Github: UnkL4b
• X: @UnkL4b

AVVERTENZA

 +---------------------------------------------------+
 | GLI SVILUPPATORI NON SI ASSUMONO ALCUNA           |
 | RESPONSABILITÀ E NON SONO RESPONSABILI PER        |
 | QUALSIASI USO IMPROPRIO O DANNO CAUSATO DA        |
 | QUESTO PROGRAMMA                                  |
 +---------------------------------------------------+

GITMINER 3

GitMiner v3 è uno strumento modulare progettato per scoprire informazioni sensibili nei repository GitHub pubblici. Utilizza query dork avanzate, corrispondenza di pattern regex e genera report completi di threat intelligence.

Questo progetto è una completa riscrittura dello script originale Gitminer, con particolare attenzione a manutenibilità, scalabilità e principi di architettura software professionale.

Indice

• Caratteristiche
• Struttura del Progetto
• Prerequisiti
• Installazione
• Configurazione
• Utilizzo
• Output
• Estendere GitMiner
• Licenza

Caratteristiche

• Design Orientato agli Oggetti: Completamente riscritto in un'architettura modulare basata su classi per una migliore manutenibilità ed estensibilità.
• Scansione Multi-Dork: Elabora più dork GitHub da un file o un singolo dork dalla riga di comando.
• Corrispondenza Avanzata dei Pattern: Utilizza un set configurabile di pattern regex per rilevare un'ampia gamma di segreti, inclusi chiavi API, token, password e chiavi private.
• Configurazione Basata su YAML: Gestisci facilmente percorsi, impostazioni API e pattern di rilevamento tramite semplici file YAML.
• Report di Threat Intelligence: Genera automaticamente report Markdown dettagliati per ogni dork, inclusi sommario esecutivo, analisi della severità e dettagli tecnici.
• Database Storico SQLite: Tiene traccia di tutte le operazioni di ricerca, dei file scaricati e dei risultati per analisi storiche e persistenza.
• Conforme a PEP 8: Scritto con codice pulito, leggibile e professionale che aderisce agli standard Python.
• Gestione Robusta degli Errori: Implementa una corretta gestione degli errori e del limite di richieste per un'esecuzione stabile.

Struttura del Progetto

Il progetto è organizzato in una struttura modulare per separare le responsabilità e migliorare la chiarezza.

gitminer_v3/
├── config/                 # File di configurazione
│   ├── paths.yaml          # Percorsi di directory, file e API
│   ├── labels.yaml         # Mappature regex-etichetta per i parametri
│   └── patterns.yaml       # Pattern regex per il rilevamento dei segreti
├── data/                   # Archiviazione dati persistente
│   └── gitminer_history.sqlite # Database SQLite per la cronologia
├── gitminer/               # Pacchetto Python principale
│   ├── __init__.py
│   ├── config_manager.py   # Carica e gestisce tutte le configurazioni
│   ├── github_client.py    # Gestisce tutte le interazioni con l'API GitHub
│   ├── file_manager.py     # Gestisce il download e l'archiviazione dei file
│   ├── pattern_analyzer.py # Scansiona i file alla ricerca di segreti
│   ├── database.py         # Gestisce le operazioni sul database SQLite
│   ├── report_generator.py # Genera report Markdown
│   └── utils.py            # Funzioni di utilità condivise
├── raw/                    # Archivia i file scaricati da GitHub
├── reports/                # Archivia i report di threat intelligence generati
├── gitminer_v3.py          # Script eseguibile principale
├── requirements.txt        # Dipendenze Python
└── README.md               # Questo file 

Prerequisiti

• Python 3.11+
• Un Personal Access Token (PAT) GitHub con ambito public_repo.

Installazione

1. Clona il repository o scarica il codice sorgente.

2. Configura il tuo Token GitHub: GitMiner richiede un token GitHub per interagire con l'API. Devi impostarlo come variabile d'ambiente.

   root@kitploit:~

   export GITHUB_TOKEN="il_tuo_personal_access_token_github_qui"
   

3. Installa i pacchetti Python richiesti:

   root@kitploit:~

   pip install -r requirements.txt
   

Configurazione

Il comportamento di GitMiner è controllato dai file nella directory config/.

paths.yaml

Questo file definisce tutti i percorsi e le impostazioni API importanti.

• directories: Specifica dove archiviare file raw, report e dati.
• files: Definisce i nomi per il database e l'output CSV predefinito.
• github: Contiene le impostazioni per l'API GitHub, come URL, timeout e limiti predefiniti dei risultati.

labels.yaml

Questo file mappa i pattern regex a etichette leggibili dall'uomo. Viene utilizzato principalmente per identificare i nomi dei parametri (es. ftp_user, api_key) nel codice.

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

patterns.yaml

Questo file contiene i pattern regex principali utilizzati per rilevare valori sensibili come chiavi, token e credenziali.

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

Utilizzo

Lo script principale gitminer_v3.py è il punto di ingresso per tutte le operazioni.

Argomenti della Riga di Comando

Esempi

1. Ricerca utilizzando un singolo dork e generazione di un report:

   root@kitploit:~

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

2. Ricerca utilizzando un file contenente più dork: Crea un file chiamato dorks.txt:

   root@kitploit:~

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

   Poi esegui il comando:

   root@kitploit:~

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

3. Esporta un elenco di tutti i file scaricati in CSV:

   root@kitploit:~

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

4. Scarica i file senza eseguire alcuna analisi:

   root@kitploit:~

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

Output

GitMiner produce diversi tipi di output, archiviati nelle directory raw/, reports/ e data/.

File Raw

Tutti i file scaricati da GitHub sono archiviati nella directory raw/, organizzati per parola chiave dork e nome del repository.

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

Report di Threat Intelligence

Se viene utilizzato il flag --report, viene generato un report Markdown dettagliato per ogni dork e salvato nella directory reports/. Questi report includono:

• Un Sommario Esecutivo con statistiche chiave.
• Risultati per Severità (Alta, Media, Bassa).
• Una sezione di Analisi Tecnica con frammenti di codice e collegamenti ai file sorgente.
• Raccomandazioni per la correzione.

Database SQLite

Il file data/gitminer_history.sqlite contiene una cronologia completa di tutte le operazioni, inclusi:

• search_history: Registrazioni di ogni ricerca dork eseguita.
• downloaded_files: Metadati per ogni file scaricato.
• findings: Registrazioni dettagliate di ogni segreto trovato.

Questo database può essere utilizzato per il monitoraggio a lungo termine e analisi avanzate.

Estendere GitMiner

GitMiner v3 è progettato per essere facilmente estensibile.

• Per aggiungere nuovi pattern di rilevamento: Aggiungi semplicemente una nuova voce a config/patterns.yaml.
• Per aggiungere nuove etichette di parametri: Aggiungi una nuova coppia regex-etichetta a config/labels.yaml.
• Per modificare il comportamento: Il codice modulare e orientato agli oggetti nel pacchetto gitminer/ è ben documentato e può essere facilmente modificato o esteso.

Licenza

Questo progetto è open-source e disponibile per uso personale ed educativo. Utilizzalo in modo responsabile ed etico. L'autore non è responsabile per qualsiasi uso improprio di questo strumento.