soc-mre 1.1.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 do sistema

Obrigatórias

Para o uso normal do projeto (menu, deteção por domínio e modo turbo), instale as duas dependências abaixo:

Componente	Função	Instalação
ripgrep (rg)	Pré-filtro rápido nos leaks (varredura recursiva, globs, --stats para contagem de ficheiros)	Linux: sudo apt install ripgrep — macOS: brew install ripgrep — Windows: releases do ripgrep
python-magic + libmagic	Deteção MIME dos ficheiros de leak (.txt, .csv, .gz, .zip, etc.)	Ver tabela por SO abaixo

Sem rg, o motor cai num caminho legado mais lento e incompleto (só ficheiros no topo da pasta leaks). Sem python-magic/libmagic, a leitura por tipo MIME falha ou degrada.

Linux (Kali / Ubuntu / Debian)

sudo apt install ripgrep libmagic1

macOS

brew install ripgrep libmagic

Windows

• Instale o binário rg e coloque-o no PATH.
• Depois do pip install / pipx install:

pip install python-magic-bin

Recomendadas (formatos específicos)

O pacote Python inclui várias bibliotecas; para UnRAR (rarfile) e outros formatos lentos, use conforme o SO:

Linux (Kali / Ubuntu / Debian)

sudo apt install unrar

macOS

Instale também as ferramentas UnRAR disponíveis para macOS se precisar de ficheiros .rar.

Windows

Para .rar, instale o binário UnRAR (WinRAR / linha de comandos) conforme a documentação do rarfile.

Instalação

cd soc-mre
pip install .

Abrir e usar o projeto (pipx, a partir do PyPI)

No Linux (por exemplo Kali), pode instalar o executável globalmente num ambiente isolado e abrir a ferramenta diretamente.

Por que usar pipx? O pip install à escala do sistema (ou misturar pacotes com o Python do SO) pode substituir bibliotecas que ferramentas do Kali/Ubuntu também usam e causar avisos, quebras ou conflitos de versões. O pipx instala cada aplicação CLI no seu próprio ambiente virtual, separado do Python do sistema: o utilizador ganha o comando soc-mre no PATH sem alterar o site-packages global nem arriscar instabilidade no resto da máquina.

sudo apt install pipx ripgrep libmagic1
pipx install soc-mre
soc-mre

O comando soc-mre fica no PATH do utilizador (gerido pelo pipx). Na primeira execução sem soc_mre.json, o assistente pede os caminhos das pastas leaks, CTI e database; depois abre o menu. Consulte também a secção Primeira execução abaixo.

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).

Primeira execução

Sem soc_mre.json (ou sem database_dir definido) e sem --database-dir na linha de comandos, ao correr:

soc-mre

o programa pede interativamente os caminhos das pastas leaks, CTI e database, cria ./database por omissão se carregar Enter nesse campo, grava a configuração em soc_mre.json e segue para o menu.

Se soc_mre.json já existir com database_dir (e, no modo menu, leaks e cti), o menu abre sem repetir o assistente.

Também pode configurar manualmente o soc_mre.json (chaves usadas pelo programa):

{
  "leaks": "/caminho/leaks",
  "cti": "/caminho/CTI",
  "database_dir": "/caminho/database"
}

Uso interativo

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

Ou defina os 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 consideram (ambos obrigatórios; ver Dependências do sistema).

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.