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.
Un serveur honeypot web moderne et personnalisable conçu pour détecter et suivre les activités malveillantes des attaquants et des robots d'exploration via des pages web trompeuses, des identifiants fictifs et des jetons canaris.
Astuce : explorez les chemins robots.txt pour plus de plaisir
Krawl est un serveur de tromperie cloud‑natif conçu pour détecter, retarder et analyser les attaquants malveillants, les robots d'exploration et les scanners automatisés.
Il crée des applications web factices réalistes remplies de pièges apparents tels que des panneaux d'administration, des fichiers de configuration et des identifiants fictifs exposés pour attirer et identifier les activités suspectes.
En gaspillant les ressources des attaquants, Krawl aide à distinguer clairement les comportements malveillants des robots légitimes.
Il propose :
Vous pouvez facilement exposer Krawl aux côtés de vos autres services pour les protéger des robots d'exploration et des utilisateurs malveillants à l'aide d'un proxy inverse. Pour plus de détails, consultez la documentation sur le proxy inverse.
Krawl fournit un tableau de bord complet, accessible via un chemin secret aléatoire généré au démarrage ou via un chemin personnalisé configuré via KRAWL_DASHBOARD_SECRET_PATH. Cela permet de dissimuler le tableau de bord aux attaquants qui scannent votre honeypot.
Le tableau de bord est organisé en six onglets :
De plus, après authentification avec le mot de passe du tableau de bord, deux onglets protégés deviennent disponibles :
Pour plus de détails, consultez la documentation sur le tableau de bord.
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.
Autonome : Idéal pour les environnements de développement ou les homelabs avec un faible volume de requêtes. Aucune configuration supplémentaire nécessaire, lancez Krawl et ça fonctionne.
Évolutif : Conçu pour les environnements de production ou les honeypots à fort trafic. Le chart Helm utilise ce mode par défaut.
Pour une configuration détaillée, des exemples Docker Compose, la mise en place Kubernetes/Helm, et des instructions de migration pas à pas, consultez la documentation sur les modes de déploiement.
Krawl maintient une banlist.txt régulièrement mise à jour des adresses IP des attaquants qui ont déclenché ses pièges honeypot. La liste est publiée chaque semaine et disponible en téléchargement, aidant la communauté à bloquer de manière préventive les acteurs malveillants connus, même sans utiliser Krawl.
La liste peut également être récupérée directement depuis : https://demo.krawlme.com/das_dashboard/api/export-ips?categories=attacker&fwtype=raw.
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.
**Autonome**: juste le serveur Krawl avec 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:
Évolutif: avec PostgreSQL et Redis:
[!CAUTION] L'exemple ci-dessous utilise des mots de passe par défaut (
krawl/krawl). Modifiez-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/. Pour le développement (constructions à partir des sources avec rechargement à chaud), utilisez les fichiers compose à la racine du projet.
Pour plus de détails sur les deux modes, consultez Modes de déploiement.
Krawl est également disponible nativement sur Kubernetes. L'installation peut être effectuée soit via un manifeste, soit en utilisant le chart Helm.
Le chart Helm par défaut en mode scalable avec PostgreSQL et Redis intégrés :```bash
helm install krawl oci://ghcr.io/blessedrebus/krawl-chart --version 2.2.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 d'exemples de valeurs minimaux sont fournis pour les deux modes :
- [`values-minimal.yaml`](https://github.com/blessedrebus/krawl/blob/HEAD/helm/values-minimal.yaml) ---> Évolutif (par défaut)
- [`values-standalone.yaml`](https://github.com/blessedrebus/krawl/blob/HEAD/helm/values-standalone.yaml) ---> Autonome
Voir [Modes de déploiement](https://github.com/blessedrebus/krawl/blob/HEAD/docs/deployment-modes.md) et [Chart documentation](https://github.com/blessedrebus/krawl/blob/HEAD/helm/README.md) 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éder au serveur à l'adresse http://localhost:5000
Krawl utilise une hiérarchie de configuration dans laquelle les variables d'environnement prennent le pas sur le fichier de configuration. Cette approche est recommandée pour les déploiements Docker et la personnalisation rapide prête à l'emploi.
Vous pouvez utiliser le fichier config.yaml pour des configurations avancées, telles que les déploiements Docker Compose ou Helm chart.
Par exemple```bash
export CONFIG_LOCATION="config.yaml" export KRAWL_CANARY_TOKEN_URL="http://your-canary-token-url"
export KRAWL_LINKS_PER_PAGE_RANGE="5,25"
export KRAWL_HTTP_RISKY_METHODS_THRESHOLD="0.2" export KRAWL_VIOLATED_ROBOTS_THRESHOLD="0.15"
export KRAWL_DASHBOARD_SECRET_PATH="/my-secret-dashboard" export KRAWL_DASHBOARD_PASSWORD="my-secret-password"
Exemple d'une 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
Krawl utilise un système basé sur la réputation pour classer les adresses IP des attaquants et propose deux manières d'exporter des listes d'IP pour l'intégration dans un 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//api/export-ips?categories=attacker&fwtype=raw"
Cela permet le blocage automatique du trafic malveillant sur diverses plates-formes :
* [OPNsense et pfSense](https://ipv64.net/v64_blocklist_integration_guide)
* [RouterOS](https://rentry.co/krawl-routeros)
* [IPtables](https://github.com/blessedrebus/krawl/blob/HEAD/plugins/iptables/README.md) et [Nftables](https://github.com/blessedrebus/krawl/blob/HEAD/plugins/nftables/README.md)
* [Fail2Ban](https://github.com/blessedrebus/krawl/blob/HEAD/plugins/fail2ban/README.md)
Pour les paramètres complets de l'API, les exemples et l'ajout de formats de pare-feu personnalisés, consultez la [documentation des exportateurs de pare-feu](https://github.com/blessedrebus/krawl/blob/HEAD/docs/firewall-exporters.md).
## 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](https://github.com/blessedrebus/krawl/blob/HEAD/src/tasks/analyze_ips.py). Il s'exécute périodiquement et évalue chaque adresse IP active sur la base de multiples indicateurs comportementaux pour la classer comme attaquant, robot d'exploration ou utilisateur régulier. Les seuils sont entièrement personnalisables.
L'analyse comprend :
- **Utilisation de méthodes HTTP risquées** (par ex. ratios POST, PUT, DELETE)
- **Violations du robots.txt**
- **Anomalies de timing des requêtes** (modèles en rafales ou irréguliers)
- **Cohérence du User-Agent**
- **Détection d'URL d'attaque** (par ex. injections 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 de mitigation automatisées telles que le bannissement IP ou l'intégration avec le pare-feu.
## Pages de leurre générées par IA
Krawl peut générer automatiquement des pages de leurre réalistes en utilisant des modèles d'IA des API **OpenRouter** ou **OpenAI**. Cette fonctionnalité crée des pages honeypot uniques et plausibles à la volée 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ôle les coûts de l'API avec des limites de requêtes configurables
- **Plusieurs fournisseurs** : Prise en charge d'OpenRouter (options gratuites) et d'OpenAI
- **Repli gracieux** : Revient au honeypot standard lorsque désactivé ou limite atteinte
- **Service en cache** : Les pages générées précédemment 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 de génération AI.
Vous pouvez également contribuer avec des modèles de leurre en ouvrant une pull request, voir Contribuer avec des modèles de leurre.
Si Krawl est déployé derrière un proxy tel que NGINX, l'en-tête du serveur doit être transféré en utilisant la configuration suivante dans votre proxy :```bash location / { proxy_pass https://your-krawl-instance; proxy_pass_header Server; }
## Métriques et Surveillance
Krawl expose des métriques [Prometheus](https://prometheus.io/) sur `/<dashboard_secret_path>/metrics` (activé par défaut) et est livré avec un tableau de bord [Grafana](https://grafana.com/) prêt à être importé dans [`grafana-dashboard.json`](https://github.com/blessedrebus/krawl/blob/HEAD/grafana-dashboard.json).
Consultez la [documentation de surveillance](https://github.com/blessedrebus/krawl/blob/HEAD/docs/monitoring.md) pour la liste complète des métriques, les étapes d'importation Grafana et la configuration du scraping Prometheus / Kubernetes (`ServiceMonitor`).
## Documentation supplémentaire
| Sujet | Description |
|-------|-------------|
| [Génération IA](https://github.com/blessedrebus/krawl/blob/HEAD/docs/ai_generation.md) | Configurer des pages de leurre générées par IA via OpenRouter ou OpenAI |
| [Pages de leurre](https://github.com/blessedrebus/krawl/blob/HEAD/docs/deception_pages.md) | Gérer, importer et exporter des pages de leurre ; opérations en masse et filtrage par date |
| [Modes de déploiement](https://github.com/blessedrebus/krawl/blob/HEAD/docs/deployment-modes.md) | Mode autonome (SQLite) vs mode évolutif (PostgreSQL + Redis), configuration et migration des données |
| [Pot de miel](https://github.com/blessedrebus/krawl/blob/HEAD/docs/honeypot.md) | Aperçu complet des pages pot de miel : faux identifiants, listes de répertoires, fichiers d'identifiants, pièges SQLi/XSS/XXE/injection de commandes, et plus |
| [Tableau de bord](https://github.com/blessedrebus/krawl/blob/HEAD/docs/dashboard.md) | Accéder et explorer le tableau de bord de surveillance en temps réel |
| [API](https://github.com/blessedrebus/krawl/blob/HEAD/docs/api.md) | API externes utilisées par Krawl pour les données IP, la réputation et la géolocalisation |
| [Proxy inverse](https://github.com/blessedrebus/krawl/blob/HEAD/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/HEAD/docs/backups.md) | Activer et configurer la tâche de vidage automatique de la base de données |
| [Jeton canari](https://github.com/blessedrebus/krawl/blob/HEAD/docs/canary-token.md) | Configurer des déclencheurs d'alerte externes via canarytokens.org |
| [Liste de mots](https://github.com/blessedrebus/krawl/blob/HEAD/docs/wordlist.md) | Personnaliser les faux noms d'utilisateur, mots de passe et listes de répertoires |
| [Architecture](https://github.com/blessedrebus/krawl/blob/HEAD/docs/architecture.md) | Aperçu technique du code, pipeline de requêtes, schéma de base de données et tâches en arrière-plan |
| [Exportateurs de pare-feu](https://github.com/blessedrebus/krawl/blob/HEAD/docs/firewall-exporters.md) | Exporter les listes de bannissement IP aux formats raw, iptables ou nftables via l'API REST |
| [Métriques et Surveillance](https://github.com/blessedrebus/krawl/blob/HEAD/docs/monitoring.md) | Point de terminaison des métriques Prometheus, référence des métriques exposées, tableau de bord Grafana et scraping ServiceMonitor |
## Contribution
Les contributions sont les bienvenues ! Merci de :
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]
> Ceci est un système de leurre/pot de miel. Déployez dans des environnements isolés et surveillez attentivement les événements de sécurité. Utilisez de manière responsable et en conformité avec les lois et réglementations applicables.
## Historique des étoiles
<img src="https://assets.kitploit.com/production/public/readmes/placeholders/f0fc86cfe65f76d40e15aaec61704ec8220a56dc89d4be03c46f67cb31b9fa8c.svg" width="600" alt="Graphique de l'historique des étoiles" />
| Autonome | Évolutif |
|---|
| Base de données | SQLite (mode WAL) | PostgreSQL |
| Cache | Dictionnaire Python en mémoire | Redis (TTL multi-niveaux) |
| Réplicas | 1 (instance unique) | 1+ (mise à l'échelle horizontale) |
| Dépendances externes | Aucune | PostgreSQL + Redis |
| Idéal pour | Développement, homelabs, <500k requêtes | Production, haute disponibilité, >500k requêtes |
| Variable d'environnement | Description | 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 forme min,max | 5,15 |
KRAWL_LINKS_PER_PAGE_RANGE | Liens par page sous forme min,max | 10,15 |
KRAWL_CHAR_SPACE | Caractères utilisés pour la génération des liens | abcdefgh... |
KRAWL_MAX_COUNTER | Valeur initiale du compteur | 10 |
KRAWL_CANARY_TOKEN_URL | URL externe du jeton canari | None |
KRAWL_CANARY_TOKEN_TRIES | Requêtes avant d'afficher le jeton canari | 10 |
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 des chargements instantanés | true |
KRAWL_DASHBOARD_WARMUP_PAGES | Nombre de pages à préchauffer par panneau de tableau | 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 des premiers chemins/agents utilisateurs (mettre à 1 pour désactiver) | 5 |
KRAWL_PROBABILITY_ERROR_CODES | Probabilité de réponse d'erreur (0-100%) | 0 |
KRAWL_DATABASE_PATH | Emplacement du fichier de base de données | data/krawl.db |
KRAWL_DATABASE_PERSIST_SUSPICIOUS_ONLY | Persister uniquement les requêtes suspectes dans le journal d'accès | false |
KRAWL_BACKUPS_PATH | Chemin où les sauvegardes de base de données sont enregistrées | backups |
KRAWL_BACKUPS_CRON | Expression cron pour planifier le travail de sauvegarde | */30 * * * * |
KRAWL_BACKUPS_ENABLED | Booléen pour activer le travail de sauvegarde de la base de données | true |
KRAWL_DATABASE_RETENTION_DAYS | Jours de conservation des données dans la base de données | 30 |
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 piège est actif | 5 |
KRAWL_HTTP_RISKY_METHODS_THRESHOLD | Seuil pour la détection des méthodes HTTP risquées | 0.1 |
KRAWL_VIOLATED_ROBOTS_THRESHOLD | Seuil pour les violations de robots.txt | 0.1 |
KRAWL_UNEVEN_REQUEST_TIMING_THRESHOLD | Seuil du coefficient de variation pour le timing | 0.5 |
KRAWL_UNEVEN_REQUEST_TIMING_TIME_WINDOW_SECONDS | Fenêtre de temps pour l'analyse du timing des requêtes en secondes | 300 |
KRAWL_USER_AGENTS_USED_THRESHOLD | Seuil pour la détection de multiples agents utilisateurs | 2 |
KRAWL_ATTACK_URLS_THRESHOLD | Seuil pour la détection d'URL d'attaque | 1 |
KRAWL_INFINITE_PAGES_FOR_MALICIOUS | Servir des pages infinies aux IP malveillantes | true |
KRAWL_MAX_PAGES_LIMIT | Limite maximale de pages pour les robots | 250 |
KRAWL_BAN_DURATION_SECONDS | Durée du bannissement en secondes pour les IP limitées en débit | 600 |
KRAWL_AI_ENABLED | Activer les pages de tromperie générées par IA | false |
KRAWL_AI_PROVIDER | Fournisseur 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 IA | None |
KRAWL_AI_MODEL | Modèle IA à utiliser pour la génération de pages | "nvidia/nemotron-3-super-120b-a12b:free" |
KRAWL_AI_TIMEOUT | Délai d'attente de requête en secondes pour les appels API 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 de prompt personnalisé pour la génération de pages IA | Prompt par défaut |
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 |
| Mode scalable | ||
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 | None |
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 à chaud (infos de bannissement, catégories IP) | 30 |
KRAWL_REDIS_TABLE_TTL | TTL en secondes pour les tableaux paginés du tableau de bord | 120 |