> [!IMPORTANTE]
> **Os arquivos `sources/*.json` são artefatos gerados automaticamente. Nunca os edite diretamente.**
> Todas as adições e modificações de fontes devem ser feitas em `build_sources.py` e aplicadas executando `python build_sources.py`. Edições manuais serão sobrescritas na próxima compilação.

#### Esquema da Fonte```json
{
  "name": "MyPrivateDB",
  "endpoint": "https://api.myprivatedb.com/search?q={target}",
  "method": "GET",
  "headers": { "Authorization": "Bearer {MY_API_KEY}" },
  "regex_pattern": "([\\w.+-]+@[\\w-]+\\.[\\w.]+):([\\S]+)",
  "required_api_key_name": "MY_API_KEY",
  "api_key_slots": ["{MY_API_KEY}"],
  "input_type": "email",
  "output_type": ["username", "ip"],
  "pivot_types": ["email", "username"],
  "confidence": 0.9
}

`scan` (sem `--autoscan`) executa apenas a Fase 1 — fontes de violação, sem pivot/dork/scrape.

---

### Motor de Avalanche Recursivo

Cada identificador descoberto durante uma varredura — de registros de violação, resultados de dork ou conteúdo raspado de paste/Telegram — é tratado como uma nova semente de inteligência. Para cada ativo, o motor executa quatro fases sequencialmente: varredura de violações → crack de hash → dork → raspagem. Os identificadores extraídos de **todas as quatro fases** são coletados e reinjetados como novas sementes. Os ativos filhos são então processados concorrentemente via `asyncio.gather`.```
[email protected]
  └─► [Breach] username: j.doe      ──► [Breach + Crack + Dork + Scrape]
  │         └─► github.com/jdoe     ──► [Breach + Crack + Dork + Scrape]
  └─► [Breach] hash: 5f4dcc...      ──► [AutoCrack] → "password123"
  │         └─► [Breach] password-recycling scan across all sources
  └─► [Dork] [email protected]          ──► [Breach + Crack + Dork + Scrape]
  └─► [Scrape/paste] [email protected] ──► [Breach + Crack + Dork + Scrape]

Exportações JSON incluem um bloco `_meta` com `scan_id`, `target`, `timestamp`, `nox_version` e `pivot_depth_reached` — tornando cada exportação autodescritiva para ingestão em plataformas de gerenciamento de casos.

Toda a saída é sanitizada — erros de proxy, timeouts e tracebacks são removidos. Apenas inteligência acionável é incluída.

---

## Layout do Sistema de Arquivos```
~/.nox/
├── sources/               # Auto-generated JSON source plugins
├── reports/               # Generated forensic reports
├── logs/                  # Runtime log (nox.log)
├── wordlists/             # Hash cracking wordlists
├── vault/                 # Secure storage
└── nox_cache.db           # Forensic persistence database (SQLite)

~/.config/nox-cli/
├── apikeys.json           # API keys — chmod 0600, never committed to VCS
└── logs/
    └── nox_system.log     # Silent system log: API events, rate-limits, crack attempts

# .deb install (isolated venv)
/opt/nox-cli/
├── nox.py
├── build_sources.py
├── requirements.txt
├── sources/
└── .venv/                 # Isolated Python environment (PEP 668 compliant)

O script de pós-instalação automaticamente:
1. Cria um ambiente virtual isolado em `/opt/nox-cli/.venv`
2. Instala todas as dependências Python dentro do venv (compatível com PEP 668 — zero poluição do sistema)
3. Compila os 124 plugins de fonte
4. Vincula `/usr/bin/nox-cli` → `/opt/nox-cli/nox-wrapper.sh`

### Opção 2: A partir do código fonte```bash
git clone https://github.com/nox-project/nox-framework.git
cd nox-framework
pip install -r requirements.txt
python build_sources.py
python3 nox.py

**Passo 2 — Configurar chaves de API**

`build_sources.py` cria `~/.config/nox-cli/apikeys.json` na primeira execução, pré-preenchido com todos os serviços suportados. O arquivo tem permissão `chmod 0600` e nunca é enviado para o VCS.

Este é o **repositório canônico único de chaves** — todas as fontes o leem em tempo de execução.```bash
# Edit the file directly
nano ~/.config/nox-cli/apikeys.json

# Or inspect plugin status and key configuration
nox-cli --list-sources

---

---

## Referência da CLI```
usage: nox-cli [-h] [-t TARGET] [-i] [--version]
               [--autoscan] [--fullscan] [--no-pivot] [--depth N]
               [--dork TARGET] [--scrape TARGET]
               [--crack HASH] [--no-online-crack]
               [--analyze PASS] [--list-sources] [--reset-sources]
               [--tor] [--proxy URL] [--guardian-off] [--allow-leak]
               [--threads N] [--timeout N]
               [-o FILE] [--format {json,csv,html,md,pdf}]
               [--diff]

  -t, --target TARGET     Target to scan (auto-detected type)
  -i, --interactive       Launch interactive REPL
  --version               Show version and exit
  --autoscan              Full pipeline: breach + pivot + dork + scrape
  --fullscan              Breach + pivot only (no dork/scrape)
  --no-pivot              Disable recursive pivot enrichment
  --depth N               Avalanche pivot depth (default: 2)
  --dork TARGET           Google/Bing/SearXNG dorking for leaked documents
  --scrape TARGET         Paste site + Telegram scraping
  --crack HASH            Identify and crack a hash
  --no-online-crack       Local wordlist only — no data sent to third-party APIs
  --analyze PASS          Deep password strength analysis
  --list-sources          Plugin debug: input type, confidence, key status
  --reset-sources         Force resync of source plugins from package
  --tor                   Route all traffic through Tor (port 9050)
  --proxy URL             HTTP/S or SOCKS5 proxy URL
  --guardian-off          Bypass OPSEC kill-switch (direct connection)
  --allow-leak            Allow direct connection if proxy/Tor is unavailable
  --threads N             Concurrency limit (default: 20)
  --timeout N             Request timeout in seconds (default: 15)
  -o, --output FILE       Output file path
  --format FORMAT         Output format: json, csv, html, md, pdf
  --diff                  Show only new findings vs last cached scan

