soc-mre 1.0.3

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

O pacote Python inclui várias bibliotecas; para deteção MIME (python-magic) e UnRAR (rarfile), use conforme o SO:

Linux (Kali / Ubuntu / Debian)

sudo apt install libmagic1 unrar

macOS

brew install libmagic

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

Windows

pip install python-magic-bin

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