Аудит проекта на основе CPG — Документация CodeGraph

CPG (Code Property Graph) — граф свойств кода. Он связывает элементы программы, вызовы и потоки данных, на которых строится аудит.

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

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

Подготовка проекта

Используйте Python-окружение установленного CodeGraph и работающий сервис GoCPG. Сначала импортируйте проект и проверьте, что его CPG соответствует ревизии исходников, которую вы собираетесь проверять.

Запустите команду из каталога установки CodeGraph, где находится config.yaml. Аудит находит проект по пути к его CPG в projects.registry. Для проекта на Python запись имеет следующий вид:

projects:
  registry:
    audit_project:
      language: python
      db_path: '<CPG_DB_PATH>'
      source_path: '<PROJECT_ROOT>'

Укажите имя существующего проекта, язык, путь к CPG и корень исходников. Сохраните остальные настройки config.yaml. Путь в реестре должен указывать на тот же файл, что и --db. Параметр --source-path задаёт корень исходников для этого зарегистрированного проекта. До запуска создайте каталог отчёта с правом записи.

Выбор глубины

Выбор глубины
Режим	Профиль CLI	Объём и стоимость	Когда запускать
`quick`	`ci_fast`	Изменённые файлы и объявленное замыкание зависимостей; ограниченный набор проверок синтаксиса, символов, CFG и критичных правил.	Pull request и короткий цикл обратной связи.
`standard`	`standard`	Весь проект, архитектура, потоки данных и метрики качества.	Регулярный аудит и подготовка сопоставимой основы.
`deep`	`deep_security`	Стандартный режим плюс учёт ссылок на один объект, отдельных полей и выполнимости путей в пределах заданного бюджета.	Подтверждение сложных находок безопасности и потоков данных.

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

Запустите стандартный аудит в PowerShell из каталога установки CodeGraph:

python -m src.cli audit --db "<CPG_DB_PATH>" --source-path "<PROJECT_ROOT>" --profile standard --format json --output "<AUDIT_OUTPUT_PATH>" --skip-llm-conclusion --skip-persistence
if ($LASTEXITCODE -ne 0) { throw 'Audit failed' }

Используйте Python-окружение установленного CodeGraph. Замените три шаблона в кавычках путём к CPG настроенного проекта, корнем его исходников и путём отчёта. Каталог отчёта должен существовать и быть доступен для записи. --skip-persistence отключает запись проекций аудита. Первичная проверка требует свежий CPG. После успешного аудита команда записывает файл отчёта. Откройте указанный JSON-файл только после успешного завершения команды. При ошибке прервите проверку отчёта: по тому же пути может оставаться файл предыдущего запуска. Устаревший граф приводит к ошибке audit_cpg_refresh_required. Обновите проект через импорт проекта и повторите ту же команду аудита.

Канонический результат

Сначала проверьте объект quality_assessment, а не поля совместимости:

pipeline_id содержит идентификатор unified_audit_pipeline.v1;
model_version задаёт версию расчётной модели;
mode и basis связывают результат с областью анализа и ревизией;
factors содержит Q1-Q12, их статус, оценку, покрытие и ограничения;
score_eligible разрешает или запрещает расчёт общего балла;
overall_score остаётся пустым при нехватке обязательных данных;
release_authority для оценки качества всегда равен false.

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

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

Типовые дефекты

Единый отчёт проверяет три регулярно встречающихся класса:

Типовые дефекты
Класс	Что нужно для подтверждённой находки	Когда фиксируется пробел анализа
Магическое число (magic number)	Контекст абстрактного синтаксического дерева (AST), роль символа или вызова и применимое правило.	Константу нельзя безопасно классифицировать или язык не поддержан.
Потерянное исключение (swallowed exception)	Путь обработки ошибки: ошибка потеряна, а не передана, обработана или намеренно преобразована.	Граф вызовов или модель обработки ошибок для языка неполны.
Несоответствие SQL схеме	Разобранный SQL, подтверждённый исполняемый вызов, движок базы, которому принадлежит запрос, идентификатор схемы, контракты привязки параметров и результата.	SQL формируется динамически, схема не определена либо для запроса отсутствуют данные разбора или схемы.

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

