## Quickstart

### Docker Run

Запустите Krawl в автономном режиме с последним образом:```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

**Масштабируемый**: с PostgreSQL и Redis:

> [!CAUTION]
> В приведённом ниже примере используются **пароли по умолчанию** (`krawl`/`krawl`). **Измените их перед развертыванием в 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:

Production-ready compose-файлы также доступны в каталоге [`docker/`](https://github.com/blessedrebus/krawl/blob/HEAD/docker/). Для **разработки** (сборка из исходного кода с hot-reload) используйте compose-файлы в [`docker/dev/`](https://github.com/blessedrebus/krawl/blob/HEAD/docker/dev/).

Подробнее об обоих режимах см. [Deployment Modes](https://github.com/blessedrebus/krawl/blob/HEAD/docs/deployment-modes.md).

### Kubernetes
**Krawl также доступен нативно в Kubernetes**. Установка может быть выполнена либо [через манифест](https://github.com/blessedrebus/krawl/blob/HEAD/kubernetes/README.md), либо [с использованием Helm-чарта](https://github.com/blessedrebus/krawl/blob/HEAD/helm/README.md).

Helm-чарт **по умолчанию использует масштабируемый режим** со встроенными PostgreSQL и Redis:```bash
helm install krawl oci://ghcr.io/blessedrebus/krawl-chart --version 2.3.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

Сервер доступен по адресу `http://localhost:5000`


## Конфигурация
Krawl использует **иерархию конфигурации**, в которой **переменные окружения имеют приоритет над конфигурационным файлом**. Такой подход рекомендуется для развёртывания в Docker и быстрой настройки без дополнительных изменений.