--pdf DEBUG
        Habilitar saída detalhada da análise de PDF.

    --crack WORDLIST, -c WORDLIST
        Quebrar hashes de senha usando um arquivo de wordlist.

    --generate-pdf-template OUTPUT_PATH
        Gerar um PDF de exemplo com metadados interessantes para testes.

    --version, -v
        Mostrar número da versão e sair.

    -h, --help
        Mostrar esta mensagem de ajuda e sair.


### Exemplos

1. Análise básica de um PDF:
    ```
    pdfsleuth -f document.pdf
    ```
2. Extrair todos os objetos e fluxos:
    ```

    pdfsleuth -f document.pdf --extract-all
    ```

3. Extrair objeto específico (por exemplo, obj 5):
    ```
    pdfsleuth -f document.pdf --extract 5
    ```

4. Pesquisar por uma string específica:
    ```
    pdfsleuth -f document.pdf --search "password"
    ```

5. Verificar PDF com regras YARA:
    ```
    pdfsleuth -f document.pdf --yara rules/malicious.yar
    ```

6. Verificar assinaturas digitais:
    ```
    pdfsleuth -f document.pdf --verify
    ```

7. Salvar extração em diretório:
    ```
    pdfsleuth -f document.pdf --extract-all -o /path/to/output
    ```

8. Extrair código JavaScript:
    ```
    pdfsleuth -f document.pdf --extract-js
    ```

9. Analisar estrutura:
    ```
    pdfsleuth -f document.pdf --analyze
    ```

10. Extrair metadados:
    ```

    pdfsleuth -f document.pdf --metadata
    ```

11. Usar configuração personalizada:
    ```
    pdfsleuth -f document.pdf -c config.json
    ```

12. Quebrar hash com wordlist:
    ```
    pdfsleuth -f document.pdf --crack wordlist.txt
    ```

13. Executar com saída detalhada:
    ```

    pdfsleuth -f document.pdf -vvv
    ```

14. Gerar PDF de teste:

    pdfsleuth --generate-pdf-template test.pdf
    ```

15. Verificação rápida de todos os PDFs em um diretório:
    ```

    pdfsleuth -d /path/to/pdfs/ -q
    ```


### Requisitos

* Python 3.8 ou superior
* Bibliotecas necessárias:
    * pycryptodome
    * pyyaml
    * colorama
    * rich
    * yara-python (opcional - para verificação YARA)
    * pdfminer.six (opcional - para extração de texto)

### Instalação

#### Do PyPI (Recomendado)

#### A partir do código fonte

### Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request. Para mudanças significativas, por favor abra uma issue primeiro para discutir o que gostaria de alterar.

### Licença

Distribuído sob a licença BSD-3-Clause. Consulte o arquivo [LICENSE](https://github.com/nox-project/nox-framework/blob/HEAD/LICENSE) para detalhes.```
Command        Description
-----------    ---------------------------------------------------------------
autoscan       Full pipeline: breach + pivot + dork + scrape
scan           Breach intelligence scan only
dork           Google/Bing/SearXNG dorking for leaked documents
scrape         Paste site + Telegram scraping
crack          Identify and crack a hash
analyze        Deep password strength analysis
graph          ASCII identity graph of last scan
visualize      ASCII relationship map (Target → Data → Pivots)
pivot <n>      Re-scan using result #n as new pivot seed
search <q>     Filter in-memory records by keyword
sources        Plugin debug: input type, confidence, key status
export         Export results (json / csv / html / md / pdf)
tor            Toggle Tor routing on/off
proxy          Set or clear proxy URL
config         Configure threads / timeout / depth
help           Show this menu
quit           Exit NOX

---

## Gerenciamento de Fontes

### Adicionando uma Fonte

**1. Defina em `build_sources.py`:**```python
_auth("NewIntelDB", "breaches",
      "https://api.newinteldb.com/v1/search?q={target}", "GET",
      {"results": "$.results"},
      headers={"X-API-Key": "{NEWINTELDB_API_KEY}"},
      api_key_slots=["{NEWINTELDB_API_KEY}"],
      normalization_map={"email": "email", "password": "password"},
      input_type="email",
      output_type=["username", "ip"],
      confidence=0.85)

> [!NOTE]
> O builder valida cada fonte no momento da construção: endpoints GET devem conter `{target}`, fontes voláteis devem ter `reliability_score ≤ 4`, e o campo `confidence` pode ser definido explicitamente para substituir o valor derivado da fórmula.

---

## Construindo o Pacote .deb```bash
gem install fpm
bash build_deb.sh
sudo dpkg -i dist/nox-cli_*_all.deb