SecureCode AI: итоговый отчёт

Состояние на 29 сентября 2026 года. Исходное задание: docs/PROJECT_BRIEF.md.

1. Постановка задачи

Статические анализаторы (SAST) работают по жёстким правилам, дают много ложных срабатываний и не понимают контекст, а отправлять приватный код в публичные облачные API нельзя. Цель проекта — прототип локального ассистента, который:

загружает исходный код Python/JavaScript/Go из локального репозитория;
анализирует его набором инструментов на базе ast/tree-sitter (AST, секреты, уязвимые зависимости, валидация кода);
с помощью мультиагентной системы на локальной квантованной LLM находит уязвимости (агент Аудитор) и предлагает безопасные исправления (агент Архитектор);
выдаёт отчёт .md/.html с классификацией по OWASP Top 10 и готовыми diff-патчами.

2. Решение

Git-снимок (точная ревизия, Python / JS / Go)
        │
        ├── детерминированный lane: CST/AST, 30+ CWE-сканеров, секреты, зависимости (OSV)
        └── модельный lane: Аудитор на LLM ищет уязвимости независимо от сканеров
        │
        ▼
  EvidenceGraph (единый контракт) → Аудитор → Скептик → решение по находке
        │
        ▼
  Архитектор: patch → проверка в эфемерной копии (парсинг, повторный скан)
        │
        ▼
  Отчёт: JSON / SARIF / Markdown / HTML с OWASP Top 10 и diff

Модуль задания	Реализация
Загрузка данных	`native_sources.py`: чтение файлов из неизменяемого Git-снимка, определение языка, лимиты
Tools Library	`cst_python.py`, `cst_ecmascript.py`, `cst_go.py` (AST и таблицы символов); поиск секретов в `secret_detection.py` и смежных модулях; `dependency_scanning*.py` (pip/npm/Go, OSV); `local_repair_validation.py`; 30+ CWE-сканеров
Единый контракт	`packages/contracts`: `Evidence`, `SourceLocation` (файл, строки, SHA-256), `DiscoveryCandidate`, `FindingCase` (CWE ID); JSON Schema в `contracts/schemas`
Оркестратор агентов	`product_audit.py`, `product_review*.py`: Аудитор, Скептик, бюджеты и tool-сессии; демо `demo/p917_real_local_demo.py`
Auto-Fix	Архитектор выдаёт unified diff; патч проверяется во временной копии и никогда не применяется к исходному checkout
Отчёты	`reports_render.py` (MD/HTML/SARIF с OWASP), `security-report.md/.html` демо

Модель подключается через OpenAI-совместимый интерфейс. Основной вариант — локальная Qwen 2.5 Coder 7B Instruct, квантование Q4_K_M в Ollama 0.34.4 (только loopback, digest модели проверяется до и после вызова). Второй вариант — DeepSeek по отдельно одобренному владельцем профилю с лимитом расходов; условия хранения данных у провайдера не проверены, поэтому этот путь предназначен только для кода, который можно раскрыть.

3. Эксперименты и метрики

3.1. Сквозной прогон Аудитор → Архитектор

Фикстура с SQL-инъекцией (demo/fixtures/real-local-cwe89). Аудитор ищет уязвимость независимо от сканера; при совпадении Архитектор предлагает patch, который проверяется в эфемерной копии.

Модель	Итог	Находка	Патч	Проверка патча	Стоимость
Qwen 2.5 Coder 7B Q4_K_M (Ollama, локально)	`COMPLETED`	CWE-89, `app.py:5`, A03:2021 Injection, совпала со сканером	параметризованный запрос	парсинг OK, повторный скан 0 сигналов, `git apply --check` OK	локально
DeepSeek Flash	`COMPLETED`	то же	то же	то же	2 вызова, $0.00014

Квитанции: current-real-local-p917.json, current-deepseek-p917.json. Исходный код и сырой ответ модели в квитанции не попадают.

3.2. Инструменты на демо-проекте

notebooks/securecode_demo.ipynb (сохранён с выводами) на проекте из app.py, server.js, main.go и requirements.txt: найдены захардкоженный пароль (значение скрыто), CWE-798, SQL-инъекция и CWE-306 в JS, 10 известных уязвимостей requests==2.19.0 по данным OSV.

3.3. Бенчмарк на 600 кейсах CVEfixes

600 файловых ревизий CVEfixes v1.0.8 (Zenodo): по 200 на Python, JavaScript/TypeScript и Go, 300 пар «уязвимая / исправленная версия», сплиты 240/120/240 без пересечения пар. Интервалы — lineage-cluster bootstrap, 5 000 итераций, seed 20260927.

Конфигурация	Завершено	Precision	Recall	F1
Детерминированные сканеры	508/600	49.0%	25.7%	33.7%
DeepSeek, прямая классификация	600/600	50.5%	16.8%	25.2%
DeepSeek, one-shot	600/600	52.0%	22.7%	31.6%
Hybrid (сканеры ∪ DeepSeek)	508/600	49.9%	35.8%	41.7%
Semgrep 1.177.0	600/600	50.0%	34.3%	40.7%

