Возможности

• Инструменты анализа на ast и tree-sitter: детерминированные правила для 35 CWE, поиск захардкоженных секретов, проверка зависимостей pip, npm и Go по базе OSV.
• Четыре агента на LLM: Поиск, Аудитор, Скептик и Архитектор (см. Архитектура).
• Проверенные исправления: каждый diff применяется к анализируемой ревизии (git apply --check), проходит синтаксическую проверку и повторное сканирование.
• Отчёты в Markdown, HTML, JSON и SARIF: CWE, категория OWASP Top 10 2021, критичность, фрагмент кода и исправление.
• Единый контракт инструментов: каждый сигнал содержит правило (CWE), путь, строки и ссылку на фрагмент кода.
• Выбор модели: локальная квантованная Qwen 2.5 Coder 7B (Ollama) или DeepSeek по API.
• Интеграция с CI: GitHub и GitLab, SARIF для GitHub code scanning.

Архитектура

         Git-ревизия (точный commit)
                    │
      ┌─────────────┴─────────────┐
      ▼                           ▼
детерминированные сканеры   Поиск (LLM)
      └─────────────┬─────────────┘
                    ▼
      граф доказательств (EvidenceGraph)
                    │
                    ▼
      Аудитор → Скептик → решение по находке
                    │
                    ▼
      Архитектор: diff + проверка
                    │
                    ▼
      отчёт: CWE, OWASP Top 10, исправления

Проверка утверждений опирается на открытые методики Anthropic и Cloudflare. Подробное описание: архитектура, модель угроз.

Быстрый старт

Демонстрация на уязвимом примере в Docker:

python deploy/docker/quickstart.py --demo

С локальной моделью (требуются uv и Ollama; модель qwen2.5-coder:7b-instruct-q4_K_M, около 4.7 ГБ, загружается автоматически):

python deploy/docker/quickstart.py --demo --provider local

Отчёты сохраняются в output/demo-report/. Прогон всех инструментов с сохранёнными выводами: notebooks/securecode_demo.ipynb.

Установка

Требования: Git 2.44 или новее, CPython 3.12–3.14, uv 0.12.0. Docker нужен только для образов, Ollama — только для локальной модели. Локальная модель Qwen 2.5 Coder 7B Q4_K_M занимает около 4,7 ГБ на диске и требует 6–8 ГБ свободной видеопамяти или, без GPU, около 8 ГБ ОЗУ (медленнее); для DeepSeek GPU не нужен.

git clone https://github.com/shorinversion/securecode-ai.git
cd securecode-ai
uv sync --locked
uv run securecode --version

Использование

Аудит репозитория

uv run securecode analyze path/to/repo --output report.md

Команда выполняет полный конвейер: сканеры, Поиск, Аудитор, Скептик, решение по каждой находке и исправления Архитектора.

Для --provider openai-compatible адрес, модель и ключ задаются в окружении или .env:

SECURECODE_MODEL_BASE_URL=https://api.openai.com/v1
SECURECODE_MODEL=gpt-4o-mini
SECURECODE_MODEL_API_KEY=...

Подходит любой сервис с этим API по публичному HTTPS-адресу: OpenAI, OpenRouter, Groq, Together, корпоративный шлюз. Необязательные настройки: SECURECODE_MODEL_PRICE_INPUT и SECURECODE_MODEL_PRICE_OUTPUT (USD за миллион токенов; без них стоимость в отчёте «не известна», а --max-cost-usd не действует, прогон ограничен 20 млн токенов), SECURECODE_MODEL_CONTEXT_TOKENS и SECURECODE_MODEL_MAX_OUTPUT_TOKENS (по умолчанию 128000 и 16384), SECURECODE_MODEL_REASONING_EFFORT. Все роли, включая Архитектора, обращаются к этому адресу; секреты маскируются так же, как для DeepSeek. Условия хранения данных у выбранного сервиса SecureCode не проверяет: выбирая его, вы соглашаетесь отправить туда код проверяемого репозитория (решение D-118).

