soc-mre 1.0.0

Credential Intelligence Tool for SOC

SOC MRE

Ferramenta defensiva de análise de credenciais vazadas para equipes de SOC. Lê ficheiros na pasta de leaks, cruza com domínios monitorados (pastas sob CTI) e grava resultados em SQLite e ficheiros de blacklist por domínio.

Dependências de sistema (Linux)

O pacote Python inclui bibliotecas para vários formatos; no sistema é recomendado:

sudo apt install libmagic1 unrar

• libmagic1 — deteção MIME (python-magic).
• unrar — leitura de alguns ficheiros .rar via rarfile (sem extrair para disco).

No Windows, instale o binário UnRAR se precisar de .rar, e as DLLs necessárias para python-magic.

Instalação

cd soc-mre
pip install .

Instalação a partir de um repositório Git

Substitua o URL pelo do seu fork ou organização:

pip install git+https://github.com/SEU-USUARIO/soc-mre.git

Configuração

Gere um ficheiro JSON de exemplo e edite os caminhos (leaks, cti, database_dir):

soc-mre --init-config

Ficheiro padrão: soc_mre.json no diretório atual (alterável com --config).

Uso interativo

soc-mre --leaks /caminho/leaks --cti /caminho/CTI --database-dir /caminho/database

Ou preencha os mesmos caminhos no soc_mre.json e execute:

soc-mre

Linha de comando e modo stdin

soc-mre --help
python -m soc_mre --help

Modo pipe (exige CTI válido para localizar a pasta do domínio e exportar blacklist):

rg -i "@exemplo.com" /caminho/leaks | soc-mre --stdin --domain @exemplo.com -c /caminho/CTI -d /caminho/database

Persistência (SQLite)

• database.db — criado/atualizado dentro do diretório passado em --database-dir / database_dir. Tabela credentials com chave (email, password), modo WAL.
• Migração — se existir masterList.txt nesse diretório na primeira execução, o conteúdo é importado para o SQLite e o ficheiro legado é renomeado para masterList.txt.bak (mensagem na consola).

Blacklists por domínio

• Ficheiros exportados seguem o padrão lógico blackList-<dominio-sanitizado>.txt, mas cada exportação com dados gera um novo ficheiro com timestamp e microssegundos no nome, por exemplo:

  blackList-exemplo.com.br_2026-05-03_14-30-00-123456.txt

• Não se sobrescrevem exportações anteriores; o histórico acumula-se no disco.

• Se não houver credenciais para aquele domínio na base, a exportação não cria ficheiro novo (retorno 0).

• O menu continua a carregar credenciais já guardadas a partir do caminho “canónico” da pasta do domínio (blackList-*.txt existentes); novas execuções acrescentam ficheiros com timestamp.

Formatos de leak suportados

Formato	Comportamento
.txt, .csv	Leitura em fluxo (linhas em bytes).
.gz	Descompressão em fluxo.
.zip	Leitura com zipfile sem extrair para disco; vários membros e subpastas internas.
.7z, .rar, .pdf, .xlsx	Tratados como formatos lentos: é pedida confirmação no terminal antes de processar; leitura em memória/streaming conforme o tipo (sem extractall para disco nos arquivos compactados).

Extensões reconhecidas na pasta de leaks estão alinhadas com o que o motor de deteção e o rg (quando instalado) consideram.

Outras dependências Python

Instaladas automaticamente com pip install . (ver pyproject.toml): Rich, tqdm, psutil, python-magic, py7zr, rarfile, pdfplumber, openpyxl.

Avisos de memória

Durante análise de ficheiros muito grandes, pode ser mostrado um aviso se a RAM do sistema ultrapassar um limiar (percentagem configurada no código); o processo não termina so por isso.

Repositório

O código-fonte vive no pacote soc_mre/ (nome com underscore). A pasta soc-mre/ (hífen) é a raiz do projeto instalável.