Castles:Защита серверов/API защиты серверов

Материал из SurvivalHost Wiki
Перейти к навигации Перейти к поиску

Castles Pro - API защиты серверов
<< Castles:Защита серверов | К концу статьи | Предыдущая глава: Поддерживаемые игры | Короткая ссылка

Castles API для защиты игровых серверов

Версия документа: 17 августа 2026 года

Назначение

Castles API позволяет подключать игровые серверы к защите, получать их текущее состояние и просматривать информацию о зафиксированных атаках.

API состоит из двух независимых частей:

  1. API управления игровыми серверами с авторизацией через Bearer-токен.
  2. API событий атак с авторизацией через заголовок X-API-Key.

Для каждого API выдаются отдельные реквизиты доступа. Не передавайте Bearer-токен в запросах к API атак и не используйте API-ключ атак в запросах управления серверами.

Адрес сервиса

Базовый адрес: 

https://api.castles.pro

Все запросы выполняются по HTTPS. Клиент должен проверять сертификат сервера. Не отключайте проверку TLS в рабочих интеграциях.

Обозначения

В примерах используются следующие значения:

  • <project> — идентификатор проекта, выданный при подключении;
  • <token> — Bearer-токен для управления игровыми серверами;
  • <api_key> — ключ доступа к данным об атаках;
  • <ip_address> — публичный IP-адрес игрового сервера;
  • <main_port> — основной порт игрового сервера;
  • <layer> — уровень атаки, например L3 или L7;
  • <uid> — уникальный идентификатор атаки.

Адреса из диапазонов 192.0.2.0/24, 198.51.100.0/24 и 203.0.113.0/24 приведены только как примеры.

Общие требования

  • Тела запросов и ответов передаются в JSON.
  • Для запросов с телом указывайте Content-Type: application/json.
  • Порты передаются как целые числа от 1 до 65535 и должны входить в разрешённый для выбранной игры диапазон.
  • Время в API атак передаётся в формате ISO 8601, как правило в UTC.
  • Не помещайте токены и API-ключи в URL, журналы, сообщения об ошибках или исходный код.

Управление игровыми серверами

Авторизация

Каждый запрос содержит Bearer-токен: 

Authorization: Bearer <token>

Базовый путь API проекта: 

https://api.castles.pro/<project>/v2

Рекомендуемый порядок подключения

  1. Получить у Castles идентификатор проекта и Bearer-токен.
  2. Запросить перечень доступных игр.
  3. Запросить перечень обслуживаемых сетей.
  4. Проверить, что адрес сервера входит в одну из доступных сетей.
  5. Добавить сервер под защиту.
  6. Получить данные сервера и проверить поле protection.status.

Получение списка игр

GET /<project>/v2/games

Пример: 

curl \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  'https://api.castles.pro/<project>/v2/games'

Пример ответа: 

[
  {
    "id": "ark",
    "name": "ARK: Survival Evolved",
    "main_port_id": "game"
  },
  {
    "id": "arma3",
    "name": "Arma 3",
    "main_port_id": "game"
  }
]

Поля объекта игры:

  • id — идентификатор игры для поля game;
  • name — отображаемое название;
  • main_port_id — имя порта, который используется как основной адресный порт.

Набор обязательных портов зависит от игры. Диапазоны включают обе указанные границы. Для Game и Query действует общий диапазон. Отдельный диапазон RCON указан только для игр, где он ограничен.

