Red Node API для хостингов
API проверяет ваши адреса из России, следит за подсетями и сообщает о блокировках в ваш биллинг через вебхуки. Адрес сервера: https://redstudio.site/rednode/api/v1. Сейчас API открыт для пилотных хостингов; чтобы подключиться, напишите на support@redstudio.site.
Ключи и права
Каждый запрос несёт ключ в заголовке Authorization: Bearer rnh_3f9a1c0d2b_Xk2pQ.... Ключ привязан к одному хостингу и к набору прав. Полный ключ мы показываем один раз, а храним только его хэш.
pools:readиpools:write: пулы, состояния адресов и подсетей, подтверждение сетиchecks:readиchecks:write: разовые проверки и результатыevents:read: лента событийwebhooks:readиwebhooks:write: вебхуки и журнал доставокstatus:write: оформление страницы статусаkeys:write: выпуск, замена и отзыв ключей
Для биллинга хватит ключа с правами pools:read checks:write checks:read. Сокращения: read даёт все права на чтение, all даёт все права. Замена ключа (POST /keys/{id}/rotate) оставляет старый ключ рабочим ещё на сутки, чтобы вы успели поменять его в конфиге.
Быстрый старт
Заводим пул, то есть набор адресов с общим портом проверки. Для VPS берите порт 22 без TLS: SSH отвечает почти на каждом выданном сервере.
curl -X POST https://redstudio.site/rednode/api/v1/pools \
-H "Authorization: Bearer $RN_KEY" -H "Content-Type: application/json" \
-d '{"name": "Москва, стойка 2", "targets": "185.12.40.0/24", "port": 22, "tls": false}'
Проверяем весь пул разом. Ответ 202 приходит сразу, а итог прилетит событием pool_check.done:
curl -X POST https://redstudio.site/rednode/api/v1/pools/moskva-stoyka-2/check -H "Authorization: Bearer $RN_KEY"
Забираем результат по каждому адресу в CSV:
curl "https://redstudio.site/rednode/api/v1/checks/chk_5b1f0c2a9e/results?format=csv" -H "Authorization: Bearer $RN_KEY" -o result.csv
В сводке проверки (GET /checks/{id}) есть строка на каждую /24: сколько адресов заявлено, сколько открывается, сколько закрыто. Так видно «в 185.12.40.0/24 закрыто 37 из 254».
Как мы проверяем и что значат ответы
Каждый адрес проверяют две точки в России. Точка открывает TCP-соединение на ваш порт и, если включён TLS, отправляет ClientHello. Ничего больше: ни перебора портов, ни запросов к сервису. Если хоть одна российская точка не прошла, тот же адрес проверяет контрольная точка в Европе.
clean: из России соединение проходит. Ответ RST тоже считается проходом: значит, до адреса пакеты доходятblocked: из России соединение не проходит, а из Европы проходит.stageпоказывает где:tcp(пакеты не доходят),tls(TCP есть, рукопожатие TLS обрывается),rst(из России приходит сброс, из Европы порт открыт)partial: из части российских точек не проходитdown: адрес не отвечает ни из России, ни из Европыunknown: данных не хватило, например все точки были заняты
Свободный адрес, на котором ничего не висит, часто не отвечает вообще, и тогда мы честно скажем down. Чтобы проверять свободные адреса до выдачи, держите их на парковочном сервере: достаточно, чтобы на порт приходил хотя бы RST.
Мониторинг подсетей
Проверять тысячи адресов без перерыва нельзя, поэтому монитор берёт выборку. Каждые 15–60 минут (зависит от тарифа) из каждой /24 пула проверяются несколько адресов: сначала те, что вы отметили как выданные клиентам (POST /pools/{id}/priority), потом те, что давно не проверялись. Два свежих плохих ответа в одной /24 запускают проверку всех её отвечающих адресов. Раз в 12–24 часа проходит полный обход пула.
Смену состояния адреса мы подтверждаем второй проверкой и только потом шлём ip.blocked или ip.unblocked. Подсеть считается деградировавшей, когда закрыто от 20% её отвечающих адресов, и тёмной от 80%.
Подтверждение сети
Проверять можно только свои адреса. Без подтверждения доступно до 1024 адресов, а диапазон не шире /22. Чтобы снять ограничение, подтвердите сеть одним из двух способов.
- TXT-запись в обратной зоне. Значение берите из
GET /verification, имя записи_rednode.<3-й октет>.<2-й>.<1-й>.in-addr.arpa. Для 185.12.40.0/24 это_rednode.40.12.185.in-addr.arpa. У диапазона шире /24 мы проверяем первую, последнюю и одну случайную /24. Потом вызовитеPOST /pools/{id}/verifyсmethod: txt - ASN. Напишите в поддержку номер вашего ASN; мы сверим whois с названием хостинга и одобрим его. После этого
method: asnподтверждает любые диапазоны, которые анонсирует этот ASN
Если сеть уже подтвердил другой хостинг, проверить её с вашего ключа не получится.
Вебхуки
Событие приходит POST-запросом с JSON на ваш https-адрес. Заголовки: X-RedNode-Event, X-RedNode-Delivery (уникален для каждой доставки, по нему отсеивайте повторы), X-RedNode-Timestamp и X-RedNode-Signature вида t=1795171482,v1=<hex>, где v1 это HMAC-SHA256 от строки t + "." + тело на секрете вебхука.
Любой ответ 2xx засчитываем как доставку. Иначе повторяем через 30 секунд, 2 минуты, 10 минут, 30 минут, 2 часа и 6 часов. Редиректы не выполняем. Журнал доставок: GET /webhooks/{id}/deliveries, повторная отправка: POST /deliveries/{id}/redeliver.
События
ip.blocked: адрес перестал открываться из России (или из части российских точек). Приходит после двух независимых проверокip.unblocked: адрес снова открывается из России, тоже после двух проверокsubnet.degraded: в /24 закрыта заметная доля отвечающих адресов: level degraded от 20%, dark от 80%subnet.recovered: подсеть снова в порядкеasn.degraded: плохо в половине и более ваших подсетей одного ASN (минимум две подсети)asn.recovered: в ASN снова порядокpool_check.done: разовая проверка закончилась, в событии итог и сводка по /24
Пример тела ip.blocked:
{
"id": "evt_3f9a1c0d2b7e4a51",
"type": "ip.blocked",
"created": 1795171482,
"org": "severny-host",
"data": {
"ip": "185.12.40.17",
"port": 443,
"stage": "tcp",
"verdict": "blocked",
"pool": {
"id": 3,
"slug": "msk-2",
"name": "Москва, стойка 2"
},
"subnet": "185.12.40.0/24",
"since": 1795171200,
"first_seen": false
}
}
Проверка подписи в PHP (WHMCS, BILLmanager)
<?php
$secret = getenv('RN_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_REDNODE_SIGNATURE'] ?? ''), $sig);
$ok = isset($sig['t'], $sig['v1']) && abs(time() - (int)$sig['t']) < 300
&& hash_equals(hash_hmac('sha256', $sig['t'] . '.' . $body, $secret), $sig['v1']);
if (!$ok) { http_response_code(401); exit; }
$event = json_decode($body, true);
if ($event['type'] === 'ip.blocked') {
// пометить $event['data']['ip'] в своей базе адресов как «не выдавать»
}
http_response_code(200);
Проверка подписи в Python
import hashlib, hmac, time
def verify(secret: str, header: str, body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
mac = hmac.new(secret.encode(), parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, parts["v1"])
Связка с биллингом
Самая полезная связка: биллинг перестаёт выдавать адреса, которые закрыты из России.
- Перед выдачей адреса спросите его состояние:
POST /ips/lookupотвечает сразу по последней проверке - Если адрес давно не проверялся, проверьте его вне очереди:
POST /ips/checkс"wait": 45вернёт вердикт в том же ответе - Вебхук
ip.blockedснимает адрес с выдачи,ip.unblockedвозвращает
curl -X POST https://redstudio.site/rednode/api/v1/ips/check -H "Authorization: Bearer $RN_KEY" -H "Content-Type: application/json" \
-d '{"ips": ["185.12.40.17"], "port": 22, "tls": false, "wait": 45}'
В WHMCS проверку вешают на хук после создания услуги, в BILLmanager на обработчик создания сервера или на скрипт по расписанию, который берёт свободные адреса и спрашивает /ips/lookup.
Страница статуса
У каждого хостинга есть публичная страница для клиентов: https://rednode.redstudio.site/status/<slug>/. На ней ваше название, логотип и цвет, локации с долей адресов, которые открываются из России, время последней проверки, история за 30 дней и блокировки подсетей за две недели. Адреса и подсети на странице не видны, пока вы сами не включите show_ranges.
Значок для сайта: <slug>/badge.svg (для одной локации ?pool=<slug пула>). Данные для своей вёрстки: <slug>/status.json, CORS открыт.
Лимиты и ошибки
Ошибки приходят JSON-ом {"error": "код", "text": "что случилось"}. Частые коды: 401 (ключ не подходит), 403 scope (у ключа нет права), 403 verify_needed (нужно подтверждение сети), 403 foreign (сеть другого хостинга), 429 rate (запросов в минуту больше тарифа), 429 quota (проверки месяца кончились), 429 daily_cap (дневной лимит наших точек).
Пока выделенные точки проверки для хостингов не запущены, разовые проверки идут на общих точках с жёстким дневным лимитом на все аккаунты вместе. Точки держат темп в несколько соединений в минуту со случайными паузами и сами отказываются стучаться в частные сети и в один адрес на разные порты.
Аккаунт
Работает с любым действующим ключом.
Ответ 200
Аккаунт, пулы, адреса по состояниям, плохие подсети, последние проверки и события одним ответом.
Нужно право ключа pools:read.
Ответ 200
Для сессии панели Red Node и для бота: доступна ли линия для хостингов, аккаунты, тарифы. API-ключом не вызывается.
Ответ 200
Создаёт аккаунт хостинга с пробной неделей для того, кто вошёл в панель или пишет боту.
- nameтело, string, обязательно
Ответ 201
Ключи
Нужно право ключа keys:write.
Ответ 200
Полный ключ приходит один раз в поле secret. Ключ не может получить прав больше, чем у ключа, которым его выпускают.
Нужно право ключа keys:write.
- nameтело, string
- scopesтело, array of string
- expires_daysтело, integer
Ответ 201
Выпускает новый ключ с теми же правами. Старый работает ещё grace_hours часов (по умолчанию 24, от 0 до 168), чтобы вы успели обновить биллинг.
Нужно право ключа keys:write.
- kidpath, string
- grace_hoursтело, integer
Ответ 201
Нужно право ключа keys:write.
- kidpath, string
Ответ 200
Пулы
Нужно право ключа pools:read.
Ответ 200
Пул это набор ваших адресов с общим портом проверки, например стойка или локация. Диапазоны шире /22 и больше 1024 адресов без подтверждения принимаем только после подтверждения сети.
Нужно право ключа pools:write.
- nameтело, string, обязательно
- targetsтело, string, обязательно
- locationтело, string
- portтело, integer
- sniтело, string
- tlsтело, boolean
- monitorтело, boolean
- publicтело, boolean
- slugтело, string
Ответ 201
Нужно право ключа pools:read.
- poolpath, string
- id или slug пула
Ответ 200
Поля как при создании, кроме targets.
Нужно право ключа pools:write.
- poolpath, string
- id или slug пула
- nameтело, string, обязательно
- targetsтело, string, обязательно
- locationтело, string
- portтело, integer
- sniтело, string
- tlsтело, boolean
- monitorтело, boolean
- publicтело, boolean
- slugтело, string
Ответ 200
Нужно право ключа pools:write.
- poolpath, string
- id или slug пула
Ответ 200
Проверяет TXT-запись в обратной зоне (method: txt) или одобренный ASN (method: asn) для всех неподтверждённых диапазонов пула или для одного (range_id).
Нужно право ключа pools:write.
- poolpath, string
- id или slug пула
- methodтело, string
- range_idтело, integer
Ответ 200
Нужно право ключа pools:read.
Ответ 200
Проверки
Разовая проверка всех адресов пула. Результаты обновляют состояние пула. Когда закончится, придёт событие pool_check.done.
Нужно право ключа checks:write.
- poolpath, string
- id или slug пула
- portтело, integer
- sniтело, string
- tlsтело, boolean
- labelтело, string
Ответ 202
Нужно право ключа checks:read.
- limitquery, integer
Ответ 200
Разовая проверка списка. Адреса из ваших пулов можно проверять в пределах тарифа; адреса вне пулов считаются новым заявлением: не шире /22 и не больше 1024 без подтверждения сети. Чужие подтверждённые сети проверить нельзя.
Нужно право ключа checks:write.
- targetsтело, string | array of string, обязательно
- Адреса, подсети CIDR и диапазоны: 185.12.40.17, 185.12.40.0/24, 185.12.40.10-185.12.40.50 или 185.12.40.10-50. Через перевод строки, запятую или пробел; CSV тоже подходит
- portтело, integer
- Порт, на который идёт рукопожатие. Один на проверку
- sniтело, string
- SNI для ClientHello; пусто значит без SNI
- tlsтело, boolean
- false: только TCP-рукопожатие
- labelтело, string
- Подпись для отчёта
Ответ 202
Нужно право ключа checks:read.
- cidpath, string
Ответ 200
format=csv отдаёт CSV с колонками ip, verdict, stage, subnet, ru_tcp, ru_tls, eu_tcp, eu_tls, note, finished.
Нужно право ключа checks:read.
- cidpath, string
- formatquery, string
- verdictquery, string
Ответ 200
До 50 адресов вне очереди, например перед выдачей IP новому клиенту. С wait (до 60 секунд) ответ ждёт результата: 200 с вердиктами или 202, если проверка ещё идёт.
Нужно право ключа checks:write.
- ipsтело, array of string, обязательно
- portтело, integer
- sniтело, string
- tlsтело, boolean
- waitтело, integer
Ответ 200
Мониторинг
Нужно право ключа pools:read.
- poolpath, string
- id или slug пула
Ответ 200
Страницами по 500 (до 5000), дальше after.
Нужно право ключа pools:read.
- poolpath, string
- id или slug пула
- statequery, string
- afterquery, integer
- limitquery, integer
Ответ 200
Эти адреса попадают в каждую выборку мониторинга первыми. priority: false снимает отметку.
Нужно право ключа pools:write.
- poolpath, string
- id или slug пула
- ipsтело, array of string, обязательно
- priorityтело, boolean
Ответ 200
Без новой проверки: что мы знаем о каждом адресе сейчас. До 1000 адресов.
Нужно право ключа pools:read.
- ipsтело, array of string, обязательно
Ответ 200
Нужно право ключа pools:read.
- ippath, string
Ответ 200
События и вебхуки
Те же события, что уходят в вебхуки. Читайте с after=<next_after> прошлого ответа.
Нужно право ключа events:read.
- afterquery, integer
- typesquery, string
- limitquery, integer
Ответ 200
Нужно право ключа webhooks:read.
Ответ 200
Только https и только публичные адреса. Секрет приходит один раз.
Нужно право ключа webhooks:write.
- urlтело, string, обязательно
- eventsтело, array of string
- descriptionтело, string
Ответ 201
Нужно право ключа webhooks:write.
- hidpath, string
- urlтело, string
- eventsтело, array of string
- activeтело, boolean
- descriptionтело, string
Ответ 200
Нужно право ключа webhooks:write.
- hidpath, string
Ответ 200
Нужно право ключа webhooks:write.
- hidpath, string
Ответ 200
Нужно право ключа webhooks:write.
- hidpath, string
Ответ 202
Нужно право ключа webhooks:read.
- hidpath, string
- limitquery, integer
Ответ 200
Нужно право ключа webhooks:write.
- didpath, string
Ответ 200
Страница статуса
Нужно право ключа pools:read.
Ответ 200
title, subtitle, accent и accent_dark (#RRGGBB), site_url, support_url, show_ranges, enabled, slug, custom_domain (тарифы Сеть и Оператор).
Нужно право ключа status:write.
- titleтело, string
- subtitleтело, string
- accentтело, string
- accent_darkтело, string
- site_urlтело, string
- support_urlтело, string
- show_rangesтело, boolean
- enabledтело, boolean
- slugтело, string
- custom_domainтело, string
Ответ 200
Тело запроса: сам файл PNG, JPEG или WebP до 256 КБ. ?theme=dark для логотипа тёмной темы.
Нужно право ключа status:write.
- themequery, string
Ответ 200
Нужно право ключа status:write.
- themequery, string
Ответ 200