Retour aux mises à jour
New releaseSep 12, 2026

Krawl v2.4.0

Krawl est un serveur de déception web personnalisable, léger et natif du cloud, ainsi qu'un anti-crawler, qui crée de fausses applications web présentant des vulnérabilités faciles à exploiter en utilisant des données leurres réalistes générées aléatoirement et des modèles HTML générés par IA.

Partager

Krawl

Un serveur honeypot web moderne et personnalisable conçu pour détecter et suivre l'activité malveillante des attaquants et des robots d'exploration web grâce à des pages web trompeuses, de faux identifiants et des canary tokens.

Table des matières

Démo

Astuce : explorez les chemins du robots.txt pour plus de plaisir

URL de Krawl : http://demo.krawlme.com

Consultez le tableau de bord http://demo.krawlme.com/das_dashboard

Qu'est-ce que Krawl ?

Krawl est un serveur de tromperie cloud‑native conçu pour détecter, retarder et analyser les attaquants malveillants, les robots d'exploration web et les scanners automatisés.

Il crée de fausses applications web réalistes remplies de cibles faciles telles que des panneaux d'administration, des fichiers de configuration et de faux identifiants exposés afin d'attirer et d'identifier les activités suspectes.

dashboard

En gaspillant les ressources des attaquants, Krawl aide à distinguer clairement les comportements malveillants des robots d'exploration légitimes.

Il comprend :

  • Pages de tromperie générées par IA : Laissez les attaquants vous aider à générer votre fausse surface d'attaque vulnérable
  • Pages Spider Trap : Liens aléatoires infinis pour gaspiller les ressources des robots d'exploration, basées sur le projet spidertrap
  • Fausses pages de connexion : WordPress, phpMyAdmin, panneaux d'administration
  • Chemins honeypot : Annoncés dans robots.txt pour piéger les scanners
  • Faux identifiants : Noms d'utilisateur, mots de passe et clés API d'apparence réaliste
  • Intégration de Canary Token : Déclenchement d'alertes externes
  • En-têtes de serveur aléatoires : Confusion des attaques basées sur l'en-tête et la version du serveur
  • Tableau de bord en temps réel : Surveillance de l'activité suspecte
  • Listes de mots personnalisables : Configuration facile basée sur JSON
  • Injection d'erreurs aléatoires : Imitation du comportement d'un vrai serveur

Vous pouvez facilement exposer Krawl aux côtés de vos autres services pour les protéger des robots d'exploration web et des utilisateurs malveillants à l'aide d'un reverse proxy. Pour plus de détails, consultez la documentation sur le reverse proxy.

use case

Tableau de bord Krawl

Krawl fournit un tableau de bord complet, accessible à un chemin secret aléatoire généré au démarrage ou à un chemin personnalisé configuré via KRAWL_DASHBOARD_SECRET_PATH. Cela permet de garder le tableau de bord caché des attaquants qui scannent votre honeypot.

Le tableau de bord est organisé en six onglets :

  • Vue d'ensemble : vue globale de l'activité d'attaque : une carte interactive des origines IP, les requêtes suspectes récentes, et les principales IP, User-Agents et chemins.

geoip

  • Attaques : répartition détaillée des identifiants capturés, des déclenchements de honeypot et des types d'attaques détectées (SQLi, XSS, path traversal, etc.) avec graphiques et tableaux.

attack_types

  • Menaces : charges utiles regroupées en campagnes par hachage flou TLSH, de sorte qu'un webshell et ses variantes modifiées soient lus comme une seule campagne plutôt que comme des occurrences sans lien, avec un index de chaque fichier capturé.

  • Analyse IP : vue forensique approfondie d'une IP sélectionnée : géolocalisation, informations FAI/ASN, indicateurs de réputation, chronologie comportementale, répartition des types d'attaque, historique des référents, fichiers et identifiants capturés, et historique complet des accès.

ipinsight

De plus, après authentification avec le mot de passe du tableau de bord, des onglets protégés deviennent disponibles :

  • IP suivies : maintenez une liste de surveillance des adresses IP que vous souhaitez surveiller dans le temps.
  • Liste de bannissement IP : gérez les bannissements d'IP, consultez les attaquants détectés et exportez la liste de bannissement au format brut ou IPTables.
  • IP expirées : consultez les IP actuellement retenues dans le tarpit, et exemptez celles qui ne devraient pas l'être.
  • Tromperie : gérez les pages générées par IA, exportez-les ou importez-en de nouvelles.
  • Webhooks : transférez les bannissements vers CloudFlare et d'autres pare-feu.

