API - nsychev/DestructiveFarm GitHub Wiki

DestructiveFarm имеет два вида API. Flag API предназначено для клиентов фермы, Client API — для игроков команды (используется фронтендом)

Авторизация

Flag API

В конфигурационном файле сервера есть две настройки авторизации:

ENABLE_FLAG_API_AUTH — включает или выключает авторизацию для Flag API
FLAG_API_TOKEN — токен Flag API

Если настройка ENABLE_FLAG_API_AUTH установлена в True, то с каждым запросом к Flag API необходимо передавать заголовок X-Token, равный FLAG_API_TOKEN. В случае его отсутствия будет возвращена ошибка 403.

Client API

В конфигурационном файле сервера есть параметр CLIENT_API_TOKEN. Его необходимо передавать в заголовке X-Token в каждом запросе. В случае его отсутствия будет возвращена ошибка 403.

Совершение запросов

Все запросы должны быть осуществлены по адресу http[s]://FARM-HOST:PORT/api/TYPE/METHOD_NAME.

Для Flag API значение TYPE равно flag, для Client API — client.

Для GET-запросов используйте передачу параметров в параметрах URL, для POST-запросов передавайте аргументы в формате application/json.

Результат возвращается в формате application/json.

Объекты Flag API

FlagSubmit

flag — string — текст флага, должен удовлетворять регулярному выражению FLAG_FORMAT
ip — string — IP-адрес команды

Методы Flag API

config (GET)

Получает настройки фермы.

Аргументы отсутствуют.

Возвращает объект настроек фермы, эквивалентный содержимому файла server/config.py, но без API-токенов.

flags (POST)

Загружает флаги на сервер.

Аргументы:

flags — FlagSubmit[], обязательный — список найденных флагов
sploit — string, обязательный — название сплойта, должно начинаться с названия сервиса и символа нижнего подчеркивания (_)

Возвращает объект {"success": true} в случае успеха.

Объекты Client API

Team

name — string — название команды
ip — string — IP-адрес команды

FlagStatus

Строка, принимающая одно из значений

ACCEPTED — принят
REJECTED — отклонен
SKIPPED — пропущен
QUEUED — в очереди

Flag

flag — string — содержимое флага
created — timestamp (aka uint64_t) — время приема флага
status — FlagStatus — статус сдачи флага
team — Team || string — команда или строка manual, если флаг сдан вручную
service — string — название сервиса или строка manual, если флаг сдан вручную
sploit — string — название сплойта или строка manual, если флаг сдан вручную
response — string — ответ проверяющей системы

Методы Client API

check_token (GET)

Проверяет статус авторизации.

Аргументы отсутствуют.

Возвращает объект {"success": true} в случае успеха.

services (GET)

Получает список сервисов.

Аргументы отсутствуют.

Возвращает объект:

services — string[] — список названий сервисов

services (POST)

Регистрирует новый сервис.

Аргументы:

name — string, обязательный — имя сервиса

Возвращает объект {"success": true} в случае успеха.

teams (GET)

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

Аргументы отсутствуют.

Возвращает объект:

teams — Team[] — список объектов команд

manual_flags (GET)

Получает флаги, отправленные вручную, в порядке убывания времени получения.

Аргументы отсутствуют.

Возвращает:

flags — Flag[] — объекты запрашиваемых флагов

manual_flags (POST)

Добавляет ручной флаг.

Аргументы:

text — string, обязательный — текст, содержащий флаги, удовлетворяющие регулярному выражению FLAG_FORMAT

Возвращает:

success — bool — true, если есть хотя бы один новый флаг, false, если их нет
flags — string[] — все новые найденные флаги

stats (GET)

Получает статистику по флагам.

Аргументы:

limit — uint64_t, по умолчанию +∞ — число последних раундов, за которые запрашивается статистика

Возвращает:

rounds — uint64_t — общее число раундов
stats — массив объектов типа RoundStats
- RoundStats — словарь с ключами – именами сплойтов и значениями – объектами типа SploitStats
- SploitStats — словарь с ключами – IP-адресами команд и значениями – объектами типа TeamStats
- TeamStats — словарь с ключами FlagStatus и значениями – числом флагов

Пример:

{
    "rounds": 1,
    "stats": [
        "nodbrary_rce.py": {
            "6.6.1.2": {"accepted": 2, "skipped": 0, "rejected": 1, "queued": 0},
            "6.6.2.2": {"accepted": 3, "skipped": 0, "rejected": 0, "queued": 1}
        },
        "cdo_sqlinj.php": {
            "6.6.1.2": {"accepted": 1, "skipped": 0, "rejected": 0, "queued": 0},
            "6.6.2.2": {"accepted": 0, "skipped": 0, "rejected": 2, "queued": 0}
        }
    ]
}

subscribe (WebSocket)

Подписаться на обновления статистики.

Важно! Так как протокол Websocket не поддерживает HTTP-заголовки (пруф), используется другой механизм авторизации.

Для авторизации необходимо отправить серверу объект {"token": CLIENT_API_TOKEN}. До этого момента обновления приходить не будут.

Если токен некорректен или не будет передан в течение 20 секунд, сервер вернет {"error": "invalid token"} и закроет соединение.

Если передан корректный токен, сервер ответит {"success": true}, а затем каждый раунд будет возвращать статистику — один объект типа RoundStats.