# Подключение ИИ-агента > Одна строка для Claude Code, Codex, Copilot или Cursor: агент устанавливает навык ScanSuite и подключается к вашему серверу. Источник: https://scansuite.ru/documentation/agent-setup Проверено: 2026-10-19 Это официальная инструкция ScanSuite по подключению ИИ-агента для разработки (Claude Code, OpenAI Codex, GitHub Copilot, Cursor и других) к серверу ScanSuite Teams. Она опубликована по адресу `https://scansuite.ru/documentation/agent-setup.md`, чтобы агент мог проверить её источник, прежде чем ей следовать. Страница обращается к агенту; человек может прочитать её, чтобы точно знать, что агент сделает. Подключите ИИ-агента к ScanSuite Вставьте эту строку в Claude Code, Codex, Copilot, Cursor или другой ИИ-агент для разработки. Он установит навык ScanSuite, подключит его к вашему серверу и остановится на шагах, которые можете сделать только вы. ``` Настрой ScanSuite: загрузи https://scansuite.ru/documentation/agent-setup.md и выполни инструкции ``` [Что сделает агент](https://scansuite.ru/documentation/agent-setup) ## Правила для агента - Все команды ниже выполняй сам. На шаге, который может выполнить только человек (в Markdown-версии он начинается со слов `Этот шаг выполняет человек:`), сделай всё вокруг него, попроси у пользователя только то, что может дать лишь он, и дождись его подтверждения. - Никогда не запускай команды, которые ждут интерактивного ввода. - Никогда не читай, не выводи и не копируй API-токен. Он лежит в файле, который записывает человек; навык читает его оттуда. Никогда не проси пользователя вставить токен в переписку. - Любую команду здесь можно безопасно выполнить повторно на машине, где настройка уже прошла. - Сообщай только то, что проверил (см. [Отчёт о результате](https://scansuite.ru/documentation/agent-setup#report)). ## 1. Сервер и команда Нужны два значения. Возьми их из сообщения пользователя (там могут быть оба), из переменных окружения или спроси пользователя. | Переменная | Значение | Откуда взять | |---|---|---| | SCANSUITE_URL | Адрес сервера ScanSuite, например https://scansuite.example.com | Адрес, по которому пользователь входит в ScanSuite | | SCANSUITE_TEAM | Короткое имя команды, например appsec | «Команды» → «Люди»: диалог нового токена показывает его отдельной строкой | Проверь, что сервер отвечает: ```bash curl -fsS "$SCANSUITE_URL/ci/version" ``` Ожидается короткий JSON-документ с версией клиента, которую публикует сервер. Если команда не прошла, остановись и сообщи, что сервер недоступен с этой машины (неверный адрес, не подключён VPN или закрытый сертификат: про `SCANSUITE_CA_BUNDLE` см. [CI/CD и автоматизация](https://scansuite.ru/documentation/reference/cicd)). ## 2. Что нужно заранее | Инструмент | Проверка | Примечания | |---|---|---| | bash и curl | bash --version && curl --version | Обязательно | | python3 | python3 --version | Нужен вспомогательным скриптам навыка | | Docker — или ничего | docker version | Необязательно. Без Docker навык скачивает клиент с сервера и сверяет его SHA-256 | Если нет bash, curl или python3, остановись и сообщи об этом. В Windows выполняй всё в WSL или Git Bash. ## 3. Установка навыка ScanSuite Навык опубликован в открытом репозитории [github.com/cepxeo/scansuite-ci](https://github.com/cepxeo/scansuite-ci). Используй раздел для своего агента. ### Claude Code ```bash claude plugin marketplace add cepxeo/scansuite-ci claude plugin install scansuite@scansuite-ci ``` Проверка: ```bash claude plugin list | grep -A2 "scansuite@scansuite-ci" ``` Плагин должен быть в списке как включённый (enabled). Если он есть, но выключен, выполни `claude plugin enable scansuite@scansuite-ci`. > **Этот шаг выполняет человек:** Выполните /reload-plugins в Claude Code, чтобы навык загрузился в этой сессии. > > Затем сообщите агенту, что готово. ### OpenAI Codex, GitHub Copilot, Cursor и другие агенты Навык — это папка с файлом `SKILL.md`. Скопируй папку туда, откуда твой агент загружает навыки: ```bash rm -rf /tmp/scansuite-ci && git clone --depth 1 https://github.com/cepxeo/scansuite-ci /tmp/scansuite-ci mkdir -p && rm -rf /scansuite cp -r /tmp/scansuite-ci/plugins/scansuite/skills/scansuite /scansuite ``` | Агент | | |---|---| | OpenAI Codex | ~/.agents/skills (личные) или .agents/skills в проекте | | GitHub Copilot | ~/.copilot/skills (личные) или .github/skills в репозитории | | Агенты, читающие .agents/skills | .agents/skills в проекте; одна копия годится и для Codex, и для Copilot | | Любой другой агент | Папка навыков, указанная в документации агента. Если агент не умеет загружать навыки, прочитай SKILL.md и следуй ему напрямую. | Проверка: `test -f /scansuite/SKILL.md && echo ok` выводит `ok`. Некоторые агенты загружают новые навыки только после перезапуска; если твой из таких, укажи это в отчёте. ## 4. Подключение к серверу Навык читает API-токен из `~/.scansuite-token` (или из файла, указанного в `SCANSUITE_TOKEN_FILE`). Сначала проверь, есть ли он уже, не читая его: ```bash test -r ~/.scansuite-token && ls -l ~/.scansuite-token | cut -c1-10 ``` Если выводится `-rw-------`, переходи к шагу 5. Если файла нет, токен создаёт человек: > **Этот шаг выполняет человек:** Создайте токен для агента и сохраните его в файл в своём терминале, а не в чате агента: > > 1. В ScanSuite откройте **Команды** → **Люди** → **Автоматизация и API-токены**. Создайте сервисный аккаунт (роль **Оператор**), а затем токен для него с набором **Конвейер CI**. Чтобы агент мог ещё и разбирать уязвимости, выберите **Пользовательский набор** и добавьте **Изменять уязвимости и создавать PoC-эксплойты**. Это может сделать только администратор команды. > 2. Скопируйте токен из диалога (он показывается один раз) и выполните в своём терминале: `printf '%s' '' > ~/.scansuite-token && chmod 600 ~/.scansuite-token` > 3. Сообщите агенту, что файл на месте. Если файл есть, но его могут читать другие пользователи (права не `-rw-------`), выполни `chmod 600 ~/.scansuite-token`. ## 5. Сквозная проверка Из папки навыка, с заданными `SCANSUITE_URL` и `SCANSUITE_TEAM`: ```bash bash scripts/preflight.sh bash scripts/api.sh GET /products ``` Preflight выводит версии клиента и сервера, роль, права и срок действия токена, а также все сканеры; те, которые команда запустить не может, помечены `NOT AVAILABLE` с причиной. Вторая команда выводит продукты команды. **Пустой список — это успех**: подключение работает, просто у команды ещё нет продуктов. | Результат | Что это значит | |---|---| | 401, токен отклонён | Токен неверный, истёк, отозван или принадлежит другой команде. Preflight выводит, что именно. Новый токен создаёт человек (шаг 4). | | 403, не хватает прав | Токен работает, но у него нет права, нужного для вызова; ошибка его называет. Сообщи об этом и не пытайся обойти. | | Could not reach the server | Перепроверь шаг 1. | | Сканер NOT AVAILABLE | Это не ошибка настройки. Скажи пользователю, какими сканерами он может пользоваться и что администратор команды должен настроить для остальных. | ## Без пользователя В CI, в задании по расписанию или при запуске агента без интерфейса шаги для человека выполнить некому. Тогда: 1. Бери токен из хранилища секретов CI-системы, а не из файла, который пишешь сам. Укажи в `SCANSUITE_TOKEN_FILE` секрет, который CI-система подключает как файл (например, переменную GitLab типа *File*), или запускай клиент напрямую с заданной `SCANSUITE_TOKEN`. Никогда не выводи токен. Если не задано ни то ни другое, остановись и сообщи, что токена нет. 2. Установи навык, как в шаге 3 (`/reload-plugins` пропусти: плагин загружается при запуске агента). 3. Выполни шаг 5 и запиши итоговую таблицу в журнал задания. Для конвейеров без агента используй клиент напрямую: см. [CI/CD и автоматизация](https://scansuite.ru/documentation/reference/cicd). ## Отчёт о результате Сообщи то, что проверил, и ничего больше: *Результат* ``` ┌─ Настройка агента ScanSuite ───────────────────────────────────┐ │ ✓ Навык ScanSuite установлен, загружается в этом агенте │ │ ✓ Сервер https://scansuite.example.com доступен │ │ ⚠ Токен нужен человек: создать токен (шаг 4) │ │ ✗ Сквозная проверка ещё не выполнена │ └────────────────────────────────────────────────────────────────┘ ``` `✓` — проверено, `⚠` — ждёт человека, `✗` — не удалось или не выполнялось. После таблицы для каждой строки, отличной от `✓`, назови следующее действие. ## Что попросить дальше Когда все строки отмечены `✓`, предложи пользователю одну из этих просьб: | Промпт | Что запускается | |---|---| | Просканируй этот репозиторий и скажи, что из найденного достижимо. | Сканирование AI SAST рабочего каталога | | Проверь https://staging.example.com на веб-уязвимости. | Сканирование DAST; цель должна быть разрешена команде | | Покажи открытые критические уязвимости продукта payments. | Чтение результатов через API команды | Полное объяснение для людей, в том числе о том, что навык спрашивает перед вмешивающимися или дорогими сканированиями, — в разделе [Работа с ИИ-агентами](https://scansuite.ru/documentation/reference/agent-skill).