Red Node API

Red Node API для хостингов

API проверяет ваши адреса из России, следит за подсетями и сообщает о блокировках в ваш биллинг через вебхуки. Адрес сервера: https://redstudio.site/rednode/api/v1. Сейчас API открыт для пилотных хостингов; чтобы подключиться, напишите на support@redstudio.site.

Ключи и права

Каждый запрос несёт ключ в заголовке Authorization: Bearer rnh_3f9a1c0d2b_Xk2pQ.... Ключ привязан к одному хостингу и к набору прав. Полный ключ мы показываем один раз, а храним только его хэш.

Для биллинга хватит ключа с правами 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. Ничего больше: ни перебора портов, ни запросов к сервису. Если хоть одна российская точка не прошла, тот же адрес проверяет контрольная точка в Европе.

Свободный адрес, на котором ничего не висит, часто не отвечает вообще, и тогда мы честно скажем down. Чтобы проверять свободные адреса до выдачи, держите их на парковочном сервере: достаточно, чтобы на порт приходил хотя бы RST.

Мониторинг подсетей

Проверять тысячи адресов без перерыва нельзя, поэтому монитор берёт выборку. Каждые 15–60 минут (зависит от тарифа) из каждой /24 пула проверяются несколько адресов: сначала те, что вы отметили как выданные клиентам (POST /pools/{id}/priority), потом те, что давно не проверялись. Два свежих плохих ответа в одной /24 запускают проверку всех её отвечающих адресов. Раз в 12–24 часа проходит полный обход пула.

Смену состояния адреса мы подтверждаем второй проверкой и только потом шлём ip.blocked или ip.unblocked. Подсеть считается деградировавшей, когда закрыто от 20% её отвечающих адресов, и тёмной от 80%.

Подтверждение сети

Проверять можно только свои адреса. Без подтверждения доступно до 1024 адресов, а диапазон не шире /22. Чтобы снять ограничение, подтвердите сеть одним из двух способов.

Если сеть уже подтвердил другой хостинг, проверить её с вашего ключа не получится.

Вебхуки

Событие приходит 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:

{
  "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"])

Связка с биллингом

Самая полезная связка: биллинг перестаёт выдавать адреса, которые закрыты из России.

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 (дневной лимит наших точек).

Пока выделенные точки проверки для хостингов не запущены, разовые проверки идут на общих точках с жёстким дневным лимитом на все аккаунты вместе. Точки держат темп в несколько соединений в минуту со случайными паузами и сами отказываются стучаться в частные сети и в один адрес на разные порты.

Аккаунт

GET/accountАккаунт, тариф, лимиты и расход

Работает с любым действующим ключом.

Ответ 200

GET/overviewСводка для главного экрана

Аккаунт, пулы, адреса по состояниям, плохие подсети, последние проверки и события одним ответом.

Нужно право ключа pools:read.

Ответ 200

GET/meКто вошёл (панель и бот)

Для сессии панели Red Node и для бота: доступна ли линия для хостингов, аккаунты, тарифы. API-ключом не вызывается.

Ответ 200

POST/onboardЗавести хостинг (панель и бот)

Создаёт аккаунт хостинга с пробной неделей для того, кто вошёл в панель или пишет боту.

nameтело, string, обязательно

Ответ 201

Ключи

GET/keysСписок ключей

Нужно право ключа keys:write.

Ответ 200

POST/keysВыпустить ключ

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

Нужно право ключа keys:write.

nameтело, string
scopesтело, array of string
expires_daysтело, integer

Ответ 201

POST/keys/{kid}/rotateЗаменить ключ

Выпускает новый ключ с теми же правами. Старый работает ещё grace_hours часов (по умолчанию 24, от 0 до 168), чтобы вы успели обновить биллинг.

Нужно право ключа keys:write.

kidpath, string
grace_hoursтело, integer

Ответ 201

DELETE/keys/{kid}Отозвать ключ

Нужно право ключа keys:write.

kidpath, string

Ответ 200

Пулы

GET/poolsПулы

Нужно право ключа pools:read.

Ответ 200

POST/poolsДобавить пул

Пул это набор ваших адресов с общим портом проверки, например стойка или локация. Диапазоны шире /22 и больше 1024 адресов без подтверждения принимаем только после подтверждения сети.

Нужно право ключа pools:write.

nameтело, string, обязательно
targetsтело, string, обязательно
locationтело, string
portтело, integer
sniтело, string
tlsтело, boolean
monitorтело, boolean
publicтело, boolean
slugтело, string

Ответ 201

GET/pools/{pool}Пул

Нужно право ключа pools:read.

poolpath, string
id или slug пула

Ответ 200

PATCH/pools/{pool}Изменить пул

Поля как при создании, кроме 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

DELETE/pools/{pool}Удалить пул

Нужно право ключа pools:write.

poolpath, string
id или slug пула

Ответ 200

