Security Audit Feature

Аудит безопасности отдельной фичи (feature-scoped security review)

Для проекта the-platform: микросервисная CRM-платформа, обрабатывающая персональные данные клиентов. Безопасность — критический приоритет, а не формальность. Аудит должен находить реальные, эксплуатируемые проблемы с привязкой к file:line, а не составлять общий чек-лист без проверки. Каждая находка обязана быть подтверждена вручную, а не только упоминанием в выводе сканера.

Это точечная версия полного аудита репозитория (см. скилл security-audit-full, если задача — весь репозиторий, а не одна фича). Принципы верификации те же, но периметр, находки и отчёт строго ограничены кодом, который относится к этой фиче и к тому, что она затрагивает. Логику ручного разбора можно делегировать через Agent tool — используй параллелизацию по зонам, как описано в разделе "Запуск проверки" ниже.

ВХОДНЫЕ ДАННЫЕ: КАК ОПРЕДЕЛИТЬ ФИЧУ

Фича: $ARGUMENTS

Фича передаётся в одном из трёх видов — определи, какой перед тобой, и построй периметр проверки соответствующим способом. Периметр ВСЕГДА шире, чем буквально указанный вход: включай прямых потребителей/вызывающий код (роутер, который регистрирует хендлер; фронтенд, который дёргает API; смежный сервис, которому уходит межсервисный вызов).

A. ДИРЕКТОРИЯ/ВЕТКА/DIFF (например services/xxx-service/feature_y/ или "diff между dev и веткой feature/PROJ-XXXX"):

• Периметр = всё содержимое директории (или файлы из git diff --stat относительно базовой ветки) + модули, которые её импортируют (grep -r по имени пакета/модуля за пределами директории) + роуты/DI, которые её регистрируют (main.py/app factory/router include).
• Если директория — общая библиотека (libs/shared_auth, libs/shared_metrics и т.п.), обязательно определи ВСЕХ потребителей библиотеки по всем сервисам — уязвимость в общем коде размножается на весь список потребителей.

B. ДОКУМЕНТ (путь к спецификации/дизайн-документу/PRD, .md/.txt/.docx):

• Прочитай документ целиком. Извлеки из него: имена эндпоинтов/маршрутов, названия моделей/таблиц, роли и права, названия UI-компонентов/экранов, упомянутые внешние интеграции (вебхуки, callback URL, сторонние API).
• По каждому извлечённому термину сделай grep/поиск по кодовой базе, чтобы перевести описание "что должно быть" в конкретные file:line "что есть на самом деле". Не ограничивайся тем, что документ говорит "реализовано" — проверяй код, а не текст документа.
• Если документ описывает намерение, а не факт (черновик ТЗ) — явно пометь в отчёте, какие пункты не нашли соответствия в коде (это тоже находка: несоответствие спеки и реализации может означать недоделанный контроль доступа).

C. YOUTRACK ISSUE (ID вида PROJ-XXXX или ссылка):

• Получи текст issue (заголовок, описание, комментарии, acceptance criteria) через доступный в проекте механизм интеграции с трекером (MCP-инструмент YouTrack/Jira/GitHub/Linear, если подключён). Если программного доступа нет — прямо запроси у пользователя текст issue и ссылки на связанные PR, не додумывай содержание.
• Найди связанные коммиты и файлы по ID тикета: коммиты в этом репозитории принято помечать номером тикета в сообщении (например PROJ-1042, PROJ-1031, PROJ-318) — используй git log --all --grep=<ISSUE-ID> --oneline, затем git show --stat <hash> / git log --all -- <файлы из commit>, чтобы построить список затронутых файлов и сервисов.
• Если тикет ссылается на PR/ветку — проверь именно diff этой ветки (git diff main...<branch>), а не только финальное состояние main, чтобы не пропустить промежуточные версии, если ветка ещё не смержена.

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

