Открытый репозиторий для валидации агентных ИИ-приложений: redteam, поведение, цепочка поставок, статический анализ
# NuGuard Open Source NuGuard — это открытый инструментарий для обеспечения безопасности AI-приложений. Его цель — обеспечить максимально широкое redteaming- и поведенческое тестирование агентных AI-приложений. С NuGuard разработчики AI могут сосредоточиться на создании своих приложений, в то время как NuGuard непрерывно тестирует и проверяет их на соответствие широкому спектру рисков безопасности, включая атаки на цепочку поставок, prompt injection, злоупотребление инструментами MCP, атаки на API, утечку данных и многое другое. NuGuard позволяет разработчикам ускорить рабочие процессы безопасности и быстрее и увереннее выходить в production. Коммерческая версия NuGuard доступна как SaaS-продукт с дополнительными функциями и поддержкой; ознакомьтесь с ней на http://nuguard.ai. ## Что он делает - Генерирует AI-SBOM из локальной кодовой базы или Git-репозитория - Анализирует SBOM на предмет структурных рисков безопасности AI и проблем цепочки поставок - Предлагает поведенческую политику AI на основе SBOM - Выполняет статическое и runtime-тестирование поведения, специально построенное вокруг AI-SBOM и поведенческой политики - Проводит red-team тестирование AI-приложения в песочнице: максимально обширный и актуальный каталог векторов атак плюс специально созданные сценарии. Это включает prompt injection, злоупотребление инструментами, утечку данных и связанные сценарии атак, которые задействуют различные субагенты, инструменты и возможности целевой системы. - Автоматические предложения по устранению выявленных проблем, включая фрагменты кода и корректировки политик - Экспорт результатов в текстовом формате, JSON, Markdown и рабочих процессах, ориентированных на SARIF ## Текущий интерфейс CLI Реализовано и доступно сегодня: - `nuguard sbom` - `nuguard analyze` - `nuguard scan` - `nuguard policy` - `nuguard behavior` - `nuguard redteam` ## Требования - Python 3.12+ - `uv` для рекомендуемого локального рабочего процесса ## Установка **Python CLI:** ```bash pip install nuguard ``` Приведённые ниже шаги описывают настройку локальной среды разработки. Это рекомендуется, если вы хотите запустить последнюю версию кода, внести вклад в проект или запустить CLI с функциями при поддержке LLM, которые требуют настройки локальных переменных окружения. ```bash uv sync --dev ``` Запустите CLI с помощью: ```bash uv run nuguard --help ``` Или из виртуального окружения: ```bash . .venv/bin/activate nuguard --help ``` ### Пользователи Claude могут использовать команды плагина. Следуйте инструкциям в [docs/plugin-guide.md](https://github.com/nuguardai/nuguard/blob/develop/docs/plugin-guide.md), чтобы настроить плагин NuGuard для Claude и использовать его для запуска таких команд, как `/nuguard-sbom`, `/nuguard-analyze` и `/nuguard-redteam`, непосредственно из ваших бесед с Claude. ## Быстрый старт ### 1. Создание AI-SBOM ```bash nuguard sbom generate --source . --output app.sbom.json ``` Вы также можете просканировать удалённый репозиторий: ```bash nuguard sbom generate \ --from-repo https://github.com/org/repo \ --ref main \ --output app.sbom.json ``` ### 2. Запуск статического анализа ```bash nuguard analyze --sbom app.sbom.json --format markdown ``` Типичные варианты вывода: - `markdown` для проверки человеком - `json` для автоматизации - `sarif` для конвейеров сканирования кода ### 3. Поведенческое тестирование ```bash nuguard behavior \ --sbom app.sbom.json \ --target http://localhost:3000 \ --format markdown ``` ### 4. Проведите red-team тестирование работающего приложения ```bash nuguard redteam \ --config nuguard.yaml \ --output reports/redteam.md \ --format markdown ``` Для более полного покрытия red-team сценариев вы также можете указать: - когнитивную политику с помощью `--policy` - canary-значения с помощью `--canary` - файл конфигурации с помощью `--config` ### 5. Запуск единого конвейера ```bash nuguard scan \ --source . \ --output-dir nuguard-reports ``` По умолчанию этот запуск выполняет генерацию SBOM вместе со статическим анализом за один проход. Чтобы включить проверки политик и red-team, явно включите эти шаги и предоставьте необходимые входные данные: ```bash nuguard scan \ --source . \ --steps sbom,analyze,policy,redteam \ --policy cognitive_policy.md \ --target http://localhost:3000 \ --output-dir nuguard-reports ``` ## Конфигурация NuGuard поддерживает конфигурацию проекта через `nuguard.yaml`. Готовый к редактированию пример находится в [`nuguard.yaml.example`](https://github.com/nuguardai/nuguard/blob/develop/nuguard.yaml.example). Ключевые разделы в примере конфигурации: - `sbom`: путь к существующему SBOM - `source`: каталог исходного кода для генерации - `policy`: путь к когнитивной политике - `llm`: настройки модели для функций с поддержкой LLM - `behavior`: целевой URL, эндпоинт и настройки профиля тестирования для поведенческого тестирования - `redteam`: целевой URL, эндпоинт, файл canary, профили, фильтры сценариев, настройки управляемого диалога и управление триггерами находок (`finding_triggers.*`) - `analyze`: минимальный порог серьёзности - `database`: настройки хранилища на базе SQLite или Postgres - `output`: формат вывода и порог сбоя Флаги CLI имеют приоритет над `nuguard.yaml`, который имеет приоритет над переменными окружения и встроенными значениями по умолчанию. ## Canary для Red-Team NuGuard может отслеживать заранее внедрённые значения canary во время динамического тестирования, чтобы формировать находки эксфильтрации с высокой степенью достоверности. Начните с [`canary.example.json`](https://github.com/nuguardai/nuguard/blob/develop/canary.example.json), создайте локальный `canary.json`, внедрите эти значения в целевую систему, затем укажите `nuguard redteam` на этот файл с помощью `--canary`. Подробнее см. в [`docs/redteam-engine.md`](https://github.com/nuguardai/nuguard/blob/develop/docs/redteam-engine.md). ## Разработка Установите зависимости для разработки: ```bash make dev ``` Запустите тесты: ```bash make test ``` Запустите линтинг и проверку типов: ```bash make lint ``` Отформатируйте кодовую базу: ```bash make fmt ``` ## Публикация Этот репозиторий включает рабочие процессы GitHub Actions для доверенной публикации (Trusted Publishing) в TestPyPI и PyPI: - [publish-testpypi.yml](https://github.com/nuguardai/nuguard/blob/develop/.github/workflows/publish-testpypi.yml) - [publish-pypi.yml](https://github.com/nuguardai/nuguard/blob/develop/.github/workflows/publish-pypi.yml) Прежде чем рабочие процессы смогут выполнять публикацию, настройте доверенных издателей (Trusted Publishers) в TestPyPI и PyPI для проекта `nuguard` со следующими параметрами: - владелец/организация: `NuGuardAI` - репозиторий: `nuguard` - файл рабочего процесса: `publish-testpypi.yml` или `publish-pypi.yml` - окружение: `testpypi` или `pypi` Рекомендуемый порядок выпуска: 1. Запустите рабочий процесс TestPyPI вручную из GitHub Actions. 2. Проверьте установку пакета и работу CLI из TestPyPI. 3. Создайте релиз GitHub, чтобы запустить рабочий процесс публикации в PyPI. ### Проверки перед публикацией Перед публикацией в TestPyPI или PyPI запустите быструю проверку работоспособности для нескольких приложений. Запуск одной командой: ```bash bash tests/apps/prepublish-sanity.sh ``` Этот runner выполняет: - Быструю проверку репозитория (`nuguard --help` плюс критически важные локальные тесты) - Запуски поведения в динамическом режиме с рабочим процессом `intent_happy_path` - Запуски Redteam с `profile: ci` - Контроль артефактов и качества (непустые отчёты, ненулевое число выполненных сценариев, строгие проверки источника эндпоинтов и защитные ограничения на ошибки транспорта) Файлы конфигурации prepublish, используемые runner: - `tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml` - `tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml` - `tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml` Ручной запуск для каждого приложения (при необходимости): ```bash # OpenAI CS agents demo uv run nuguard sbom generate --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --format json -o tests/apps/openai-cs-agents-demo/openai-cs.sbom.json uv run nuguard behavior --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/openai-cs-agents-demo/reports/openai-cs-prepublish-behavior --verbose uv run nuguard redteam --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --format json --format markdown --output tests/apps/openai-cs-agents-demo/reports/openai-cs-prepublish-redteam --verbose # Gemini Auto app uv run nuguard sbom generate --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --format json -o tests/apps/Gemini-Auto-app/gemini-auto.sbom.json uv run nuguard behavior --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/Gemini-Auto-app/reports/gemini-auto-prepublish-behavior --verbose uv run nuguard redteam --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --format json --format markdown --output tests/apps/Gemini-Auto-app/reports/gemini-auto-prepublish-redteam --verbose # Pinnacle Bank app uv run nuguard sbom generate --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --format json -o tests/apps/pinnacle-bank-app/pinnacle-bank.sbom.json uv run nuguard behavior --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/pinnacle-bank-app/reports/pinnacle-bank-prepublish-behavior --verbose uv run nuguard redteam --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --format json --format markdown --output tests/apps/pinnacle-bank-app/reports/pinnacle-bank-prepublish-redteam --verbose ``` Важно: - Не используйте `|| true` в запусках с публикационным гейтингом. - Код выхода `2` может указывать на находки или политические гейты; рассматривайте его как сигнал и полагайтесь на проверки качества отчёта для принятия решения о прохождении/непрохождении. ## Заметки о репозитории - В настоящее время репозиторий содержит примеры выходных данных и фикстуры бенчмарков в каталоге `tests/output/` - Некоторые тесты red-team и бенчмарков являются опциональными и включаются через переменные окружения - Функции с поддержкой LLM зависят от доступности учётных данных провайдера через переменные окружения ## Лицензия Информация о лицензии доступна в файле [LICENSE](https://github.com/nuguardai/nuguard/blob/develop/LICENSE).