Быстрый старт: после Установки запустите Демо — оно работает сразу без настройки данных. config.example.yaml, описанный далее в разделе Конфигурация, является шаблоном для ваших собственных результатов/артефактов и не будет работать, пока вы его не отредактируете.

Установка

Задайте ключ API:

Для прокси LiteLLM организации используйте config.litellm.example.yaml — он содержит встроенные комментарии. Учётные данные и пользовательские значения заголовков считываются из переменных окружения и никогда не сохраняются в конфигурации SAFE или файлах результатов.

Демо

demo/ содержит три небольших, полностью синтетических примера артефактов — ни один из них не получен из реального опубликованного исследовательского артефакта и не соответствует ему, — по одному на каждую метку таксономии, чтобы рецензенты могли проверить весь конвейер без внешних данных:

• demo-contextual-risk/ — игрушечный агрегатор контрольных точек федеративного обучения, который десериализует контрольную точку, загруженную с URL, предоставленного вызывающим кодом, с помощью torch.load. Ненадёжный, поступающий из сети ввод достигает небезопасного приёмника десериализации, который SAFE должен классифицировать как CONTEXTUAL_RISK.
• demo-hardening-recommendation/ — игрушечный бенчмарк-харнесс, который запускает subprocess.run(..., shell=True) с командными строками, которые все являются жёстко заданными литералами Python, без ввода, контролируемого вызывающим кодом. SAFE должен классифицировать это как HARDENING_RECOMMENDATION: шаблон shell является реальным и заслуживает флага, но ничто внешнее не может достичь его или повлиять на него.
• demo-false-positive/ — генератор тестовых фикстур, привязанный к старой версии Pillow с гипотетическим предупреждением о бомбе декомпрессии. Код только создаёт новые изображения в памяти и никогда не открывает внешние данные, поэтому фактический путь кода из предупреждения никогда не достигается. SAFE должен классифицировать это как FALSE_POSITIVE.

demo/findings.csv содержит по одному результату на артефакт, а demo/demo-zero-shot.yaml / demo/demo-agentic.yaml — готовые к запуску конфигурации (artifact_root: . разрешается относительно файла конфигурации, поэтому запускайте изнутри demo/):

Результаты попадают в demo/runs/demo-zero-shot/ и demo/runs/demo-agentic/ соответственно (см. Вывод).

Три метки

• CONTEXTUAL_RISK
• HARDENING_RECOMMENDATION
• FALSE_POSITIVE

Никакая дополнительная категория и никакое детерминированное правило смены меток не используется. Документированный, изолированный исследовательский/защитный механизм в собственном коде артефакта классифицируется как HARDENING_RECOMMENDATION, поскольку лежащая в основе практика всё ещё реальна, даже когда изоляция ограничивает реалистичную эксплуатируемость.

Бинарные классы

• SECURITY_RELEVANT: обоснованная контекстная угроза или проблема укрепления, включая намеренное, изолированное поведение исследовательской безопасности.
• NON_SECURITY: ложный, несоответствующий, неприменимый, отсутствующий или демонстративно неиспользуемый результат по затронутой функции.

Оценщик также выводит бинарное представление из мультиклассовых предсказаний: FALSE_POSITIVE становится NON_SECURITY; каждая другая мультиклассовая метка становится SECURITY_RELEVANT. Прямые и производные бинарные результаты остаются явно раздельными.

Структура ввода

Сопоставление точное: artifact_id = artifact_001 разрешается в artifacts/artifact_001/.

Обязательные столбцы CSV:

Необязательные столбцы:

Начальный безымянный столбец индекса игнорируется. Дополнительные столбцы сохраняются моделью ввода.

Пример:

Генерация результатов из новой кодовой базы

scripts/run_scanners.py и scripts/build_findings_csv.py создают findings.csv и структуру артефактов, описанные выше, непосредственно из вашего собственного кода, используя Semgrep и Trivy.

Установите Semgrep (работает одинаково на любой ОС, включая Linux):

Установите Trivy на Linux — либо через apt-репозиторий (Debian/Ubuntu):

или через официальный скрипт установки, который работает на любом дистрибутиве Linux и устанавливает бинарный релиз в /usr/local/bin (не требуются root-пакеты, кроме sudo для этого каталога):

Убедитесь, что оба инструмента находятся в PATH, прежде чем продолжить:

Затем разложите по одному каталогу на артефакт внутри artifact_root/ и запустите:

Первая команда запускает Semgrep и Trivy (сканирование уязвимостей и секретов) для каждого каталога артефакта и сохраняет необработанный JSON сканеров. Вторая анализирует этот JSON в совместимый с SAFE findings.csv (столбцы соответствуют Структуре ввода; file указывается относительно каждого каталога артефакта). Передайте --skip-semgrep/--skip-trivy любому из скриптов, чтобы запустить только один инструмент. --config в run_scanners.py фиксирует конкретный набор правил Semgrep вместо стандартного auto, который удобен, но не воспроизводимо зафиксирован.

Конфигурация

Этот раздел предназначен для запуска SAFE с вашим собственным CSV-файлом результатов и папками артефактов (см. Структуру ввода выше). Если вы просто хотите увидеть, как работает SAFE, используйте Демо — config.example.yaml ниже является шаблоном и не будет работать как есть.

Скопируйте config.example.yaml:

Затем отредактируйте input_csv и artifact_root (и опционально paper_root), чтобы указать на ваши собственные данные перед запуском.

Ключевые настройки:

• model / provider: точный идентификатор модели OpenAI (или псевдоним LiteLLM) и openai или litellm с URL прокси и именем переменной окружения для учётных данных.
• analysis_mode: zero_shot или agentic.
• classification_task: binary или multiclass; независимо от analysis_mode.
• max_agent_steps: требуется только в агентной конфигурации.
• max_workers / max_output_tokens / max_schema_retries: параллелизм, потолок вывода на ответ и бюджет повторов вызовов модели для ответов с недействительной схемой.
• resume / resume_policy: incomplete повторяет сбои, отсутствующие артефакты и непройденные результаты; failed_only повторяет только сбои, сохраняя записанные успехи.
• cost: опциональный учёт стоимости в реальном времени и завершение по max_run_cost_usd.

Модель по умолчанию — gpt-5.6-sol. Измените её явно, если требования к доступности, стоимости или задержке отличаются.

Запуск анализа

Или без установки консольной команды:

Для запускаемого сопоставимого сравнения с включёнными синтетическими данными см. Демо (demo/demo-zero-shot.yaml и demo/demo-agentic.yaml). Они отличаются только analysis_mode и run_name. Zero-shot выполняет один вызов модели на основе базовых свидетельств. Агентный режим начинается с тех же свидетельств и может выполнять ограниченные инструменты чтения репозитория перед возвратом того же структурированного результата.

Вывод

results.csv предназначен для анализа. results.jsonl сохраняет полные структурированные записи. Свидетельства и необработанные выходные данные модели поддерживают аудит и анализ ошибок. Оба являются каноническими: они содержат только последнюю запись для каждого результата, тогда как logs/result_attempts.jsonl является append-only и сохраняет каждый исторический исход.

При возобновлении SAFE сначала повторно анализирует сохранённые необработанные ответы каждого неудачного результата текущим строгим парсером; однозначно допустимая классификация восстанавливается без вызова API. Только невосстановимые сбои планируются для инференса модели. Для продолжения только неудачных результатов частично завершённого запуска сохраните тот же output_root и run_name и задайте:

Для оценки предсказаний по размеченному золотому CSV (со столбцом security_label или security_class):

Тестирование

Набор тестов использует фиктивного провайдера и поэтому не требует ключа API.