### Конфигурация через config.yaml
Вы можете использовать файл [config.yaml](https://github.com/blessedrebus/krawl/blob/HEAD/config.yaml) для расширенной конфигурации, например, при развёртывании с помощью Docker Compose или Helm chart.

### Конфигурация через переменные окружения

Все настройки можно задавать через переменные окружения, которые переопределяют `config.yaml`.
Имя переменной состоит из `KRAWL_` и пути к настройке в верхнем регистре, так что `dashboard.password` становится `KRAWL_DASHBOARD_PASSWORD`.

<details>
<summary><b>Сервер и генерация ссылок</b> (12 переменных)</summary>

Как Krawl представляет себя и формирует лабиринт генерируемых страниц.

| Environment Variable | Description | Default |
|----------------------|-------------|---------|
| `CONFIG_LOCATION` | Path to yaml config file | `config.yaml` |
| `KRAWL_PORT` | Server listening port | `5000` |
| `KRAWL_DELAY` | Response delay in milliseconds | `100` |
| `KRAWL_SERVER_HEADER` | HTTP Server header for deception | `""` |
| `KRAWL_LINKS_LENGTH_RANGE` | Link length range as `min,max` | `5,15` |
| `KRAWL_LINKS_PER_PAGE_RANGE` | Links per page as `min,max` | `10,15` |
| `KRAWL_CHAR_SPACE` | Characters used for link generation | `abcdefgh...` |
| `KRAWL_MAX_COUNTER` | Initial counter value | `10` |
| `KRAWL_PROBABILITY_ERROR_CODES` | Error response probability (0-100%) | `0` |
| `KRAWL_INFINITE_PAGES_FOR_MALICIOUS` | Serve infinite pages to malicious IPs | `true` |
| `KRAWL_MAX_PAGES_LIMIT` | Maximum page limit for crawlers | `250` |
| `KRAWL_BAN_DURATION_SECONDS` | Ban duration in seconds for rate-limited IPs | `600` |

</details>

<details>
<summary><b>Панель управления, метрики и журналирование</b> (8 переменных)</summary>

Доступ к панели управления, прогрев кэша, Prometheus и уровень журналирования.

| Environment Variable | Description | Default |
|----------------------|-------------|---------|
| `KRAWL_DASHBOARD_SECRET_PATH` | Custom dashboard path | Auto-generated |
| `KRAWL_DASHBOARD_PASSWORD` | Password for protected dashboard panels | Auto-generated |
| `KRAWL_DASHBOARD_CACHE_WARMUP` | Pre-compute dashboard data every 5 minutes for instant page loads | `true` |
| `KRAWL_DASHBOARD_WARMUP_PAGES` | Number of pages to pre-warm per table panel | `10` |
| `KRAWL_DASHBOARD_WARMUP_AGGREGATION` | Pre-compute full top_paths/top_ua aggregations for zero-query serving | `false` |
| `KRAWL_DASHBOARD_TOP_N_MIN_COUNT` | Minimum access count for top paths/user agents panels (set to 1 to disable) | `5` |
| `KRAWL_METRICS_ENABLED` | Expose Prometheus metrics at `/<dashboard_path>/metrics` | `true` |
| `KRAWL_LOG_LEVEL` | Application log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |

</details>

<details>
<summary><b>База данных, хранение и резервное копирование</b> (6 переменных)</summary>

Место хранения, срок хранения данных и задание дампа.

| Environment Variable | Description | Default |
|----------------------|-------------|---------|
| `KRAWL_DATABASE_PATH` | Database file location | `data/krawl.db` |
| `KRAWL_DATABASE_PERSIST_SUSPICIOUS_ONLY` | Only persist suspicious requests to the access log | `false` |
| `KRAWL_DATABASE_RETENTION_DAYS` | Days to retain data in database | `30` |
| `KRAWL_BACKUPS_PATH` | Path where database dump are saved | `backups` |
| `KRAWL_BACKUPS_CRON` | cron expression to control backup job schedule | `*/30 * * * *` |
| `KRAWL_BACKUPS_ENABLED` | Boolean to enable db dump job | `true` |

</details>

<details>
<summary><b>Ловушки: tarpit, страницы обмана и canary</b> (6 переменных)</summary>

Дополнительные ловушки и страницы, отдаваемые атакующим.

| Environment Variable | Description | Default |
|----------------------|-------------|---------|
| `KRAWL_TARPIT_ENABLED` | Trap AI agents with slow responses and random text | `false` |
| `KRAWL_TARPIT_DELAY_SECONDS` | Extra delay in seconds added per response when tarpit is active | `5` |
| `KRAWL_DECEPTION_IMPORT_PAGES` | Auto-import deception pages from `src/templates/deception/` at startup | `true` |
| `KRAWL_CUSTOM_TEMPLATE_PATH` | Path inside the container to a custom HTML template. Template must include `{counter}` and `{content}` placeholders. | `/templates/custom_page.html` |
| `KRAWL_CANARY_TOKEN_URL` | External canary token URL | None |
| `KRAWL_CANARY_TOKEN_TRIES` | Requests before showing canary token | `10` |

</details>

<details>
<summary><b>Анализатор репутации IP-адресов</b> (6 переменных)</summary>

Пороговые значения, определяющие классификацию IP-адреса.

| Environment Variable | Description | Default |
|----------------------|-------------|---------|
| `KRAWL_HTTP_RISKY_METHODS_THRESHOLD` | Threshold for risky HTTP methods detection | `0.1` |
| `KRAWL_VIOLATED_ROBOTS_THRESHOLD` | Threshold for robots.txt violations | `0.1` |
| `KRAWL_UNEVEN_REQUEST_TIMING_THRESHOLD` | Coefficient of variation threshold for timing | `0.5` |
| `KRAWL_UNEVEN_REQUEST_TIMING_TIME_WINDOW_SECONDS` | Time window for request timing analysis in seconds | `300` |
| `KRAWL_USER_AGENTS_USED_THRESHOLD` | Threshold for detecting multiple user agents | `2` |
| `KRAWL_ATTACK_URLS_THRESHOLD` | Threshold for attack URL detection | `1` |

</details>

<details>
<summary><b>Бан-листы и игнорируемые IP-адреса</b> (4 переменных)</summary>

Обмен бан-листами с другими экземплярами и трафик, который никогда не отслеживается.

| Environment Variable | Description | Default |
|----------------------|-------------|---------|
| `KRAWL_IGNORED_IPS` | Comma-separated IPs/CIDRs never tracked, banned or exported | Loopback, RFC1918, link-local, CGNAT |
| `KRAWL_BANLIST_EXPORT_PATH` | Public banlist download path, e.g. `/public_banlist.txt` (empty = disabled) | `""` |
| `KRAWL_BANLIST_SOURCES` | Comma-separated upstream banlist URLs to fetch and merge | Бан-лист сообщества Krawl |
| `KRAWL_BANLIST_REFRESH_INTERVAL` | Seconds between upstream banlist fetches | `3600` |

</details>

<details>
<summary><b>Страницы обмана, созданные ИИ</b> (10 переменных)</summary>

См. [документацию по генерации ИИ](https://github.com/blessedrebus/krawl/blob/HEAD/docs/ai_generation.md).

| Environment Variable | Description | Default |
|----------------------|-------------|---------|
| `KRAWL_AI_ENABLED` | Enable AI-generated deception pages | `false` |
| `KRAWL_AI_PROVIDER` | AI provider (`"openrouter"` or `"openai"`) | `"openrouter"` |
| `KRAWL_AI_OPENAI_BASE_URL` | Optional OpenAI Base URL for custom API endpoints | `"https://api.openai.com/v1"` |
| `KRAWL_AI_API_KEY` | API key for AI provider | `None` |
| `KRAWL_AI_MODEL` | AI model to use for page generation | `"nvidia/nemotron-3-super-120b-a12b:free"` |
| `KRAWL_AI_TIMEOUT` | Request timeout in seconds for AI API calls | `60` |
| `KRAWL_AI_MAX_DAILY_REQUESTS` | Max number of AI-generated pages per day (0 = unlimited) | `0` |
| `KRAWL_AI_PROMPT` | Custom prompt template for AI page generation | Default prompt |
| `KRAWL_AI_REASONING_ENABLED` | Enable reasoning tokens (OpenRouter reasoning models only) | `false` |
| `KRAWL_AI_REASONING_EFFORT` | Reasoning effort (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`) | `"medium"` |

</details>

<details>
<summary><b>Масштабируемый режим: PostgreSQL и Redis</b> (13 переменных)</summary>

Используется только при `KRAWL_MODE=scalable`. См. [Режимы развёртывания](https://github.com/blessedrebus/krawl/blob/HEAD/docs/deployment-modes.md).

| Environment Variable | Description | Default |
|----------------------|-------------|---------|
| `KRAWL_MODE` | Deployment mode (`standalone` or `scalable`) | `standalone` |
| `KRAWL_POSTGRES_HOST` | PostgreSQL hostname | `localhost` |
| `KRAWL_POSTGRES_PORT` | PostgreSQL port | `5432` |
| `KRAWL_POSTGRES_USER` | PostgreSQL username | `krawl` |
| `KRAWL_POSTGRES_PASSWORD` | PostgreSQL password | `krawl` |
| `KRAWL_POSTGRES_DATABASE` | PostgreSQL database name | `krawl` |
| `KRAWL_REDIS_HOST` | Redis hostname | `localhost` |
| `KRAWL_REDIS_PORT` | Redis port | `6379` |
| `KRAWL_REDIS_DB` | Redis database number | `0` |
| `KRAWL_REDIS_PASSWORD` | Redis password | None |
| `KRAWL_REDIS_CACHE_TTL` | TTL in seconds for dashboard warmup data | `600` |
| `KRAWL_REDIS_HOT_TTL` | TTL in seconds for hot-path data (ban info, IP categories) | `30` |
| `KRAWL_REDIS_TABLE_TTL` | TTL in seconds for paginated dashboard tables | `120` |

</details>


Например```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"

## Использование Krawl для блокировки вредоносных IP-адресов

Krawl использует систему на основе репутации для классификации IP-адресов атакующих и предоставляет два способа экспорта списков IP-адресов для интеграции с межсетевыми экранами.

Конечная точка `/api/export-ips` напрямую запрашивает базу данных и поддерживает фильтрацию по категории IP-адреса (`attacker`, `bad_crawler`, `regular_user`, `good_crawler`) и формату вывода (`raw`, `iptables`, `nftables`):```bash
curl "https://your-krawl-instance/<DASHBOARD-PATH>/api/export-ips?categories=attacker&fwtype=raw"

Подробную информацию о настройке и использовании см. в [документации по генерации с помощью ИИ](https://github.com/blessedrebus/krawl/blob/HEAD/docs/ai_generation.md).

Вы также можете **внести свой вклад в шаблоны обмана**, открыв PR, см. [Вклад в шаблоны обмана](https://github.com/blessedrebus/krawl/blob/HEAD/docs/deception_pages.md#contributing-deception-templates-via-pr).

## Работа за обратным прокси или CDN

**NGINX, Traefik и другие прокси, такие как CloudFlare**, требуют пересылки заголовков, чтобы Krawl мог видеть реальный IP-адрес. Примеры конфигурации и полный список заголовков см. в [документации по обратному прокси](https://github.com/blessedrebus/krawl/blob/HEAD/docs/reverse-proxy.md).

## Метрики и мониторинг

Krawl предоставляет метрики [Prometheus](https://prometheus.io/) по адресу `/<dashboard_secret_path>/metrics` (включено по умолчанию) и поставляется с готовым к импорту дашбордом [Grafana](https://grafana.com/) в файле [`grafana-dashboard.json`](https://github.com/blessedrebus/krawl/blob/HEAD/grafana-dashboard.json).

Полный список метрик, шаги импорта Grafana и настройку сбора данных Prometheus / Kubernetes (`ServiceMonitor`) см. в [документации по мониторингу](https://github.com/blessedrebus/krawl/blob/HEAD/docs/monitoring.md).

## Дополнительная документация

| Тема | Описание |
|-------|-------------|
| [Генерация с помощью ИИ](https://github.com/blessedrebus/krawl/blob/HEAD/docs/ai_generation.md) | Настройка генерируемых ИИ обманных страниц с помощью OpenRouter или OpenAI |
| [Обманные страницы](https://github.com/blessedrebus/krawl/blob/HEAD/docs/deception_pages.md) | Управление обманными страницами, их импорт и экспорт; массовые операции и фильтрация по датам |
| [Режимы развертывания](https://github.com/blessedrebus/krawl/blob/HEAD/docs/deployment-modes.md) | Автономный (SQLite) и масштабируемый (PostgreSQL + Redis) режимы, конфигурация и миграция данных |
| [Honeypot](https://github.com/blessedrebus/krawl/blob/HEAD/docs/honeypot.md) | Полный обзор honeypot-страниц: поддельные формы входа, листинги каталогов, файлы с учетными данными, ловушки SQLi/XSS/XXE/инъекций команд и многое другое |
| [Панель мониторинга](https://github.com/blessedrebus/krawl/blob/HEAD/docs/dashboard.md) | Доступ к панели мониторинга в реальном времени и её изучение |
| [API панели мониторинга](https://github.com/blessedrebus/krawl/blob/HEAD/docs/dashboard-api.md) | Собственный JSON API Krawl: справочник конечных точек, аутентификация, интерактивная документация OpenAPI и загрузка вложений |
| [Внешние API](https://github.com/blessedrebus/krawl/blob/HEAD/docs/api.md) | Сторонние API, к которым Krawl обращается для получения данных об IP-адресах, репутации и геолокации |
| [Обратный прокси](https://github.com/blessedrebus/krawl/blob/HEAD/docs/reverse-proxy.md) | Как развернуть Krawl за NGINX или использовать подставные поддомены |
| [Резервное копирование базы данных](https://github.com/blessedrebus/krawl/blob/HEAD/docs/backups.md) | Включение и настройка автоматического задания по дампу базы данных |
| [Canary-токен](https://github.com/blessedrebus/krawl/blob/HEAD/docs/canary-token.md) | Настройка внешних триггеров оповещений через canarytokens.org |
| [Wordlist](https://github.com/blessedrebus/krawl/blob/HEAD/docs/wordlist.md) | Настройка поддельных имен пользователей, паролей и листингов каталогов |
| [Архитектура](https://github.com/blessedrebus/krawl/blob/HEAD/docs/architecture.md) | Технический обзор кодовой базы, конвейера запросов, схемы базы данных и фоновых задач |
| [Синхронизация бан-листа Cloudflare](https://github.com/blessedrebus/krawl/blob/HEAD/docs/cloudflare_banlist.md) | Отправляет заблокированные IP-адреса из Krawl в список IP учетной записи Cloudflare для использования в правилах WAF. Синхронизация выполняется как фоновая задача и обновляет список полной заменой. |
| [Экспортеры межсетевого экрана](https://github.com/blessedrebus/krawl/blob/HEAD/docs/firewall-exporters.md) | Экспорт бан-листов IP-адресов в форматах raw, iptables или nftables через REST API |
| [Tarpit](https://github.com/blessedrebus/krawl/blob/HEAD/docs/tarpit.md) | Замедление и «отравление» ИИ-краулеров задержанными ответами с шумовым заполнением |
| [Метрики и мониторинг](https://github.com/blessedrebus/krawl/blob/HEAD/docs/monitoring.md) | Конечная точка метрик Prometheus, справочник метрик, дашборд Grafana и сбор данных ServiceMonitor |

## Внесение вклада

Вклад приветствуется! Пожалуйста:
1. Сделайте форк репозитория
2. Создайте feature-ветку
3. Внесите свои изменения
4. Отправьте pull request (опишите изменения!)


## Отказ от ответственности
> [!CAUTION]
> Это система обмана/honeypot. Развертывайте её в изолированных средах и внимательно следите за событиями безопасности. Используйте ответственно и в соответствии с применимыми законами и нормативными актами.

## История звёзд
<img src="https://star-history.dera.page/svg?repos=BlessedRebuS/Krawl&amp;type=Date" width="600" alt="Star History Chart" />