Как читать отчёт CodeAuditAgent и действовать по нему

Отчёт по безопасности полезен только тогда, когда превращается во влитые исправления. Отчёты CodeAuditAgent построены вокруг этого: каждая находка достаточно конкретна, чтобы её можно было быстро проверить, и сопровождается патчем, который можно адаптировать. Это руководство объясняет каждую часть отчёта, как разбирать его, когда у вас нет выделенного инженера по безопасности, и как убедиться, что исправления сработали.

Что именно проверяется

Аудит выполняется либо для публичного репозитория GitHub, либо для фрагмента кода, который вы вставили. Для репозиториев CodeAuditAgent читает ветку по умолчанию. Приватные репозитории нельзя проверить по URL, и комментариев в pull request пока нет; результаты живут в панели и в экспортах.

Сколько именно кода репозитория будет прочитано, зависит от тарифа. План Free покрывает 1 репозиторий, 3 аудита в месяц и до 20 файлов за аудит. Starter за $49 в месяц покрывает 5 репозиториев, 50 аудитов и 40 файлов за аудит. Pro за $199 в месяц покрывает неограниченное число репозиториев, 500 аудитов и 80 файлов за аудит. Отдельные файлы больше 60 KB пропускаются. Месячные счётчики аудитов обнуляются в начале каждого календарного месяца (UTC). Вставленный фрагмент — ещё и быстрый способ проверить один беспокоящий вас файл до аудита всего репозитория.

Когда файлы остаются за пределами аудита из-за этих ограничений, отчёт помечается как частичный снимок. Отнеситесь к этой пометке серьёзно. Чистый частичный отчёт означает, что чисто выглядят прочитанные файлы, а не репозиторий целиком. Если самый важный для вас код не попал в выборку, проверьте его как вставленный фрагмент или на тарифе, который охватывает больше файлов.

Оценка риска

В начале каждого отчёта стоит оценка риска от 0 до 100; в экспорте в Markdown рядом с ней указана и общая критичность. Больше — рискованнее. Это сводка находок конкретного аудита, полезная для двух вещей: решить, насколько срочно стоит заняться репозиторием, и отследить, становится ли он лучше со временем.

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

Критичность и уверенность

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

• Critical: напрямую эксплуатируется с серьёзными последствиями — например, инъекция на публичном эндпоинте, обход аутентификации или раскрытые боевые учётные данные.
• High: настоящая уязвимость, требующая некоторого предусловия, или со значительным, но ограниченным влиянием.
• Medium: слабость, которая важна в сочетании с другими ошибками или имеет умеренное влияние.
• Low: вопросы укрепления защиты и пробелы в эшелонированной обороне.
• Info: наблюдения, о которых полезно знать, но которые сами по себе не являются уязвимостями.

Уверенность бывает высокой, средней или низкой. Находка с высокой уверенностью имеет явные доказательства в прочитанном коде. Находка с низкой уверенностью обычно зависит от того, чего аудит не видел: middleware в другом файле, политики базы данных или значения конфигурации, задаваемого при развёртывании. Низкая уверенность не значит «игнорировать»: она значит, что человеку стоит проверить недостающий контекст, прежде чем исправлять.

Из чего состоит находка

Каждая находка устроена одинаково, поэтому проверять её можно в одном и том же порядке.

• Заголовок и CWE: класс слабости, например CWE-639 для обхода авторизации через ключ, контролируемый пользователем. CWE подсказывает, какого рода исправления ждать.
• Расположение: файл и строка, чтобы сразу открыть код.
• Доказательство: относящийся к делу код, процитированный из файла. Убедитесь, что цитата совпадает с вашим текущим кодом; если строка уже изменилась, находка может быть устаревшей.
• Сценарий эксплуатации: как атакующий на деле воспользуется слабостью, шаг за шагом. Это самый быстрый способ понять, реальна ли она в вашем контексте.
• Патч-исправление: предлагаемое изменение в стиле окружающего кода.

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

--- a/app/api/invoices/[id]/route.ts
+++ b/app/api/invoices/[id]/route.ts
@@
-  const invoice = await db.invoice.findUnique({ where: { id } });
+  const invoice = await db.invoice.findFirst({
+    where: { id, userId: session.user.id },
+  });
   if (!invoice) return Response.json({ error: 'not_found' }, { status: 404 });

Положительные наблюдения и следующие шаги

Отчёты перечисляют и то, что сделано хорошо: последовательно используемые параметризованные запросы, секреты, загружаемые из окружения, строгая конфигурация cookie. Это стоит читать. Так вы узнаёте, какие шаблоны стоит сохранять и переносить в новый код, и это полезно, когда нужно объяснить состояние проекта кому-то ещё.

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

Порядок разбора для небольших команд

Без инженера по безопасности риск не в том, что отчёт проигнорируют, а в том, что день уйдёт на находки уровня Low, пока ждёт критическая. Хорошо работает простой порядок:

• Сначала прочитайте все находки уровня Critical и High. По каждой прочитайте сценарий эксплуатации и решите: настоящая, не настоящая или нужен контекст.
• Настоящие критические находки исправляйте в тот же день. Если исправление требует времени, добавьте временную меру: отключите эндпоинт или ужесточите проверку.
• Для находок, которым нужен контекст, проверьте недостающую часть: есть ли middleware, политика на уровне строк или конфигурация, которая уже это предотвращает? Запишите ответ.
• Находки уровня High планируйте в текущий спринт, Medium — в бэклог, а Low и Info собирайте в отдельный проход по укреплению защиты.
• Когда находка оказалась ненастоящей, запишите почему. Эта заметка избавит следующего человека от повторного разбирательства.

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

Обзор находок и экспорты

Когда аудитов накопилось несколько, работать из обзора находок удобнее, чем из отдельных отчётов. Он перечисляет находки по всем аудитам и фильтрует их по критичности, CWE и репозиторию. Фильтр по CWE особенно полезен: если одна и та же слабость появляется в трёх репозиториях, это обычно указывает на общий шаблон или отсутствующий вспомогательный код, а исправить шаблон дешевле, чем каждый случай по отдельности.

Находки можно выгрузить из обзора в CSV — удобно для импорта в трекер задач или таблицу. Отдельные отчёты экспортируются в Markdown, который хорошо читается в описании pull request, внутренней вики или сообщении подрядчику, который будет делать исправление.

Повторный аудит для подтверждения исправления

Исправление не завершено, пока вы его не проверили. После слияния запустите новый аудит того же репозитория. Каждый отчёт можно сравнить с предыдущим аудитом, чтобы увидеть, какие находки исчезли, какие остались и не появилось ли что-то новое. Оценка риска должна снижаться, когда настоящие проблемы исправлены; если этого не произошло, посмотрите на сравнение и разберитесь почему.

Сравнивайте честно. Если первый аудит был частичным снимком, а второй прочитал другие файлы, разница отражает и охват, и исправления. Аудиты расходуют месячный лимит, поэтому обычно выгоднее собрать несколько исправлений вместе, чем запускать аудит после каждого коммита.

Чего отчёт не покрывает

Знание границ помогает закрыть пробелы. Аудиты читают ваш исходный код; они не сканируют зависимости на известные уязвимые версии, поэтому держите включённым и сканер зависимостей — встроенный в ваш пакетный менеджер или в GitHub. Аудиты не видят конфигурацию, задаваемую при развёртывании, инфраструктуру вне репозитория и пропущенные файлы. И, как любой рецензент, человек или ИИ, аудит может ошибаться: доказательства и уровни уверенности существуют для того, чтобы вы могли быстро всё перепроверить, а не принимать на веру.

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