Разработка
Безопасность API: требования к доступу и проверке интеграций
Структура ТЗ на защиту API: объекты и роли, входные данные, ограничения, внешние события, журналы и доказательства выполнения требований.
Определите границы проверки API
Требования к безопасности API нужны до интеграции и до заказа аудита. Формулировка «защитить все методы» не объясняет, какие данные доступны, какие действия опасны и кто принимает остаточный риск. Начните с перечня интерфейсов: публичные, партнёрские, мобильные, внутренние и административные. Для каждого укажите владельца, среду, потребителей, версии и способ отключения. Отдельно отметьте устаревшие методы, которые ещё используются. Неизвестный интерфейс трудно проверить и невозможно осознанно включить в границы приёмки проекта.
Опишите бизнес-объекты и последствия действий. Чтение справочника, выгрузка клиентов, изменение банковских реквизитов и отмена заказа требуют разного внимания. Зафиксируйте данные, которые нельзя раскрывать, операции, которые нельзя повторять без проверки, и зависимости от внешних сервисов. Это основа модели угроз, а не список предполагаемых атак на конкретную чужую систему. Все проверки должны выполняться в согласованной среде и области доступа, с безопасными тестовыми данными и понятным порядком остановки.
OWASP API Security Top 10 помогает выделить распространённые классы рисков, включая ошибки авторизации объектов и функций, а ASVS предлагает проверяемые требования к приложениям. Эти документы не являются автоматическим сертификатом безопасности. В ТЗ выберите применимые требования, зафиксируйте версии и объясните исключения. Общая фраза «соответствует OWASP» недостаточна: разные команды могут понимать её как обзор, автоматическое сканирование или полный набор проверок. Результат должен быть привязан к конкретному интерфейсу и доказательствам.
Согласуйте модель идентификации и полномочий
Разделите установление личности и проверку разрешения на действие. Действительный токен подтверждает определённую сессию или клиента, но не даёт права читать любой заказ. Для каждой роли опишите разрешённые объекты, операции и поля. Укажите, как учитываются организация, филиал, владелец записи и временное делегирование. Если правила зависят от нескольких условий, приложите таблицу примеров. Разработчику и проверяющему нужны одинаковые ответы на пограничные ситуации, а не разные трактовки устного объяснения владельца продукта.
В приёмочных сценариях используйте две тестовые организации с похожими данными. Пользователь первой организации должен получить собственный объект и не получить объект второй через карточку, поиск, экспорт или вложенный ресурс. Проверка только главного метода чтения недостаточна, если сведения доступны другим маршрутом. Отдельно проверьте изменение полей, которые клиент не должен задавать: владельца, роли, подтверждённой оплаты или внутреннего статуса. Сервер должен применять правила независимо от того, какие элементы скрыты в интерфейсе приложения.
Опишите жизненный цикл полномочий: выдачу, обновление, отзыв и смену роли. Что происходит с действующей сессией после увольнения сотрудника или отключения партнёра? Как ограничивается сервисная учётная запись, используемая интеграцией? Кто владеет её ключами и видит срок действия? В требованиях нужны наблюдаемые последствия этих событий. Не оставляйте бессрочный доступ как неявное поведение только потому, что основной сценарий входа работает и демонстрационный запрос успешно возвращает нужные данные.
Задайте контракт входных и выходных данных
Для каждого метода согласуйте допустимые поля, типы, размеры и диапазоны значений. Уточните поведение при неизвестном поле, повторяющемся параметре, пустом значении и слишком большом запросе. Эти решения влияют на совместимость и обработку ошибок. Не считайте ограничение в мобильной форме достаточной защитой API: тот же интерфейс может использовать другой клиент. Серверная проверка должна быть частью контракта, а сообщения об ошибках — помогать исправить запрос без раскрытия лишних внутренних подробностей.
Выходной контракт также требует внимания. Укажите поля, доступные каждой роли, и исключите случайную передачу служебных данных. Учебный пример: клиенту нужен статус доставки, но не внутренний комментарий менеджера и не полный профиль сотрудника. Проверьте вложенные объекты, списки и экспорт, где лишние поля часто появляются при повторном использовании общей модели. Стабильный формат ответа полезен и для безопасности, и для интеграций: потребитель не должен зависеть от случайного устройства таблиц в базе.
Для файлов определите разрешённые типы, пределы размера, хранение и доступ после загрузки. Имя файла и заявленный тип не являются достаточным основанием доверять содержимому. В брифе задайте требуемый результат проверки, обработку отказа и правила выдачи ссылки. Если ссылка предназначена одному пользователю, уточните срок и условия её использования. Отдельно рассмотрите удаление файла, замену версии и сохранение истории: доступ к старому вложению не должен обходить актуальные ограничения самого объекта.
Ограничьте расход ресурсов и опасные операции
Определите лимиты по смыслу операции. Чтение маленькой карточки и построение большой выгрузки расходуют разные ресурсы, даже если оба действия представлены одним HTTP-запросом. Для поиска задайте границы страницы и сложности фильтра, для выгрузки — объём, очередь и срок хранения результата. Укажите реакцию на превышение: отказ, ограниченный ответ или постановка задания в фон. Защита должна сохранять основные рабочие действия, а не превращать тяжёлый запрос одного пользователя в остановку всего сервиса.
Для изменения состояния опишите подтверждение и повтор. Если клиент не получил ответ после создания заказа, он не знает, завершилась ли операция. Требование должно сохранять возможность узнать результат по устойчивому идентификатору. Повтор одного намерения не должен создавать вторую оплату или второй документ. При этом два разных намерения нельзя объединять только из-за одинакового текста запроса. Согласуйте область уникальности, срок хранения результата и поведение при повторе идентификатора с изменёнными данными.
Добавьте требования к массовым операциям. У сотрудника может быть право изменять один заказ, но не экспортировать весь каталог клиентов или отменять сотни записей одновременно. Такие действия должны иметь отдельную область разрешений и понятный журнал. Для необратимых последствий обсудите предварительный просмотр и дополнительную проверку контекста. Конкретные механизмы зависят от продукта; в ТЗ важно описать риск, ожидаемое поведение и способ доказать, что обычный доступ не превращается в неограниченное управление данными.
Проверьте внешние зависимости и события
Составьте реестр внешних адресов и способов подключения. Для исходящих запросов задайте допустимые назначения, ограничения времени и объёма ответа, правила перенаправлений и обработки недоступности. Не позволяйте пользовательскому значению незаметно определять произвольный внутренний ресурс для запроса сервера. Если продукт действительно принимает адреса, опишите безопасные границы этой функции отдельно. Приёмка должна учитывать не только ответ ожидаемого партнёра, но и ошибочный формат, медленный ответ и неожиданное изменение поведения зависимости.
Для входящих событий укажите способ проверки происхождения, допустимый возраст, идентификатор и правила повторной доставки. Одно событие может приходить повторно, а последовательность получения не всегда совпадает с бизнес-порядком. Тестовый набор должен включать повтор, задержку и изменение статуса между получением и обработкой. Не используйте факт доставки события как единственное доказательство завершения внешней операции, если контракт требует дополнительной сверки. Сохраните исходное событие и результат решения в пределах согласованной политики хранения.
Опишите, как отключается одна интеграция без остановки всего приложения. При утечке ключа или нарушении контракта команда должна отозвать доступ конкретного потребителя и увидеть последствия. Заранее определите владельца связи, контакт для инцидента и безопасный режим работы. Не храните секреты в общих логах, примерах документации и файлах тестовых сценариев. Для воспроизведения проверки достаточно идентификатора версии конфигурации и обезличенных данных; реальные ключи не должны попадать в отчёт подрядчика.
Определите наблюдение и доказательства
Журнал должен позволять связать запрос с субъектом, объектом, действием и результатом проверки. При этом полное тело каждого запроса может содержать сведения, которые не следует распространять внутри команды. Согласуйте перечень записываемых полей, маскирование, сроки хранения и доступ к журналу. Разделите техническую ошибку, отказ в полномочиях и бизнес-отказ. Иначе рост корректных отказов пользователям будет выглядеть как авария, а реальная проблема затеряется в шуме общей статистики запросов.
Для каждого критического сценария определите доказательство. Это может быть обезличенный запрос и ответ, запись журнала, состояние тестового объекта и отсутствие запрещённого изменения. Одной отметки сканера «не найдено проблем» недостаточно для бизнес-правила, которого инструмент не знает. Проверяющий должен иметь возможность воспроизвести сценарий на согласованной версии. Зафиксируйте условия, ограничения и неохваченные области, чтобы отчёт не воспринимался как гарантия безопасности всех будущих изменений приложения и подключённых сервисов.
Согласуйте классификацию замечаний и порядок исправления. Укажите, какие находки блокируют запуск, кто принимает решение об исключении и как проверяется устранение. Повторная проверка должна подтверждать исправление исходного сценария и отсутствие очевидного обхода через связанные методы. Не закрывайте замечание только по сообщению разработчика о внесённом изменении. В отчёте сохраняйте связь между находкой, версией исправления и фактическим результатом повторного испытания, включая случаи, которые пока остаются нерешёнными.
Организуйте безопасную приёмочную среду
Подготовьте тестовые роли, организации и набор объектов заранее. Среда должна достаточно точно воспроизводить правила доступа и интеграции, но не требовать использования реальных клиентских данных. Для внешних последствий применяйте тестовые режимы или управляемые имитации. Опишите, какие части проверяются реально, а какие заменены стендом. Это особенно важно для отправок, платежей и удаления: успешная имитация подтверждает локальную логику, но не доказывает доставку сообщения или завершение операции у внешнего провайдера.
Согласуйте нагрузочные ограничения и условия остановки теста. Даже проверка безопасности может создать тяжёлые запросы или большое количество событий. На рабочем сервере такие действия нельзя проводить без отдельной оценки влияния на сотрудников и клиентов. Начните с изолированной среды, затем выполняйте только согласованные ограниченные проверки действующего контура. Сохраните контакт ответственного, порядок уведомления об инциденте и критерий немедленного прекращения проверки. Это часть организации работ, а не формальная строка в конце технического задания.
Проверьте восстановление после отказа зависимости и отзыва доступа. Приложение должно корректно прекратить запрещённые действия, сохранить понятное состояние заданий и дать сотруднику способ разобраться. Неизвестный результат не следует автоматически обозначать успехом или безусловно повторять. В учебном сценарии интеграция отключается во время операции, затем включается снова; принимающая команда проверяет, что история объясняет произошедшее, а восстановление не создаёт дополнительных бизнес-последствий, которых пользователь не запрашивал.
Сохраните требования после первого выпуска
Инвентарь API должен обновляться вместе с продуктом. Новый метод, поле или потребитель может изменить границы доступа, даже если общая авторизация не менялась. Включите проверку применимых требований в обычный процесс изменений. Укажите, кто согласует расширение полномочий, новые выгрузки и внешние назначения. Устаревшие версии должны иметь понятный срок и владельца отключения. Иначе безопасность постепенно расходится с документом, который был корректен только для первой принятой версии системы.
Передайте команде карту интерфейсов, матрицу полномочий, тестовые сценарии, ограничения и инструкцию реагирования. Секреты передаются отдельным защищённым способом, а доступы оформляются на владельца продукта. Для наблюдения нужны ответственные и понятные сигналы, требующие действия. Не обещайте отсутствие всех возможных уязвимостей: приёмка подтверждает конкретный набор требований в конкретных условиях. Такая формулировка позволяет честно оценивать результат и планировать дальнейшие проверки по мере изменения риска и архитектуры.
Заполняемый бриф в источниках статьи предназначен для согласования этой области работ. Начните с наиболее важных объектов и операций, затем дополните карту зависимостями и исключениями. Хорошее ТЗ связывает угрозу с правилом, правило — со сценарием, а сценарий — с наблюдаемым доказательством. В результате заказчик получает понятные границы проверки, исполнитель — воспроизводимые условия, а команда сопровождения — материалы, которые можно использовать после запуска, вместо общего обещания «API защищён» без объяснения, что именно было проверено.
Источники
- OWASP API Security Top 10 2023
OWASP Foundation / доступ 2026-10-18
Первичный источник для соответствующих принципов и технических свойств. Структура требований и учебные примеры подготовлены редакцией; конкретная конфигурация проверяется отдельно.
- Application Security Verification Standard
OWASP Foundation / доступ 2026-10-18
Первичный источник для соответствующих принципов и технических свойств. Структура требований и учебные примеры подготовлены редакцией; конкретная конфигурация проверяется отдельно.
- Скачать заполняемый бриф / ТЗ (.txt)
Малевич — практическое приложение / доступ 2026-10-18
Сохраните файл и заполните данные проекта, открытые решения и критерии приёмки.
FAQ
Можно ли заменить ТЗ ссылкой на OWASP?
Нет. Стандарт помогает выбрать ориентиры, но нужно указать применимые требования, границы API, роли, данные и способ проверки. Ссылка без согласованного профиля оставляет слишком много неопределённости.
Достаточно ли проверить токен перед запросом к API?
Нет. После установления личности необходима проверка права на конкретный объект и действие. Пользователь с действительным токеном не должен получать чужие записи только из-за изменения идентификатора.
Как проводить приёмочные проверки API без риска для сотрудников?
На согласованном изолированном стенде с тестовыми данными, ограничениями нагрузки и фиксированным перечнем сценариев. Производственные испытания оформляют отдельно; их нельзя подменять самовольной проверкой работающей системы.
