Документация

Как подключить и настроить

Быстрый старт: домен под защитой за 5 шагов

Зарегистрируйтесь в дашборде — бесплатный период начинается сразу, карта не нужна.
Добавьте домен и укажите origin — адрес вашего сервера (например, https://1.2.3.4 или внутренний хост). Пользователи его не увидят.
Подтвердите владение: добавьте TXT-запись из инструкции в DNS домена. Дашборд проверит её автоматически.
Направьте домен на edge: для поддомена (например, www) — одна CNAME-запись на edge.crawlguard.ru; для голого домена — запись ALIAS/ANAME на тот же адрес, а если ваша DNS-панель их не поддерживает — A-записи на IP из инструкции. CNAME/ALIAS надёжнее: адреса edge обновляются автоматически, включая переключение при сбое узла. Точные записи для вашего домена показывает дашборд. TLS-сертификат выпустится автоматически при первом запросе.
Закройте origin: разрешите на своём сервере/файрволе трафик только с нашим заголовком X-Crawlguard-Origin-Lock (значение — в дашборде) или только с нашего IP. Иначе боты смогут обойти защиту, обращаясь к серверу напрямую. Дашборд показывает статус origin locked, когда всё правильно.

Все пять статусов — ownership · TLS · origin reachable · origin locked · protected — видны на странице сайта в дашборде с живой проверкой.

Как именно закрыть origin

Достаточно одного из способов. «Origin» здесь — ваш сервер, куда мы проксируем трафик.

По нашим IP (проще всего). На файрволе разрешите к origin входящие только с IP-адресов CrawlGuard (показаны в дашборде), остальное закройте. Например, ufw: ufw allow from <IP1> to any port 443, ufw allow from <IP2> to any port 443, затем запретить прочее.
По секретному заголовку (nginx). Пропускать только запросы с нашим заголовком: if ($http_x_crawlguard_origin_lock != "<значение из дашборда>") { return 403; } в server{}. Заголовок неугадываем и уникален для вашего домена.
Apache: аналогично через mod_headers/RewriteCond %{HTTP:X-Crawlguard-Origin-Lock}. Панель хостинга: правило файрвола «разрешить только IP-адреса CrawlGuard». Сайт за Cloudflare: снимите проксирование (серый значок) — CrawlGuard должен стоять первым в пути трафика.

Пока origin открыт напрямую, бот может обойти проверку, обратившись к серверу в обход нас. Дашборд загорится origin locked, когда доступ закрыт правильно.

Если ваш сервер сам держит HTTPS-сертификат

Многие серверы (Traefik, nginx или Apache с certbot, Caddy, панели хостинга) сами выпускают и автоматически продлевают бесплатный сертификат Let's Encrypt. После подключения к CrawlGuard домен указывает на нас — поэтому проверка Let's Encrypt при продлении приходит к нам, а не на ваш сервер. Чтобы это не ломало автопродление, мы прозрачно пропускаем ACME-проверку на ваш origin: запросы вида /.well-known/acme-challenge/… идут насквозь к вашему серверу.

Проверка HTTP-01 (по умолчанию у большинства) — ничего делать не нужно. Продление продолжит работать само. Так настроены Traefik (httpChallenge на entrypoint web), certbot (--webroot/--standalone), Caddy, большинство панелей.
Проверка TLS-ALPN-01 — переключите на HTTP-01 или DNS-01. Она идёт по 443-му порту, который теперь терминируем мы, поэтому до вашего сервера не доходит. В Traefik замените в резолвере tlsChallenge на httpChallenge: { entryPoint: web } — одна правка.
Проверка DNS-01 — работает как раньше, она вообще не зависит от веб-трафика.

Закрытие origin (шаг 5) автопродлению не мешает: ACME-запросы мы проксируем с нашего IP и фирменным заголовком, а серверы вроде Traefik отдают токен проверки ещё до своих правил доступа.

Не хотите держать сертификат на своей стороне вообще? Отдавайте контент внутренним HTTP (за закрытым origin), а публичный HTTPS полностью держим мы — тогда сертификат на вашем сервере не нужен.

Как работает защита

Посетитель без cookie доверия получает лёгкую страницу проверки. Браузер за ~1 секунду решает криптографическую задачу (proof-of-work), отправляет решение — сервер проверяет его, гасит одноразовый seed (повторно использовать решение нельзя) и ставит подписанную HttpOnly-cookie на вашем домене. Дальше запросы проходят мгновенно: подпись проверяется локально, без обращений к базе.

Посмотреть вживую на демо-сайте: curl -I https://demo.crawlguard.ru/ вернёт 401, а браузер пройдёт проверку и увидит содержимое.

Сложность (difficulty) настраивается per-домен в дашборде: выше — дороже для ботов, дольше для слабых устройств. Дефолт сбалансирован.
Срок cookie (TTL) — тоже per-домен; по истечении посетитель незаметно проходит проверку заново.
Решение «пустить или показать проверку» всегда принимает сервер. JavaScript на странице только решает задачу — отключить защиту из браузера нельзя.

Поисковые боты и SEO

Googlebot, YandexBot и Bingbot пропускаются без проверки. Верификация — по forward-confirmed reverse-DNS (IP → PTR → IP), а не по User-Agent: подделать UA может любой скрипт, подделать обратную DNS-запись поисковика — нет. Индексация и позиции не страдают; страница проверки отдаётся с noindex и корректными кодами ответов.

SPA, API и мобильные клиенты

HTML-проверка показывается только на навигацию браузера (GET с Accept: text/html). Fetch/XHR/POST-запросы без cookie получают чистый ответ:

HTTP/1.1 401 Unauthorized
X-Guard-Challenge: required

Ваш фронтенд может перехватить этот ответ и перезагрузить страницу — пользователь пройдёт проверку, и запрос повторится уже с cookie. API-клиенты и мобильные приложения, которым проверка не нужна, добавляются в allowlist.

Allowlist

Per-домен настраиваются исключения — им проверка не показывается никогда:

IP-диапазоны (CIDR) — офисные сети, партнёрские интеграции, мониторинг;
Пути — входящие вебхуки (/api/webhooks/), статика, health-чеки;
API-ключи — ваши доверенные клиенты передают ключ в заголовке X-Api-Key.

Всё редактируется в дашборде на странице домена или через API.

Производительность

Проверка стоит дёшево и не замедляет сайт заметным образом:

Возвращающиеся посетители: проверка cookie добавляет доли миллисекунды к ответу — в нагрузочных тестах 99% запросов укладывались в 8 мс вместе с проксированием, а потолка edge достичь не удалось: раньше сдавался генератор трафика.
Новые посетители: полная проверка (страница + задача + выдача cookie) — ~1 секунда в браузере. Задачу вычисляет браузер посетителя, а не наш узел, поэтому даже массовый наплыв новых посетителей или ботов нагружает edge незначительно.
На каждый запрос защита не обращается ни к базе данных, ни к внешним сервисам — поэтому отказ наших хранилищ не влияет на ваш трафик (fail-open).

Fail-open: ваш сайт важнее нашей защиты

Недоступна наша инфраструктура (выдача проверок, хранилище) — трафик пропускается без проверки, сайт продолжает работать.
Превышен лимит тарифа или не прошла оплата — защита переходит в passthrough (трафик насквозь), а не в блокировку. Мы никогда не выключаем ваш сайт из-за денег.

FAQ

Не заблокируете ли вы моих реальных клиентов?: Цель — не задеть живого человека. Проверка невидима и решается автоматически, без CAPTCHA и кликов. Поисковики и ваши интеграции (API, мобильные приложения) — в белом списке. Порог чувствительности настраивается, а детект автоматизации на новом домене можно перевести в режим наблюдения: сначала смотрите статистику, потом ужесточаете. Сама невидимая проверка браузера при этом работает с первого дня.
Вы терминируете мой HTTPS — что с данными посетителей?: Да, мы снимаем TLS — иначе нельзя проверять браузер и прятать ваш сервер. Но мы не храним тела запросов и ответов: в аналитику идут только обезличенные поминутные агрегаты решений, а IP усечён до подсети. Инфраструктура и данные — в России, по 152-ФЗ. Подробнее — в политике конфиденциальности.
Что будет, если ваш сервис станет недоступен?: Ваш сайт продолжит работать. При сбое нашей инфраструктуры трафик пропускается без проверки (fail-open), а не блокируется. Проверка cookie у вернувшихся посетителей вообще не зависит от нашей базы.
Пройдут ли мобильные и старые браузеры?: Современные — да, включая мобильные: проверка использует стандартный Web Crypto, он есть во всех браузерах последних лет. Совсем старые браузеры без Web Crypto (например, Internet Explorer) увидят сообщение о неподдерживаемом браузере, а посетитель с выключенным JavaScript — просьбу его включить.
Как устроена оплата и как её прекратить?: Вы пополняете баланс, оплата плана списывается с него раз в месяц — никаких автосписаний с карты. Чтобы прекратить оплату, просто не пополняйте баланс: защита доработает оплаченный период (плюс 7 дней запаса), сайт при этом не блокируется. По возвратам остатка напишите в поддержку; условия — в оферте.
Замедлится ли сайт?: Возвращающиеся посетители проходят за доли миллисекунды (локальная проверка подписи). Новые — один раз решают задачу ~1 с, дальше ходят свободно, пока жива cookie.
Что увидят пользователи?: Новый посетитель — короткий экран «проверяем браузер» примерно на секунду, без картинок и кликов. Дальше — ваш сайт как обычно.
Совместимо ли с CDN?: CrawlGuard сам терминирует TLS и должен стоять первым в пути трафика. CDN перед CrawlGuard не поддерживается; статику можно отдавать с отдельного домена-CDN либо добавить её пути в allowlist.
Как быстро выключить защиту?: Верните DNS-записи домена на свой сервер — трафик пойдёт напрямую (не забудьте открыть origin). Или удалите домен в дашборде.

Control-plane API

Всё, что умеет дашборд, доступно программно. Ключ выпускается на странице API keys; передаётся в заголовке Authorization: Bearer <key> или X-Api-Key: <key>.

curl -s https://app.crawlguard.ru/v1/sites \
  -H "Authorization: Bearer $CRAWLGUARD_KEY"

Метод и путь	Что делает
`POST /v1/sites`	добавить домен: `{"domain": "...", "origin_url": "..."}`
`GET /v1/sites`	список доменов аккаунта
`GET /v1/sites/{домен}`	карточка домена
`PATCH /v1/sites/{домен}`	настройки: difficulty, TTL, allowlist
`DELETE /v1/sites/{домен}`	удалить домен
`POST /v1/sites/{домен}/verification`	получить TXT-токен подтверждения владения
`POST /v1/sites/{домен}/verify`	проверить владение и продвинуть статус
`GET /v1/sites/{домен}/status`	статусы онбординга с живой проверкой origin
`GET /v1/sites/{домен}/events`	агрегаты решений для графиков
`POST /v1/sites/{домен}/rotate-secret`	ротация секрета подписи cookie
`POST /v1/sites/{домен}/allow-keys`	выпустить allowlist-ключ для `X-Api-Key` (показывается один раз)
`DELETE /v1/sites/{домен}/allow-keys`	отозвать все allowlist-ключи домена

Изменения настроек edge подхватывает без перезапусков — за секунды.