blessedrebus/krawlKrawl é um servidor de decepção web personalizável, leve e nativo da nuvem, e um anti-crawler que cria aplicações web falsas com vulnerabilidades de baixa complexidade, utilizando dados fictícios realistas gerados aleatoriamente e modelos HTML gerados por IA.
<h1 align="center">Krawl</h1>
<h3 align="center">
<a name="readme-top"></a>
<img
src="https://raw.githubusercontent.com/blessedrebus/krawl/HEAD/img/krawl-svg.svg"
height="250"
>
</h3>
<div align="center">
<p align="center">
Um servidor honeypot web moderno e personalizável, projetado para detectar e rastrear atividades maliciosas de atacantes e rastreadores web por meio de páginas web enganosas, credenciais falsas e tokens canário.
</p>
<div align="center">
<a href="https://github.com/blessedrebus/krawl/blob/main/LICENSE">
<img src="https://img.shields.io/github/license/blessedrebus/krawl" alt="License">
</a>
<a href="https://github.com/blessedrebus/krawl/releases">
<img src="https://img.shields.io/github/v/release/blessedrebus/krawl" alt="Release">
</a>
</div>
<div align="center">
<a href="https://ghcr.io/blessedrebus/krawl">
<img src="https://img.shields.io/badge/ghcr.io-krawl-blue" alt="GitHub Container Registry">
</a>
<a href="https://kubernetes.io/">
<img src="https://img.shields.io/badge/kubernetes-ready-326CE5?logo=kubernetes&logoColor=white" alt="Kubernetes">
</a>
<a href="https://github.com/BlessedRebuS/Krawl/pkgs/container/krawl-chart">
<img src="https://img.shields.io/badge/helm-chart-0F1689?logo=helm&logoColor=white" alt="Helm Chart">
</a>
</div>
</div>
## Índice
- [Demonstração](#demo)
- [O que é o Krawl?](#what-is-krawl)
- [Painel do Krawl](#krawl-dashboard)
- [Modos de Implantação](#deployment-modes)
- [Lista de Banimentos do Krawl](#krawl-banlist)
- [Início Rápido](#quickstart)
- [Docker Run](#docker-run)
- [Docker Compose](#docker-compose)
- [Kubernetes](#kubernetes)
- [Uvicorn (Python)](#uvicorn-python)
- [Configuração](#configuration)
- [config.yaml](#configuration-via-configyaml)
- [Variáveis de Ambiente](#configuration-via-environmental-variables)
- [Banir IPs Maliciosos](#use-krawl-to-ban-malicious-ips)
- [Reputação de IP](#ip-reputation)
- [Executando Atrás de um Proxy Reverso ou CDN](#running-behind-a-reverse-proxy-or-cdn)
- [Métricas e Monitoramento](#metrics--monitoring)
- [Documentação Adicional](#additional-documentation)
- [Engano usando IA](#ai-generated-deception-pages)
- [Contribuindo](#contributing)
## Demonstração
Dica: rastreie os caminhos do `robots.txt` para diversão adicional
### URL do Krawl: [http://demo.krawlme.com](http://demo.krawlme.com)
### Veja o painel [http://demo.krawlme.com/das_dashboard](http://demo.krawlme.com/das_dashboard)
## O que é o Krawl?
**Krawl** é um servidor de engano nativo da nuvem projetado para detectar, atrasar e analisar atacantes maliciosos, rastreadores web e scanners automatizados.
Ele cria aplicações web falsas realistas repletas de alvos fáceis, como painéis de administração, arquivos de configuração e credenciais falsas expostas, para atrair e identificar atividades suspeitas.
Ao desperdiçar recursos do atacante, o Krawl ajuda a distinguir claramente o comportamento malicioso de rastreadores legítimos.
Ele apresenta:
- **[Páginas de Engano Geradas por IA](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md)**: **Deixe os atacantes ajudarem a gerar sua superfície de ataque falsa e vulnerável**
- **Páginas Armadilha para Spiders**: Links aleatórios infinitos para desperdiçar recursos de rastreadores, baseado no [projeto spidertrap](https://github.com/adhdproject/spidertrap)
- **Páginas de Login Falsas**: WordPress, phpMyAdmin, painéis de administração
- **Caminhos Honeypot**: Anunciados no robots.txt para capturar scanners
- **Credenciais Falsas**: Nomes de usuário, senhas e chaves de API com aparência realista
- **Integração com [Token Canário](https://github.com/blessedrebus/krawl/blob/main/docs/canary-token.md)**: Disparo de alertas externos
- **Cabeçalhos de servidor aleatórios**: Confundem ataques baseados no cabeçalho e versão do servidor
- **Painel em Tempo Real**: Monitore atividades suspeitas
- **Wordlists Personalizáveis**: Configuração fácil baseada em JSON
- **Injeção de Erros Aleatórios**: Imita o comportamento de um servidor real
Você pode facilmente expor o Krawl ao lado de seus outros serviços para protegê-los de rastreadores web e usuários maliciosos usando um proxy reverso. Para mais detalhes, consulte a [documentação de Proxy Reverso](https://github.com/blessedrebus/krawl/blob/main/docs/reverse-proxy.md).
## Painel do Krawl
O Krawl fornece um painel abrangente, acessível em um **caminho secreto aleatório** gerado na inicialização ou em um **caminho personalizado** configurado via `KRAWL_DASHBOARD_SECRET_PATH`. Isso mantém o painel oculto de atacantes que escaneiam seu honeypot.
O painel está organizado em seis abas:
- **Visão Geral**: visão de alto nível da atividade de ataque: um mapa interativo das origens de IP, requisições suspeitas recentes e principais IPs, User-Agents e caminhos.
- **Ataques**: detalhamento das credenciais capturadas, gatilhos de honeypot e tipos de ataque detectados (SQLi, XSS, path traversal, etc.) com gráficos e tabelas.
- **Ameaças**: payloads agrupados em campanhas por hash fuzzy TLSH, de modo que um webshell e suas variantes editadas sejam lidos como uma única campanha em vez de acertos não relacionados, com um índice de cada arquivo capturado.
- **IP Insight**: visão forense aprofundada de um IP selecionado: geolocalização, informações de ISP/ASN, sinalizações de reputação, linha do tempo comportamental, distribuição de tipos de ataque, histórico de referer, arquivos e credenciais capturados e histórico completo de acesso.
Além disso, após autenticar com a senha do painel, abas protegidas ficam disponíveis:
- **IPs Rastreados**: mantenha uma lista de observação de endereços IP que você deseja monitorar ao longo do tempo.
- **Lista de Banimentos de IP**: gerencie banimentos de IP, visualize atacantes detectados e exporte a lista de banimentos em formato raw ou IPTables.
- **IPs em Timeout**: revise os IPs atualmente mantidos no tarpit e isente qualquer um que não deveria estar lá.
- **Engano**: gerencie páginas geradas por IA, exporte-as ou importe novas.
- **Webhooks**: encaminhe banimentos para CloudFlare e outros firewalls.
Os ícones do cabeçalho abrem a documentação da API, a exportação da lista de banimentos e um painel de configurações mostrando a configuração em execução e uma página de manutenção para executar tarefas agendadas sob demanda.
Para mais detalhes, consulte a [documentação do Painel](https://github.com/blessedrebus/krawl/blob/main/docs/dashboard.md).
## Modos de Implantação
O Krawl suporta dois modos de implantação, controlados pela configuração `mode` em `config.yaml` ou pela variável de ambiente `KRAWL_MODE`.
| | Standalone | Escalável |
|---|---|---|
| **Banco de Dados** | SQLite (modo WAL) | PostgreSQL |
| **Cache** | Dicionário Python em memória | Redis (TTL multi-camadas) |
| **Réplicas** | 1 (instância única) | 1+ (escalonamento horizontal) |
| **Dependências externas** | Nenhuma | PostgreSQL + Redis |
| **Melhor para** | Desenvolvimento, homelabs, <500k requisições | Produção, HA, >500k requisições |
**Standalone**: ideal para ambientes de desenvolvimento ou homelabs com baixo volume de requisições. Nenhuma configuração adicional necessária, basta executar o Krawl e ele funciona.
- Implantação em contêiner único sem dependências externas
- Menor uso de RAM e recursos
**Escalável**: projetado para ambientes de produção ou honeypots de alto tráfego. O Helm chart usa este modo por padrão.
- Painel mais rápido e responsivo graças ao cache multi-camadas do Redis
- Menor I/O de disco com o Redis atuando como cache de caminho rápido na frente do PostgreSQL
- Escalonamento horizontal aumenta o número de réplicas do Krawl atrás de um balanceador de carga
Para configuração detalhada, exemplos de Docker Compose, configuração de Kubernetes/Helm e instruções de migração passo a passo, consulte a [documentação de Modos de Implantação](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md).
## Lista de Banimentos do Krawl
O Krawl mantém um [`banlist.txt`](https://github.com/blessedrebus/krawl/blob/main/banlist.txt) atualizado regularmente com endereços IP de **atacantes que acionaram suas armadilhas honeypot**. A lista de banimentos é publicada semanalmente e está disponível para download, ajudando a comunidade a bloquear preventivamente atores maliciosos conhecidos mesmo sem usar o Krawl.
A lista de banimentos também pode ser obtida diretamente de:
[https://demo.krawlme.com/das_dashboard/api/export-ips?categories=attacker&fwtype=raw](https://demo.krawlme.com/das_dashboard/api/export-ips?categories=attacker&fwtype=raw).
### Compartilhando listas de banimentos entre instâncias
Instâncias do Krawl podem federar suas listas de banimentos: cada uma pode publicar sua própria lista em um
caminho não autenticado e importar listas de outras instâncias (ou qualquer lista de IPs em texto simples).
Os IPs obtidos são mesclados nas decisões de banimento locais e exibidos no painel.```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
```
## Início Rápido
### Execução com Docker
Execute o Krawl em modo autônomo com a imagem mais recente:```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
```
Acesse o servidor em `http://localhost:5000`
### Docker Compose
Crie um `docker-compose.yaml` com um dos dois modos de implantação.
**Standalone**: apenas o servidor Krawl com armazenamento 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:
```
**Escalável**: com PostgreSQL e Redis:
> [!CAUTION]
> O exemplo abaixo usa **senhas padrão** (`krawl`/`krawl`). **Altere-as antes de implantar em produção.**```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:
```
Para implantar, basta executar```bash
docker compose up -d
```
Arquivos compose prontos para produção também estão disponíveis no diretório [`docker/`](https://github.com/blessedrebus/krawl/blob/main/docker). Para **desenvolvimento** (compila a partir do código-fonte com hot-reload), use os arquivos compose em [`docker/dev/`](https://github.com/blessedrebus/krawl/blob/main/docker/dev).
Para mais detalhes sobre ambos os modos, consulte [Modos de Implantação](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md).
### Kubernetes
**O Krawl também está disponível nativamente no Kubernetes**. A instalação pode ser feita [via manifest](https://github.com/blessedrebus/krawl/blob/main/kubernetes/README.md) ou [usando o Helm chart](https://github.com/blessedrebus/krawl/blob/main/helm/README.md).
O Helm chart **usa o modo escalável por padrão** com PostgreSQL e Redis incluídos:```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
```
Arquivos de valores de exemplo mínimos são fornecidos para ambos os modos:
- [`values-minimal.yaml`](https://github.com/blessedrebus/krawl/blob/main/helm/values-minimal.yaml) ---> Escalável (padrão)
- [`values-standalone.yaml`](https://github.com/blessedrebus/krawl/blob/main/helm/values-standalone.yaml) ---> Standalone
Consulte [Modos de Implantação](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md) e [Documentação do Chart](https://github.com/blessedrebus/krawl/blob/main/helm/README.md) para configuração completa e instruções de migração.
### Uvicorn (Python)
Execute o Krawl diretamente com Python 3.13+ e uvicorn para desenvolvimento local ou testes:```bash
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 5000 --app-dir src --no-server-header
```
Acesse o servidor em `http://localhost:5000`
## Configuração
O Krawl usa uma **hierarquia de configuração** na qual **variáveis de ambiente têm precedência sobre o arquivo de configuração**. Essa abordagem é recomendada para implantações Docker e personalização rápida pronta para uso.
### Configuração via config.yaml
Você pode usar o arquivo [config.yaml](https://github.com/blessedrebus/krawl/blob/main/config.yaml) para configurações avançadas, como implantações com Docker Compose ou Helm chart.
### Configuração via Variáveis de Ambiente
Todas as configurações podem ser fornecidas como variáveis de ambiente, que substituem o `config.yaml`.
O nome da variável é `KRAWL_` mais o caminho da configuração em maiúsculas, então `dashboard.password`
se torna `KRAWL_DASHBOARD_PASSWORD`.
<details>
<summary><b>Servidor e geração de links</b> (11 variáveis)</summary>
Como o Krawl se apresenta e molda o labirinto de páginas geradas.
| Variável de Ambiente | Descrição | Padrão |
|----------------------|-------------|---------|
| `CONFIG_LOCATION` | Caminho para o arquivo de configuração yaml | `config.yaml` |
| `KRAWL_PORT` | Porta de escuta do servidor | `5000` |
| `KRAWL_DELAY` | Atraso de resposta em milissegundos | `100` |
| `KRAWL_SERVER_HEADER` | Cabeçalho HTTP Server para decepção | `""` |
| `KRAWL_LINKS_LENGTH_RANGE` | Intervalo de comprimento dos links como `min,max` | `5,15` |
| `KRAWL_LINKS_PER_PAGE_RANGE` | Links por página como `min,max` | `10,15` |
| `KRAWL_CHAR_SPACE` | Caracteres usados para geração de links | `abcdefgh...` |
| `KRAWL_MAX_COUNTER` | Valor inicial do contador | `10` |
| `KRAWL_PROBABILITY_ERROR_CODES` | Probabilidade de resposta de erro (0-100%) | `0` |
| `KRAWL_INFINITE_PAGES_FOR_MALICIOUS` | Servir páginas infinitas para IPs maliciosos | `true` |
| `KRAWL_MAX_PAGES_LIMIT` | Limite máximo de páginas para crawlers | `250` |
| `KRAWL_BAN_DURATION_SECONDS` | Duração do banimento em segundos para IPs com taxa limitada | `600` |
</details>
<details>
<summary><b>Dashboard, métricas e logging</b> (13 variáveis)</summary>
Acesso ao dashboard, aquecimento de cache, Prometheus e nível de log.
| Variável de Ambiente | Descrição | Padrão |
|----------------------|-------------|---------|
| `KRAWL_DASHBOARD_SECRET_PATH` | Caminho personalizado do dashboard | Gerado automaticamente |
| `KRAWL_DASHBOARD_PASSWORD` | Senha para painéis protegidos do dashboard | Gerado automaticamente |
| `KRAWL_DASHBOARD_CACHE_WARMUP` | Pré-calcular dados do dashboard a cada 5 minutos para carregamento instantâneo das páginas | `true` |
| `KRAWL_DASHBOARD_WARMUP_PAGES` | Número de páginas para pré-aquecer por painel de tabela | `10` |
| `KRAWL_DASHBOARD_WARMUP_AGGREGATION` | Pré-calcular agregações completas de top_paths/top_ua para servir sem consultas | `false` |
| `KRAWL_DASHBOARD_TOP_N_MIN_COUNT` | Contagem mínima de acessos para os painéis de top paths/user agents (defina como 1 para desativar) | `5` |
| `KRAWL_DASHBOARD_BRAND_NAME` | Nome na marca nominativa e no título do dashboard | `Krawl` |
| `KRAWL_DASHBOARD_BRAND_URL` | Para onde a marca nominativa aponta (vazio renderiza como texto simples) | Repositório do Krawl |
| `KRAWL_DASHBOARD_BRAND_LOGO` | URL da imagem exibida em vez da marca do GitHub | Não definido |
| `KRAWL_DASHBOARD_BRAND_SHOW_VERSION` | Mostrar a versão ao lado do nome | `true` |
| `KRAWL_DASHBOARD_BRAND_CONTACT` | Contato exibido sob a marca nominativa (endereço, URL ou texto simples) | Não definido |
| `KRAWL_METRICS_ENABLED` | Expor métricas Prometheus em `/<dashboard_path>/metrics` | `true` |
| `KRAWL_LOG_LEVEL` | Nível de log da aplicação (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |
</details>
<details>
<summary><b>Banco de dados, retenção e backups</b> (12 variáveis)</summary>
Local de armazenamento, por quanto tempo os dados são mantidos e o job de dump.
| Variável de Ambiente | Descrição | Padrão |
|----------------------|-------------|---------|
| `KRAWL_DATABASE_PATH` | Localização do arquivo do banco de dados | `data/krawl.db` |
| `KRAWL_DATABASE_PERSIST_SUSPICIOUS_ONLY` | Persistir apenas requisições suspeitas no log de acesso | `false` |
| `KRAWL_MAP_TILE_URL` | Template de URL de tile para o mapa do dashboard (`{z}/{x}/{y}`, opcional `{s}`/`{r}`) | Esri dark canvas |
| `KRAWL_MAP_TILE_ATTRIBUTION` | Atribuição exibida no mapa | Esri/OSM |
| `KRAWL_MAP_API_KEY` | Anexado a cada requisição de tile como parâmetro de consulta — exigido pelo CARTO | _(vazio)_ |
| `KRAWL_MAP_API_KEY_PARAM` | Nome desse parâmetro de consulta (`api_key`, `apikey`, `key`) | `api_key` |
| `KRAWL_IPV6_IGNORE` | Descartar requisições IPv6 completamente: ainda registradas no stdout, nunca persistidas, verificadas para banimento ou exportadas | `false` |
| `KRAWL_IPV6_PURGE_EXISTING` | Também excluir linhas IPv6 existentes na próxima inicialização (irreversível; requer `KRAWL_IPV6_IGNORE`) | `false` |
| `KRAWL_DATABASE_RETENTION_DAYS` | Dias para reter dados no banco de dados | `30` |
| `KRAWL_BACKUPS_PATH` | Caminho onde os dumps do banco de dados são salvos | `backups` |
| `KRAWL_BACKUPS_CRON` | expressão cron para controlar o agendamento do job de backup | `*/30 * * * *` |
| `KRAWL_BACKUPS_ENABLED` | Booleano para habilitar o job de dump do banco de dados | `true` |
</details>
<details>
<summary><b>Armadilhas: tarpit, páginas de decepção e canary</b> (6 variáveis)</summary>
Armadilhas opcionais e as páginas servidas aos atacantes.
| Variável de Ambiente | Descrição | Padrão |
|----------------------|-------------|---------|
| `KRAWL_TARPIT_ENABLED` | Prender agentes de IA com respostas lentas e texto aleatório | `false` |
| `KRAWL_TARPIT_DELAY_SECONDS` | Atraso extra em segundos adicionado por resposta quando o tarpit está ativo | `5` |
| `KRAWL_DECEPTION_IMPORT_PAGES` | Importar automaticamente páginas de decepção de `src/templates/deception/` na inicialização | `true` |
| `KRAWL_CUSTOM_TEMPLATE_PATH` | Caminho dentro do contêiner para um template HTML personalizado. O template deve incluir os placeholders `{counter}` e `{content}`. | `/templates/custom_page.html` |
| `KRAWL_CANARY_TOKEN_URL` | URL de token canary externo | Nenhum |
| `KRAWL_CANARY_TOKEN_TRIES` | Requisições antes de mostrar o token canary | `10` |
</details>
<details>
<summary><b>Analisador de reputação de IP</b> (6 variáveis)</summary>
Limiares que decidem como um IP é classificado.
| Variável de Ambiente | Descrição | Padrão |
|----------------------|-------------|---------|
| `KRAWL_HTTP_RISKY_METHODS_THRESHOLD` | Limiar para detecção de métodos HTTP de risco | `0.1` |
| `KRAWL_VIOLATED_ROBOTS_THRESHOLD` | Limiar para violações de robots.txt | `0.1` |
| `KRAWL_UNEVEN_REQUEST_TIMING_THRESHOLD` | Limiar do coeficiente de variação para timing | `0.5` |
| `KRAWL_UNEVEN_REQUEST_TIMING_TIME_WINDOW_SECONDS` | Janela de tempo para análise de timing de requisições em segundos | `300` |
| `KRAWL_USER_AGENTS_USED_THRESHOLD` | Limiar para detecção de múltiplos user agents | `2` |
| `KRAWL_ATTACK_URLS_THRESHOLD` | Limiar para detecção de URLs de ataque | `1` |
</details>
<details>
<summary><b>Captura de threat-intel</b> (4 variáveis)</summary>
Fuzzy-hash de payloads capturados (arquivos e corpos de requisição sinalizados) e agrupamento
de variantes quase duplicadas em clusters de campanha. Requer `py-tlsh`.
O hashing é executado como a tarefa em segundo plano agendada `hash-payloads` (veja
`src/tasks/hash_payloads.py`), que faz o hash de cada ataque capturado uma vez — novos
hits no momento da ingestão, e uma varredura retroativa única do histórico existente
rastreada por uma marca d'água `payload_hash_watermark` — e então agrupa os
digests em campanhas de padrões recorrentes.
| Variável de Ambiente | Descrição | Padrão |
|----------------------|-------------|---------|
| `KRAWL_TLSH_ENABLED` | Fazer hash de arquivos enviados e corpos de requisição sinalizados com TLSH para agrupamento de quase duplicatas | `true` |
| `KRAWL_TLSH_CLUSTER_THRESHOLD` | Distância TLSH abaixo da qual um payload entra em uma campanha existente (0 = bytes idênticos; variantes de um webshell normalmente diferem < 100) | `150` |
| `KRAWL_TLSH_CAMPAIGN_MIN_EVENTS` | Número de vezes que um payload deve ser visto antes de sua campanha aparecer na aba Threats | `10` |
| `KRAWL_REFERER_ENABLED` | Registrar o HTTP Referer de entrada nos logs de acesso, para rastreamento de cadeia de iscas | `true` |
</details>
<details>
<summary><b>Banlist e IPs ignorados</b> (4 variáveis)</summary>
Compartilhamento de banlists com outras instâncias e tráfego que nunca deve ser rastreado.
| Variável de Ambiente | Descrição | Padrão |
|----------------------|-------------|---------|
| `KRAWL_IGNORED_IPS` | IPs/CIDRs separados por vírgula nunca rastreados, banidos ou exportados | Loopback, RFC1918, link-local, CGNAT |
| `KRAWL_BANLIST_EXPORT_PATH` | Caminho público de download da banlist, ex.: `/public_banlist.txt` (vazio = desativado) | `""` |
| `KRAWL_BANLIST_SOURCES` | URLs de banlists upstream separadas por vírgula para buscar e mesclar | Banlist da comunidade Krawl |
| `KRAWL_BANLIST_REFRESH_INTERVAL` | Segundos entre buscas de banlists upstream | `3600` |
</details>
<details>
<summary><b>Páginas de decepção geradas por IA</b> (10 variáveis)</summary>
Veja a [documentação de Geração por IA](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md).
| Variável de Ambiente | Descrição | Padrão |
|----------------------|-------------|---------|
| `KRAWL_AI_ENABLED` | Habilitar páginas de decepção geradas por IA | `false` |
| `KRAWL_AI_PROVIDER` | Provedor de IA (`"openrouter"` ou `"openai"`) | `"openrouter"` |
| `KRAWL_AI_OPENAI_BASE_URL` | URL Base opcional da OpenAI para endpoints de API personalizados | `"https://api.openai.com/v1"` |
| `KRAWL_AI_API_KEY` | Chave de API para o provedor de IA | `None` |
| `KRAWL_AI_MODEL` | Modelo de IA a usar para geração de páginas | `"nvidia/nemotron-3-super-120b-a12b:free"` |
| `KRAWL_AI_TIMEOUT` | Tempo limite de requisição em segundos para chamadas à API de IA | `60` |
| `KRAWL_AI_MAX_DAILY_REQUESTS` | Número máximo de páginas geradas por IA por dia (0 = ilimitado) | `0` |
| `KRAWL_AI_PROMPT` | Template de prompt personalizado para geração de páginas por IA | Prompt padrão |
| `KRAWL_AI_REASONING_ENABLED` | Habilitar tokens de raciocínio (apenas modelos de raciocínio do OpenRouter) | `false` |
| `KRAWL_AI_REASONING_EFFORT` | Esforço de raciocínio (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`) | `"medium"` |
</details>
<details>
<summary><b>Modo escalável: PostgreSQL e Redis</b> (13 variáveis)</summary>
Usado apenas quando `KRAWL_MODE=scalable`. Veja [Modos de Implantação](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md).
| Variável de Ambiente | Descrição | Padrão |
|----------------------|-------------|---------|
| `KRAWL_MODE` | Modo de implantação (`standalone` ou `scalable`) | `standalone` |
| `KRAWL_POSTGRES_HOST` | Nome do host PostgreSQL | `localhost` |
| `KRAWL_POSTGRES_PORT` | Porta do PostgreSQL | `5432` |
| `KRAWL_POSTGRES_USER` | Nome de usuário do PostgreSQL | `krawl` |
| `KRAWL_POSTGRES_PASSWORD` | Senha do PostgreSQL | `krawl` |
| `KRAWL_POSTGRES_DATABASE` | Nome do banco de dados PostgreSQL | `krawl` |
| `KRAWL_REDIS_HOST` | Nome do host Redis | `localhost` |
| `KRAWL_REDIS_PORT` | Porta do Redis | `6379` |
| `KRAWL_REDIS_DB` | Número do banco de dados Redis | `0` |
| `KRAWL_REDIS_PASSWORD` | Senha do Redis | Nenhum |
| `KRAWL_REDIS_CACHE_TTL` | TTL em segundos para dados de aquecimento do dashboard | `600` |
| `KRAWL_REDIS_HOT_TTL` | TTL em segundos para dados de hot-path (informações de banimento, categorias de IP) | `30` |
| `KRAWL_REDIS_TABLE_TTL` | TTL em segundos para tabelas paginadas do dashboard | `120` |
</details>
Por exemplo```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"
```
Exemplo de execução do Docker com variáveis de ambiente (modo autônomo):```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
```
## Use o Krawl para Banir IPs Maliciosos
O Krawl usa um sistema baseado em reputação para classificar endereços IP de atacantes e fornece duas maneiras de exportar listas de IPs para integração com firewall.
O endpoint `/api/export-ips` consulta o banco de dados diretamente e suporta filtragem por categoria de IP (`attacker`, `bad_crawler`, `regular_user`, `good_crawler`) e formato de saída (`raw`, `iptables`, `nftables`):```bash
curl "https://your-krawl-instance/<DASHBOARD-PATH>/api/export-ips?categories=attacker&fwtype=raw"
```
Isso permite o bloqueio automático de tráfego malicioso em várias plataformas:
* [OPNsense e pfSense](https://ipv64.net/v64_blocklist_integration_guide)
* [RouterOS](https://rentry.co/krawl-routeros)
* [IPtables](https://github.com/blessedrebus/krawl/blob/main/plugins/iptables/README.md) e [Nftables](https://github.com/blessedrebus/krawl/blob/main/plugins/nftables/README.md)
* [Fail2Ban](https://github.com/blessedrebus/krawl/blob/main/plugins/fail2ban/README.md)
Para parâmetros completos da API, exemplos e adição de formatos personalizados de firewall, consulte a [documentação dos Exportadores de Firewall](https://github.com/blessedrebus/krawl/blob/main/docs/firewall-exporters.md).
O Krawl também pode enviar IPs banidos diretamente para uma Lista de IPs de Conta Cloudflare para uso em regras de WAF. A sincronização é executada como uma tarefa em segundo plano e atualiza a lista por substituição total em um intervalo configurável. Consulte a documentação do [Cloudflare Banlist Sync](https://github.com/blessedrebus/krawl/blob/main/docs/cloudflare_banlist.md).
## Reputação de IP
O Krawl [usa tarefas que analisam o tráfego recente para construir e atualizar continuamente uma pontuação de reputação de IP](https://github.com/blessedrebus/krawl/blob/main/src/tasks/analyze_ips.py). Ela é executada periodicamente e avalia cada endereço IP ativo com base em múltiplos indicadores comportamentais para classificá-lo como atacante, crawler ou usuário regular. Os limites são totalmente personalizáveis.
A análise inclui:
- **Uso de métodos HTTP de risco** (por exemplo, proporções de POST, PUT, DELETE)
- **Violações de Robots.txt**
- **Anomalias de tempo de requisição** (padrões em rajadas ou irregulares)
- **Consistência de User-Agent**
- **Detecção de URL de ataque** (por exemplo, injeção de SQL, padrões de XSS)
Cada sinal contribui para um modelo de pontuação ponderada que atribui uma categoria de reputação:
- `attacker`
- `bad_crawler`
- `good_crawler`
- `regular_user`
- `unknown` (para dados insuficientes)
As pontuações e métricas resultantes são armazenadas no banco de dados e usadas pelo Krawl para alimentar dashboards, rastreamento de reputação e ações automatizadas de mitigação, como banimento de IP ou integração com firewall.
## Páginas de Engano Geradas por IA
O Krawl pode gerar automaticamente páginas de engano realistas usando modelos de IA das APIs **OpenRouter** ou **OpenAI**. Esse recurso cria páginas honeypot únicas e plausíveis em tempo real para enganar atacantes sem a criação manual de páginas.
**Principais Recursos:**
- **Geração Dinâmica**: Cria páginas HTML únicas para qualquer caminho de requisição
- **Cache Inteligente**: Armazena em cache as páginas geradas para evitar chamadas de API redundantes
- **Limitação de Taxa Diária**: Controle os custos da API com limites de requisições configuráveis
- **Múltiplos Provedores**: Suporte para OpenRouter (opções gratuitas) e OpenAI
- **Fallback Gracioso**: Recorre ao honeypot padrão quando desabilitado ou quando o limite é atingido
- **Serviço em Cache**: Páginas geradas anteriormente são servidas mesmo quando a IA está desabilitada
**Configuração Rápida:**```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
```
Para configuração e uso detalhados, consulte a [documentação de Geração por IA](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md).
Você também pode **contribuir com templates de decepção** abrindo um PR, consulte [Contribuindo com Templates de Decepção](https://github.com/blessedrebus/krawl/blob/main/docs/deception_pages.md#contributing-deception-templates-via-pr).
## Executando Atrás de um Proxy Reverso ou CDN
```
---
[Read more](https://github.com/blessedrebus/krawl)