По умолчанию API-ключ работает откуда угодно. Белый список привязывает его к тем местам, где на самом деле работает ваш код.
Как это работает
Пограничный слой API сверяет IP-адрес источника каждого запроса со списком. Если адрес есть в списке или попадает в указанный диапазон, запрос идёт дальше, к обычной проверке ключа. Если нет — он отклоняется.
Диапазоны записываются в нотации CIDR: адрес, косая черта и длина префикса. RFC 4632 объясняет, что длина префикса — это число фиксированных старших битов. Для IPv4:
| Запись | Охватывает |
|---|---|
203.0.113.7 |
один адрес |
198.51.100.0/24 |
256 адресов, от 198.51.100.0 до 198.51.100.255 |
10.0.0.0/16 |
65 536 адресов |
IPv6 устроен так же, но со 128-битными адресами, например 2001:db8::/48.
Важен ваш исходящий (egress) IP — публичный адрес, с которого уходит трафик сервера. За NAT, балансировщиком нагрузки или корпоративным прокси это часто не тот адрес, который машина показывает сама.
Почему это важно
API-ключи — это bearer-токены: кто ими владеет, тот и пользуется. Ключи утекают через коммиты, логи, скриншоты и ноутбуки. С белым списком украденный ключ не работает из сети злоумышленника, и утечка превращается из инцидента с расходами в событие без последствий. GitHub, например, применяет свой белый список не только ко входу через веб, но и к вызовам API и персональным токенам доступа.
Цена — дополнительная операционная работа. Для каждого нового сервера, региона или CI-раннера нужно добавлять исходящий IP, а при динамических IP нужен фиксированный путь для исходящего трафика.
В BroadNet Inference
На странице аккаунта добавьте по одному адресу IPv4 или IPv6 либо диапазону CIDR на строку, до 32 записей. Пустой список означает отсутствие ограничений. Новые ключи наследуют список аккаунта. Параметр allowed_ips на уровне ключа заменяет его для этого ключа:
curl -X POST https://inference.broadnet.ai/portal/keys \
-H "Authorization: Bearer $BROADNET_PORTAL_CREDENTIAL" \
-H "Content-Type: application/json" \
-d '{"label":"worker-1","allowed_ips":["203.0.113.7","198.51.100.0/24"]}'
Запросы с других адресов получают 403. После изменения списка или отзыва ключа новые запросы перестают проходить в течение пяти секунд. Пошаговая инструкция — в руководстве API-ключи и белые списки IP, таблица ошибок — в руководстве ошибки и повторы. Более широкую картину защиты данных даёт чек-лист ZDR.
Частые ошибки
- Вносить в список частный адрес сервера, например
10.x.x.x, вместо его публичного исходящего IP. - Указывать слишком широкий диапазон, лишь бы ошибки пропали. Диапазон
/8охватывает более 16 млн адресов.