Явно зафиксируй в начале отчёта итоговый периметр (список file/директорий/сервисов), который получился после этого шага — это твой рабочий SCOPE, дальше весь аудит идёт по нему, плюс точки соприкосновения с остальной системой (см. СРЕЗ 3 ниже).

КЛЮЧЕВОЙ ПРИНЦИП: ВЕРИФИКАЦИЯ, А НЕ ДОВЕРИЕ

Причина, по которой проверки фич проваливаются, — принятие на веру того, что "код написан по ТЗ" эквивалентно "фича безопасна". Это НЕ так. Проверяй адверсариально:

1. Если фича добавляет проверку (флаг, HMAC-подпись, экранирование, авторизация) — убедись, что она ВКЛЮЧЕНА по умолчанию и активна во всех окружениях (dev/staging/prod), а не только реализована в коде и выключена флагом.
2. Если фича добавляет экранирование ввода — проверь ПОЛНОТУ (одиночная кавычка, двойная кавычка, обратный слэш, null-байт, юникод-обход), а не только очевидный случай.
3. Если фича защищает один эндпоинт/сервис — проверь, нет ли у неё "братьев и сестёр" того же класса операций в другом месте кодовой базы, которые остались незащищёнными (например, фича добавила auth на POST, но не на DELETE того же ресурса, или на аналогичный bulk-эндпоинт).
4. Если в фиче есть RBAC/switch/if-else по ролям — проверь ветку "иначе" (default case). Отсутствие явного отказа в доступе по умолчанию — это дыра.
5. Не принимай описание в тикете/ТЗ ("это уже защищено", "тут используется общий middleware") без самостоятельной проверки текущего кода.
6. Формулируй статус явно: "не реализовано" / "реализовано формально (код есть, защиты нет)" / "реализовано выборочно (часть класса покрыта)" / "реализовано полностью" / "новая находка вне рамок задачи фичи".

МЕТОДОЛОГИЯ: ТРИ НЕЗАВИСИМЫХ СРЕЗА (в границах SCOPE фичи)

СРЕЗ 1 — Точечное автоматизированное сканирование

• Если фича добавила новые зависимости (новая запись в requirements/pyproject/package.json) — прогони pip-audit/npm audit точечно по изменившемуся lock-файлу, а не по всему репозиторию.
• semgrep/bandit по файлам из SCOPE (injection, ssrf, insecure deserialization, hardcoded secrets, weak crypto).
• Если фича трогает Dockerfile/helm-values/k8s-манифесты — checkov/ kube-linter точечно по изменённым файлам.
• gitleaks/trufflehog по diff'у фичи (git diff/git log -p на затронутых файлах и коммитах) — секрет мог быть закоммичен и затем удалён в рамках той же ветки.

СРЕЗ 2 — Ручной построчный разбор кода фичи

Разбери построчно (не по диагонали) каждый файл из SCOPE, применяя чек-лист по категориям ниже — только те категории, которые реально применимы к тому, что делает фича (см. подсказки применимости перед чек-листом). Для каждой находки: file:line, тип уязвимости, конкретный сценарий эксплуатации ("запрос X с параметром Y даёт результат Z"), severity, статус.

Если SCOPE большой (несколько сервисов/директорий) и доступен Agent tool — раздели на независимые зоны и используй несколько субагентов, каждому — своя зона, чтобы не срезать угол по всему объёму разом (см. "Запуск проверки" ниже).

СРЕЗ 3 — Точки соприкосновения с остальной системой

Независимо от построчного разбора ответь: как фича встраивается в существующие security-инварианты платформы, а не только "нет ли дыр в её собственном коде"?