Коды возврата: 0 — подтверждённых уязвимостей нет и все обязательные этапы выполнены; 2 — есть хотя бы одна подтверждённая уязвимость (этот код важнее незавершённых этапов); 3 — подтверждённых уязвимостей нет, но часть этапов или кандидатов осталась без решения; 4 — ошибка аргументов, нет ключа, Git старше 2.44, в ревизии нет поддерживаемых исходников или файл отчёта уже существует. Если прогон остановился без отчёта, сообщение называет код причины (например, GIT_COMMAND_FAILED). Checkout другого пользователя (CI-контейнер, смонтированный том) проверяется, если Git ему доверяет: git config --global --add safe.directory <путь>. В JSON проверенные исправления лежат в patch_refs и validation_refs находки, в SARIF — в стандартном поле fixes. Сканер и модель могут подтвердить одну и ту же слабость: такие находки получают общий weakness_group в JSON и partialFingerprints (securecodeWeakness/v2) в SARIF; считать и показывать их нужно один раз. Группа — CWE в одном файле, а для захардкоженных секретов — ещё и строка: два ключа в разных строках файла — две слабости. Блок decision у находки показывает, кто её подтвердил: authority MODEL_REVIEW (согласие Аудитора и Скептика) или DETERMINISTIC_DETECTOR (детектор секретов, D-117), причину reason, вердикты обеих моделей и число обращений к ним (auditor_calls, skeptic_attempts). При коде 3 отчёт перечисляет кандидатов без окончательного решения с причиной для каждого; это не «уязвимостей нет», а места для ручной проверки. В JSON они лежат в undecided_candidates с теми же счётчиками и признаком retries_exhausted; кандидаты, которые уже покрыты подтверждённой находкой того же места, — в covered_candidates с полем covered_by. Стоимость прогона — в model_cost (usd, known). Если этап не завершён, отчёт называет причину кодом; в JSON она лежит в coverage_diagnostics (deterministic.reasons: OBSTACLE:…, SCAN_INCOMPLETE, RECEIPT_NOT_SUCCEEDED:…, BINDING_MISMATCH:…, EXCEPTION:…; в них нет путей и исходников). SECURECODE_TRACE=файл дописывает JSONL-трассу этапов (статусы, типы исключений, длительности; без исходников, промптов и путей), SECURECODE_SCAN_BUDGET_SECONDS (60..600) задаёт время на все процессы сканеров: по умолчанию две секунды на файл, но не меньше минуты и не больше десяти (D-121).

Комментарии в pull request

securecode analyze . --base origin/main --format json --output report.json
securecode publish github --report report.json --repo OWNER/NAME --pr 7

Команда publish github ведёт один сводный комментарий (обновляется на месте по маркеру) и по одному комментарию к строке на каждую новую подтверждённую слабость; если проверенное исправление — один hunk рядом со строкой, в комментарии есть блок suggestion. Известные по baseline находки в комментарии не выносятся, только в счётчик сводки. Токен берётся из переменной --token-env (по умолчанию GITHUB_TOKEN) и никогда не печатается; --dry-run показывает тела комментариев без сети и токена. GitHub отклоняет комментарий к строке вне diff pull request: такая находка остаётся в сводке. Готовый шаблон для Actions (с --base, SARIF и комментариями; все действия закреплены по SHA) — integrations/github/action.yml, пример — в integrations/github/README.md (D-126).

Baseline для CI

Команда без изменений кода принимает существующие слабости и ловит только новые:

securecode analyze . --write-baseline .securecode-baseline.json   # один раз, файл — в репозиторий
securecode analyze . --baseline .securecode-baseline.json          # в CI: код 2 только для новой слабости

Файл — JSON {"schema": "securecode-baseline/v1", "created", "head_sha", "weaknesses": [...]}; запись — weakness_group (из отчёта), cwe_id, path, reason (accepted или false_positive) и expires (дата или null). Ключ — weakness_group: он не зависит от правок вокруг, кроме захардкоженных секретов, где в группу входит строка (D-125). Известные находки остаются в JSON с полем suppressed, получают suppressions в SARIF и уходят в свёрнутый раздел «Известные находки (N)»; outcome ядра не меняется, итог для CI — в effective_outcome. Запись с истёкшим expires игнорируется (предупреждение в сводке). Если всё подтверждённое известно, прогон даёт 0 при полном покрытии и без нерешённых кандидатов, иначе 3. Неверный файл — код 4 до первого вызова модели.

Пример фрагмента отчёта:

| № | Уязвимость           | OWASP Top 10       | Критичность | Место    | Исправление          |
| 1 | CWE-89 SQL Injection | A03:2021 Injection | HIGH        | app.py:5 | исправление проверено |

Исправление в виде pull request