Les icônes d'en-tête ouvrent la documentation de l'API, l'export de la liste de bannissement, et un panneau de paramètres affichant la configuration en cours ainsi qu'une page de maintenance pour exécuter les tâches planifiées à la demande.

Pour plus de détails, consultez la documentation du tableau de bord.

Modes de déploiement

Krawl prend en charge deux modes de déploiement, contrôlés par le paramètre mode dans config.yaml ou la variable d'environnement KRAWL_MODE.

StandaloneScalable
Base de donnéesSQLite (mode WAL)PostgreSQL
CacheDictionnaire Python en mémoireRedis (TTL multi-niveaux)
Réplicas1 (instance unique)1+ (mise à l'échelle horizontale)
Dépendances externesAucunePostgreSQL + Redis
Idéal pourDev, homelabs, <500k requêtesProduction, HA, >500k requêtes

Standalone : idéal pour les environnements de développement ou les homelabs à faible volume de requêtes. Aucune configuration supplémentaire nécessaire, lancez simplement Krawl et cela fonctionne.

  • Déploiement en conteneur unique sans dépendances externes
  • Utilisation réduite de RAM et de ressources

Scalable : conçu pour les environnements de production ou les honeypots à fort trafic. Le chart Helm utilise ce mode par défaut.

  • Tableau de bord plus rapide et plus réactif grâce au cache multi-niveaux Redis
  • E/S disque réduites avec Redis agissant comme cache de chemin chaud devant PostgreSQL
  • Mise à l'échelle horizontale : augmentez le nombre de réplicas Krawl derrière un load balancer

Pour une configuration détaillée, des exemples Docker Compose, une configuration Kubernetes/Helm et des instructions de migration étape par étape, consultez la documentation sur les modes de déploiement.

Liste de bannissement Krawl

Krawl maintient une banlist.txt régulièrement mise à jour contenant les adresses IP des attaquants ayant déclenché ses pièges honeypot. La liste de bannissement est publiée chaque semaine et disponible au téléchargement, aidant la communauté à bloquer de manière préventive les acteurs malveillants connus, même sans utiliser Krawl.

La liste de bannissement peut également être récupérée directement depuis : https://demo.krawlme.com/das_dashboard/api/export-ips?categories=attacker&fwtype=raw.

Partage des listes de bannissement entre instances

Les instances Krawl peuvent fédérer leurs listes de bannissement : chacune peut publier sa propre liste sur un chemin non authentifié et récupérer les listes d'autres instances (ou toute liste d'IP en texte brut). Les IP récupérées sont fusionnées dans les décisions de bannissement locales et affichées dans le tableau de bord.```yaml banlist:

Public, unauthenticated download path for this instance's banlist.

Supports the same ?categories= and ?fwtype= parameters as the main API.

Empty = disabled.

export_path: "/public_banlist.txt"

Upstream banlists to fetch and merge. Plain ".txt" lists work too.

sources: - "https://demo.krawlme.com/das_dashboard/api/export-ips?categories=attacker&fwtype=raw" - "https://krawl.example.com/public_banlist.txt"

refresh_interval: 3600 # seconds between fetches

## Démarrage rapide

### Docker Run

Exécutez Krawl en mode autonome avec la dernière image :```bash
docker run -d \
  -p 5000:5000 \
  -e KRAWL_DASHBOARD_SECRET_PATH="/my-secret-dashboard" \
  -e KRAWL_DASHBOARD_PASSWORD="my-secret-password" \
  -v krawl-data:/app/data \
  --name krawl \
  ghcr.io/blessedrebus/krawl:latest

Accédez au serveur à l'adresse http://localhost:5000

Docker Compose

Créez un fichier docker-compose.yaml avec l'un des deux modes de déploiement.

Standalone : uniquement le serveur Krawl avec un stockage Sqlite :```yaml services: krawl: image: ghcr.io/blessedrebus/krawl:latest container_name: krawl-server ports: - "5000:5000" environment: - CONFIG_LOCATION=config.yaml # - KRAWL_DASHBOARD_PASSWORD=my-secret-password volumes: - ./config.yaml:/app/config.yaml:ro - krawl-data:/app/data restart: unless-stopped

volumes: krawl-data:

**Scalable** : avec PostgreSQL et Redis :

> [!CAUTION]
> L'exemple ci-dessous utilise des **mots de passe par défaut** (`krawl`/`krawl`). **Changez-les avant de déployer en production.**```yaml
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: krawl
      POSTGRES_USER: krawl
      POSTGRES_PASSWORD: krawl
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U krawl -d krawl"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  krawl:
    image: ghcr.io/blessedrebus/krawl:latest
    container_name: krawl-server
    ports:
      - "5000:5000"
    environment:
      - CONFIG_LOCATION=config.yaml
      - KRAWL_MODE=scalable
      - KRAWL_POSTGRES_HOST=postgres
      - KRAWL_POSTGRES_PORT=5432
      - KRAWL_POSTGRES_USER=krawl
      - KRAWL_POSTGRES_PASSWORD=krawl
      - KRAWL_POSTGRES_DATABASE=krawl
      - KRAWL_REDIS_HOST=redis
      - KRAWL_REDIS_PORT=6379
      # - KRAWL_DASHBOARD_PASSWORD=my-secret-password
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