Разрешённые игры и диапазоны портов

  1. 7 Days to Die (7dtd)
    Game/Query: 26900–26990
    RCON: 26991–26999
  2. ARK: Survival Evolved (ark)
    Game/Query: 29000–29700
    RCON: 29000–29700
  3. Arma 3 (arma3)
    Game/Query: 2302–2902
    RCON: 2903–2990
  4. Beasts of Bermuda (bermuda)
    Game/Query: 24615–24715
  5. Conan Exiles (conan)
    Game/Query: 17000–17100
    RCON: 17101–17200
  6. Conan Exiles Legacy (conan)
    Game/Query: 17000–17100
    RCON: 17101–17200
  7. DayZ Standalone (dayz)
    Game/Query: 2202–2906
    RCON: 2910–2950
  8. Day Of Dragons (dod)
    Game/Query: 24815–24890
  9. Factorio (fact)
    Game/Query: 34197–35197
  10. Garry's Mod (garrys)
    Game/Query: 24215–24315
  11. Minecraft (mc)
    Game/Query: 25565–25765
    RCON: 25770–25870
  12. Minecraft Bedrock (mcbedrock)
    Game/Query: 19130–19172
    RCON: 19232–19272
  13. Rust (rust)
    Game/Query: 35000–36000
    RCON: 36001–36100
  14. Space Engineers (spaceen)
    Game/Query: 25016–25026
  15. Squad (squad)
    Game/Query: 27165–27365
  16. The Isle (theisle)
    Game/Query: 24315–24415
  17. Valheim (valheim)
    Game/Query: 24416–24561
    RCON: 24562–24614

Если Query или RCON не используется игрой, соответствующее поле не передаётся в запросе.

Получение списка обслуживаемых сетей

GET /<project>/v2/network

Пример: 

curl \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  'https://api.castles.pro/<project>/v2/network'

Пример ответа: 

[
  "192.0.2.0/24",
  "198.51.100.0/24"
]

Добавить под защиту можно только сервер с адресом из сети, доступной проекту.

Получение всех серверов

GET /<project>/v2?start=<start>&length=<length>&endUser=<endUser>

Параметры запроса:

  • start — смещение от начала выборки, целое число от 0;
  • length — количество записей, целое число больше 0;
  • endUser — необязательный фильтр по идентификатору конечного пользователя.

Обратите внимание: параметр запроса называется endUser, а поле в JSON называется enduser.

Пример: 

curl \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  'https://api.castles.pro/<project>/v2?start=0&length=50&endUser=customer-123'

Пример ответа: 

{
  "rows": [
    {
      "game": "ark",
      "ipAddress": "192.0.2.10",
      "enduser": "customer-123",
      "ports": {
        "game": 29016,
        "query": 29015,
        "rcon": 29020
      },
      "protection": {
        "status": "online",
        "address": "192.0.2.10/29016",
        "additional": "query:29015, rcon:29020",
        "comment": "Защита игрового сервера"
      }
    }
  ],
  "total_count": 1
}

Получение серверов по IP-адресу

GET /<project>/v2/<ip_address>

Пример: 

curl \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  'https://api.castles.pro/<project>/v2/192.0.2.10'

Ответ содержит массив серверов, зарегистрированных на указанном IP-адресе: 

[
  {
    "game": "ark",
    "ipAddress": "192.0.2.10",
    "enduser": "customer-123",
    "ports": {
      "game": 29016,
      "query": 29015,
      "rcon": 29020
    },
    "protection": {
      "status": "online",
      "address": "192.0.2.10/29016",
      "additional": "query:29015, rcon:29020",
      "comment": "Защита игрового сервера"
    }
  }
]

Возможные ошибки:

  • 400 Request must contain a valid IP. — передан некорректный IP-адрес.

Получение одного сервера

GET /<project>/v2/<ip_address>/<main_port>

Пример: 

curl \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  'https://api.castles.pro/<project>/v2/192.0.2.10/29016'

Пример ответа: 

{
  "game": "ark",
  "ipAddress": "192.0.2.10",
  "enduser": "customer-123",
  "ports": {
    "game": 29016,
    "query": 29015,
    "rcon": 29020
  },
  "protection": {
    "status": "online",
    "address": "192.0.2.10/29016",
    "additional": "query:29015, rcon:29020",
    "comment": "Защита игрового сервера"
  }
}

Возможные ошибки:

  • 400 Request must contain a valid IP. — передан некорректный IP-адрес;
  • 400 The port must be in the range 1-65535. — порт находится вне допустимого диапазона;
  • 404 Machine not found. — адрес не найден;
  • 404 Server not found. — сервер с указанным основным портом не найден.

Добавление сервера под защиту

POST /<project>/v2/<ip_address>

Тело запроса: 

{
  "game": "ark",
  "ports": {
    "game": 29016,
    "query": 29015,
    "rcon": 29020
  },
  "enduser": "customer-123"
}

