Metadata-Version: 2.4
Name: soc-mre
Version: 1.0.3
Summary: Credential Intelligence Tool for SOC
License: MIT
License-File: LICENSE
Keywords: credentials,cti,leaks,security,soc
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: openpyxl>=3.1
Requires-Dist: pdfplumber>=0.10
Requires-Dist: psutil>=5.9
Requires-Dist: py7zr<1,>=0.20
Requires-Dist: python-magic>=0.4
Requires-Dist: rarfile>=4.0
Requires-Dist: rich>=13.0
Requires-Dist: tqdm>=4.0
Description-Content-Type: text/markdown

# 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)**

```bash
sudo apt install libmagic1 unrar
```

**macOS**

```bash
brew install libmagic
```

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

**Windows**

```bash
pip install python-magic-bin
```

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

## Instalação

```bash
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.

```bash
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:

```bash
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`):

```bash
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:

```bash
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):

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

## Uso interativo

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

Ou defina os caminhos no `soc_mre.json` e execute:

```bash
soc-mre
```

## Linha de comando e modo stdin

```bash
soc-mre --help
python -m soc_mre --help
```

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

```bash
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.