На held-out части recall hybrid 32.8% против 32.5% у Semgrep; разница +0.3 п.п., 95% интервал от −8.9 до +10.0 п.п. включает ноль. Hybrid на уровне Semgrep, превосходство не доказано. Исправление сравнения узлов tree-sitter и дефектов Go-сканеров подняло recall детерминированного lane с 19.7% до 25.7% и сократило число сбоев сканера с 253 до 92 (оставшиеся — непарсящиеся файлы: Python 2, фрагменты JS). Precision всех конфигураций около 50%: корпус состоит из пар одного файла до и после исправления, и файловый детектор часто срабатывает на обе версии. Подробности: отчёт бенчмарка.

3.4. Качество кода

scripts/quality.py и CI на Python 3.12–3.14: ruff format/lint, mypy для Linux и Windows, 3292 теста (unit и интеграционные тесты демо), покрытие ядра не ниже 80%, проверка секретов и зависимостей.

4. Соответствие заданию

Требование	Статус	Где / как проверить
Локальная квантованная LLM	выполнено	Qwen Q4_K_M в Ollama; `quickstart.py --demo --provider local`
Мультиагентность: Аудитор и Архитектор	выполнено	демо P9.17 (оба агента на живой модели); продуктовый конвейер Аудитор → Скептик → решение покрыт интеграционными тестами
Tools: AST, секреты, уязвимые версии библиотек, валидация кода	выполнено	notebook, раздел 2; `local_repair_validation.py`
Загрузчик Python/JS/Go	выполнено	`native_sources.py`; notebook (находки в `.py` и `.js`)
Единый контракт: код, CWE ID, строки	выполнено	`packages/contracts`, JSON Schema; notebook, раздел 3
Auto-Fix в формате diff	выполнено	`model-proposed.patch` в выводе демо; `git apply --check`
Отчёт .md/.html с OWASP Top 10	выполнено	`security-report.md/.html` демо
Документация (README ru/en)	выполнено	README
Unit-тесты	выполнено	`tests/unit`, `scripts/quality.py`, CI
Notebook с прогоном аудита	выполнено	`notebooks/securecode_demo.ipynb`
Файл зависимостей	выполнено	`pyproject.toml`, `uv.lock`
Итоговый отчёт с метриками	выполнено	этот отчёт, бенчмарк
Dockerfile и инструкция	выполнено для демо	`deploy/docker/demo.Dockerfile`, `quickstart.py --demo`; полный стек сервер + worker (`--up`) на Linux не перепроверялся
Датасеты ссылками	выполнено	CVEfixes на Zenodo; в репозитории только манифест без исходников
Скринкаст 2–5 минут	выполнено	`docs/media/securecode-demo.mp4` (2:50, результаты v1.0; английская версия — `securecode-demo.en.mp4`); пересборка `docs/media/build_video.py`

5. Ограничения

Модельная демонстрация охватывает одно правило (CWE-89 в Python); общего вердикта о безопасности репозитория она не даёт.
Патч проверяется парсингом и повторным сканированием, но не поведенческими тестами.
Бенчмарк оценивает файловую классификацию; модельные конфигурации — прямые запросы к DeepSeek, а не полный конвейер с Аудитором и Скептиком. Hybrid — парная композиция сохранённых результатов, а не отдельный прогон.
92 из 600 кейсов не анализируются сканерами (непарсящийся код); они учтены как незавершённые, а не как «чистые».
Precision около 50% ограничивает практическую пользу без доработки детекторов.
Полный securecode scan требует защищённого одобрения хоста; для проверяющего предназначены демо и notebook.

6. Выводы

Прототип закрывает требования задания: локальная квантованная модель в роли Аудитора и Архитектора находит SQL-инъекцию, предлагает параметризованный запрос, патч проверяется и попадает в отчёт с OWASP Top 10; инструменты анализа покрывают AST, секреты, уязвимые зависимости и три языка. Тот же сценарий работает на облачной модели без изменений кода. На публичном корпусе комбинация сканеров и LLM достигает уровня Semgrep по recall, но не превосходит его статистически значимо; главные направления развития — точность детекторов, покрытие непарсящегося кода и оценка полного агентного конвейера на корпусе.

7. Воспроизведение

git clone https://github.com/shorinversion/securecode-ai && cd securecode-ai
python deploy/docker/quickstart.py --demo                   # нужен только Docker
python deploy/docker/quickstart.py --demo --provider local  # uv + Ollama, модель скачается
uv run --with nbconvert --with ipykernel jupyter nbconvert --to notebook --execute notebooks/securecode_demo.ipynb
uv run --locked python -I scripts/quality.py                # линтеры, типы, тесты