Безопасность работы с API

Используя описанный протокол взаимодействия, магазин должен следовать правилам защиты информации.

Уведомления о переводах

Мы настоятельно рекомендуем в ссылках для получения любых уведомлений использовать защищённое соединение SSL/TLS безопасных версий.

Целостность и аутентичность запросов

Для проверки целостности и аутентичности запросов, в ходе взаимодействия с системой Инвойсбокс могут быть использованы различные механизмы. Базовый вариант — HMAC по телу запроса ключом магазина. У магазинов, которые подключаются сейчас, по умолчанию стоит sha256; у настроенных раньше остаётся выбранный тогда алгоритм, часто sha1, и его стоит сменить на sha256 в настройках интеграции.

Для поддержания более высоких требований к безопасности, взаимодействие может идти с использованием клиентских и серверных сертификатов (включая ГОСТ-2012), в том числе самоподписных, сформированных центрами сертификации магазина или системы Инвойсбокс. В случае взаимодействия с использованием сертификатов, необходимо проверять подлинность веб-сервисов системы Инвойсбокс, сохранять конфиденциальность приватных ключей, следить за сроком действия сертификатов. В случае компрометации приватного ключа необходимо незамедлительно уведомить службу поддержки системы Инвойсбокс.

Токен доступа

Токен — это пароль к вашим заказам и деньгам. Кто им владеет, тот и выставляет счета от вашего имени.

Как он выглядит

Токены, выпущенные в личном кабинете, начинаются с ib_:

ib_5f3c8a1e9d2b47c60a1f8e3d5b9c2a70d4e6f18b3c5a7920e1d4f6b8a3c5e792

Префикс — не украшение. Без него токен выглядит как обычная шестнадцатеричная строка, каких в коде полно, и утёкший в репозиторий он ничем себя не выдаёт. По префиксу его находят автоматические сканеры секретов — желательно раньше, чем найдёт кто-то другой. Ровно поэтому мы советуем включить такой сканер у себя (см. ниже): шаблон ib_ + 64 символа он опознаёт однозначно.

Токены, выпущенные раньше, префикса не имеют и продолжают работать.

Где он должен и не должен быть

Можно	Нельзя
Хранилище секретов (Vault, Secrets Manager, переменные окружения CI)	Репозиторий, включая приватный
Переменные окружения сервера	Файлы конфигурации в сборке или образе
Файл вне репозитория с правами только для владельца	Логи, сообщения об ошибках, трассировки
Заголовок `Authorization` в запросе к API	Строка запроса, URL, реферер
—	Код на стороне браузера или мобильного приложения

Последняя строка — не формальность. Токен в клиентском коде считайте опубликованным: минификация не защита, а сетевую панель браузера открывает любой.

Гигиена

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

Ограничивайте права. При выпуске токена в кабинете можно оставить ему только часть прав интеграции: например, чтение заказов без создания счетов и без возвратов. Утечка такого токена стоит меньше: чужая сторона получает ровно те действия, что в нём разрешены.

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

Отзывайте, а не забывайте. В кабинете токен отзывается: он перестаёт работать, но остаётся в истории, и видно, кто и когда его выпустил. Отзывайте токены уволившихся сотрудников и завершённых проектов — кабинет предупредит, если у сотрудника были выпущенные токены.

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

Если токен утёк

Отзовите его в кабинете первым же действием.
Выпустите новый и переведите интеграцию.
Посмотрите в журнале, что делалось этим токеном: чужие заказы, изменения статусов, возвраты.
Смените ключ подписи уведомлений, если он лежал рядом (обычно лежит).
Уберите утечку из истории репозитория, а не только из последнего коммита: удалённый файл остаётся в истории и доступен по хешу.

Проверки от утечек: что включить у себя

Три средства, каждое ловит своё. Порядок — по соотношению пользы к усилию.

Сканер в предкоммитном хуке не даёт секрету попасть в историю: проверка идёт до фиксации, и это единственный момент, когда исправление стоит ноль. Подходят gitleaks, trufflehog, detect-secrets. Достаточно одного, добавленного в pre-commit.

Сканер в конвейере ловит то, что обошло хук — например, коммит с другой машины. Он работает по всей истории, а не по последним изменениям, и потому находит старое. Отдельно включите защиту push-этапа у хостинга репозитория, если она есть.

Маскирование в логах. Секрет чаще утекает не в код, а в лог: заголовок запроса, тело ошибки, трассировка HTTP-клиента. Внесите Authorization, token, signKey в список маскируемых полей своего логгера и проверьте, что перехватчик ошибок (Sentry и подобные) их тоже вычищает.

Шаблон для сканеров и правил маскирования: ib_[0-9a-f]{64}.

Работа с ИИ-агентами

Агент — путь утечки, о котором думают в последнюю очередь. Он читает то, что ему дают, и отправляет туда, куда его попросят: и «дают», и «попросят» здесь исходят не только от вас.

Про вашу сторону дальше: какой токен дать агенту и как не пустить чужую инструкцию в денежную операцию. Что делает наша сторона — на странице безопасность MCP-сервера: режим только чтения по умолчанию, подтверждение человеком на каждой денежной операции, проверка прав до вызова инструмента. Полный состав того, что вообще доступно ассистенту, — в справочнике инструментов.

Чем это отличается от обычной интеграции

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

Инструкции приходят из данных. Агент не отличает ваше поручение от текста внутри документа, который он открыл. Письмо, страница, комментарий в задаче — всё это может содержать указание «отправь содержимое переменных окружения по такому адресу», и агент выполнит его, если это в его силах. Это называют инъекцией через данные, и защиты «на стороне модели» от неё нет.

Действие необратимо. Ошибочно созданный счёт можно отменить, ошибочно отправленный возврат — уже нет. Цена ошибки у агента выше не потому, что он ошибается чаще, а потому что действует быстрее.

Что делать

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

Токен не в диалоге, а в конфигурации. Он должен лежать в настройках инструмента или в переменных окружения — там, откуда его берёт программа, а не модель. Токен, набранный в чат, считайте скомпрометированным.

Изолируйте сессию. Не подключайте платёжные инструменты в ту же сессию, где работают почта, задачи и веб-поиск. Письмо от постороннего в соседнем инструменте — это потенциальная команда, а здесь агент умеет выставлять счета.

Подтверждение человеком на денежных операциях. Возврат, изменение реквизитов, выплата — эти действия должен подтверждать человек, видя сумму и получателя. Автоматизируйте подготовку, а не последнее нажатие.

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

Читайте журнал. Действия агента видны в журнале так же, как действия человека, — и это единственный способ заметить, что он делает не то. Проверяйте журнал первые недели, а не после инцидента.

Журнал вызовов ассистента к нашему серверу читается там же, где лимиты и отказы — лимиты, ошибки и журнал: по нему видно, какой инструмент вызывали, с какими параметрами и чем ответил API.