# Работа с ИИ-агентами

> Как спросить ИИ-ассистента о ScanSuite, поручить ИИ-агенту установить и запустить его и дать агенту навык ScanSuite для сканирования и чтения результатов.

Источник: https://scansuite.ru/documentation/reference/agent-skill
Проверено: 2026-11-19

ИИ-ассистент или ИИ-агент для разработки может работать со ScanSuite тремя способами. Он может отвечать на вопросы о ScanSuite по этой документации; может установить сервер ScanSuite и администрировать его по документации, останавливаясь там, где нужно действие человека; а с навыком ScanSuite — запускать сканирования и читать их результаты.

Подключите ИИ-агента к ScanSuite

Вставьте эту строку в Claude Code, Codex, Copilot, Cursor или другой ИИ-агент для разработки. Он установит навык ScanSuite, подключит его к вашему серверу и остановится на шагах, которые можете сделать только вы.

```
Настрой ScanSuite: загрузи https://scansuite.ru/documentation/agent-setup.md и выполни инструкции
```

[Что сделает агент](https://scansuite.ru/documentation/agent-setup)

| Что вы хотите | Что для этого нужно | Что ему понадобится |
|---|---|---|
| Спросить о ScanSuite | Дайте любому ассистенту ссылку на документацию. | Ничего. |
| Поручить агенту установку и администрирование | ИИ-агент для разработки с доступом к командной оболочке сервера, например Claude Code. | Страницы документации; шаги, отмеченные как шаги человека, делаете вы. |
| Поручить агенту сканирование | ИИ-агент для разработки с навыком ScanSuite. | API-токен команды в файле, который читает агент. |

## Спросить о ScanSuite

Каждая страница документации доступна и в формате Markdown, который ассистенты читают надёжнее, чем HTML:

| Источник | Что в нём | Когда использовать |
|---|---|---|
| https://scansuite.ru/documentation/llms.txt | Оглавление: что такое ScanSuite, типовые задачи со страницей для каждой и все страницы в виде ссылок на Markdown с описанием в одну строку. | Дайте его ассистенту, который умеет загружать страницы: он прочитает только то, что нужно. |
| https://scansuite.ru/documentation/llms-full.txt | Все страницы в одном файле, в порядке бокового меню. | Ассистент не умеет открывать страницы: загрузите или вставьте файл целиком. |
| Адрес любой страницы с .md на конце | Эта страница в Markdown, например https://scansuite.ru/documentation/reference/cicd.md. | Вопрос об одной задаче. |
| «Копировать для ИИ» (вверху каждой страницы) | Копирует Markdown страницы в буфер обмена. | Нужно вставить в чат одну страницу. |

Примеры запросов:

*Запросы*

```
Прочитай https://scansuite.ru/documentation/llms.txt и скажи, может ли ScanSuite просканировать
сервис на Java Spring и его Terraform, что он найдёт и каким частям нужен AI-провайдер.

По https://scansuite.ru/documentation/llms.txt сравни, что ScanSuite запускает в merge request и
что — по ночам, и скажи, сколько длится каждое сканирование и сколько оно стоит в AI.

Прочитай https://scansuite.ru/documentation/installation/technical-requirements.md и скажи, хватит
ли сервера с 8 ядрами CPU, 32 ГБ памяти и 200 ГБ диска для полного набора сканеров.
```

## Поручить агенту установку и администрирование

ИИ-агент для разработки с доступом к командной оболочке целевого сервера (например, Claude Code) может шаг за шагом выполнить инструкции со страниц об установке и администрировании. Дайте ему страницу для задачи, а не свои учётные данные.

| Задача | Какую страницу дать агенту |
|---|---|
| Проверить сервер перед установкой | [Технические требования](https://scansuite.ru/documentation/installation/technical-requirements) |
| Установить на Linux-сервер | [Установка ScanSuite Teams](https://scansuite.ru/documentation/installation/install-scansuite-server) |
| Установить в Google Cloud или Azure | [Установка в Google Cloud](https://scansuite.ru/documentation/installation/install-on-google-cloud), [Установка в Microsoft Azure](https://scansuite.ru/documentation/installation/install-on-azure) |
| Заменить сертификат | [Настройка SSL/TLS](https://scansuite.ru/documentation/installation/ssl-tls-setup) |
| Что-то не работает | [Устранение неполадок](https://scansuite.ru/documentation/installation/troubleshooting) |
| Резервное копирование и восстановление | [Резервное копирование и восстановление](https://scansuite.ru/documentation/administration/backup-and-restore) |
| От чистого сервера до первого отчёта | [Быстрый старт](https://scansuite.ru/documentation/quick-start) |

### Где агент останавливается

В Markdown-версии каждой страницы шаг, который может выполнить только человек, начинается со слов `Этот шаг выполняет человек:`. Всё вокруг такого шага агент делает сам и просит у вас только то, что можете дать лишь вы: где лежит файл, пароль, который вы вводите в ответ на запрос самой программы в терминале, открытом агентом для вас, изменение DNS, вход в систему или одобрение. Он не просит вас переносить файлы или выполнять команды, которые может выполнить сам. Никогда не вставляйте в чат код лицензии, пароль, токен или закрытый ключ: каждый секрет вы вводите там, где указано на странице, — в своём терминале или в консоли ScanSuite. Эти шаги всегда за человеком:

- указать, где лежит файл лицензии, и ввести пароль реестра в ответ на запрос установщика;
- записи DNS и замена сертификата TLS;
- создание первой учётной записи на `https://<YOUR_DOMAIN>/setup` и любой вход в систему;
- выпуск API-токенов и ввод любых секретов;
- одобрение изменений на рабочем сервере, в том числе `terraform apply`;
- подтверждение того, что вы вправе тестировать цель, и разрешение целей для команды.

### Что агент может сделать сам

Большая часть администрирования делается в консоли, где нужен вошедший в систему человек. Вот что агент может сделать без него и что остаётся за человеком:

| Задача | Агент может | Человек делает |
|---|---|---|
| Установка, обновление, проверка | Проверить узел на соответствие требованиям, скопировать файл лицензии на место, запустить установщик в терминале, в котором вы можете печатать, и выполнять ./scansuite update --yes, doctor, status, version и logs. В Google Cloud и Azure: заполнить terraform.tfvars и выполнить terraform plan. | Указать, где лежит файл лицензии, ввести пароль реестра в ответ на запрос установщика, DNS, сертификат, первая учётная запись на /setup, terraform apply. |
| Команды, участники, сервисные аккаунты, токены | Ничего: для этого нужен вошедший в систему человек. | Всё — на странице «Команды» и в «Настройках системы». |
| Настройки команды: разрешённые цели, ИИ, ключ SSH команды, интеграции | Ничего. | Всё — на странице «Команды». |
| Продукты | Создавать и переименовывать через API команды или поручить создание конвейеру (scansuite-ci --create-product). | Удаление продукта. |
| Сканирования: статические, веб, инфраструктура | Запускать, отслеживать, отменять и читать их через scansuite-ci или API команды. | Разрешение целей; подтверждение права их тестировать. |
| Расписания | Расписание в системе CI (расписание конвейера GitLab, cron), которое запускает scansuite-ci. | Расписания на странице «Расписания» в ScanSuite. |
| Разбор уязвимостей | Читать уязвимости и секреты; менять статус, заметки и ответственного у уязвимости токеном с правом «Изменять уязвимости и создавать PoC-эксплойты» (набор «Пользовательский набор»). | Правила подавления, «Подавить по названию», действия с выбранными записями, выгрузки со страницы «Уязвимости». |
| Активы | Читать, добавлять, изменять и удалять через API команды, с правами на активы. | — |
| Резервное копирование и восстановление | ./scansuite backup db, ./scansuite restore db FILE --yes; SCANSUITE_BACKUP_PASSWORD открывает архив, защищённый паролем. | backup secrets и backup db --encrypt один раз выводят пароль: их запускает человек. Хранение архивов вне узла. |

Примеры запросов:

*Установка*

```
Установи ScanSuite Teams на этот сервер по инструкции
https://scansuite.ru/documentation/installation/install-scansuite-server. Сначала проверь
технические требования и покажи, что нашёл. Делай работу сам: спроси меня, где лежит файл
лицензии, и скопируй его на место, а установщик запусти в терминале, в котором я могу печатать,
чтобы мне оставалось только ввести пароль к реестру, когда он его запросит. Никогда не проси
вставить в этот чат код лицензии или пароль.
```

*Продукты*

```
Создай в ScanSuite по продукту на каждый репозиторий из repos.txt через API команды, по инструкции
https://scansuite.ru/documentation/usage/products. SCANSUITE_URL и SCANSUITE_TEAM заданы; токен
прочитай из ~/.scansuite-token и никогда его не выводи. Уже существующие продукты пропусти и
покажи, что создал.
```

*Сканирования*

```
Запусти навыком ScanSuite сканирование AI SAST этого репозитория в продукт shop-api, по инструкции
https://scansuite.ru/documentation/reference/agent-skill. Отключи порог качества, а потом перескажи
уязвимости уровней Critical и High с файлом.
```

*Резервное копирование*

```
Добавь на этом сервере ночную запись cron, которая делает резервную копию баз данных ScanSuite, по
инструкции https://scansuite.ru/documentation/administration/backup-and-restore. Не используй
--encrypt в cron: он выводит пароль архива в журнал. Покажи запись, прежде чем её устанавливать, и
скажи, куда попадают архивы, чтобы я скопировал их с узла.
```

## Поручить агенту сканирование

У ScanSuite есть **навык для ИИ-агентов** — небольшой пакет, с которым ИИ-ассистент для разработки сам запускает сканирования ScanSuite и читает их результаты. Скажите «просканируй этот репозиторий» или «посмотри, что торчит наружу у example.com» — и он подберёт сканирование, запустит его через клиент ScanSuite, дождётся конца и перескажет главное. Формат навыка — открытый `SKILL.md`, его понимают Claude, OpenAI Codex и GitHub Copilot. Лежит он в открытом репозитории [github.com/cepxeo/scansuite-ci](https://github.com/cepxeo/scansuite-ci).

Навык запускает статический анализ кода (AI SAST, классический SAST, секреты, зависимости, IaC), динамическое сканирование веб-приложений и сканирование инфраструктуры (обнаружение узлов и портов, OSINT и поддомены, Nuclei, OpenVAS или Nessus, если они настроены, CVE в образах контейнеров); выстраивает их в цепочку, например OSINT по домену, а затем сканирование портов на найденных узлах; и читает уязвимости, секреты, журналы и отчёты. С подходящим токеном он ещё и разбирает уязвимости.

*Запрос*

```
Установи навык ScanSuite из github.com/cepxeo/scansuite-ci по инструкции
https://scansuite.ru/documentation/reference/agent-skill, запусти его предварительную проверку
(preflight), затем просканируй этот репозиторий и перескажи главное. Останавливайся на каждом шаге
с пометкой «Этот шаг выполняет человек»; никогда не спрашивай у меня токен — он лежит в
~/.scansuite-token.
```

### Что нужно заранее

| Что нужно | Как проверить |
|---|---|
| Команда на сервере ScanSuite Teams и роль «Администратор команды», чтобы выпустить токен | На странице «Команды» написано: «Ваша роль в этой команде: Администратор команды». |
| bash, curl и python3 на машине, где работает агент | bash --version; curl --version; python3 --version |
| Docker или Python-клиент | docker --version. Без Docker навык скачивает клиент, который раздаёт ваш сервер, и сверяет его контрольную сумму, или использует файл, указанный в SCANSUITE_CLIENT. |
| Для DAST и сканирования инфраструктуры: цели, разрешённые команде | Страница «Команды», вкладка «Сканирование», «Проверить, разрешены ли цели». |
| Для AI-сканирований: AI-провайдер команды | Предварительная проверка ниже не отмечает mlsast как NOT AVAILABLE. |

В Windows запускайте агента в WSL или Git Bash; в Git Bash задайте `MSYS_NO_PATHCONV=1`, чтобы пути для Docker передавались без изменений.

### Дайте ему токен

1. **Заведите сервисный аккаунт**

   Страница «Команды», вкладка «Люди», карточка «Автоматизация и API-токены»: в поле «Новый сервисный аккаунт» укажите имя, например agent, в поле «Роль» выберите «Оператор» и нажмите «Создать».
2. **Выпустите токен**

   Нажмите «Новый токен» у этого аккаунта. Набор «Конвейер CI» позволяет агенту запускать сканирования и читать результаты. Чтобы он мог разбирать уязвимости и видеть узлы и порты, выберите «Пользовательский набор» и отметьте права набора «Конвейер CI», а также «Изменять уязвимости и создавать PoC-эксплойты» и «Видеть активы». Нажмите «Создать токен» и запомните имя команды, которое показывает окно.

> **Этот шаг выполняет человек:** Сохраните токен в файл, доступный только вам. Выполните эту команду в своём терминале, вставьте токен, когда она будет ждать ввода, и нажмите Enter; токен не отображается и не попадает в историю командной оболочки:
>
> ```
> umask 077; read -rs SST && printf '%s' "$SST" > ~/.scansuite-token; unset SST
> ```
>
> Навык читает токен из этого файла и никогда не выводит его в чат или в командную строку, которую показывает. Не вставляйте токен в переписку.

| Переменная, которую читает навык | По умолчанию | Что это |
|---|---|---|
| SCANSUITE_URL | — | Адрес вашего ScanSuite, например https://scansuite.example.com. |
| SCANSUITE_TEAM | — | Имя команды, которое показывают карточка «Автоматизация и API-токены» и окно нового токена. |
| SCANSUITE_TOKEN_FILE | ~/.scansuite-token | Другой файл с токеном. |
| SCANSUITE_CLIENT | образ Docker appsec4u/scansuite-ci:1 | Путь к scansuite-ci.py, чтобы запускать клиент без Docker. |

Назовите агенту `SCANSUITE_URL` и `SCANSUITE_TEAM` или ответьте, когда он спросит.

> **Внимание:** Токен — это учётные данные: любой, кто может прочитать ~/.scansuite-token, может сканировать от имени этого сервисного аккаунта. Когда агенту токен больше не нужен, отзовите его на странице «Команды».

### Установка в вашем ассистенте

Навык — это папка с файлом `SKILL.md`. Каждый инструмент ищет её в своём месте, поэтому вся установка — положить папку туда, где инструмент её найдёт. В репозитории навык лежит в `plugins/scansuite/skills/scansuite/` — копируйте именно эту папку.

#### Claude Code

Этот репозиторий — ещё и маркетплейс плагинов Claude Code, так что можно обойтись без копирования файлов. В сессии Claude Code:

```text
/plugin marketplace add cepxeo/scansuite-ci
/plugin install scansuite@scansuite-ci
```

Или скопируйте папку в каталог навыков: `~/.claude/skills/` — для всех проектов, `.claude/skills/` — внутри одного репозитория:

```bash
git clone https://github.com/cepxeo/scansuite-ci
cp -r scansuite-ci/plugins/scansuite/skills/scansuite ~/.claude/skills/scansuite
```

#### Claude (claude.ai и приложение)

Откройте **Settings → Customize → Skills** и загрузите навык в виде `.zip`, в котором лежит папка `scansuite/` (то есть внутри архива — `scansuite/SKILL.md`). Навык привяжется к аккаунту и будет синхронизироваться между claude.ai, приложением и Claude Code. Для сканирований нужна командная оболочка, поэтому запускайте их из Claude Code или из приложения с терминалом.

#### OpenAI Codex

Codex ищет навыки в `.agents/skills/` внутри проекта и в `~/.agents/skills/` — для личных. Скопируйте папку туда и вызывайте навык как `$scansuite` (см. [руководство по навыкам Codex](https://developers.openai.com/codex/skills)):

```bash
cp -r scansuite-ci/plugins/scansuite/skills/scansuite ~/.agents/skills/scansuite
```

#### GitHub Copilot

Copilot ищет навыки в `.github/skills/` репозитория (а также в `.claude/skills/` и `.agents/skills/`) и в `~/.copilot/skills/` — для личных. Скопируйте папку туда и включите навык командой `/skills` в сессии Copilot CLI (см. [документацию по навыкам Copilot](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)):

```bash
cp -r scansuite-ci/plugins/scansuite/skills/scansuite .github/skills/scansuite
```

> **Примечание:** Codex и Copilot оба читают .agents/skills/, так что одной копии там хватит на двоих. Поддержку и точные пути задают сами инструменты — сверяйтесь с их документацией для вашей версии.

### Проверьте, что всё работает

Попросите агента запустить предварительную проверку навыка (`scripts/preflight.sh` в папке навыка). Она выводит:

- версии клиента и сервера;
- роль токена, его права и дату окончания срока действия;
- все сканеры, которые предлагает сервер; те, что ваша команда запустить не может, отмечены `NOT AVAILABLE` с причиной (например, сканер, интеграция которого не настроена, или AI-сканеры, когда у команды нет AI-провайдера).

Если токен отклонён, выводится причина (истёк, отозван, другая команда, неизвестен); как это исправить, сказано в разделе [CI/CD и автоматизация](https://scansuite.ru/documentation/reference/cicd#test-token).

### Как пользоваться

Говорите обычными словами — агент сам подберёт и запустит сканирование. Например:

| Вы говорите | Что запускается |
|---|---|
| «Просканируй этот репозиторий на эксплуатируемые уязвимости и скажи, что из них достижимо.» | AI SAST рабочего каталога, уязвимости по уровням критичности. |
| «Сделай OSINT по example.com, а потом просканируй все TCP-порты найденных хостов, без ping.» | OSINT, затем обнаружение узлов по адресам, которые разрешаются в DNS и принадлежат вам. |
| «Просканируй образ registry.example.com/app:1.4 на CVE.» | Сканирование образа контейнера. |
| «Проверь staging.example.com на веб-уязвимости за нашей авторизацией.» | DAST с заголовком авторизации. |
| «Покажи критичные уязвимости из последнего сканирования продукта payments.» | Читает результаты через API команды. |
| «Отметь уязвимость 506 как ложное срабатывание: это тестовые данные.» | Разбор через API команды. Нужен токен с правом «Изменять уязвимости и создавать PoC-эксплойты». |

Прежде чем что-то запустить, навык:

- спрашивает разрешения перед агрессивными или дорогими сканерами: Bruteforcer (`hosts_bruter`), «Глубокое сканирование» (`zap_full`) и наборы с AI, прежде всего `full-ai`;
- сканирует только цели, которые вы назвали и которые вам принадлежат: имена, найденные OSINT, проверяются в DNS, а похожие домены и чужие адреса отбрасываются;
- проверяет, что политика целей команды разрешает каждую цель (на запрещённой цели клиент завершается с кодом 3) и что сканер есть на вашем сервере;
- достаёт результаты низкого уровня из архива отчёта, если они не сохранены как уязвимости.

По каждому сканированию он выдаёт короткую сводку, а не сырой вывод. Типы сканирований, ключи и коды выхода, которыми он пользуется, описаны в разделе [CI/CD и автоматизация](https://scansuite.ru/documentation/reference/cicd); вызовы API команды, которые он делает, с правом, нужным для каждого, — в [справочнике по API](https://github.com/cepxeo/scansuite-ci/blob/main/plugins/scansuite/skills/scansuite/references/api.md) навыка.
