Об этом проекте

# Zentra CLI Zentra — это открытый ИИ-сканер безопасности приложений для разработчиков. Он сканирует кодовые базы на предмет рисков безопасности с помощью анализа фреймворков, моделирования угроз, статического анализа (SAST), сканеров цепочки поставок, API и инфраструктуры как кода (IaC). Он может работать локально с интерактивным терминальным интерфейсом или безголово в конвейерах CI. Бинарный файл называется `zentra`. ## Возможности - **Безголовый режим CI** для конвейеров GitHub Actions и GitLab merge request. - **Оркестрация сканеров на основе LLM** с провайдерами Anthropic, OpenAI-совместимыми, Claude CLI и экспериментальным Codex CLI. - **Динамический режим пентеста в браузере** для авторизованных целей. - **Несколько форматов вывода**: Markdown, JSON, SARIF и стилизованный HTML в `.zentra/`. - **Хранилище учетных данных с шифрованием в состоянии покоя** (DPAPI в Windows, файлы `0600` в Unix). ## Установка ### Быстрая установка (рекомендуется) Не требуется инструментарий Rust, клонирование репозитория или этап сборки. ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/johannus22/zentra/releases/latest/download/zentra-cli-installer.sh | sh ``` Для Windows PowerShell: ```powershell powershell -ExecutionPolicy Bypass -c "irm https://github.com/johannus22/zentra/releases/latest/download/zentra-cli-installer.ps1 | iex" ``` После этого откройте новое окно терминала, чтобы `zentra` стал доступен. Для ручной установки загрузите сборку со [страницы релизов](https://github.com/johannus22/zentra/releases). > **Примечание для Linux:** Бинарный файл связывается с `libdbus` во время выполнения для доступа к системной связке ключей. В минимальных или безголовых образах установите его сначала (`sudo apt-get install -y libdbus-1-3` или эквивалент). Альтернативно, установите `ZENTRA_NO_OS_KEYCHAIN=1`, чтобы использовать зашифрованное файловое хранилище учетных данных. ### Установка из исходного кода Сборка и локальный запуск: ```bash cargo build ``` Установка бинарного файла из проверенного репозитория: ```bash cargo install --path . ``` ## Использование TUI — это основной локальный интерфейс для настройки провайдеров, запуска сканирования и просмотра результатов. Главное меню группирует статическое тестирование безопасности приложений (SAST), динамическое тестирование безопасности приложений (DAST) и прочие действия. ### Команды сканирования Запуск только одного семейства сканеров: ```bash zentra scan --only sast zentra scan --only supply-chain zentra scan --only api zentra scan --only iac ``` Используйте `--pack`, чтобы предоставить каждому сканеру пакет репозитория с проверкой контекста. Состояние сканирования хранится в `.zentra/checkpoint.json` для инкрементальных запусков. SAST может использовать до 50 раундов провайдера ReAct; другие сканеры — до 30. Локальные запуски `zentra scan` включают постоянную панель чата только для чтения. Чат отвечает на ограниченные и отредактированные вопросы о сканировании и репозитории с профилем только для чтения (`list_files`, `read_file`, `grep_code` и ограниченные команды Git). Он может предлагать типизированные действия фокусировки/повторного запуска или категории уязвимостей, но ни вывод модели, ни вызов инструмента не могут применить их без локального подтверждения. Подтвержденные действия сохраняются в контрольной точке и применяются только при следующем сканировании. Чат недоступен в `zentra ci` или других безголовых путях сканирования. ### CI-сканирование безопасности Zentra включает выделенную команду CI: ```bash zentra ci ``` `zentra ci` — это не псевдоним для `zentra scan`. Он обнаруживает GitHub Actions или GitLab CI, подтверждает, что задание выполняется в конвейере PR/MR, запускает целевые сканеры безопасности без TUI, записывает артефакты CI и завершается с ошибкой только для находок на уровне порога отказа или выше или при сбоях сканера/системы. По умолчанию `zentra ci` блокирует PR/MR при любой находке **Critical** или **High**. Находки Medium, Low и Info сообщаются, но не приводят к сбою задания. #### Порог отказа Установите переменную окружения `ZENTRA_CI_FAIL_THRESHOLD` (одно из значений `critical`, `high`, `medium`, `low`, `info`) или используйте поле `fail_threshold` в `.zentra/config.json`, чтобы сохранить политику. Пример задания GitHub Actions: ```yaml - name: Run Zentra CI env: ZENTRA_API_KEY: ${{ secrets.ZENTRA_API_KEY }} ZENTRA_PROVIDER_MODEL: ${{ vars.ZENTRA_PROVIDER_MODEL }} ZENTRA_CI_FAIL_THRESHOLD: critical run: zentra ci ``` #### GitLab CI Рабочий процесс GitLab CI включает второе задание для конвейеров push-to-`staging`. Оно выполняет полное сканирование репозитория, никогда не приводит к сбою конвейера и создает или обновляет одну проблему GitLab с метками `security` и `zentra-triage`. Используйте персональный токен доступа с областью `api` в качестве замаскированной переменной CI/CD. Артефакты CI находятся в `.zentra/ci-report.md`, `.zentra/ci-report.json` и `.zentra/ci-report.html`. #### Переменные окружения CI | Переменная | Обязательная | Примечания | |----------|----------|-------| | `ZENTRA_API_KEY` | да | Секрет — ключ API провайдера LLM | | `ZENTRA_PROVIDER_BASE_URL` | да | Секрет или переменная — например, `https://api.anthropic.com` | | `ZENTRA_PROVIDER_MODEL` | да | Переменная — например, `claude-sonnet-5` | | `ZENTRA_PROVIDER_KIND` | нет | По умолчанию `openai_compat` | | `ZENTRA_PROVIDER_REASONING_EFFORT` | нет | Передается OpenAI-совместимым провайдерам | | `ZENTRA_PROVIDER_CONTEXT_WINDOW` | нет | Переопределяет контекстное окно провайдера по умолчанию | | `ZENTRA_CI_FAIL_THRESHOLD` | нет | Минимальная серьезность, блокирующая PR | Если ни `ZENTRA_API_KEY`, ни `ZENTRA_PROVIDER_BASE_URL`, ни `ZENTRA_PROVIDER_MODEL` не установлены, `zentra ci` возвращается к профилю, настроенному с помощью `zentra config setup` в `~/.zentra/config.toml`. ### Генерация CI-рабочих процессов ```bash zentra init --ci github # создать рабочий процесс GitHub Actions zentra init --ci gitlab # создать задание GitLab CI ``` ### Режим пентеста Zentra включает авторизованный динамический режим пентеста для живых веб-целей: ```bash zentra pentest --url https://target.example --authorized \ --allow-host target.example \ --allow-host api.target.example ``` Флаг `--authorized` обязателен, поэтому случайное сканирование завершается с ошибкой. Запускайте этот режим только против систем, которыми вы владеете или на тестирование которых имеете явное разрешение. Используйте `--exclude-path` для исключения путей и `--scope-domain` для разрешения домена и всех его поддоменов. Режим пентеста использует Docker-образ `zentra/pentest-sandbox:0.1.0` для изолированного инструментария. Установите `ZENTRA_SANDBOX_IMAGE` и `ZENTRA_SANDBOX_VERSION` для пользовательских образов. Запуск пентеста использует три агента песочницы (Recon, Exploit, Validator) и генерирует отчеты с базовыми векторами CVSS v3.1. Каталоги вывода: - Внутри инициализированного проекта: `./.zentra/pentest/<host>/<run-id>/` - Снаружи: `<Documents>/Zentra/pentest/<host>/<run-id>/` (или настроенный `output_dir`) ### Другие команды ```bash zentra init # создать .zentra/config.json zentra scan --only sast # запустить одно семейство сканеров zentra ci # безголовое CI-сканирование PR/MR zentra ci --refresh-architecture zentra ci --full --report-only # полное сканирование без блокировки staging-конвейера zentra security verify-audit [session] ``` ## Примечания по безопасности - Zentra хранит учетные данные провайдера за пределами каталога проекта в зашифрованном хранилище секретов. DPAPI защищает ключ шифрования данных в Windows; Unix использует ограничительные права доступа к файлам и доступный бэкенд связки ключей. - Файловые инструменты блокируют обход пути и ограничивают чтение файлов. - Интерактивный чат использует отдельный ограниченный профиль инструментов только для чтения. - Стандартная оболочка безопасности записывает цепочку аудита с защитой от несанкционированного доступа, ограничивает вызовы инструментов и помечает недоверенный вывод инструментов. Установите `ZENTRA_SECURITY=hardened`, чтобы обеспечить привязку ответов и прерывание при инъекциях; используйте `ZENTRA_SECURITY=off` только для доверенной локальной разработки. - Проверьте цепочку аудита с помощью `zentra security verify-audit [session]`. - Инструменты аудита истории Git и зависимостей корректно деградируют, когда требуемые бинарные файлы или история недоступны. ## Структура проекта - `.zentra/config.json` — конфигурация проекта - `.zentra/checkpoint.json` — состояние сканирования для инкрементальных запусков - `.zentra/reports/findings.html` — HTML-отчеты - `.zentra/architecture.md` — вывод анализа фреймворков, используемый как контекст CI Не сохраняйте секреты или состояние сканирования в системе контроля версий.