{
  "index": 166,
  "slug": "editorial-2023-05-field-static-analysis",
  "title": "Шумное правило статического анализа: как принять обратимое решение",
  "excerpt": "Один результат статического анализа не объясняет, нужно ли менять правило или ограничить только этот сигнал. Разбираем контекст, scope, срок, rollback и проверяемый критерий готовности.",
  "contentHtml": "<p>В CI появляется результат правила, которое ищет передачу недоверенного значения в построение команды. Команда открывает строку, видит безопасный для своего сценария путь и предлагает выключить правило. На следующем запуске исчезают все результаты этой категории. Цена ошибки — потеря сигнала в коде, который ещё никто не проверил, и отсутствие ответа на простой вопрос: почему правило стало тише и кто разрешил это изменение.</p>\n<p>Обратная ошибка стоит не меньше. Если каждое совпадение называть уязвимостью, review получает ложную срочность. Инженеры начинают закрывать предупреждения по тексту сообщения, а затем перестают доверять анализатору. Результат анализатора — это повод проверить контекст, а не готовый вердикт. В этой статье <code>keep</code>, <code>tune</code> и <code>scoped suppress</code> — названия проектной policy, а не универсальные поля SARIF и не обещание, что любой анализатор понимает эти действия.</p>\n<h2>Отделите результат от вывода</h2>\n<p>SARIF (Static Analysis Results Interchange Format) описывает обмен результатами статического анализа. В записи можно найти инструмент, правило, результат, сообщение, расположение в артефакте и уровень сигнала. Эти поля отвечают на вопросы «какая гипотеза сработала» и «где её обнаружили». Они сами по себе не доказывают, что ветка исполняется, значение пришло от внешнего пользователя или опасный вызов достижим в выпущенном артефакте.</p>\n<p>У результата есть ещё одна важная граница: <code>fingerprint</code> нужен системе управления результатами для сопоставления логически одинаковых сигналов между запусками. Спецификация допускает, что fingerprint добавит именно result management system после загрузки отчёта; прямой производитель SARIF обычно не должен выдумывать его без устойчивого алгоритма. Поэтому строка, которую команда вручную назвала fingerprint, не становится стабильным идентификатором только из-за имени.</p>\n<p>Возьмём узкую гипотезу: значение из параметра запроса передают в функцию, которая строит команду. Фрагмент показывает форму, которую может искать правило. Это не результат реального сканирования и не доказательство уязвимости.</p>\n<pre><code>function runReport(request) {\n  const reportName = request.query.name;\n  return runShell(\"report --name \" + reportName);\n}\n\n// Отдельно проверяем источник, экранирование,\n// достижимость ветки и фактический sink.</code></pre>\n<p>Для этого совпадения нужны четыре независимых ответа. Может ли внешний пользователь менять <code>request.query.name</code>? Проверяет ли код значение до вызова? Принимает ли <code>runShell</code> строку как команду или передаёт аргументы безопасным массивом? Попадает ли функция в собираемый артефакт? Пока ответов нет, точная формулировка звучит так: «результат требует проверки, контекст неполный».</p>\n<h2>Восстановите цепочку данных</h2>\n<p>Начинайте с наблюдаемого результата, а не с предполагаемого исправления. Сохраните <code>ruleId</code>, revision правила, URI, строку, уровень, сообщение и идентификатор сопоставления, если его выдала система управления результатами. Затем пройдите значение от входа до операции, на которую указывает правило. На каждом переходе фиксируйте не впечатление, а проверяемый факт: какой тип данных получен, какая функция вызвана и в какой сборочный путь она попадает.</p>\n<p>Граница доверия находится там, где данные переходят из внешнего или неуправляемого источника в код, принимающий решение. Для HTTP-запроса такой границей может быть контроллер; для очереди — consumer; для файла конфигурации — загрузчик и права на файл. Валидация меняет риск, но её наличие нужно подтвердить кодом и тестом. Название функции вроде <code>sanitize</code> не является доказательством корректного экранирования.</p>\n<div class=\"table-scroll\"><table><caption>Симптом, проверка и допустимое решение</caption><thead><tr><th scope=\"col\">Что видно</th><th scope=\"col\">Чего не хватает</th><th scope=\"col\">Проверка</th><th scope=\"col\">Решение policy</th></tr></thead><tbody><tr><td>Один результат выглядит безопасным</td><td>Источник и trust boundary</td><td>Проследить значение до sink и проверить достижимость</td><td><code>keep</code> до завершения triage</td></tr><tr><td>Сигнал появляется на безопасном API</td><td>Правило различает формы слишком грубо</td><td>Сравнить intent правила с двумя минимальными примерами</td><td><code>tune</code> с новой revision и diff</td></tr><tr><td>Один результат мешает выпуску</td><td>Точный scope, владелец и срок</td><td>Сверить fingerprint, owner, reviewBy и expiresOn</td><td>Только <code>scoped suppress</code></td></tr><tr><td>Предлагают выключить правило целиком</td><td>Оценка будущей потери сигнала</td><td>Рассмотреть изменение категории как отдельную policy</td><td>Отдельное решение с rollback</td></tr><tr><td>После изменения непонятен возврат</td><td>Повторный запуск на том же commit</td><td>Сравнить конфигурацию и новый отчёт</td><td>Вернуть узкое исключение или revision</td></tr></tbody></table></div>\n<h2>Проверьте правило на минимальной паре</h2>\n<p>Если подозрение относится к гипотезе правила, сначала подготовьте два маленьких примера: один должен соответствовать намерению правила, второй — быть безопасной формой, которую оно не должно захватывать. Запускайте одну и ту же версию CLI с одной и той же конфигурацией. Команда ниже показывает общий путь для локального Semgrep-скана; имя конфигурации и каталог замените своими. Она сохраняет SARIF-файл, но не отвечает за достижимость кода или эксплуатацию сигнала.</p>\n<pre><code>semgrep --version\nsemgrep scan \\\n  --config rules/command-input.yml \\\n  --sarif \\\n  --output /tmp/command-input.sarif \\\n  src/</code></pre>\n<p>После запуска сравните не только число строк. Проверьте <code>ruleId</code>, revision, URI и содержимое <code>results</code>. Если CLI обновился, формат дополнительных полей и поддерживаемые опции нужно сверить с документацией именно этой версии. Отдельный diff правила должен объяснять, какой класс безопасных совпадений исключается и какие опасные формы остаются в области проверки.</p>\n<h2>Выберите узкое действие</h2>\n<p><code>keep</code> оставляет результат видимым. Выбирайте его, когда контекст ещё не собран или проверка не завершена. Это не признание уязвимости и не отказ от исправления: команда сохраняет наблюдаемость до следующего шага.</p>\n<p><code>tune</code> меняет гипотезу правила. Такое действие оправданно, если правило захватывает форму, которая не соответствует его назначению. Укажите новую revision, покажите минимальный diff и проверьте положительный и отрицательный пример. Не называйте tune снижением false-positive rate без измерения на заранее выбранном наборе кода.</p>\n<p><code>scoped suppress</code> ограничивает один идентифицируемый результат. В нашей policy у него должны быть точный fingerprint, узкий scope, владелец, причина, дата следующей проверки и дата окончания. Suppress не делает код безопасным: он меняет видимость конкретного сигнала. Формат исключения и его область зависят от инструмента, поэтому эти поля нельзя механически перенести в конфигурацию другого анализатора.</p>\n<p>Глобальное <code>disable</code> не заменяет ни одно из трёх действий. Оно меняет поведение правила для текущих и будущих результатов. Если проекту действительно нужна такая смена, назовите категорию, оцените потерю сигнала, назначьте владельца, зафиксируйте срок и отдельно опишите способ возврата. Комментарий к одной строке не может быть policy для всей категории.</p>\n<figure><img src=\"/assets/editorial/2023/static-analysis-2023-decision-gate.svg\" alt=\"Гейт решения для результата статического анализа: после проверки rule, result и контекста команда выбирает keep, tune или ограниченный suppress; глобальное отключение требует отдельного решения, а rollback возвращает прежнюю видимость.\" loading=\"lazy\" /><figcaption>Сначала собирается контекст результата, затем выбирается узкое действие. Схема показывает проектный policy-контракт, а не формат SARIF, запуск анализатора или эффект в production.</figcaption></figure>\n<h2>Запишите evidence так, чтобы его повторили</h2>\n<p>Evidence — это короткая запись, по которой другой инженер может повторить решение. Для любого действия укажите <code>owner</code>, <code>reason</code>, <code>action</code> и <code>reviewBy</code>. Для <code>tune</code> добавьте новую <code>ruleRevision</code> и описание diff. Для <code>scoped suppress</code> добавьте точный <code>fingerprint</code>, scope и <code>expiresOn</code>. Дата следующей проверки не должна быть позже срока окончания исключения.</p>\n<p>Причина «шум» ничего не объясняет. Причина должна связывать решение с фактом: «вызов получает массив аргументов после нормализации; правило ожидает конкатенацию строки; оба минимальных примера проверены». В настоящем проекте добавьте ссылку на задачу или commit, но не добавляйте токены, пользовательские данные и полный чувствительный фрагмент кода.</p>\n<h2>Проверьте отрицательные пути</h2>\n<p>До применения policy проверьте, что неполная запись не проходит. Нужна не проверка непустых строк, а минимальный контракт: разрешены только три действия; suppress требует точного scope и двух корректных дат; tune требует новой revision. Фрагмент ниже запускается в Node.js и работает только с объектом в памяти. Он не читает репозиторий, не запускает сканер и не применяет конфигурацию.</p>\n<pre><code>node --input-type=module &lt;&lt;'NODE'\nconst decision = {\n  action: 'scoped-suppress',\n  owner: 'security-review',\n  reason: 'Проверены источник, граница доверия и sink',\n  fingerprint: 'result-command-001',\n  scope: 'exact-result',\n  reviewBy: '2023-05-20',\n  expiresOn: '2023-05-27',\n  ruleRevision: 'command-input/v3'\n};\n\nconst allowedActions = new Set(['keep', 'tune', 'scoped-suppress']);\nconst isDate = (value) =&gt; {\n  if (!/^\\\\d{4}-\\\\d{2}-\\\\d{2}$/.test(value)) return false;\n  return new Date(value + 'T00:00:00Z').toISOString().startsWith(value);\n};\n\nconst valid =\n  allowedActions.has(decision.action) &amp;&amp;\n  decision.owner &amp;&amp; decision.reason &amp;&amp;\n  (decision.action !== 'tune' || decision.ruleRevision !== 'command-input/v2') &amp;&amp;\n  (decision.action !== 'scoped-suppress' ||\n    (decision.fingerprint &amp;&amp; decision.scope === 'exact-result' &amp;&amp;\n      isDate(decision.reviewBy) &amp;&amp; isDate(decision.expiresOn) &amp;&amp;\n      decision.reviewBy &lt;= decision.expiresOn));\n\nconsole.log(valid ? 'plan-valid' : 'plan-invalid');\nNODE</code></pre>\n<p>Положительный путь печатает <code>plan-valid</code>. Для отрицательной проверки удалите fingerprint, поставьте <code>2023-02-31</code>, замените scope на общий или используйте действие <code>disable-globally</code>: во всех случаях должен получиться <code>plan-invalid</code>. Сравнение дат строкой безопасно только после строгой проверки формата и календаря, как в примере. Без этого значение вроде 31 февраля может пройти поверхностную проверку.</p>\n<h2>Сделайте rollback проверяемым</h2>\n<p>Rollback — не удаление строки из конфигурации. Для suppress удалите именно это исключение, повторите анализ на том же commit и проверьте, что ожидаемый результат снова виден. Для tune верните прежнюю revision, повторите минимальную пару и сравните отчёты. Если повторный анализ невозможен, зафиксируйте причину и риск, а не называйте возврат завершённым.</p>\n<p>У rollback есть ограничение: он возвращает видимость правила или убирает узкое исключение. Он не отменяет уже выпущенный код и не доказывает безопасность старого состояния. Если исключение успело скрыть другие результаты, их нужно искать отдельным повторным запуском и сверкой baseline.</p>\n<h2>Ограничения применимости</h2>\n<p>Статический анализ не видит весь runtime-контекст. Правило может не знать о конфигурации, feature flag, генерации кода, маршруте данных, правах пользователя и фактическом deploy-артефакте. SARIF фиксирует структуру обмена, но не превращает позицию в файле в доказательство исполнения. Одинаковая строка может быть опасной в одном сервисе и безопасной в другом.</p>\n<p>Команда Semgrep в примере — ориентир для CLI, а не зафиксированный контракт всех будущих версий. Закрепите версию в CI, сохраните вывод <code>semgrep --version</code> и проверьте опции в документации перед миграцией. Не переносите названия <code>keep</code>, <code>tune</code> и <code>scoped-suppress</code> в инструмент без адаптера и теста его реального формата.</p>\n<p>Не заявляйте покрытие, снижение ложных срабатываний или отсутствие пропущенных опасных случаев без измерения на конкретном наборе кода. Если неизвестны источник, граница доверия, владелец или артефакт, оставьте результат видимым. Это честнее, чем скрыть неопределённость глобальным выключателем.</p>\n<h2>Порядок действий и критерий готовности</h2>\n<ol><li><strong>Зафиксируйте симптом.</strong> Сохраните ruleId, revision, URI, строку, уровень, сообщение и fingerprint, если его выдала система управления результатами.</li><li><strong>Восстановите контекст.</strong> Найдите источник значения, путь до sink, trust boundary, владельца и артефакт, в который попадает модуль.</li><li><strong>Проверьте intent правила.</strong> Прочитайте описание и версию, затем сравните безопасную и соответствующую гипотезе формы на минимальной паре.</li><li><strong>Выберите действие.</strong> Используйте keep для неполного контекста, tune для неверной гипотезы, scoped suppress для одного проверенного результата. Global disable вынесите в отдельное решение.</li><li><strong>Заполните evidence.</strong> Добавьте owner, reason, scope, fingerprint и даты. Для tune укажите новую revision и проверенный diff.</li><li><strong>Проверьте отказ.</strong> Убедитесь, что неполный контекст, общий suppress, неверная дата и просроченный review отклоняются.</li><li><strong>Подготовьте rollback.</strong> Верните прежнюю policy или revision и повторите анализ на том же commit.</li></ol>\n<p>Решение готово, когда другой инженер может ответить на пять вопросов: какой result разбирали, какую гипотезу проверяли, почему выбрали действие, кто и когда пересматривает решение, как вернуть прежнюю видимость. Для tune существует новая revision и проверенный diff. Для suppress совпадают fingerprint и scope, даты корректны, а expiry не прошёл. Для rollback есть повторный анализ или явно записана причина, почему он невозможен.</p>\n<h2>Проверяемые источники</h2>\n<ul><li><a href=\"https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html\" target=\"_blank\" rel=\"noopener noreferrer\">OASIS: Static Analysis Results Interchange Format (SARIF) Version 2.1.0</a> — спецификация описывает структуру log, result, rule, location и fingerprints; она не подтверждает достоверность отдельного результата.</li><li><a href=\"https://semgrep.dev/products/community-edition\" target=\"_blank\" rel=\"noopener noreferrer\">Semgrep Community Edition</a> — официальное описание локального статического анализа и вывода результатов в SARIF или JSON; конкретные CLI-опции нужно сверять с установленной версией.</li><li><a href=\"https://csrc.nist.gov/pubs/sp/800/218/final\" target=\"_blank\" rel=\"noopener noreferrer\">NIST SP 800-218: Secure Software Development Framework</a> — рамка практик безопасной разработки и управления риском; она не заменяет проверку конкретного кода и правила.</li></ul>"
}