GitMiner3

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

AVISO

 +---------------------------------------------------+
 | OS DESENVOLVEDORES NÃO ASSUMEM NENHUMA             |
 | RESPONSABILIDADE E NÃO SÃO RESPONSÁVEIS POR        |
 | QUALQUER USO INDEVIDO OU DANO CAUSADO POR          |
 | ESTE PROGRAMA                                     |
 +---------------------------------------------------+

GITMINER 3

O GitMiner v3 é uma ferramenta modular projetada para descobrir informações sensíveis em repositórios públicos do GitHub. Ele utiliza consultas dork avançadas, correspondência de padrões regex e gera relatórios abrangentes de inteligência de ameaças.

Este projeto é uma refatoração completa do script original Gitminer, com foco em manutenibilidade, escalabilidade e princípios profissionais de arquitetura de software.

Índice

• Recursos
• Estrutura do Projeto
• Pré-requisitos
• Instalação
• Configuração
• Uso
• Saída
• Estendendo o GitMiner
• Licença

Recursos

• Design Orientado a Objetos: Totalmente refatorado em uma arquitetura modular baseada em classes para melhor manutenibilidade e extensibilidade.
• Varredura Multi-Dork: Processa múltiplas dorks do GitHub a partir de um arquivo ou uma única dork pela linha de comando.
• Correspondência Avançada de Padrões: Utiliza um conjunto configurável de padrões regex para detectar uma ampla gama de segredos, incluindo chaves de API, tokens, senhas e chaves privadas.
• Configuração Baseada em YAML: Gerencie facilmente caminhos, configurações de API e padrões de detecção por meio de arquivos YAML simples.
• Relatórios de Inteligência de Ameaças: Gera automaticamente relatórios detalhados em Markdown para cada dork, incluindo um resumo executivo, análise de severidade e detalhes técnicos.
• Banco de Dados de Histórico SQLite: Rastreia todas as operações de busca, arquivos baixados e descobertas para análise histórica e persistência.
• Conformidade com PEP 8: Escrito com código limpo, legível e profissional que adere aos padrões do Python.
• Tratamento Robusto de Erros: Implementa tratamento adequado de erros e gerenciamento de limites de taxa para execução estável.

Estrutura do Projeto

O projeto está organizado em uma estrutura modular para separar responsabilidades e melhorar a clareza.

gitminer_v3/
├── config/                 # Arquivos de configuração
│   ├── paths.yaml          # Caminhos de diretórios, arquivos e API
│   ├── labels.yaml         # Mapeamentos de regex para rótulos de parâmetros
│   └── patterns.yaml       # Padrões regex para detecção de segredos
├── data/                   # Armazenamento persistente de dados
│   └── gitminer_history.sqlite # Banco de dados SQLite para histórico
├── gitminer/               # Pacote Python principal
│   ├── __init__.py
│   ├── config_manager.py   # Carrega e gerencia todas as configurações
│   ├── github_client.py    # Lida com todas as interações com a API do GitHub
│   ├── file_manager.py     # Gerencia downloads e armazenamento de arquivos
│   ├── pattern_analyzer.py # Examina arquivos em busca de segredos
│   ├── database.py         # Gerencia operações do banco de dados SQLite
│   ├── report_generator.py # Gera relatórios em Markdown
│   └── utils.py            # Funções utilitárias compartilhadas
├── raw/                    # Armazena arquivos baixados do GitHub
├── reports/                # Armazena relatórios de inteligência de ameaças gerados
├── gitminer_v3.py          # Script executável principal
├── requirements.txt        # Dependências do Python
└── README.md               # Este arquivo 

Pré-requisitos

• Python 3.11+
• Um Token de Acesso Pessoal (PAT) do GitHub com escopo public_repo.

Instalação

1. Clone o repositório ou baixe o código-fonte.

2. Configure seu Token do GitHub: O GitMiner requer um token do GitHub para interagir com a API. Você deve defini-lo como uma variável de ambiente.

   root@kitploit:~

   export GITHUB_TOKEN="seu_token_de_acesso_pessoal_do_github_aqui"
   

3. Instale os pacotes Python necessários:

   root@kitploit:~

   pip install -r requirements.txt
   

Configuração

O comportamento do GitMiner é controlado por arquivos no diretório config/.

paths.yaml

Este arquivo define todos os caminhos e configurações importantes da API.

• directories: Especifica onde armazenar arquivos brutos, relatórios e dados.
• files: Define os nomes para o banco de dados e a saída CSV padrão.
• github: Contém configurações para a API do GitHub, como URLs, timeouts e limites padrão de resultados.

labels.yaml

Este arquivo mapeia padrões regex para rótulos legíveis por humanos. É usado principalmente para identificar nomes de parâmetros (por exemplo, ftp_user, api_key) no código.

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

patterns.yaml

Este arquivo contém os padrões regex principais usados para detectar valores sensíveis como chaves, tokens e credenciais.

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

Uso

O script principal gitminer_v3.py é o ponto de entrada para todas as operações.

Argumentos de Linha de Comando

Exemplos

1. Buscar usando uma única dork e gerar um relatório:

   root@kitploit:~

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

2. Buscar usando um arquivo contendo múltiplas dorks: Crie um arquivo chamado dorks.txt:

   root@kitploit:~

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

   Em seguida, execute o comando:

   root@kitploit:~

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

3. Exportar uma lista de todos os arquivos baixados para CSV:

   root@kitploit:~

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

4. Baixar arquivos sem realizar nenhuma análise:

   root@kitploit:~

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

Saída

O GitMiner produz vários tipos de saída, armazenados nos diretórios raw/, reports/ e data/.

Arquivos Brutos

Todos os arquivos baixados do GitHub são armazenados no diretório raw/, organizados por palavra-chave da dork e nome do repositório.

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

Relatórios de Inteligência de Ameaças

Se a flag --report for usada, um relatório detalhado em Markdown é gerado para cada dork e salvo no diretório reports/. Esses relatórios incluem:

• Um Resumo Executivo com estatísticas principais.
• Descobertas por Severidade (Alta, Média, Baixa).
• Uma seção de Análise Técnica com trechos de código e links para os arquivos de origem.
• Recomendações para remediação.

Banco de Dados SQLite

O arquivo data/gitminer_history.sqlite contém um histórico completo de todas as operações, incluindo:

• search_history: Registros de cada busca de dork realizada.
• downloaded_files: Metadados de cada arquivo baixado.
• findings: Registros detalhados de cada segredo encontrado.

Este banco de dados pode ser usado para rastreamento de longo prazo e análises avançadas.

Estendendo o GitMiner

O GitMiner v3 foi projetado para ser facilmente extensível.

• Para adicionar novos padrões de detecção: Basta adicionar uma nova entrada em config/patterns.yaml.
• Para adicionar novos rótulos de parâmetros: Adicione um novo par regex-rótulo em config/labels.yaml.
• Para modificar o comportamento: O código modular e orientado a objetos no pacote gitminer/ é bem documentado e pode ser facilmente modificado ou estendido.

Licença

Este projeto é de código aberto e está disponível para uso pessoal e educacional. Use-o de forma responsável e ética. O autor não é responsável por qualquer uso indevido desta ferramenta.