raquer-raqueia/credscan
GitHub: raquer-raqueia/credscan
Stars: 0 | Forks: 0
# 🛡️ CREDSCAN — Threat Intelligence Credential Scanner
## 📋 Índice
- [Sobre o projeto](#sobre-o-projeto)
- [Funcionalidades](#funcionalidades)
- [Pré-requisitos](#pré-requisitos)
- [Instalação](#instalação)
- [Estrutura esperada de arquivos](#estrutura-esperada-de-arquivos)
- [Como usar](#como-usar)
- [Parâmetros disponíveis](#parâmetros-disponíveis)
- [Entendendo os resultados](#entendendo-os-resultados)
- [Arquivo de saída](#arquivo-de-saída)
- [Fluxo de trabalho recomendado](#fluxo-de-trabalho-recomendado)
- [Domínios monitorados](#domínios-monitorados)
- [Como adicionar ou remover domínios](#como-adicionar-ou-remover-domínios)
- [Aviso legal](#aviso-legal)
## Sobre o projeto
O **CREDSCAN** foi desenvolvido para auxiliar analistas de Threat Intelligence no processo de monitoramento e reporte responsável de credenciais corporativas expostas em vazamentos de dados (*data leaks*).
O script percorre centenas (ou milhares) de arquivos `.txt` de dump — que geralmente contêm dados sujos e mal formatados — extrai pares `email:senha` válidos, filtra pelos domínios dos clientes monitorados e cruza os resultados com uma blacklist de credenciais já reportadas, evitando duplicidade nos reportes.
## Funcionalidades
- ✅ **Varredura em massa** — suporta diretórios com dezenas a centenas de GB de arquivos `.txt`
- ✅ **Limpeza automática de dados sujos** — extrai `email:senha` de linhas com URLs, pipes, separadores variados (`:` e `;`) e outros ruídos comuns em dumps
- ✅ **Filtro por domínio** — processa apenas e-mails dos domínios configurados
- ✅ **Verificação contra blacklist** — cruza cada achado com `blacklist.txt` antes de exibir
- ✅ **Deduplicação** — elimina pares repetidos entre arquivos diferentes
- ✅ **Progress bar em tempo real** — exibe progresso, contador de novos vs. já reportados e tempo decorrido
- ✅ **Interrupção segura com Ctrl+C** — exibe resultados parciais sem perda de dados
- ✅ **Exportação automática** — gera arquivo `.txt` com os novos achados ao final da execução
- ✅ **Resultado colorido no terminal** — verde para novos achados, vermelho para itens já reportados
## Pré-requisitos
- Python **3.10+** (utiliza `str | None` como type hint)
- Nenhuma biblioteca externa — apenas módulos da biblioteca padrão do Python
Para verificar sua versão:
python3 --version
## Instalação
# Clone o repositório
git clone https://github.com/raquer-raqueia/credscan
cd credscan
# Dê permissão de execução
chmod +x credscan.py
## Estrutura esperada de arquivos
credscan/
├── credscan.py # Script principal
├── blacklist.txt # Credenciais já reportadas (um email:senha por linha)
└── leaks/ # Exemplo de diretório com os dumps
├── dump_001.txt
├── dump_002.txt
└── ...
### Formato do `blacklist.txt`
Cada linha deve conter um par `email:senha` já reportado. Linhas iniciadas com `#` são tratadas como comentários e ignoradas.
## Como usar
### Modo com argumento (recomendado)
Execute o script com argumentos (pipelines e automação).
python3 credscan.py -d /caminho/para/leaks -b /caminho/para/blacklist.txt -o resultado.txt
## Parâmetros disponíveis
| Parâmetro | Forma curta | Descrição | Padrão |
|-----------|-------------|-----------|--------|
| `--directory` | `-d` | Caminho do diretório com os arquivos `.txt` | *(solicitado interativamente)* |
| `--blacklist` | `-b` | Caminho para o arquivo `blacklist.txt` | `./blacklist.txt` |
| `--output` | `-o` | Nome do arquivo de saída com os novos achados | `credscan_novos_.txt` |
## Entendendo os resultados
Durante a execução, o terminal exibe uma barra de progresso em tempo real:
⠹ [████████████░░░░░░░░░░░░░░░░░░] 40.0% │ Arqs: 40/100 │ Novos: 12 │ BL: 3 │ ⏱ 00:02:15 dump_042.txt
| Elemento | Descrição |
|----------|-----------|
| Barra de progresso | Percentual de arquivos processados |
| `Arqs` | Arquivos concluídos / total |
| `Novos` | Achados **não** presentes na blacklist |
| `BL` | Achados já presentes na blacklist (já reportados) |
| ⏱ | Tempo decorrido desde o início |
| Nome do arquivo | Último arquivo processado |
#### Ao finalizar, o relatório é exibido com as seguintes seções:
## Como adicionar ou remover domínios
Abra o arquivo `credscan.py` e localize a lista `TARGET_DOMAINS`:
TARGET_DOMAINS = [
"@domain.gov.br",
"@domain.gov.br",
# adicione ou remova domínios aqui
]
Salve o arquivo. Nenhuma outra alteração é necessária.
## Aviso legal
## 📋 Índice
- [Sobre o projeto](#sobre-o-projeto)
- [Funcionalidades](#funcionalidades)
- [Pré-requisitos](#pré-requisitos)
- [Instalação](#instalação)
- [Estrutura esperada de arquivos](#estrutura-esperada-de-arquivos)
- [Como usar](#como-usar)
- [Parâmetros disponíveis](#parâmetros-disponíveis)
- [Entendendo os resultados](#entendendo-os-resultados)
- [Arquivo de saída](#arquivo-de-saída)
- [Fluxo de trabalho recomendado](#fluxo-de-trabalho-recomendado)
- [Domínios monitorados](#domínios-monitorados)
- [Como adicionar ou remover domínios](#como-adicionar-ou-remover-domínios)
- [Aviso legal](#aviso-legal)
## Sobre o projeto
O **CREDSCAN** foi desenvolvido para auxiliar analistas de Threat Intelligence no processo de monitoramento e reporte responsável de credenciais corporativas expostas em vazamentos de dados (*data leaks*).
O script percorre centenas (ou milhares) de arquivos `.txt` de dump — que geralmente contêm dados sujos e mal formatados — extrai pares `email:senha` válidos, filtra pelos domínios dos clientes monitorados e cruza os resultados com uma blacklist de credenciais já reportadas, evitando duplicidade nos reportes.
## Funcionalidades
- ✅ **Varredura em massa** — suporta diretórios com dezenas a centenas de GB de arquivos `.txt`
- ✅ **Limpeza automática de dados sujos** — extrai `email:senha` de linhas com URLs, pipes, separadores variados (`:` e `;`) e outros ruídos comuns em dumps
- ✅ **Filtro por domínio** — processa apenas e-mails dos domínios configurados
- ✅ **Verificação contra blacklist** — cruza cada achado com `blacklist.txt` antes de exibir
- ✅ **Deduplicação** — elimina pares repetidos entre arquivos diferentes
- ✅ **Progress bar em tempo real** — exibe progresso, contador de novos vs. já reportados e tempo decorrido
- ✅ **Interrupção segura com Ctrl+C** — exibe resultados parciais sem perda de dados
- ✅ **Exportação automática** — gera arquivo `.txt` com os novos achados ao final da execução
- ✅ **Resultado colorido no terminal** — verde para novos achados, vermelho para itens já reportados
## Pré-requisitos
- Python **3.10+** (utiliza `str | None` como type hint)
- Nenhuma biblioteca externa — apenas módulos da biblioteca padrão do Python
Para verificar sua versão:
python3 --version
## Instalação
# Clone o repositório
git clone https://github.com/raquer-raqueia/credscan
cd credscan
# Dê permissão de execução
chmod +x credscan.py
## Estrutura esperada de arquivos
credscan/
├── credscan.py # Script principal
├── blacklist.txt # Credenciais já reportadas (um email:senha por linha)
└── leaks/ # Exemplo de diretório com os dumps
├── dump_001.txt
├── dump_002.txt
└── ...
### Formato do `blacklist.txt`
Cada linha deve conter um par `email:senha` já reportado. Linhas iniciadas com `#` são tratadas como comentários e ignoradas.
## Como usar
### Modo com argumento (recomendado)
Execute o script com argumentos (pipelines e automação).
python3 credscan.py -d /caminho/para/leaks -b /caminho/para/blacklist.txt -o resultado.txt
## Parâmetros disponíveis
| Parâmetro | Forma curta | Descrição | Padrão |
|-----------|-------------|-----------|--------|
| `--directory` | `-d` | Caminho do diretório com os arquivos `.txt` | *(solicitado interativamente)* |
| `--blacklist` | `-b` | Caminho para o arquivo `blacklist.txt` | `./blacklist.txt` |
| `--output` | `-o` | Nome do arquivo de saída com os novos achados | `credscan_novos_
## Como adicionar ou remover domínios
Abra o arquivo `credscan.py` e localize a lista `TARGET_DOMAINS`:
TARGET_DOMAINS = [
"@domain.gov.br",
"@domain.gov.br",
# adicione ou remova domínios aqui
]
Salve o arquivo. Nenhuma outra alteração é necessária.
## Aviso legal