Поле ipAddress в теле не обязательно. Если оно отсутствует, API использует адрес из пути запроса.

Пример: 

curl \
  -X POST \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"game":"ark","ports":{"game":29016,"query":29015,"rcon":29020},"enduser":"customer-123"}' \
  'https://api.castles.pro/<project>/v2/192.0.2.10'

При успешном выполнении API возвращает созданный объект сервера.

Возможные ошибки:

  • 400 Request must contain a valid IP. — передан некорректный IP-адрес;
  • 400 Body must contain valid json. — тело запроса не является корректным JSON;
  • 400 The game field is required. — отсутствует поле game;
  • 400 The ports[] field is required. — отсутствует объект ports;
  • 400 Game not found. — игра не поддерживается или указан неверный идентификатор;
  • 400 The <port_id> port is required. — отсутствует обязательный для игры порт;
  • 400 The <port_id> port must be in the range 1-65535. — порт находится вне допустимого диапазона;
  • 400 The <ip>:<port> is overlaps with current servers. — адрес и порт пересекаются с существующей конфигурацией;
  • 503 Service Unavailable. — сервис временно не может выполнить операцию.

Удаление сервера из защиты

DELETE /<project>/v2/<ip_address>/<main_port>

Запрос удаляет сервер из защиты. Перед вызовом убедитесь, что IP-адрес и основной порт относятся к нужному серверу.

Пример: 

curl \
  -X DELETE \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  'https://api.castles.pro/<project>/v2/192.0.2.10/29016'

Пример ответа: 

{
  "status": true
}

Возможные ошибки:

  • 400 Request must contain a valid IP. — передан некорректный IP-адрес;
  • 400 The port must be in the range 1-65535. — порт находится вне допустимого диапазона;
  • 404 Server not found. — сервер не найден;
  • 503 Service Unavailable. — сервис временно не может выполнить операцию.

Изменение сервера

> Состояние метода: планируется. Не используйте его в рабочей интеграции без отдельного подтверждения Castles. 

PUT /<project>/v2/<ip_address>/<main_port>

В пути указываются текущие IP-адрес и основной порт. Новые значения передаются в теле запроса: 

{
  "game": "ark",
  "ipAddress": "192.0.2.20",
  "ports": {
    "game": 27030,
    "query": 27025,
    "rcon": 27110
  },
  "enduser": "customer-123"
}

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

Статусы защиты

Статус находится в поле protection.status.

  • protected — сервер поставлен под защиту;
  • online — сервер поставлен под защиту и успешно отвечает через игровой query-протокол;
  • updating — изменение запланировано, но ещё не применено;
  • deleted — сервер удалён из защиты, статус является терминальным.

Если сервер длительное время остаётся в статусе updating, проверьте доступность сервера, корректность адреса и портов, затем обратитесь в поддержку Castles.

Модель игрового сервера

Основные поля объекта:

  • game — идентификатор игры;
  • ipAddress — IP-адрес сервера;
  • enduser — идентификатор конечного пользователя на стороне клиента;
  • ports.game — основной игровой порт;
  • ports.query — query-порт, если он требуется для игры;
  • ports.rcon — RCON-порт, если он требуется для игры;
  • protection.status — состояние защиты;
  • protection.address — адрес и основной порт в конфигурации защиты;
  • protection.additional — дополнительные порты;
  • protection.comment — служебный комментарий.

События атак

Авторизация

API событий атак использует отдельный ключ: 

X-API-Key: <api_key>

Ответ содержит только атаки на адреса из CIDR-префиксов, назначенных этому API-ключу. Если для ключа не назначены префиксы, список будет пустым.

Получение списка атак

GET /alerts

Поддерживаемые параметры:

  • days — глубина выборки в днях, значение по умолчанию 7;
  • layer — уровень атаки: l3 или l7;
  • severity — один или несколько уровней через запятую: high, middle, low;
  • search — поиск по цели, описанию или UID;
  • limit — количество записей, значение по умолчанию 50;
  • offset — смещение, значение по умолчанию 0;
  • sort_by — поле сортировки: startTime, stopTime, target, layer, severity, peakBps, peakPps или peakRps;
  • sort_direction — направление сортировки: asc или desc, значение по умолчанию desc.

Пример: 

