A primeira inicialização leva de 15 a 30 segundos enquanto o pool de navegadores aquece. As inicializações subsequentes são rápidas.

### Catálogos de aplicações NAS

Prefere uma instalação com um clique? O TRAWL está disponível nos catálogos de aplicações da comunidade tanto para TrueNAS como para Unraid:

- [TrueNAS Community Apps](https://apps.truenas.com/catalog/trawl_community/) —
  abra **Apps → Discover Apps** e procure por **TRAWL**.
- [Unraid Community Apps](https://ca.unraid.net/apps/trawl-1o4q23p06utr4h) —
  abra o separador **Apps** e procure por **Trawl**.

Agradecimentos aos contribuidores das comunidades TrueNAS e Unraid que empacotaram e publicaram estas integrações.

## API

### Compatível com FlareSolverr (`/v1`)```bash
curl -X POST http://localhost:8191/v1 \
  -H 'Content-Type: application/json' \
  -d '{"cmd":"request.get","url":"https://nowsecure.nl","maxTimeout":60000}'

### Ferramentas MCP (`/mcp`)

Defina `MCP_ENABLED=true` para expor as ferramentas Streamable HTTP independentes de cliente do TRAWL
para conteúdo legível, HTML, extração estruturada, capturas de ecrã e diagnósticos de navegador a qualquer
aplicação ou agente de IA compatível com MCP. Elas carregam URLs públicos conhecidos; o TRAWL não
fornece pesquisa ou classificação na web. Consulte o
[guia de integração MCP](https://github.com/germondai/trawl/blob/dev/apps/docs/integrations/mcp.md).

### Conectar Prowlarr / Jackett

Defina o URL do FlareSolverr para:```
http://localhost:8191        # running on the same host
http://trawl:8191            # running via Docker Compose on the same network

Por padrão, o listener vincula `0.0.0.0` para que clientes em uma rede bridge do Docker possam alcançá-lo; defina `MITM_HOST=127.0.0.1` para restringi-lo ao loopback em um host bare-metal.

1. Instale a CA do proxy no trust store do cliente para que ele aceite os certificados por host:
   `curl http://<trawl-host>:8191/proxy-ca.crt` → adicione ao CA store do contêiner Prowlarr
   (por exemplo, um script linuxserver `/custom-cont-init.d` que o copia para
   `/usr/local/share/ca-certificates/` e executa `update-ca-certificates`).
2. Prowlarr → Settings → Indexer Proxies → **HTTP**, host `<trawl-host>`, porta `8192`.
   Atribua uma tag se apenas indexers selecionados devem usá-lo.

Requisições comuns usam um caminho direto HTTP/TLS. Respostas pequenas de HTML, JSON e texto são armazenadas em buffer para detecção de desafios; desafios detectados escalam pelo mesmo pipeline de camadas que `POST /scrape`. Vídeos e respostas binárias grandes são transmitidos diretamente. Requisições Range são encaminhadas de ponta a ponta e podem escalar quando sua resposta é um desafio detectado; upgrades de WebSocket usam um relay direto sem escalonamento para navegador.

Consulte a [documentação completa do proxy](https://github.com/germondai/trawl/blob/dev/apps/docs/proxy/overview.md) para detalhes de roteamento, tráfego suportado, limitações, instalação da CA e exemplos de cliente.

> ⚠️ Um proxy MITM pode se passar por qualquer host para um cliente que confie em sua CA. Exponha-o apenas em uma interface privada (localhost / uma rede Docker privada), nunca publicamente.

### Instalando o certificado CA do proxy

O proxy autogera uma CA raiz na primeira execução. Seu certificado e chave privada são persistidos em `MITM_CA_DIR` (padrão `/data/proxy-ca`). Certificados por host são emitidos e armazenados em cache na memória enquanto o TRAWL é executado; eles não precisam de instalação separada porque são assinados pela raiz persistente. Todo cliente que usa o proxy deve confiar nessa raiz. Sem isso, o HTTPS falha com `ERR_CERT_AUTHORITY_INVALID` (navegadores) ou `PKIX path building failed` (Java).

Baixe a CA uma vez por cliente:```bash
curl http://<trawl-host>:8191/proxy-ca.crt -o trawl-ca.crt
# or in a Docker setup where the API isn't reachable from outside:
docker cp trawl:/data/proxy-ca/ca.crt ./trawl-ca.crt

#### Linux (Debian/Ubuntu — em todo o sistema para curl, wget, apt, etc.)```bash
sudo cp trawl-ca.crt /usr/local/share/ca-certificates/trawl-ca.crt
sudo update-ca-certificates
# Verify
awk '/BEGIN/{c++} c==2' /etc/ssl/certs/ca-certificates.crt | grep -c "TRAWL MITM"

#### Trust stores do Firefox e do NSS

Instalações do Firefox que não usam raízes do sistema operacional precisam de uma importação NSS por perfil:```bash
# Firefox 115+ uses a file-backed NSS DB; older versions use the legacy libnssdb format.
# The certutil command is the same either way.
certutil -A -n "TRAWL MITM" -t "CT,C,C" -i trawl-ca.crt \
  -d sql:$HOME/.mozilla/firefox/<profile-dir>
# Or via Firefox UI: Settings → Privacy & Security → Certificates → View Certificates →
# Authorities → Import… → check "Trust this CA to identify websites".
# Profile dir location: about:profiles in Firefox.

#### Java (incluindo JDownloader)```bash
# Find the JRE cacerts file for your client.
#   JDownloader:    <install>/jre/lib/security/cacerts
keytool -importcert -alias trawl -file trawl-ca.crt \
  -keystore "<path-to-cacerts>" -storepass changeit
# If `keytool` reports "Certificate already exists in keystore", use -delete first:
#   keytool -delete -alias trawl -keystore "<path-to-cacerts>" -storepass changeit

| `-s` | `--server` | `SERVER` | `http://localhost:8080` | URL base do servidor |
| `-t` | `--token` | `TOKEN` | | Token de autenticação |
| `-o` | `--output` | `OUTPUT` | | Arquivo de saída |
| `-f` | `--format` | `FORMAT` | `json` | Formato de saída |
| `-v` | `--verbose` | | | Saída detalhada |
| `-q` | `--quiet` | | | Modo silencioso |
| `-d` | `--debug` | | | Modo de depuração |
| `-c` | `--config` | `CONFIG` | | Arquivo de configuração |
| `-n` | `--no-color` | | | Desabilitar saída colorida |
| `-y` | `--yes` | | | Confirmar automaticamente |
| `-h` | `--help` | | | Mostrar mensagem de ajuda |
| `-V` | `--version` | | | Mostrar versão |

### Exemplos

```bash
# Iniciar o servidor
python3 server.py --port 8080

# Executar o cliente
python3 client.py --server http://localhost:8080

# Executar com opções
python3 client.py -s http://localhost:8080 -t mytoken -o output.json -f json -v

# Usar arquivo de configuração
python3 client.py -c config.yaml

# Modo silencioso
python3 client.py -q

# Modo de depuração
python3 client.py -d

project/
├── server.py           # Arquivo principal do servidor
├── client.py           # Arquivo principal do cliente
├── config.yaml         # Arquivo de configuração
├── requirements.txt    # Dependências do projeto
├── README.md           # Documentação do projeto
├── LICENSE             # Arquivo de licença
├── modules/            # Módulos do projeto
│   ├── __init__.py
│   ├── core.py         # Módulo principal
│   ├── utils.py        # Módulo de utilitários
│   └── handlers.py     # Módulo de manipuladores
├── tests/              # Testes do projeto
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
└── docs/               # Documentação do projeto
    ├── index.md
    └── api.md

# Clonar o repositório
git clone https://github.com/username/project.git
cd project

# Criar ambiente virtual
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# ou
venv\Scripts\activate     # Windows

# Instalar dependências
pip install -r requirements.txt

# Instalar dependências de desenvolvimento
pip install -r requirements-dev.txt

# Executar todos os testes
pytest

# Executar com cobertura
pytest --cov=modules --cov-report=html

# Executar testes específicos
pytest tests/test_core.py

# Executar com saída detalhada
pytest -v

# Executar em paralelo
pytest -n auto

# Executar linter
flake8 modules/

# Executar formatador
black modules/

# Executar verificador de tipos
mypy modules/

# Executar verificações de segurança
bandit -r modules/

# Executar todas as verificações
make lint

# Compilar o projeto
python3 -m build

# Compilar pacote wheel
python3 setup.py bdist_wheel

# Compilar pacote source
python3 setup.py sdist

# Limpar artefatos de compilação
make clean

# Compilar imagem Docker
docker build -t project:latest .

# Executar contêiner
docker run -d -p 8080:8080 --name project project:latest

# Executar com variáveis de ambiente
docker run -d -p 8080:8080 \
  -e SERVER_PORT=8080 \
  -e LOG_LEVEL=info \
  --name project project:latest

# Usar docker-compose
docker-compose up -d

# Visualizar logs
docker-compose logs -f

# Parar contêiner
docker-compose down

# Instalar o pacote
pip install .

# Instalar em modo de desenvolvimento
pip install -e .

# Executar o servidor
python3 server.py --port 8080 --host 0.0.0.0

# Executar como serviço
systemctl start project
systemctl enable project

# Verificar processo usando a porta
lsof -i :8080

# Encerrar processo
kill -9 <PID>

# Ou usar porta diferente
python3 server.py --port 8081

# Verificar permissões
ls -la

# Alterar permissões
chmod +x server.py
chmod +x client.py

# Verificar instalação do Python
python3 --version

# Verificar pacotes instalados
pip list

# Reinstalar dependências
pip install -r requirements.txt --force-reinstall

# Verificar conectividade
ping localhost

# Verificar portas abertas
netstat -tuln

# Verificar firewall
sudo ufw status

# Executar com saída de depuração
python3 server.py --debug

# Executar com nível de log
python3 server.py --log-level DEBUG

# Executar com rastreamento
python3 -m trace --trace server.py

# Mostrar ajuda
python3 server.py --help

# Mostrar versão
python3 server.py --version

# Verificar documentação
man project

# Verificar informações do pacote
pip show project

Este software é fornecido "como está", sem garantia de qualquer tipo,
expressa ou implícita, incluindo, mas não se limitando a, garantias de
comercialização, adequação a um propósito específico e não violação.

O LinuxServer executa scripts em `/custom-cont-init.d/` quando o container inicia. Clientes Java como o
JDownloader requerem a importação separada com `keytool` descrita acima.

#### JDownloader 2 (Windows / macOS / Linux — instalação manual)

O JDownloader inclui a sua própria JRE; a CA deve ser importada nela.

1. Localize a JRE: `Settings → Advanced → Java Path` (no JDownloader) ou procure no diretório de instalação:
   - Windows: `C:\Program Files\JDownloader 2\jre\lib\security\cacerts`
   - macOS: `/Applications/JDownloader 2.app/Contents/app/jre/lib/security/cacerts`
   - Linux: `<install>/jre/lib/security/cacerts`
2. Execute o comando `keytool -importcert` acima contra esse arquivo.
3. Reinicie o JDownloader.

#### Windows (repositório de confiança do sistema)```powershell
# Run PowerShell as Administrator.
Import-Certificate -FilePath .\trawl-ca.crt `
  -CertStoreLocation Cert:\LocalMachine\Root
# Remove later
Get-ChildItem Cert:\LocalMachine\Root | Where-Object { $_.Subject -like "*TRAWL MITM*" } | Remove-Item

## Arquivos Docker Compose

| Arquivo                      | Descrição                                                |
| ---------------------------- | -------------------------------------------------------- |
| `docker-compose.yml`         | Scraper + Redis (padrão)                                 |
| `docker-compose.minimal.yml` | Apenas scraper, sem Redis                                |
| `docker-compose.prod.yml`    | Produção: `restart: always`, limite de memória, healthcheck |

## Imagens Docker (um pacote GHCR, duas variantes de release)

| Tag da imagem                      | Construída a partir de         | Runtime                       | Caso de uso                                                |
| ---------------------------------- | ------------------------------ | ----------------------------- | ---------------------------------------------------------- |
| `ghcr.io/germondai/trawl:latest`   | `apps/api/Dockerfile`          | Bun 1.4.2 (moderno, AVX2)     | Padrão compacto — fingerprints Linux                       |
| `ghcr.io/germondai/trawl:baseline` | `apps/api/Dockerfile.baseline` | Bun 1.4.2 baseline (sem AVX2) | CPUs mais antigas / kernels mais antigos (Synology NAS, J4125, era Atom) |

Todas as tags ficam no mesmo pacote `ghcr.io/germondai/trawl` — compartilham o registry, mas diferem na origem do Dockerfile ou nos argumentos de build. Escolha a tag que se adequa ao seu hardware e saída:```yaml
# Modern hardware (most users)
image: ghcr.io/germondai/trawl:latest

# Older CPUs without AVX2 / Synology / older kernels
image: ghcr.io/germondai/trawl:baseline

## Configuração

O TRAWL suporta proxies HTTP, proxies HTTP autenticados e proxies SOCKS5. Os arquivos Compose
padrão leem as configurações de proxy do arquivo `.env` local:```ini
# Optional Tier 3 datacenter proxy
PROXY_URL=http://user:[email protected]:8080

# Optional Tier 4 residential proxy
RESIDENTIAL_PROXY_URL=socks5://user:[email protected]:1080

# Iniciar o servidor
python -m kitploit.server --port 8080

# Executar uma verificação
python -m kitploit.scan --target example.com

# Exportar resultados
python -m kitploit.export --format json --output results.json

# Clonar o repositório
git clone https://github.com/kitploit/kitploit.git
cd kitploit

# Criar ambiente virtual
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Instalar dependências de desenvolvimento
pip install -r requirements-dev.txt

# Instalar hooks de pré-commit
pre-commit install

# Executar todos os testes
pytest

# Executar com cobertura
pytest --cov=kitploit --cov-report=html

# Executar testes específicos
pytest tests/test_scanner.py -v

# Executar linter
ruff check .

# Formatar código
ruff format .

# Verificação de tipos
mypy kitploit/

Deixe qualquer um dos valores vazio para desativar esse nível de proxy. Vários endpoints podem ser separados por
vírgulas; pools maiores podem usar a variável correspondente `*_LIST_FILE`. Consulte
[Configuration → Proxies](https://github.com/germondai/trawl/blob/dev/apps/docs/getting-started/configuration.md#proxies)
para exemplos de pool e de arquivo montado.

| Variável                         | Padrão                   | Descrição                                                                           |
| -------------------------------- | ------------------------ | ----------------------------------------------------------------------------------- |
| `BROWSER_POOL_SIZE`              | `1`                      | Instâncias Camoufox Firefox pré-aquecidas; aumente para resoluções de browser concorrentes |
| `LOG_LEVEL`                      | `info`                   | Logs operacionais: `error`, `warn`, `info`, `debug` ou `silent`                     |
| `METRICS_DASHBOARD_ENABLED`      | `false`                  | Ativa explicitamente o dashboard local sem token; vincula a porta a `127.0.0.1`    |
| `METRICS_DASHBOARD_TOKEN`        | —                        | Protege o dashboard, o endpoint JSON e o stream ao vivo com um token de 32+ caracteres |
| `METRICS_DB_PATH`                | `/data/metrics/trawl.sqlite` | Caminho SQLite para o histórico local de métricas (monte `/data/metrics` de forma persistente) |
| `BROWSER_ACQUIRE_TIMEOUT_MS`     | `15000`                  | Quanto tempo `acquire()` aguarda por um browser livre antes de retornar HTTP 429    |
| `BROWSER_RECYCLE_AFTER_CONTEXTS` | `8`                      | Substituição contínua após este número de contextos Tier 3/4; defina `0` para desativar |
| `BROWSER_MAX_CONTENT_PROCESSES`  | `2`                      | Limita os processos de conteúdo do Firefox por browser (`dom.ipc.processCount`); reduz RAM/CPU |
| `SCRAPE_MIN_TIER`                | `1`                      | Nível mais baixo permitido globalmente (`1` HTTP, `2` browser em cache, `3` novo, `4` residencial) |
| `SESSION_CACHE_DRIVER`           | `redis`                  | Backend do cache de sessão: `redis` ou `memory` de processo único                   |
| `REDIS_SESSION_TTL_SECONDS`      | `3600`                   | TTL da sessão em Redis ou em memória (segundos)                                     |
| `MEMORY_SESSION_CACHE_MAX_ENTRIES` | `1000`                 | Número máximo de entradas limitadas por LRU para o driver de memória                |
| `REDIS_URL`                      | —                        | String de conexão Redis; vazio ou não definido desativa o cache Redis               |
| `REDIS_CONNECT_TIMEOUT_MS`       | `5000`                   | Tempo máximo para cada tentativa de conexão Redis                                   |
| `REDIS_RETRY_DELAY_MS`           | `5000`                   | Atraso antes de reconectar após falha na inicialização; `0` desativa a nova tentativa |
| `SCRAPE_PROXY_SELECTION`         | `failover`               | Política do pool: `failover` fixo, `roundrobin` por requisição ou `random`          |
| `PROXY_URL`                      | —                        | Proxy HTTP ou SOCKS5 opcional de Tier 3, ou pool separado por vírgulas              |
| `PROXY_LIST_FILE`                | —                        | Arquivo contendo uma URL de proxy Tier 3 por linha                                  |
| `RESIDENTIAL_PROXY_URL`          | —                        | Ativa a escalada para proxy Tier 4                                                  |
| `RESIDENTIAL_PROXY_LIST_FILE`    | —                        | Arquivo contendo uma URL de proxy Tier 4 por linha                                  |
| `STT_URL`                        | —                        | Endpoint Whisper local para reCAPTCHA (opcional)                                    |
| `PORT`                           | `8191`                   | Porta de escuta da API                                                              |
| `MITM_ENABLED`                   | `false`                  | Ativa o proxy HTTP/HTTPS que contorna desafios                                      |
| `MITM_PORT`                      | `8192`                   | Porta de escuta do forward-proxy                                                    |
| `MITM_HOST`                      | `0.0.0.0`                | Endereço de bind; `127.0.0.1` para apenas loopback                                  |
| `MITM_CA_DIR`                    | `/data/proxy-ca`         | Diretório persistente do certificado raiz CA e da chave privada                     |
| `MITM_MAX_TIER`                  | `4`                      | Limita a escalada usada pelo proxy (ex.: `3` para permanecer fora do residencial)   |
| `MITM_ALWAYS_SCRAPE`             | `false`                  | Ignora o Tier 0 do proxy; desativa o caminho direto de streaming de mídia/arquivos grandes |
| `MITM_DEBUG`                     | `false`                  | Registra uma linha por requisição proxyficada (erros são sempre registrados)        |

Atualizar a partir de uma versão anterior exige renomear várias variáveis de ambiente. Consulte o
[guia de migração de configuração](https://github.com/germondai/trawl/blob/dev/apps/docs/deployment/configuration-migration.md) para o mapeamento completo
de antigo para novo e o comportamento de adesão ao Redis.

## Stack

Construído sobre uma stack moderna e rápida por padrão: Bun + Elysia para a API, Redis para cache,
Camoufox (Firefox reforçado) para automação de browser e Nuxt para a interface web — sem bagagem
legada de Node/Express.

| Camada        | Tecnologia                         |
| ------------- | ---------------------------------- |
| Runtime       | Bun                                |
| API           | Elysia                             |
| Browser       | Camoufox Firefox (via camoufox-js) |
| Cache de sessão | Redis 8.8                        |
| Landing page  | Nuxt 4                             |
| Documentação  | VitePress                          |

## Licença

[AGPL-3.0](https://github.com/germondai/trawl/blob/dev/LICENSE)

---

<p align="center">
    <span>Feito com ❤️ por</span>
    <a href="https://github.com/germondai" target="_blank">@germondai</a>
</p>