POST/pools/{pool}/verifyПодтвердить сеть

Проверяет TXT-запись в обратной зоне (method: txt) или одобренный ASN (method: asn) для всех неподтверждённых диапазонов пула или для одного (range_id).

Нужно право ключа pools:write.

poolpath, string
id или slug пула
methodтело, string
range_idтело, integer

Ответ 200

GET/verificationЧто добавить в DNS для подтверждения

Нужно право ключа pools:read.

Ответ 200

Проверки

POST/pools/{pool}/checkПроверить весь пул

Разовая проверка всех адресов пула. Результаты обновляют состояние пула. Когда закончится, придёт событие pool_check.done.

Нужно право ключа checks:write.

poolpath, string
id или slug пула
portтело, integer
sniтело, string
tlsтело, boolean
labelтело, string

Ответ 202

GET/checksПоследние проверки

Нужно право ключа checks:read.

limitquery, integer

Ответ 200

POST/checksПроверить список адресов

Разовая проверка списка. Адреса из ваших пулов можно проверять в пределах тарифа; адреса вне пулов считаются новым заявлением: не шире /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

GET/checks/{cid}Проверка и сводка по /24

Нужно право ключа checks:read.

cidpath, string

Ответ 200

GET/checks/{cid}/resultsРезультат по каждому адресу

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

POST/ips/checkПроверить адреса сейчас

До 50 адресов вне очереди, например перед выдачей IP новому клиенту. С wait (до 60 секунд) ответ ждёт результата: 200 с вердиктами или 202, если проверка ещё идёт.

Нужно право ключа checks:write.

ipsтело, array of string, обязательно
portтело, integer
sniтело, string
tlsтело, boolean
waitтело, integer

Ответ 200

Мониторинг

GET/pools/{pool}/subnetsСостояние каждой /24 пула

Нужно право ключа pools:read.

poolpath, string
id или slug пула

Ответ 200

GET/pools/{pool}/ipsСостояние адресов пула

Страницами по 500 (до 5000), дальше after.

Нужно право ключа pools:read.

poolpath, string
id или slug пула
statequery, string
afterquery, integer
limitquery, integer

Ответ 200

POST/pools/{pool}/priorityОтметить выданные клиентам адреса

Эти адреса попадают в каждую выборку мониторинга первыми. priority: false снимает отметку.

Нужно право ключа pools:write.

poolpath, string
id или slug пула
ipsтело, array of string, обязательно
priorityтело, boolean

Ответ 200

POST/ips/lookupПоследнее известное состояние адресов

Без новой проверки: что мы знаем о каждом адресе сейчас. До 1000 адресов.

Нужно право ключа pools:read.

ipsтело, array of string, обязательно

Ответ 200

GET/ips/{ip}Состояние одного адреса

Нужно право ключа pools:read.

ippath, string

Ответ 200

События и вебхуки

GET/eventsЛента событий

Те же события, что уходят в вебхуки. Читайте с after=<next_after> прошлого ответа.

Нужно право ключа events:read.

afterquery, integer
typesquery, string
limitquery, integer

Ответ 200

GET/webhooksВебхуки

Нужно право ключа webhooks:read.

Ответ 200

POST/webhooksДобавить вебхук

Только https и только публичные адреса. Секрет приходит один раз.

Нужно право ключа webhooks:write.

urlтело, string, обязательно
eventsтело, array of string
descriptionтело, string

Ответ 201

PATCH/webhooks/{hid}Изменить вебхук

Нужно право ключа webhooks:write.

hidpath, string
urlтело, string
eventsтело, array of string
activeтело, boolean
descriptionтело, string

Ответ 200

DELETE/webhooks/{hid}Удалить вебхук

Нужно право ключа webhooks:write.

hidpath, string

Ответ 200

POST/webhooks/{hid}/rotate-secretНовый секрет подписи

Нужно право ключа webhooks:write.

hidpath, string

Ответ 200

POST/webhooks/{hid}/testОтправить тестовое событие ping

Нужно право ключа webhooks:write.

hidpath, string

Ответ 202

GET/webhooks/{hid}/deliveriesЖурнал доставок

Нужно право ключа webhooks:read.

hidpath, string
limitquery, integer

Ответ 200

POST/deliveries/{did}/redeliverОтправить доставку ещё раз

Нужно право ключа webhooks:write.

didpath, string

Ответ 200

Страница статуса

GET/status-pageНастройки страницы статуса

Нужно право ключа pools:read.

Ответ 200

PATCH/status-pageИзменить страницу статуса

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

PUT/status-page/logoЗагрузить логотип

Тело запроса: сам файл PNG, JPEG или WebP до 256 КБ. ?theme=dark для логотипа тёмной темы.

Нужно право ключа status:write.

themequery, string

Ответ 200

DELETE/status-page/logoУбрать логотип

Нужно право ключа status:write.

themequery, string

Ответ 200