SAFE

SAFE выполняет контролируемую, учитывающую особенности репозитория оценку безопасности результатов Semgrep и Trivy в исследовательских артефактах.

Он поддерживает две независимые задачи классификации: прямое бинарное предсказание (SECURITY_RELEVANT или NON_SECURITY) и детальную мультиклассовую контекстную таксономию (три метки — см. Три метки). Каждая задача может выполняться в zero-shot или агентном режиме.

Он ожидает только:

1. CSV-файл с результатами, разделённый точкой с запятой.
2. Каталог, содержащий по одной папке исследовательского артефакта на каждый artifact_id.
3. Опционально, коллекцию PDF/текстов статей, привязанную по artifact_id.
4. Ключ OpenAI API или доступ к прокси LiteLLM организации.

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

Этот релиз содержит полный исходный код safe_audit, CLI и тесты, а также автономное demo/ с тремя полностью синтетическими примерами артефактов, которые можно запустить от начала до конца без каких-либо внешних данных. Он исключает реальный корпус исследовательских артефактов, метки истинности и оценочные результаты, использованные в статье.

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

Установка

cd path/to/safe-artifact-auditor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

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

export OPENAI_API_KEY="your-key"

Для прокси 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/):

cd demo
safe-audit run --config demo-zero-shot.yaml
safe-audit run --config demo-agentic.yaml

Результаты попадают в 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. Прямые и производные бинарные результаты остаются явно раздельными.

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

project/
├── config.yaml
├── data/
│   └── findings.csv
└── artifacts/
    ├── artifact_001/
    ├── artifact_002/
    └── artifact_003/

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

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

artifact_id;tool;finding_id

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

artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable

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

Пример:

artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable
artifact_001;semgrep;python.lang.security.audit.subprocess-shell-true;code;HIGH;src/probe.py;42;Shell command uses shell=True;;;;CWE-78;;yes
artifact_002;trivy;DEMO-CVE-0001;dependency;HIGH;;;Affected package (illustrative, not a real CVE);example-lib;1.2.0;CWE-502;8.1;yes

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

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

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

pip install semgrep

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

sudo apt-get install wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy

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

curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo sh -s -- -b /usr/local/bin

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

semgrep --version
trivy --version

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

python scripts/run_scanners.py artifact_root --output scan-output
python scripts/build_findings_csv.py scan-output --output data/findings.csv