uv run python -I demo/p917_real_local_demo.py --repository path/to/repo --output out --provider deepseek --open-pr

Архитектор коммитит проверенное исправление в ветку securecode/fix-… и открывает pull request через GitHub CLI (gh). Для GitLab тот же флаг открывает merge request через glab: платформа определяется по адресу origin, явно её задаёт --forge gitlab. Исправления из securecode analyze --patch-dir DIR применяются вручную: git apply DIR/01-….diff, затем glab mr create или gh pr create. Пример: shorinversion/securecode-demo-app#1.

CI и серверный режим

securecode scan — блокирующая проверка для CI на заранее одобренном хосте: привязка к точному commit, одобренные профили модели и политики исходящих данных. Развёртывание control plane, worker и интеграций с GitHub и GitLab описано в docs/OPERATIONS.md.

Результаты

Демонстрация Аудитор → Архитектор на локальной Qwen 2.5 Coder 7B Q4_K_M и на DeepSeek: SQL-инъекция (CWE-89, A03:2021) найдена, исправление с параметризованным запросом прошло проверку. Квитанции: Qwen, DeepSeek.

Реальные репозитории на Python, JavaScript и Go: подтверждены SQL-инъекции, внедрение команд, открытый редирект, обход пути, отсутствие проверки подписи JWT; ложное срабатывание CSRF отклонено. Стоимость прогона — $0.003–0.011.

OWASP Benchmark for Python (1230 кейсов, 14 категорий; оценка TPR − FPR, 1 — идеально). В конфигурации SecureCode решение принимается согласием трёх проверок: Поиск (модель без подсказок), Аудитор (модель проверяет находки сканеров) и вторая модель; CWE попадает в отчёт, если её назвали минимум две из трёх (голоса сравниваются по семействам CWE из иерархии MITRE); слабое хеширование решает детерминированное правило. «Только модель» — та же модель без сканеров, для сравнения:

CVEfixes (3000 файлов: пары «до и после исправления CVE», 118 CWE; отложенная выборка 1200 файлов):

Методика, Bandit, gosec, ESLint, модели с открытыми весами, разбивка по языкам и ограничения: отчёт об экспериментах. Датасеты: CVEfixes, OWASP Benchmark for Python.

Языки и правила

Детерминированные правила покрывают инъекции (CWE-78, 79, 89, 90, 94), обход пути (22), SSRF (918), отсутствие аутентификации и авторизации (306, 862), небезопасную десериализацию (502), слабую криптографию (327, 338), захардкоженные учётные данные (798), ReDoS (1333) и другие. Агенты не ограничены этим списком: модель может сообщить о любой из 139 CWE таблицы соответствия OWASP Top 10 2021.

Безопасность

• Анализ привязан к точному commit; изменение ревизии отменяет публикацию результата.
• Незавершённая проверка даёт итог INDETERMINATE, а не «уязвимостей нет».
• Ответы модели — недоверенные данные: они проходят проверку по закрытой схеме.
• Найденные секреты маскируются до отправки модели: все агенты, включая Архитектора, видят код файла, но вместо значения — маркер редакции. Значения секретов не попадают в отчёты, diff и журналы. Маскируется то, что распознал детектор секретов: значение, собранное из частей ("sk-" + "..."), детектор не распознаёт, и такой код уходит в модель как есть. Найденный детектором секрет (CWE-798) подтверждается самим детектором: модели видят только маркер и не решают, настоящий ли это ключ.
• Локальная модель доступна только через loopback; внешний API используется лишь с явным согласием владельца.
• Исправления не применяются к исходному checkout без явного решения пользователя.

Подробнее: классификация данных, защита от prompt injection.

Разработка

uv sync --locked --group quality
uv run --locked python -I scripts/quality.py

scripts/quality.py запускает форматирование и линтер Ruff, mypy для Linux и Windows, unit- и интеграционные тесты с порогом покрытия ядра 80%. CI повторяет проверки на Python 3.12, 3.13 и 3.14 и дополнительно сканирует секреты и зависимости.

Структура репозитория

Документация

• Итоговый отчёт — постановка, решение, эксперименты, выводы
• Архитектура и продуктовая модель
• Эксплуатация: Docker, CI, GitHub и GitLab
• Воспроизведение экспериментов
• Модель угроз
• Исходное задание

Лицензия

Лицензия не выбрана; все права принадлежат автору. Учебный корпус в evaluation/development/ распространяется под CC0-1.0.