volumes:
  postgres_data:
  redis_data:

Pour déployer, exécutez simplement```bash docker compose up -d

Des fichiers compose prêts pour la production sont également disponibles dans le répertoire [`docker/`](https://github.com/blessedrebus/krawl/blob/main/docker). Pour le **développement** (compilations depuis les sources avec rechargement à chaud), utilisez les fichiers compose dans [`docker/dev/`](https://github.com/blessedrebus/krawl/blob/main/docker/dev).

Pour plus de détails sur les deux modes, consultez [Modes de déploiement](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md).

### Kubernetes
**Krawl est également disponible nativement sur Kubernetes**. L'installation peut se faire soit [via manifeste](https://github.com/blessedrebus/krawl/blob/main/kubernetes/README.md), soit [en utilisant le chart Helm](https://github.com/blessedrebus/krawl/blob/main/helm/README.md).

Le chart Helm **utilise par défaut le mode scalable** avec PostgreSQL et Redis intégrés :```bash
helm install krawl oci://ghcr.io/blessedrebus/krawl-chart --version 2.4.0 \
  -n krawl-system --create-namespace \
  --set postgres.password=your-password \
  --set redis.password=your-redis-password \
  --set dashboardPassword=your-dashboard-password \
  --set config.dashboard.secret_path=/my-secret-dashboard

Des fichiers de valeurs d'exemple minimaux sont fournis pour les deux modes :

Voir Modes de déploiement et Documentation du chart pour la configuration complète et les instructions de migration.

Uvicorn (Python)

Exécutez Krawl directement avec Python 3.13+ et uvicorn pour le développement local ou les tests :```bash pip install -r requirements.txt uvicorn app:app --host 0.0.0.0 --port 5000 --app-dir src --no-server-header

Accédez au serveur à l'adresse `http://localhost:5000`


## Configuration
Krawl utilise une **hiérarchie de configuration** dans laquelle **les variables d'environnement ont la priorité sur le fichier de configuration**. Cette approche est recommandée pour les déploiements Docker et une personnalisation rapide prête à l'emploi.