• Использует ли фича существующие механизмы аутентификации/авторизации/ мультитенантности, или изобретает собственный путь в обход них (новый хендлер, который не проходит через общий auth-middleware/RBAC-декоратор)?
• Если фича добавляет новый internal-эндпоинт между сервисами — защищён ли он тем же shared-secret/mTLS механизмом, что и остальной класс /internal/* эндпоинтов, или это исключение?
• Если фича добавляет новую точку чтения/записи данных — фильтруется ли она по company_id/tenant_id так же, как остальные точки того же типа в системе?
• Если фича переиспользует общую библиотеку (libs/shared_auth и т.п.) — использует ли актуальную версию как единый пакет, или скопировала/ форкнула логику себе?
• Ломает ли фича какой-то из существующих security-инвариантов, описанных в предыдущих аудитах репозитория. В проекте это не абстрактная оговорка — реестр прошлых находок лежит в docs/bugs/security_audit/ (по каждой находке прошлого аудита зафиксирован вердикт: подтвердилась / false positive / уже исправлена), а регрессионная проверка по нему — scripts/verify_audit_fixes.py. Если SCOPE фичи пересекается по теме или файлам с одной из находок в этой папке — обязательно прогони скрипт (если он есть в репозитории) и явно сверь текущий статус, а не переоткрывай находку с нуля.
• Если находка по фиче фактически совпадает с уже трекнутым в docs/bugs/security_audit/ риском, который был осознанно принят (низкая реплика для HA, отключённый networkPolicy и т.п.) — сошлись на существующий файл-находку вместо того, чтобы заводить дубликат как "новую находку фичи"; отметь только если фича делает риск хуже, чем он был зафиксирован.

ЧЕК-ЛИСТ ПО КАТЕГОРИЯМ (применяй те, что релевантны фиче)

Перед разбором быстро классифицируй фичу: какие из блоков ниже применимы (новый API-эндпоинт → блоки 1,2,5,6,10; новый UI-экран → блоки 1,7; загрузка файлов → блок 9; интеграция/вебхук → блоки 4,6,8; инфраструктурное изменение → блоки 11,12). Не пропускай блок только потому что "фича маленькая" — маленькие фичи типично и есть источник точечных дыр (см. "Edge cases" ниже).

1. Аутентификация и авторизация

   • Требует ли новый/изменённый эндпоинт аутентификации так же, как остальные эндпоинты того же сервиса (нет ли "забытого" открытого маршрута)?
   • RBAC-ветки: что происходит для роли, не попавшей ни в одну явную ветку (default/else)? Приводит ли это к утечке (нет фильтра по assigned_user_id/owner_id)?
   • IDOR/BOLA: можно ли, меняя ID в URL/body, получить доступ к чужому объекту, которым оперирует фича?
   • Broken function level authorization: доступна ли новая административная/массовая операция без проверки роли?
   • Mass assignment/over-posting: принимает ли новый/изменённый API произвольные поля тела запроса (role, is_admin, company_id, balance и т.п.), или список разрешённых полей — explicit whitelist?
   • Session/token: если фича трогает сессии/токены — где хранение, есть ли инвалидация, ограничение времени жизни?
   • Rate limiting: если фича добавляет login/сброс пароля/OTP-подобный поток — есть ли лимит попыток?

2. Мультитенантность (изоляция между компаниями-клиентами) — разбирай отдельно от общего IDOR, межтенантная утечка тяжелее по последствиям.

   • Каждая новая точка чтения/записи (REST-хендлер, WS-подписка, кэш-ключ, поисковый индекс, очередь, экспорт) — фильтруется ли по company_id/tenant_id на уровне запроса к БД, а не только на уровне UI/роутера?
   • Совпадение company_id проверяется явным сравнением значения из токена/контекста с company_id записи, а не подразумевается?
   • Общие ресурсы (Redis-ключи, RabbitMQ-очереди, файловое хранилище) — не коллизирует ли ключ/имя между компаниями при одинаковых внутренних ID?
   • Новая Alembic-миграция/DDL: у новой таблицы/колонки, которая хранит данные конкретной компании, есть ли company_id/tenant_id и индекс по нему — структурный пробел на уровне схемы не поймать построчным разбором запросов, если сам столбец отсутствует.

3. WebSocket / realtime (если фича трогает realtime-канал)

   • Проверяется ли токен/роль/company_id при connect И отдельно при каждой подписке на канал/комнату (join)?
   • Может ли клиент подписаться на чужой канал, подставив/угадав room-id/dialog-id/user-id?
   • Broadcast фильтруется по company_id/роли перед отправкой, или сервер полагается на то, что клиент "просто не подписан"?

4. Internal-API между сервисами (если фича добавляет/меняет /internal/*)

   • Требует ли shared-secret/mTLS так же, как остальные эндпоинты того же класса операций в других сервисах? Проверяется ли секрет фактически (а не только объявлен в env)?
   • Может ли новый internal-эндпоинт быть вызван напрямую снаружи кластера?

5. Инъекции (SQL / NoSQL / Command / Template / Deserialization)

   • Сборка запросов конкатенацией/f-string/format вместо параметризованных запросов/ORM — особенно в новых query-параметрах (фильтры, поиск, сортировка).
   • Экранирование "вручную" — проверь полноту (обратный слэш, юникод, вложенные кавычки).
   • Command injection: новые subprocess/os.system/exec с пользовательским вводом.
   • Небезопасная десериализация новых данных из очереди/вебхука/ межсервисного вызова (pickle, yaml.load без SafeLoader, eval/exec).

6. SSRF (если фича делает исходящий HTTP-запрос по внешнему URL)

   • Есть ли allow-list доменов, блокировка приватных/internal IP-диапазонов (169.254.x.x, 10.x, 172.16-31.x, 192.168.x, 127.x, cloud metadata)?
   • Проверяется ли подпись/источник вебхука перед тем, как система инициирует ответный запрос по URL из его тела?

7. XSS (включая клиентские виджеты, если фича — frontend/встраиваемый компонент)

   • innerHTML/dangerouslySetInnerHTML/document.write с недоверенными данными.
   • Если фича — встраиваемый на сторонних сайтах виджет: уязвимость видна конечным пользователям клиентов вашей платформы — квалифицируй severity с учётом расширенного радиуса поражения.
   • CSP/clickjacking-заголовки не ослаблены ли новым кодом.

8. Работа с секретами и PII (если фича трогает интеграции/токены/PII)

   • Новые секреты в коде/конфигах, отслеживаемых git.
   • Токены новых интеграций в БД — открытым текстом или зашифрованы?
   • Маскирование секретов в новых логах — работает ли для новых типов данных, которые ввела фича?

9. Загрузка и хранение файлов (если фича добавляет upload/скачивание)

   • Проверка MIME-типа/расширения (не доверять Content-Type от клиента).
   • Ограничение размера, защита от zip-бомб.
   • Path traversal при формировании пути из пользовательского ввода.
   • Публичная раздача — требует ли аутентификации, если файлы содержат PII?

10. Зависимости и суплай-чейн (если фича добавила новые пакеты)

    • Критичность новых зависимостей, есть ли более безопасная альтернатива.
    • Новый внутренний пакет — устанавливается из приватного индекса/ локального пути, или по голому имени, которое можно подменить с публичного PyPI/npm (dependency confusion)?

11. Docker / контейнеры (если фича меняет Dockerfile)

    • USER указан (non-root)? Секреты не через ARG/ENV?

12. Kubernetes / Helm (если фича меняет values/манифесты)

    • networkPolicy/securityContext/resources не ослаблены ли новым values-файлом относительно существующего baseline проекта?
    • Секреты через Kubernetes Secrets, а не открытым текстом в values.yaml?

13. Обработка ошибок и наблюдаемость

    • Новый broad except с логированием и возвратом None/пустого результата без re-raise — не маскирует ли это отказ проверки авторизации как "разрешено"?
    • Логируются ли новые security-события (неудачные авторизации, изменения ролей) отдельно?
    • Утечка внутренней информации через новые сообщения об ошибках наружу.

14. CI/CD (если фича меняет пайплайн)

    • CI script injection: интерполируется ли непроверенный внешний ввод (заголовок PR, имя ветки) напрямую в шаг run:?
    • Новый security-гейт реально блокирует мерж, или только печатает предупреждение?

EDGE CASES, КОТОРЫЕ ЧАСТО ПРОПУСКАЮТ ПРИ ТЕСТИРОВАНИИ ФИЧИ

• Функциональность, защищённая на UI-уровне (кнопка скрыта), но доступная напрямую через API без проверки на бэкенде.
• Race condition в "check-then-act" (проверка роли и действие не атомарны).
• Поведение для soft-deleted записей — доступны ли они через новый эндпоинт, который не учитывает флаг удаления.
• Bulk-вариант новой фичи (bulk-эндпоинт) — часто добавлен "по-быстрому" со слабее проверенной авторизацией, чем у единичного аналога.
• Вебхук, который фича добавляет — проверяется ли подпись/источник.
• Feature-флаг фичи, выключенный "временно для отладки" и оставленный выключенным по умолчанию в конфиге.
• Различия dev/staging/prod — фикс, применённый в одной helm-values- конфигурации, может отсутствовать в другой.
• Экспорт данных, если фича его добавляет — авторизация на экспортируемый объём так же строга, как на обычное чтение?
• Старый/дублирующий путь, оставшийся после рефакторинга фичи (например, старый эндпоинт не удалили, а просто перестали вызывать с фронтенда — он всё ещё доступен и не обновлён под новую логику авторизации).

ШКАЛА SEVERITY (единая с полным аудитом репозитория)

Единая шкала нужна, чтобы находки были сравнимы между проверками отдельных фич и общими аудитами (см. security-audit-full).

• Critical: неаутентифицированный внешний атакующий получает полный компромисс через эту фичу (RCE, доступ ко всем данным всех компаний-клиентов, обход аутентификации целиком).
• High: аутентифицированный пользователь (в т.ч. с минимальной ролью) получает через эту фичу доступ к чужим данным/привилегиям — включая межтенантный доступ, либо неаутентифицированный атакующий получает доступ к данным одной компании/одного пользователя.
• Medium: требует специфичных условий (гонка, конкретная роль, MITM, социальная инженерия) или ограничивается утечкой метаданных/DoS без потери данных.
• Low: нарушение best practice без прямого сценария эксплуатации на момент проверки.

Для каждой находки указывай кто может эксплуатировать (аноним / аутентифицированный юзер / только внутренняя сеть) и что теряется (чтение / запись / полный компромисс).

ФОРМАТ ОТЧЁТА

1. Executive summary (без технического жаргона): безопасна ли фича к релизу, что критично, что рискует бизнесом/регуляторикой, что делать в первую очередь.
2. SCOPE — итоговый список проверенных файлов/директорий/сервисов (см. раздел "Входные данные" выше) и явное указание, что осталось ЗА пределами SCOPE и почему (например, "общая библиотека X не проверялась повторно, так как не менялась в рамках этой фичи").
3. Вердикт по фиче: "готова к релизу" / "готова с оговорками (см. low/medium)" / "не готова — есть critical/high находки" — одной фразой в начале отчёта.
4. Полный список находок: file:line, категория (можно сослаться на OWASP Top 10 / OWASP API Security Top 10 / CWE), конкретный сценарий эксплуатации, severity с обоснованием, статус, рекомендация по исправлению.
5. Раздел "что сделано хорошо" — сильные паттерны в реализации фичи, которые стоит тиражировать.
6. План действий: что блокирует релиз сейчас (critical/high), что можно исправить после релиза с тикетом (medium/low).
7. Раздел "что не было проверено" — ограничения покрытия (нет доступа к прод-окружению, нет возможности прогнать сканер и т.п.), чтобы отсутствие находок не читалось как "там всё чисто".

ПРАВИЛА ОФОРМЛЕНИЯ НАХОДОК

Перед началом проверь, нет ли уже отчёта по этой же фиче в docs/bugs/security_audit/ (например, по её feature-slug или ISSUE-ID из предыдущего прогона этого же скилла). Если есть — не начинай нумерацию с нуля: продолжи существующую последовательность ID и обнови статус уже известных находок ("не исправлено" → "исправлено" и т.п.), а не заводи их повторно как новые.

Для каждой находки обязательны:

• Стабильный ID находки (например, SEC-<ISSUE-ID или feature-slug>-001), уникальный в рамках отчётов по этой фиче (см. выше про повторный прогон).
• Путь к файлу и номер строки (или диапазон).
• Название уязвимости и категория (OWASP Top 10 / OWASP API Security Top 10 / CWE).
• Конкретный сценарий эксплуатации: "если сделать запрос X с параметром Y, система вернёт/сделает Z" — не абстрактные формулировки вроде "может быть уязвимость".
• Severity с обоснованием (кто может использовать, что теряется).
• Рекомендация по исправлению — конкретная ("добавить else-ветку с явным отказом", "включить флаг X по умолчанию", "заменить f-string на параметризованный запрос").

ЗАПУСК ПРОВЕРКИ (практическая инструкция)

1. Сначала САМ (в основном потоке) выполни раздел "Входные данные" — определи тип входных данных (директория/ветка/diff, документ, YouTrack issue) и построй SCOPE. Не делегируй этот шаг: субагент стартует без контекста разговора и не знает, что имелось в виду под "фичей". Зафиксируй SCOPE явно, прежде чем переходить к разбору.
2. Классифицируй фичу по типу изменений (новый API, новый UI, интеграция/ вебхук, загрузка файлов, инфраструктура и т.д.) и выбери применимые блоки чек-листа.
3. Проверь, нет ли уже отчёта по этой фиче в docs/bugs/security_audit/ (см. "Правила оформления находок") — это дешёвая проверка, которая экономит повторную работу и сохраняет непрерывность нумерации находок.
4. Запусти точечные автоматизированные проверки СРЕЗА 1 по файлам/ зависимостям из SCOPE (semgrep/bandit точечно, SCA на изменившиеся lock-файлы, gitleaks по diff'у фичи).
5. Проведи ручной построчный разбор СРЕЗА 2. Если SCOPE охватывает несколько сервисов/директорий и доступен Agent tool — раздели на независимые зоны и запусти отдельного субагента на зону (в foreground, если результат нужен для дальнейшего решения в этом же диалоге), чтобы не срезать угол по всему объёму разом. Каждому субагенту передай конкретные пути и применимые разделы этого скилла (чек-лист, шкалу severity, формат находки) — субагент не видит этот файл сам. Записывай подтверждённые находки в промежуточный файл сразу по мере разбора каждой зоны, а не держи их только в контексте до финального отчёта.
6. Проведи СРЕЗ 3 — точки соприкосновения фичи с существующими security-инвариантами платформы (аутентификация, мультитенантность, internal-API, общие библиотеки).
7. Сведи все три среза в единый отчёт по формату выше, убери дубликаты, но не объединяй находки разной природы (сканер нашёл паттерн ≠ ручной разбор подтвердил эксплуатируемость — фиксируй оба факта, если они есть). Сохрани финальный отчёт файлом в docs/bugs/security_audit/<feature-slug>-security-review.md (slug — по ISSUE-ID или по имени фичи/директории) — это то же место, где лежит реестр прошлых аудиторских находок, и следующий прогон этого скилла по той же фиче должен его найти и обновить, а не пересоздавать с нуля.
8. Явно укажи, какие проверки НЕ были выполнены (нет доступа к прод-секретам, нет доступа к рантайм-логам, нет возможности прогнать сканер и т.п.) — это часть честного отчёта, а не его слабость.
9. Если в проекте настроен скилл/агент security-review (быстрое ревью pending-изменений на текущей ветке) — можно использовать его как отправную точку для СРЕЗА 2 по изменённым файлам, но не ограничивайся только diff'ом: фича может опираться на существующий код, который не менялся в текущей ветке, но участвует в её security-модели (см. СРЕЗ 3).

Это тестирование, не имплементация: правки вносит разработчик по итогам отчёта, не ты в рамках этого скилла.