После исправления укажите одно из допустимых итоговых решений: application_fix, detector_fix, approved_defer или evidence_gap. Повторите подходящий режим на той же основе сравнения; старый результат должен остаться неизменным.

Диагностические метрики

Метрики методов и классов версионируются. Запись содержит контрольный отпечаток определения, языковой профиль, единицу измерения, идентификатор сущности, ревизии исходников и CPG, статус полноты и подтверждающие данные. Неподдерживаемые или неизмеримые значения остаются пустыми, а не превращаются в нули.

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

Очередь вмешательств

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

Разберите предложения очереди и выберите изменения для проверки. Согласуйте исправление и критерии выпуска с ответственным за проект. Пользу изменения проверяйте экспериментом. При нехватке данных эксперимент получает статус inconclusive; действующая основа сохраняется, пока проверка на фиксированной выборке не выполнит заданные критерии.

Проверка полноты и сопоставимости

Не используйте общий балл, если:

CPG устарел, неполон или относится к другой ревизии;
отсутствует обязательная возможность анализатора или число сущностей, пригодных для оценки;
детектор вернул неподдерживаемый или неразрешённый результат;
режим, версия модели, отпечаток определения, область проекта или группа сравнения несовместимы с результатом для сравнения;
score_eligible=false либо overall_score=null.

Восстановите доказательства и повторите тот же штатный запуск. Код завершения 0, пустой список находок или прежний числовой балл не исправляют неполный канонический результат.

Проектные архитектурные правила описаны в руководстве по контролю архитектуры. GoCPG загружает инварианты только из явно выбранных файлов правил и контроля выпуска и не подставляет правила CodeGraph при анализе другого проекта.

Автоматические аудиты по расписанию

Администратор проекта настраивает регулярный композитный аудит в разделе «Расписания» каталога проектов. CodeGraph хранит параметры действия проекта, а Temporal запускает его по cron. Для работы нужны доступ к проекту, права администратора или разрешение записи, подключённый Temporal с исполнителем и одобренный сервисный аккаунт для аудита. Получите идентификатор этого аккаунта у администратора установки.

Откройте каталог проектов, выберите проект и раздел «Расписания». Перейдите в режим «Планирование» и нажмите «Создать расписание».
Выберите тип действия «Композитный аудит» (audit_composite). Укажите ответственного и идентификатор сервисного аккаунта.
Заполните «Выражение расписания» и «Часовой пояс». Например, 30 2 * * * и Asia/Yekaterinburg означают ежедневный запуск в 02:30 по времени Екатеринбурга. Согласуйте время с окнами других аудитов проекта: сервер проверяет пересечение активных окон.
Выберите поведение для пропущенного запуска: «Пропустить» (skip), «Запустить один раз» (run_once) или «Догнать» (catch_up). «Догнать» использует ограниченный повтор; текущий предел — один пропущенный запуск.
Включите расписание и, если нужен отчёт в панели, флаг «Создавать снимок панели». Нажмите «Создать», чтобы подтвердить настройки и создать расписание.
Проверьте идентификатор и статус расписания оркестратора, а также время следующего запуска. Нажмите «Запустить сейчас», чтобы проверить настроенное действие без ожидания cron. Это запускает настоящий аудит выбранного проекта.
Откройте «Историю запусков». Дождитесь завершения задания и откройте артефакт аудита. Если вы включили создание снимка панели, проверьте и его. Сверьте проект, ревизию кода, область анализа и результаты с настройками задания. При блокировке прочитайте её причину в деталях запуска.

Для изменения периодичности выберите существующее расписание, исправьте cron или часовой пояс и сохраните его. Кнопка «Поставить на паузу» останавливает следующие запуски по расписанию; «Возобновить расписание» включает их снова. Проверьте новое состояние и время следующего запуска.

Значение analysis.full_scan_interval_days в конфигурации задаёт срок между полными анализами для контроля своевременности. Автоматический запуск настраивается отдельно в расписании действия проекта.

Для автоматизации через API используйте маршруты расписаний в REST API: создание и чтение /api/v1/traceability/projects/{project_name}/scheduled-actions, команды run_now, pause, resume по /api/v1/traceability/projects/{project_name}/scheduled-actions/{schedule_id}/commands.