### Configuration via config.yaml
Vous pouvez utiliser le fichier [config.yaml](https://github.com/blessedrebus/krawl/blob/main/config.yaml) pour des configurations avancées, telles que les déploiements Docker Compose ou Helm chart.

### Configuration via les variables d'environnement

Tous les paramètres peuvent être fournis sous forme de variables d'environnement, qui remplacent `config.yaml`.
Le nom de la variable est `KRAWL_` suivi du chemin du paramètre en majuscules, ainsi `dashboard.password`
devient `KRAWL_DASHBOARD_PASSWORD`.

<details>
<summary><b>Serveur et génération de liens</b> (11 variables)</summary>

Comment Krawl se présente et façonne le labyrinthe des pages générées.

| Variable d'environnement | Description | Valeur par défaut |
|----------------------|-------------|---------|
| `CONFIG_LOCATION` | Chemin vers le fichier de configuration yaml | `config.yaml` |
| `KRAWL_PORT` | Port d'écoute du serveur | `5000` |
| `KRAWL_DELAY` | Délai de réponse en millisecondes | `100` |
| `KRAWL_SERVER_HEADER` | En-tête HTTP Server pour la tromperie | `""` |
| `KRAWL_LINKS_LENGTH_RANGE` | Plage de longueur des liens sous la forme `min,max` | `5,15` |
| `KRAWL_LINKS_PER_PAGE_RANGE` | Liens par page sous la forme `min,max` | `10,15` |
| `KRAWL_CHAR_SPACE` | Caractères utilisés pour la génération de liens | `abcdefgh...` |
| `KRAWL_MAX_COUNTER` | Valeur initiale du compteur | `10` |
| `KRAWL_PROBABILITY_ERROR_CODES` | Probabilité de réponse d'erreur (0-100%) | `0` |
| `KRAWL_INFINITE_PAGES_FOR_MALICIOUS` | Servir des pages infinies aux IP malveillantes | `true` |
| `KRAWL_MAX_PAGES_LIMIT` | Limite maximale de pages pour les crawlers | `250` |
| `KRAWL_BAN_DURATION_SECONDS` | Durée de bannissement en secondes pour les IP à débit limité | `600` |

</details>

<details>
<summary><b>Tableau de bord, métriques et journalisation</b> (13 variables)</summary>

Accès au tableau de bord, préchauffage du cache, Prometheus et niveau de journalisation.

| Variable d'environnement | Description | Valeur par défaut |
|----------------------|-------------|---------|
| `KRAWL_DASHBOARD_SECRET_PATH` | Chemin personnalisé du tableau de bord | Généré automatiquement |
| `KRAWL_DASHBOARD_PASSWORD` | Mot de passe pour les panneaux protégés du tableau de bord | Généré automatiquement |
| `KRAWL_DASHBOARD_CACHE_WARMUP` | Pré-calculer les données du tableau de bord toutes les 5 minutes pour un chargement instantané des pages | `true` |
| `KRAWL_DASHBOARD_WARMUP_PAGES` | Nombre de pages à préchauffer par panneau de table | `10` |
| `KRAWL_DASHBOARD_WARMUP_AGGREGATION` | Pré-calculer les agrégations complètes top_paths/top_ua pour un service sans requête | `false` |
| `KRAWL_DASHBOARD_TOP_N_MIN_COUNT` | Nombre d'accès minimum pour les panneaux top paths/user agents (définir à 1 pour désactiver) | `5` |
| `KRAWL_DASHBOARD_BRAND_NAME` | Nom dans le logo textuel et le titre du tableau de bord | `Krawl` |
| `KRAWL_DASHBOARD_BRAND_URL` | Vers quoi le logo textuel renvoie (vide l'affiche en texte brut) | Dépôt de Krawl |
| `KRAWL_DASHBOARD_BRAND_LOGO` | URL de l'image affichée à la place du logo GitHub | Non défini |
| `KRAWL_DASHBOARD_BRAND_SHOW_VERSION` | Afficher la version à côté du nom | `true` |
| `KRAWL_DASHBOARD_BRAND_CONTACT` | Contact affiché sous le logo textuel (adresse, URL ou texte brut) | Non défini |
| `KRAWL_METRICS_ENABLED` | Exposer les métriques Prometheus à `/<dashboard_path>/metrics` | `true` |
| `KRAWL_LOG_LEVEL` | Niveau de journalisation de l'application (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |

</details>

<details>
<summary><b>Base de données, rétention et sauvegardes</b> (12 variables)</summary>

Emplacement de stockage, durée de conservation des données et tâche de dump.

| Variable d'environnement | Description | Valeur par défaut |
|----------------------|-------------|---------|
| `KRAWL_DATABASE_PATH` | Emplacement du fichier de base de données | `data/krawl.db` |
| `KRAWL_DATABASE_PERSIST_SUSPICIOUS_ONLY` | Ne persister que les requêtes suspectes dans le journal d'accès | `false` |
| `KRAWL_MAP_TILE_URL` | Modèle d'URL de tuile pour la carte du tableau de bord (`{z}/{x}/{y}`, `{s}`/`{r}` optionnels) | Esri dark canvas |
| `KRAWL_MAP_TILE_ATTRIBUTION` | Attribution affichée sur la carte | Esri/OSM |
| `KRAWL_MAP_API_KEY` | Ajoutée à chaque requête de tuile en tant que paramètre de requête — requise par CARTO | _(vide)_ |
| `KRAWL_MAP_API_KEY_PARAM` | Nom de ce paramètre de requête (`api_key`, `apikey`, `key`) | `api_key` |
| `KRAWL_IPV6_IGNORE` | Ignorer entièrement les requêtes IPv6 : toujours journalisées sur stdout, jamais persistées, vérifiées pour bannissement ou exportées | `false` |
| `KRAWL_IPV6_PURGE_EXISTING` | Supprimer également les lignes IPv6 existantes au prochain démarrage (irréversible ; nécessite `KRAWL_IPV6_IGNORE`) | `false` |
| `KRAWL_DATABASE_RETENTION_DAYS` | Nombre de jours de conservation des données dans la base de données | `30` |
| `KRAWL_BACKUPS_PATH` | Chemin où les dumps de base de données sont enregistrés | `backups` |
| `KRAWL_BACKUPS_CRON` | expression cron pour contrôler la planification de la tâche de sauvegarde | `*/30 * * * *` |
| `KRAWL_BACKUPS_ENABLED` | Booléen pour activer la tâche de dump de la base de données | `true` |

</details>

<details>
<summary><b>Pièges : tarpit, pages de tromperie et canary</b> (6 variables)</summary>

Pièges opt-in et pages servies aux attaquants.

| Variable d'environnement | Description | Valeur par défaut |
|----------------------|-------------|---------|
| `KRAWL_TARPIT_ENABLED` | Piéger les agents IA avec des réponses lentes et du texte aléatoire | `false` |
| `KRAWL_TARPIT_DELAY_SECONDS` | Délai supplémentaire en secondes ajouté par réponse lorsque le tarpit est actif | `5` |
| `KRAWL_DECEPTION_IMPORT_PAGES` | Importer automatiquement les pages de tromperie depuis `src/templates/deception/` au démarrage | `true` |
| `KRAWL_CUSTOM_TEMPLATE_PATH` | Chemin à l'intérieur du conteneur vers un modèle HTML personnalisé. Le modèle doit inclure les espaces réservés `{counter}` et `{content}`. | `/templates/custom_page.html` |
| `KRAWL_CANARY_TOKEN_URL` | URL du jeton canary externe | Aucune |
| `KRAWL_CANARY_TOKEN_TRIES` | Nombre de requêtes avant d'afficher le jeton canary | `10` |

</details>

<details>
<summary><b>Analyseur de réputation IP</b> (6 variables)</summary>

Seuils qui déterminent comment une IP est classifiée.

| Variable d'environnement | Description | Valeur par défaut |
|----------------------|-------------|---------|
| `KRAWL_HTTP_RISKY_METHODS_THRESHOLD` | Seuil de détection des méthodes HTTP risquées | `0.1` |
| `KRAWL_VIOLATED_ROBOTS_THRESHOLD` | Seuil de violations de robots.txt | `0.1` |
| `KRAWL_UNEVEN_REQUEST_TIMING_THRESHOLD` | Seuil du coefficient de variation pour la temporisation | `0.5` |
| `KRAWL_UNEVEN_REQUEST_TIMING_TIME_WINDOW_SECONDS` | Fenêtre temporelle pour l'analyse de la temporisation des requêtes en secondes | `300` |
| `KRAWL_USER_AGENTS_USED_THRESHOLD` | Seuil de détection de multiples user agents | `2` |
| `KRAWL_ATTACK_URLS_THRESHOLD` | Seuil de détection d'URL d'attaque | `1` |

</details>

<details>
<summary><b>Capture de threat-intel</b> (4 variables)</summary>

Hachage flou des charges utiles capturées (fichiers et corps de requêtes signalés) et regroupement
des variantes quasi-identiques en clusters de campagnes. Nécessite `py-tlsh`.

Le hachage s'exécute en tant que tâche d'arrière-plan planifiée `hash-payloads` (voir
`src/tasks/hash_payloads.py`), qui hache chaque attaque capturée une fois — les nouvelles
détections au moment de l'ingestion, et un balayage rétroactif unique de l'historique existant
suivi par un repère de haute eau `payload_hash_watermark` — puis regroupe les
empreintes en campagnes à motifs récurrents.

| Variable d'environnement | Description | Valeur par défaut |
|----------------------|-------------|---------|
| `KRAWL_TLSH_ENABLED` | Hacher les fichiers téléversés et les corps de requêtes signalés avec TLSH pour le regroupement des quasi-doublons | `true` |
| `KRAWL_TLSH_CLUSTER_THRESHOLD` | Distance TLSH en dessous de laquelle une charge utile rejoint une campagne existante (0 = octets identiques ; les variantes d'un webshell diffèrent généralement de < 100) | `150` |
| `KRAWL_TLSH_CAMPAIGN_MIN_EVENTS` | Nombre de fois qu'une charge utile doit être vue avant que sa campagne n'apparaisse dans l'onglet Threats | `10` |
| `KRAWL_REFERER_ENABLED` | Enregistrer le Referer HTTP entrant dans les journaux d'accès, pour le suivi des chaînes d'appât | `true` |

</details>

<details>
<summary><b>Liste de bannissement et IP ignorées</b> (4 variables)</summary>

Partage de listes de bannissement avec d'autres instances, et trafic à ne jamais suivre.

| Variable d'environnement | Description | Valeur par défaut |
|----------------------|-------------|---------|
| `KRAWL_IGNORED_IPS` | IP/CIDR séparés par des virgules jamais suivis, bannis ou exportés | Loopback, RFC1918, link-local, CGNAT |
| `KRAWL_BANLIST_EXPORT_PATH` | Chemin de téléchargement public de la liste de bannissement, ex. `/public_banlist.txt` (vide = désactivé) | `""` |
| `KRAWL_BANLIST_SOURCES` | URL de listes de bannissement amont séparées par des virgules à récupérer et fusionner | Liste de bannissement communautaire Krawl |
| `KRAWL_BANLIST_REFRESH_INTERVAL` | Secondes entre les récupérations de listes de bannissement amont | `3600` |

</details>

<details>
<summary><b>Pages de tromperie générées par IA</b> (10 variables)</summary>

Voir la [documentation sur la génération par IA](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md).

| Variable d'environnement | Description | Valeur par défaut |
|----------------------|-------------|---------|
| `KRAWL_AI_ENABLED` | Activer les pages de tromperie générées par IA | `false` |
| `KRAWL_AI_PROVIDER` | Fournisseur d'IA (`"openrouter"` ou `"openai"`) | `"openrouter"` |
| `KRAWL_AI_OPENAI_BASE_URL` | URL de base OpenAI optionnelle pour des points de terminaison API personnalisés | `"https://api.openai.com/v1"` |
| `KRAWL_AI_API_KEY` | Clé API pour le fournisseur d'IA | `None` |
| `KRAWL_AI_MODEL` | Modèle d'IA à utiliser pour la génération de pages | `"nvidia/nemotron-3-super-120b-a12b:free"` |
| `KRAWL_AI_TIMEOUT` | Délai d'expiration des requêtes en secondes pour les appels à l'API d'IA | `60` |
| `KRAWL_AI_MAX_DAILY_REQUESTS` | Nombre maximum de pages générées par IA par jour (0 = illimité) | `0` |
| `KRAWL_AI_PROMPT` | Modèle d'invite personnalisé pour la génération de pages par IA | Invite par défaut |
| `KRAWL_AI_REASONING_ENABLED` | Activer les jetons de raisonnement (modèles de raisonnement OpenRouter uniquement) | `false` |
| `KRAWL_AI_REASONING_EFFORT` | Effort de raisonnement (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`) | `"medium"` |

</details>

<details>
<summary><b>Mode évolutif : PostgreSQL et Redis</b> (13 variables)</summary>

Utilisé uniquement lorsque `KRAWL_MODE=scalable`. Voir [Modes de déploiement](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md).

| Variable d'environnement | Description | Valeur par défaut |
|----------------------|-------------|---------|
| `KRAWL_MODE` | Mode de déploiement (`standalone` ou `scalable`) | `standalone` |
| `KRAWL_POSTGRES_HOST` | Nom d'hôte PostgreSQL | `localhost` |
| `KRAWL_POSTGRES_PORT` | Port PostgreSQL | `5432` |
| `KRAWL_POSTGRES_USER` | Nom d'utilisateur PostgreSQL | `krawl` |
| `KRAWL_POSTGRES_PASSWORD` | Mot de passe PostgreSQL | `krawl` |
| `KRAWL_POSTGRES_DATABASE` | Nom de la base de données PostgreSQL | `krawl` |
| `KRAWL_REDIS_HOST` | Nom d'hôte Redis | `localhost` |
| `KRAWL_REDIS_PORT` | Port Redis | `6379` |
| `KRAWL_REDIS_DB` | Numéro de base de données Redis | `0` |
| `KRAWL_REDIS_PASSWORD` | Mot de passe Redis | Aucun |
| `KRAWL_REDIS_CACHE_TTL` | TTL en secondes pour les données de préchauffage du tableau de bord | `600` |
| `KRAWL_REDIS_HOT_TTL` | TTL en secondes pour les données de chemin chaud (infos de bannissement, catégories d'IP) | `30` |
| `KRAWL_REDIS_TABLE_TTL` | TTL en secondes pour les tables paginées du tableau de bord | `120` |

</details>


Par exemple```bash
# Set canary token
export CONFIG_LOCATION="config.yaml"
export KRAWL_CANARY_TOKEN_URL="http://your-canary-token-url"

# Set number of pages range (min,max format)
export KRAWL_LINKS_PER_PAGE_RANGE="5,25"

# Set analyzer thresholds
export KRAWL_HTTP_RISKY_METHODS_THRESHOLD="0.2"
export KRAWL_VIOLATED_ROBOTS_THRESHOLD="0.15"

# Set custom dashboard path and password
export KRAWL_DASHBOARD_SECRET_PATH="/my-secret-dashboard"
export KRAWL_DASHBOARD_PASSWORD="my-secret-password"

Exemple d'exécution Docker avec des variables d'environnement (mode autonome) :```bash docker run -d
-p 5000:5000
-e KRAWL_MODE=standalone
-e KRAWL_PORT=5000
-e KRAWL_DELAY=100
-e KRAWL_DASHBOARD_PASSWORD="my-secret-password"
-e KRAWL_CUSTOM_TEMPLATE_PATH="/templates/custom_page.html"
-e KRAWL_CANARY_TOKEN_URL="http://your-canary-token-url"
--name krawl
ghcr.io/blessedrebus/krawl:latest

## Utiliser Krawl pour bannir les IP malveillantes
Krawl utilise un système basé sur la réputation pour classer les adresses IP des attaquants et propose deux méthodes d'exportation de listes d'IP pour l'intégration au pare-feu.

Le point de terminaison `/api/export-ips` interroge directement la base de données et prend en charge le filtrage par catégorie d'IP (`attacker`, `bad_crawler`, `regular_user`, `good_crawler`) et par format de sortie (`raw`, `iptables`, `nftables`) :```bash
curl "https://your-krawl-instance/<DASHBOARD-PATH>/api/export-ips?categories=attacker&fwtype=raw"

Cela permet le blocage automatique du trafic malveillant sur diverses plateformes :

Pour les paramètres complets de l'API, des exemples et l'ajout de formats de pare-feu personnalisés, consultez la documentation des exportateurs de pare-feu.

Krawl peut également pousser directement les IP bannies vers une liste d'IP de compte Cloudflare pour une utilisation dans les règles WAF. La synchronisation s'exécute en tant que tâche en arrière-plan et met à jour la liste par remplacement complet à un intervalle configurable. Consultez la documentation Cloudflare Banlist Sync.

Réputation IP

Krawl utilise des tâches qui analysent le trafic récent pour construire et mettre à jour en continu un score de réputation IP. Elle s'exécute périodiquement et évalue chaque adresse IP active en fonction de multiples indicateurs comportementaux afin de la classer comme attaquant, crawler ou utilisateur régulier. Les seuils sont entièrement personnalisables.

ip reputation

L'analyse comprend :

  • Utilisation de méthodes HTTP à risque (par ex. ratios POST, PUT, DELETE)
  • Violations de Robots.txt
  • Anomalies de timing des requêtes (motifs en rafale ou irréguliers)
  • Cohérence du User-Agent
  • Détection d'URL d'attaque (par ex. injection SQL, motifs XSS)

Chaque signal contribue à un modèle de notation pondéré qui attribue une catégorie de réputation :

  • attacker
  • bad_crawler
  • good_crawler
  • regular_user
  • unknown (pour données insuffisantes)

Les scores et métriques résultants sont stockés dans la base de données et utilisés par Krawl pour alimenter les tableaux de bord, le suivi de réputation et les actions d'atténuation automatisées telles que le bannissement d'IP ou l'intégration au pare-feu.

Pages de déception générées par IA

Krawl peut générer automatiquement des pages de déception réalistes à l'aide de modèles d'IA provenant des API OpenRouter ou OpenAI. Cette fonctionnalité crée à la volée des pages honeypot uniques et plausibles pour tromper les attaquants sans création manuelle de pages.

Fonctionnalités clés :

  • Génération dynamique : Crée des pages HTML uniques pour tout chemin de requête
  • Mise en cache intelligente : Met en cache les pages générées pour éviter les appels API redondants
  • Limitation de débit quotidienne : Contrôlez les coûts API avec des limites de requêtes configurables
  • Fournisseurs multiples : Prise en charge d'OpenRouter (options gratuites) et d'OpenAI
  • Repli gracieux : Revient au honeypot standard lorsqu'il est désactivé ou que la limite est atteinte
  • Service en cache : Les pages précédemment générées sont servies même lorsque l'IA est désactivée

Configuration rapide :```yaml ai: enabled: true provider: "openrouter" openai_base_url: "your-custom-base-url" api_key: "your-api-key" model: "nvidia/nemotron-3-super-120b-a12b:free" timeout: 60 max_daily_requests: 10

Pour une configuration et une utilisation détaillées, consultez la [documentation sur la génération par IA](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md).

Vous pouvez également **contribuer à des modèles de leurre** en ouvrant une PR, voir [Contribuer aux modèles de leurre](https://github.com/blessedrebus/krawl/blob/main/docs/deception_pages.md#contributing-deception-templates-via-pr).

## Exécution derrière un reverse proxy ou un CDN

**NGINX, Traefik et d'autres proxys comme CloudFlare** nécessitent la transmission des en-têtes pour que Krawl puisse voir la véritable IP. Consultez la [documentation sur le reverse proxy](https://github.com/blessedrebus/krawl/blob/main/docs/reverse-proxy.md) pour des exemples de configuration et la liste complète des en-têtes.

## Métriques et supervision

Krawl expose des métriques [Prometheus](https://prometheus.io/) à l'adresse `/<dashboard_secret_path>/metrics` (activé par défaut) et est livré avec un tableau de bord [Grafana](https://grafana.com/) prêt à importer dans [`grafana-dashboard.json`](https://github.com/blessedrebus/krawl/blob/main/grafana-dashboard.json).

Consultez la [documentation sur la supervision](https://github.com/blessedrebus/krawl/blob/main/docs/monitoring.md) pour la liste complète des métriques, les étapes d'import dans Grafana, et la configuration du scraping Prometheus / Kubernetes (`ServiceMonitor`).

## Documentation complémentaire

| Sujet | Description |
|-------|-------------|
| [Génération par IA](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md) | Configurer les pages de leurre générées par IA à l'aide d'OpenRouter ou OpenAI |
| [Pages de leurre](https://github.com/blessedrebus/krawl/blob/main/docs/deception_pages.md) | Gérer, importer et exporter les pages de leurre ; opérations en masse et filtrage par date |
| [Modes de déploiement](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md) | Mode autonome (SQLite) vs évolutif (PostgreSQL + Redis), configuration et migration des données |
| [Honeypot](https://github.com/blessedrebus/krawl/blob/main/docs/honeypot.md) | Aperçu complet des pages de honeypot : faux identifiants de connexion, listages de répertoires, fichiers d'identifiants, pièges SQLi/XSS/XXE/injection de commandes, et plus encore |
| [Tableau de bord](https://github.com/blessedrebus/krawl/blob/main/docs/dashboard.md) | Accéder et explorer le tableau de bord de supervision en temps réel |
| [API du tableau de bord](https://github.com/blessedrebus/krawl/blob/main/docs/dashboard-api.md) | L'API JSON propre à Krawl : référence des endpoints, authentification, documentation OpenAPI interactive et téléchargements de pièces jointes |
| [API externes](https://github.com/blessedrebus/krawl/blob/main/docs/api.md) | API tierces que Krawl appelle pour les données d'IP, la réputation et la géolocalisation |
| [Reverse Proxy](https://github.com/blessedrebus/krawl/blob/main/docs/reverse-proxy.md) | Comment déployer Krawl derrière NGINX ou utiliser des sous-domaines leurres |
| [Sauvegardes de base de données](https://github.com/blessedrebus/krawl/blob/main/docs/backups.md) | Activer et configurer la tâche automatique de vidage de la base de données |
| [Canary Token](https://github.com/blessedrebus/krawl/blob/main/docs/canary-token.md) | Configurer des déclencheurs d'alerte externes via canarytokens.org |
| [Wordlist](https://github.com/blessedrebus/krawl/blob/main/docs/wordlist.md) | Personnaliser les faux noms d'utilisateur, mots de passe et listages de répertoires |
| [Architecture](https://github.com/blessedrebus/krawl/blob/main/docs/architecture.md) | Aperçu technique de la base de code, du pipeline de requêtes, du schéma de base de données et des tâches en arrière-plan |
| [Synchronisation de la liste de bannissement Cloudflare](https://github.com/blessedrebus/krawl/blob/main/docs/cloudflare_banlist.md) | Pousse les IP bannies depuis Krawl vers une liste d'IP de compte Cloudflare pour utilisation dans les règles WAF. La synchronisation s'exécute en tâche de fond et met à jour la liste par remplacement complet. |
| [Exportateurs de pare-feu](https://github.com/blessedrebus/krawl/blob/main/docs/firewall-exporters.md) | Exporter les listes de bannissement d'IP aux formats brut, iptables ou nftables via l'API REST |
| [Tarpit](https://github.com/blessedrebus/krawl/blob/main/docs/tarpit.md) | Ralentir et empoisonner les crawlers IA avec des réponses retardées et enrichies de bruit |
| [Métriques et supervision](https://github.com/blessedrebus/krawl/blob/main/docs/monitoring.md) | Endpoint de métriques Prometheus, référence des métriques exposées, tableau de bord Grafana et scraping ServiceMonitor |

## Contribution

Les contributions sont les bienvenues ! Veuillez :
1. Forker le dépôt
2. Créer une branche de fonctionnalité
3. Effectuer vos modifications
4. Soumettre une pull request (expliquez les modifications !)


## Avertissement
> [!CAUTION]
> Il s'agit d'un système de leurre/honeypot. Déployez-le dans des environnements isolés et surveillez attentivement les événements de sécurité. Utilisez-le de manière responsable et en conformité avec les lois et réglementations applicables.

## Historique des étoiles
<img src="https://star-history.dera.page/svg?repos=BlessedRebuS/Krawl&amp;type=Date" width="600" alt="Star History Chart" />
Lire plus

Catégories

Sécurité des ConteneursCollecte d'InformationsSécurité WebSécurité RéseauSécurité CloudRenseignement sur les MenacesRéponse aux IncidentsAnti-BotSécurité de l'IA