curl \
  -H 'X-API-Key: <api_key>' \
  -H 'Accept: application/json' \
  'https://api.castles.pro/alerts?days=7&limit=10&severity=high&sort_direction=desc'

Пример ответа: 

{
  "status": "success",
  "payload": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "results": [
      {
        "uid": "example-attack-id",
        "layer": "L3",
        "target": "192.0.2.10",
        "active": false,
        "detector": "BPS",
        "severity": "high",
        "reason": "Traffic threshold exceeded",
        "description": "TCP(SYN) traffic",
        "startTime": "2026-08-17T10:00:00Z",
        "stopTime": "2026-08-17T10:12:30Z",
        "peakBps": 599031573,
        "peakPps": 807534,
        "peakRps": null
      }
    ]
  }
}

Получение данных одной атаки

GET /alerts/<layer>/<uid>

Пример: 

curl \
  -H 'X-API-Key: <api_key>' \
  -H 'Accept: application/json' \
  'https://api.castles.pro/alerts/L3/<uid>'

Ответ содержит объект атаки в поле payload.

Получение графика и распределений трафика

GET /alerts/<layer>/<uid>/traffic?type=as

Пример: 

curl \
  -H 'X-API-Key: <api_key>' \
  -H 'Accept: application/json' \
  'https://api.castles.pro/alerts/L3/<uid>/traffic?type=as'

Сокращённый пример ответа: 

{
  "status": "success",
  "payload": {
    "items": [
      {
        "name": "total",
        "data": [
          {
            "timestamp": "2026-08-17T10:00:00Z",
            "bits": 120000000,
            "packets": 180000
          }
        ]
      }
    ],
    "tops": {
      "ip": [],
      "protocol": [],
      "sourceAs": [],
      "tcpPorts": [],
      "udpPorts": []
    }
  }
}

Поля атаки

  • uid — уникальный идентификатор атаки;
  • layer — уровень атаки, L3 или L7;
  • target — атакованный IP-адрес, сеть или домен;
  • active — признак активной атаки;
  • detector — сработавший детектор, например BPS, PPS или RPS;
  • severity — уровень серьёзности: high, middle или low;
  • reason — причина регистрации события;
  • description — краткое описание трафика;
  • startTime — время начала;
  • stopTime — время завершения или null для активной атаки;
  • peakBps — пиковая скорость в битах в секунду;
  • peakPps — пиковая скорость в пакетах в секунду;
  • peakRps — пиковое число запросов в секунду для L7 или null.

Коды ответа

Наиболее распространённые коды:

  • 200 OK — запрос выполнен;
  • 400 Bad Request — неверный параметр, адрес, порт или JSON;
  • 401 Unauthorized — отсутствуют или недействительны реквизиты доступа;
  • 403 Forbidden — реквизиты действительны, но операция не разрешена;
  • 404 Not Found — проект, сервер, адрес или атака не найдены;
  • 503 Service Unavailable — операция временно недоступна.

При ошибке сохраняйте HTTP-код и тело ответа, предварительно удалив из журналов значения Authorization и X-API-Key.

Рекомендации по безопасности

  • Храните токены и API-ключи в менеджере секретов целевой системы.
  • Передавайте реквизиты только в соответствующем HTTP-заголовке.
  • Не размещайте реквизиты в репозитории, образе контейнера, Wiki, тикете или журнале.
  • Ограничивайте доступ к секретам только компонентами, которым требуется обращение к API.
  • При подозрении на раскрытие отзовите реквизиты и выпустите новые.
  • Не отключайте проверку TLS-сертификата.

Обращение в поддержку

Для диагностики передайте поддержке Castles:

  • идентификатор проекта;
  • дату и время запроса с часовым поясом;
  • HTTP-метод и путь без секретных параметров;
  • HTTP-код ответа;
  • очищенное от реквизитов тело ошибки;
  • UID атаки или IP-адрес и основной порт сервера, если они относятся к проблеме.

Никогда не отправляйте Bearer-токен или API-ключ в обращении.

<< Castles:Защита серверов | К началу статьи

Источник — https://survivalhost.wiki/index.php?title=Castles:Защита_серверов/API_защиты_серверов&oldid=5581