trawl — Moteur de scraping auto-hébergé — contourne tout challenge JS et captcha : Cloudflare, Turnstile, reCAPTCHA, hCaptcha, GeeTest. Alternative à FlareSolverr et Byparr, et remplacement direct pour votre stack *arr. | Kitploit

Le premier démarrage prend 15 à 30 s pendant que le pool de navigateurs s'initialise. Les démarrages suivants sont rapides.

### Catalogues d'applications NAS

Vous préférez une installation en un clic ? TRAWL est disponible dans les
catalogues d'applications communautaires pour TrueNAS et Unraid :

- [TrueNAS Community Apps](https://apps.truenas.com/catalog/trawl_community/) —
  ouvrez **Apps → Discover Apps** et recherchez **TRAWL**.
- [Unraid Community Apps](https://ca.unraid.net/apps/trawl-1o4q23p06utr4h) —
  ouvrez l'onglet **Apps** et recherchez **Trawl**.

Merci aux contributeurs des communautés TrueNAS et Unraid qui ont empaqueté et
publié ces intégrations.

## API

### Compatible 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}'

### Outils MCP (`/mcp`)

Définissez `MCP_ENABLED=true` pour exposer les outils Streamable HTTP indépendants du client de TRAWL
pour le contenu lisible, le HTML, l'extraction structurée, les captures d'écran et les diagnostics du navigateur à toute
application ou agent IA compatible MCP. Ils chargent des URL publiques connues ; TRAWL ne
fournit pas de recherche web ni de classement. Consultez le
[guide d'intégration MCP](https://github.com/germondai/trawl/blob/dev/apps/docs/integrations/mcp.md).

### Connecter Prowlarr / Jackett

Définissez l'URL de FlareSolverr sur :```
http://localhost:8191        # running on the same host
http://trawl:8191            # running via Docker Compose on the same network

Par défaut, le listener se lie à `0.0.0.0` afin que les clients sur un réseau bridge Docker puissent l'atteindre ; définissez `MITM_HOST=127.0.0.1` pour le restreindre à la loopback sur un hôte bare-metal.

1. Installez le CA du proxy dans le trust store du client afin qu'il accepte les certificats par hôte :
   `curl http://<trawl-host>:8191/proxy-ca.crt` → ajoutez-le au CA store du conteneur Prowlarr
   (par exemple un script linuxserver `/custom-cont-init.d` qui le copie vers
   `/usr/local/share/ca-certificates/` et exécute `update-ca-certificates`).
2. Prowlarr → Settings → Indexer Proxies → **HTTP**, hôte `<trawl-host>`, port `8192`.
   Attribuez-lui un tag si seuls certains indexeurs doivent l'utiliser.

Les requêtes ordinaires empruntent un chemin HTTP/TLS direct. Les petites réponses HTML, JSON et texte sont mises en mémoire tampon pour la détection de challenge ; les challenges détectés escaladent via le même pipeline de niveaux que `POST /scrape`. Les vidéos et les réponses binaires volumineuses sont diffusées directement. Les requêtes Range sont transmises de bout en bout et peuvent escalader lorsque leur réponse est un challenge détecté ; les upgrades WebSocket utilisent un relais direct sans escalade vers le navigateur.

Consultez la [documentation complète du proxy](https://github.com/germondai/trawl/blob/dev/apps/docs/proxy/overview.md) pour les détails de routage, le trafic pris en charge, les limitations, l'installation du CA et des exemples de clients.

> ⚠️ Un proxy MITM peut usurper l'identité de n'importe quel hôte auprès d'un client qui fait confiance à son CA. Ne l'exposez que sur une interface privée (localhost / un réseau Docker privé), jamais publiquement.

### Installation du certificat CA du proxy

Le proxy auto-génère un CA racine au premier lancement. Son certificat et sa clé privée sont persistés sous `MITM_CA_DIR` (par défaut `/data/proxy-ca`). Les certificats par hôte sont générés et mis en cache en mémoire pendant l'exécution de TRAWL ; ils n'ont pas besoin d'être installés séparément car ils sont signés par la racine persistante. Chaque client qui utilise le proxy doit faire confiance à cette racine. Sans cela, HTTPS échoue avec `ERR_CERT_AUTHORITY_INVALID` (navigateurs) ou `PKIX path building failed` (Java).

Téléchargez le CA une fois par client :```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 — à l'échelle du système pour 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"

#### Dépôts de confiance Firefox et NSS

Les installations de Firefox qui n'utilisent pas les racines du système d'exploitation nécessitent un import NSS par profil :```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 (y compris 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` | Adresse du serveur C2 (par défaut : `127.0.0.1`) |
| `-p` | `--port` | Port du serveur C2 (par défaut : `443`) |
| `-t` | `--token` | Jeton d'authentification pour l'agent |
| `-i` | `--interval` | Intervalle de beacon en secondes (par défaut : `5`) |
| `-j` | `--jitter` | Pourcentage de gigue pour l'intervalle de beacon (par défaut : `0`) |
| `-d` | `--debug` | Activer la journalisation de débogage |
| `-h` | `--help` | Afficher le message d'aide |

### Exemples

Démarrer l'agent avec les paramètres par défaut :

```bash
./agent

Option courte	Option longue	Description
`-l`	`--listen`	Adresse d'écoute (par défaut : `0.0.0.0`)
`-p`	`--port`	Port d'écoute (par défaut : `443`)
`-c`	`--cert`	Chemin vers le fichier de certificat TLS
`-k`	`--key`	Chemin vers le fichier de clé TLS
`-d`	`--debug`	Activer la journalisation de débogage
`-h`	`--help`	Afficher le message d'aide

Option courte	Option longue	Description
`-s`	`--server`	Adresse du serveur C2 (par défaut : `127.0.0.1`)
`-p`	`--port`	Port du serveur C2 (par défaut : `443`)
`-t`	`--token`	Jeton d'authentification pour la charge utile
`-o`	`--output`	Chemin de sortie pour la charge utile générée (par défaut : `payload`)
`-h`	`--help`	Afficher le message d'aide

LinuxServer exécute des scripts dans `/custom-cont-init.d/` au démarrage du conteneur. Les clients Java tels que
JDownloader nécessitent l'import `keytool` distinct décrit ci-dessus.

#### JDownloader 2 (Windows / macOS / Linux — installation manuelle)

JDownloader embarque son propre JRE ; le CA doit y être importé.

1. Localisez le JRE : `Settings → Advanced → Java Path` (dans JDownloader) ou cherchez dans le répertoire d'installation :
   - 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. Exécutez la commande `keytool -importcert` ci-dessus sur ce fichier.
3. Redémarrez JDownloader.

#### Windows (magasin de certificats système)```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

## Fichiers Docker Compose

| Fichier                      | Description                                              |
| ---------------------------- | -------------------------------------------------------- |
| `docker-compose.yml`         | Scraper + Redis (par défaut)                             |
| `docker-compose.minimal.yml` | Scraper uniquement, sans Redis                           |
| `docker-compose.prod.yml`    | Production : `restart: always`, limite mémoire, healthcheck |

## Images Docker (un paquet GHCR, deux variantes de release)

| Tag de l'image                      | Construit depuis               | Runtime                       | Cas d'usage                                                |
| ---------------------------------- | ------------------------------ | ----------------------------- | ---------------------------------------------------------- |
| `ghcr.io/germondai/trawl:latest`   | `apps/api/Dockerfile`          | Bun 1.4.2 (moderne, AVX2)     | Par défaut compact — empreintes Linux                      |
| `ghcr.io/germondai/trawl:baseline` | `apps/api/Dockerfile.baseline` | Bun 1.4.2 baseline (sans AVX2) | CPU plus anciens / noyaux plus anciens (NAS Synology, J4125, ère Atom) |

Tous les tags résident sur le même paquet `ghcr.io/germondai/trawl` — ils partagent le registre mais diffèrent par la source du Dockerfile ou les arguments de build. Choisissez le tag adapté à votre matériel et à votre sortie :```yaml
# Modern hardware (most users)
image: ghcr.io/germondai/trawl:latest

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

## Configuration

TRAWL prend en charge les proxys HTTP, les proxys HTTP authentifiés et les proxys SOCKS5. Les fichiers Compose standard lisent les paramètres de proxy depuis le fichier `.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

# Lister tous les projets
kitploit-cli projects list

# Obtenir les détails d'un projet spécifique
kitploit-cli projects get --id 12345

# Créer un nouveau projet à partir d'un fichier de configuration
kitploit-cli projects create --file project.yaml

# Exporter les résultats au format JSON
kitploit-cli scan run --target example.com --output results.json --format json

# Utiliser un jeton d'authentification personnalisé
kitploit-cli --token "your-api-token" projects list

# Activer la sortie détaillée
kitploit-cli -v scan run --target example.com

Variable	Description
`KITPLOIT_SERVER`	URL du serveur cible
`KITPLOIT_TOKEN`	Jeton d'authentification
`KITPLOIT_OUTPUT`	Fichier de sortie
`KITPLOIT_FORMAT`	Format de sortie
`KITPLOIT_TIMEOUT`	Délai d'expiration de la requête
`KITPLOIT_RETRY`	Nombre de tentatives
`KITPLOIT_INSECURE`	Ignorer la vérification du certificat TLS

Laissez l'une ou l'autre valeur vide pour désactiver ce niveau de proxy. Plusieurs points de terminaison peuvent être séparés par
des virgules ; les pools plus importants peuvent utiliser la variable `*_LIST_FILE` correspondante. Voir
[Configuration → Proxies](https://github.com/germondai/trawl/blob/dev/apps/docs/getting-started/configuration.md#proxies)
pour des exemples de pools et de fichiers montés.

| Variable                         | Défaut                  | Description                                                                         |
| -------------------------------- | ------------------------ | ----------------------------------------------------------------------------------- |
| `BROWSER_POOL_SIZE`              | `1`                      | Instances Camoufox Firefox préchauffées ; augmentez pour les résolutions de navigateur concurrentes |
| `LOG_LEVEL`                      | `info`                   | Journaux opérationnels : `error`, `warn`, `info`, `debug` ou `silent`                     |
| `METRICS_DASHBOARD_ENABLED`      | `false`                  | Active explicitement le tableau de bord local sans jeton ; lie son port à `127.0.0.1` |
| `METRICS_DASHBOARD_TOKEN`        | —                        | Protège le tableau de bord, le point de terminaison JSON et le flux en direct avec un jeton de 32 caractères ou plus |
| `METRICS_DB_PATH`                | `/data/metrics/trawl.sqlite` | Chemin SQLite pour l'historique local des métriques (monter `/data/metrics` de manière persistante) |
| `BROWSER_ACQUIRE_TIMEOUT_MS`     | `15000`                  | Durée pendant laquelle `acquire()` interroge pour un navigateur libre avant qu'un HTTP 429 ne soit renvoyé |
| `BROWSER_RECYCLE_AFTER_CONTEXTS` | `8`                      | Remplacement progressif après ce nombre de contextes Tier 3/4 ; définir `0` pour désactiver |
| `BROWSER_MAX_CONTENT_PROCESSES`  | `2`                      | Limite les processus de contenu Firefox par navigateur (`dom.ipc.processCount`) ; réduit la RAM/CPU |
| `SCRAPE_MIN_TIER`                | `1`                      | Niveau le plus bas autorisé globalement (`1` HTTP, `2` navigateur en cache, `3` frais, `4` résidentiel) |
| `SESSION_CACHE_DRIVER`           | `redis`                  | Backend du cache de session : `redis` ou `memory` mono-processus                           |
| `REDIS_SESSION_TTL_SECONDS`      | `3600`                   | TTL de session Redis ou en mémoire (secondes)                                            |
| `MEMORY_SESSION_CACHE_MAX_ENTRIES` | `1000`                 | Nombre maximal d'entrées limitées par LRU pour le pilote mémoire                                   |
| `REDIS_URL`                      | —                        | Chaîne de connexion Redis ; vide ou non définie désactive le cache Redis                     |
| `REDIS_CONNECT_TIMEOUT_MS`       | `5000`                   | Durée maximale pour chaque tentative de connexion Redis                                      |
| `REDIS_RETRY_DELAY_MS`           | `5000`                   | Délai avant reconnexion après un échec de démarrage ; `0` désactive la nouvelle tentative                 |
| `SCRAPE_PROXY_SELECTION`         | `failover`               | Politique de pool : `failover` persistant, `roundrobin` par requête ou `random`                |
| `PROXY_URL`                      | —                        | Proxy HTTP ou SOCKS5 Tier 3 facultatif, ou pool séparé par des virgules                       |
| `PROXY_LIST_FILE`                | —                        | Fichier contenant une URL de proxy Tier 3 par ligne                                       |
| `RESIDENTIAL_PROXY_URL`          | —                        | Active l'escalade vers le proxy Tier 4                                                     |
| `RESIDENTIAL_PROXY_LIST_FILE`    | —                        | Fichier contenant une URL de proxy Tier 4 par ligne                                       |
| `STT_URL`                        | —                        | Point de terminaison Whisper local pour reCAPTCHA (facultatif)                                     |
| `PORT`                           | `8191`                   | Port d'écoute de l'API                                                                     |
| `MITM_ENABLED`                   | `false`                  | Active le proxy HTTP/HTTPS contournant les challenges                                     |
| `MITM_PORT`                      | `8192`                   | Port d'écoute du proxy de transfert                                                           |
| `MITM_HOST`                      | `0.0.0.0`                | Adresse de liaison ; `127.0.0.1` pour une écoute en boucle locale uniquement                                         |
| `MITM_CA_DIR`                    | `/data/proxy-ca`         | Répertoire persistant du certificat CA racine et de la clé privée                            |
| `MITM_MAX_TIER`                  | `4`                      | Limite l'escalade utilisée par le proxy (par ex. `3` pour rester hors du résidentiel)                 |
| `MITM_ALWAYS_SCRAPE`             | `false`                  | Ignore le Tier 0 du proxy ; désactive le chemin de streaming direct des médias/gros fichiers               |
| `MITM_DEBUG`                     | `false`                  | Journalise une ligne par requête proxifiée (les erreurs sont toujours journalisées)                         |

La mise à niveau depuis une version antérieure nécessite de renommer plusieurs variables d'environnement. Consultez le
[guide de migration de configuration](https://github.com/germondai/trawl/blob/dev/apps/docs/deployment/configuration-migration.md) pour la correspondance complète
ancien-vers-nouveau et le comportement d'activation de Redis.

## Stack

Construit sur une stack moderne et rapide par défaut : Bun + Elysia pour l'API, Redis pour la mise en cache,
Camoufox (Firefox renforcé) pour l'automatisation du navigateur, et Nuxt pour l'interface web — sans le bagage
hérité de Node/Express.

| Couche         | Technologie                         |
| ------------- | ---------------------------------- |
| Runtime       | Bun                                |
| API           | Elysia                             |
| Navigateur       | Camoufox Firefox (via camoufox-js) |
| Cache de session | Redis 8.8                          |
| Page d'accueil  | Nuxt 4                             |
| Documentation | VitePress                          |

## Licence

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

---

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

TRAWL35

TRAWL40

trawl

Populaires

TRAWL

Bienvenue sur TRAWL ! 👋

Fonctionnalités

Sponsors

Tableau de bord local

Démarrage rapide```bash

Clone and configure

Start scraper + Redis

Verify

API native (/scrape)

Proxy HTTP/HTTPS contournant les challenges

macOS (trousseau du système — affecte la plupart des applications, y compris Safari, curl, wget)```bash

Verify

Remove later

Linux (RHEL/Fedora/Amazon)```bash

Chrome / Chromium (Linux : séparé de la confiance système)

Option A: launch Chrome with --user-data-dir + NSS DB update (same as Firefox).

Option B: use Chrome's --ignore-certificate-errors-spki-list= (per-session, less safe).

Option C: add the cert to the system store (above) — Chrome picks it up automatically on

most Linux distros via the nss-tool lookup.

In the client's Compose service:

Serveur

Compilation

Exécution

Options de ligne de commande

Exemples

Interface Web

Accès à l'interface web

Fonctionnalités

Captures d'écran

Charge utile

Génération d'une charge utile

Options de ligne de commande

Exemples

Développement

Prérequis

Configuration

Tests

Analyse statique

Contribution

Licence

Remerciements

Suppression de l'autorité de certification (nettoyage)

Niveaux```

Releases & versioning

Exemples

Fichier de configuration

Variables d'environnement

Dépannage

Problèmes courants

Journaux

Obtenir de l'aide

Contribuer

Signaler des vulnérabilités

Licence

Remerciements

API native (`/scrape`)