Документация

Безопасность коннектора

Что делает коннектор CoRoid на вашем устройстве и чего не делает, какие запросы он отправляет, на что он рассчитан и как проверить, что релиз соответствует исходному коду из открытого репозитория.

Коннектор CoRoid — это программа, которая позволяет агентам по разработке на вашем собственном устройстве выполнять работу для CoRoid (см. Агенты по разработке на вашем собственном устройстве). Он является открытым программным обеспечением под лицензией Apache-2.0, а весь его исходный код находится по адресу github.com/COROID-AI/coroid-connector. Эта страница предназначена для тех, кто принимает решение о возможности его запуска на устройствах вашей организации.

Как передаются данные

Ваше устройство

Коннектор CoRoid

Открытый исходный код. Запускает агента на один цикл в новой пустой директории и останавливает его после завершения.

Ваш агент по написанию кода

Агент, который вы используете, авторизован как вы, при этом его собственные инструменты отключены.

  1. 1Запрашивает задание. Каждый запрос обрабатывается до 25 секунд; соединитель передаёт информацию от агента каждые 3 секунды.
  2. 2Вызывает инструменты данной роли. Токен действует только для этого цикла и перестаёт работать после его завершения.
  3. 3Запрашивает своя модель. Как и в случае без использования CoRoid. CoRoid никогда не видит эту авторизацию.

CoRoid

Оркестратор

Распределяет задачи роли на устройство человека, инициировавшего задачу (1).

Инструменты данной роли

Работают в песочнице задачи, где хранится ваш код (2).

Провайдер агента

Отвечает на запросы модели агента под вашей собственной авторизацией, в рамках вашего тарифа (3).

Ничто не проникает на устройство: соединитель не открывает портов, не отправляет файлов и не выполняет собственных команд.

На устройстве остаётся ваша авторизация в системе агента и данные, сохранённые агентом в рамках одного цикла.

Каждое соединение начинается на устройстве и идёт через HTTPS. Репозиторий остаётся в песочнице задачи в CoRoid; агент работает с ним только через инструменты, предоставленные ролью.
  • Только исходящие запросы. Коннектор не открывает никаких портов, кроме как на короткое время при 127.0.0.1 в процессе входа в систему. Он запрашивает работу у CoRoid через протокол HTTPS. Каждый запрос обрабатывается до 25 секунд, после чего запрос повторяется — именно так CoRoid определяет, что устройство подключено.
  • Ваш код остается в CoRoid. Репозиторий никогда не копируется на устройство. Инструменты роли (чтение файла, запуск тестов, изменение кода) выполняются в песочнице задачи внутри CoRoid. На устройство поступают только инструкции роли и результаты работы этих инструментов, например содержимое прочитанного файла или вывод тестов.
  • Запросы модели агента отправляются его провайдеру, под вашими учетными данными и в рамках вашего тарифа, как это происходило бы и без CoRoid. Данные, отправляемые агентом модели, включают результаты работы инструментов роли, поэтому они покрываются вашим соглашением с этим провайдером.
  • Работа передается только тому, кто ее инициировал. Роль выполняется на устройстве только если в ее назначении указан агент, у человека, инициировавшего задачу, есть подключенное устройство в этой организации, а политика организации разрешает использование этого агента. Работа, инициированная автоматически, например автоматизация, выполняется на модели.

Что делает коннектор

  • Выполняет вход в систему с использованием протоколов OAuth 2.1 и PKCE в вашем браузере, для одной области доступа (connector.turns). Срок действия токена доступа — 15 минут; токена обновления — 30 дней, и он заменяется при каждом использовании. Отключение в разделе Ваши компьютеры отзывает оба токена.
  • Хранит эти токены в ключнице macOS или в сервисе хранения секретов Linux-десктопа, передавая их этим инструментам через стандартный ввод, но никогда не через командную строку. Только в случае отсутствия таких средств они сохраняются в файле, доступном только вам. coroid-connector status указывает, где они находятся.
  • Сообщает CoRoid, в первом же запросе, имя устройства, его операционную систему, собственную версию, а также версии, состояние и доступные модели каждого агента.
  • Запускает один цикл: запускает агента в новой пустой директории с отключенными собственными инструментами агента, предоставляет ему один набор инструментов (инструменты роли для этого цикла), передает полученные от него данные, отклоняет любые запросы на разрешение, не относящиеся к этим инструментам, и останавливает его. Затем директория удаляется.

Чего он не делает

  • Не читает и не отправляет ваши файлы, не выполняет собственные команды. Единственный файл, который он читает, помимо собственных — настройки Cursor, для двух параметров, определяющих возможность использования Cursor (см. раздел «Ограничения»); ничто из них не покидает устройство.
  • Не позволяет агенту использовать свою оболочку, редактирование файлов, поиск в интернете или собственные серверы и коннекторы MCP. Каждый агент запускается с соответствующим ему параметром, проверенным на версиях агента; агент другой версии будет указан в списке и не будет использоваться.
  • Не открывает порты, доступные для других, и не принимает инструкции от кого-либо, кроме CoRoid, через открытое им соединение.
  • Не загружает ничего во время выполнения. coroid-connector add устанавливает адаптер агента один раз, строго из пакетов, указанных в файле блокировки релиза (каждый привязан к версии и хешу SHA-512), с отключенными скриптами установки.

Запросы, которые он отправляет

КудаКогдаЗачем
CoRoid's API (https://api.coroid.ai)Вход в систему и выход из нееРегистрация коннектора, обмен, обновление и отзыв его токенов (/oauth/…)
CoRoid's APIВ процессе работыЗапрос работы (/connector/v1/poll) и отчет о цикле (/connector/v1/turns/…/events)
Регистр npmТолько во время coroid-connector addПакеты адаптера соответствуют именам из файла блокировки релиза

Агент, а не коннектор, вызывает инструменты роли (адрес под /connector/v1/turns/, с токеном этого цикла) и своего провайдера.

На что он рассчитан

ЕслиТогда
Кто-то другой пытается подключить устройство от вашего имениПодтверждение происходит в вашем браузере, при входе в систему под вашими учетными данными, а вход завершается только на устройстве, которое инициировало процесс (по адресу 127.0.0.1, с использованием протокола PKCE). Утверждайте только тот коннектор, который вы запустили мгновение назад.
Токены коннектора были украдены.Они ограничены одной областью доступа: запрос данных о работе этого пользователя и формирование отчетов по ней. Срок действия токена доступа истекает через 15 минут, а команда «Отключить» аннулирует оба токена.
Токен для текущего сеанса используется повторно.Он работает только в рамках этого сеанса и перестает функционировать после его завершения.
В рамках сеанса агент запрашивает что-то другое.Собственные инструменты агента отключены, и коннектор отклоняет другие запросы на разрешение. Инструменты роли совпадают с инструментами облачной модели, включая те же процедуры контроля качества, рецензирования, проверки и ограничения по количеству шагов.
Релиз не соответствует описанию его исходного кода.Каждый выпуск собирается с помощью GitHub Actions из коммита с тегом в публичном репозитории, проходит аттестацию и публикуется в npm с данными в поле «происхождение». Формула Homebrew принимает новую версию только после проверки аттестации. Вы можете проверить её самостоятельно (ниже).

Ограничения

  • Агент запускается от вашего имени с правами вашего пользователя на машине. Возможность использования инструментов CoRoid зависит от отдельного переключателя каждого агента, поэтому коннектор применяет агент только к тем версиям, на которых он был протестирован.
  • Что именно агент сохраняет в своем хранилище для текущего сеанса, зависит от самого агента (см. Что остается на вашей машине). Политика вашей организации определяет, какие агенты могут использоваться ее сотрудниками (см. Что разрешено вашей организацией).
  • Cursor запрашивает разрешение перед выполнением операций веб-загрузки, веб-поиска и работы с браузером только в стандартных настройках. Коннектор считывает два параметра на машине (режим утверждения и возможность автоматического принятия веб-поисковых запросов) и не использует Cursor, если эти параметры позволяют запускать указанные инструменты без запроса.
  • Коннектор не был протестирован на платформе Windows.

Проверить релиз

Каждый релиз в GitHub содержит опубликованный пакет, файл коннектора, спецификацию CycloneDX и SHA256SUMS. Замените <version> на тот релиз, который вы проверяете.

Подпись реестра пакета npm и данные с меткой «происхождение»:

mkdir check && cd check && npm init -y
npm install @coroid/connector@<version>
npm audit signatures

Аттестация, указывающая коммит и рабочий процесс, создавший файл:

gh release download v<version> --repo COROID-AI/coroid-connector
gh attestation verify coroid-connector-<version>.tgz --repo COROID-AI/coroid-connector \
  --signer-workflow COROID-AI/coroid-connector/.github/workflows/release.yml

Файл, собранный вами из исходного кода с тегом:

git clone https://github.com/COROID-AI/coroid-connector && cd coroid-connector
git checkout v<version> && npm ci && npm run build
shasum -a 256 dist/coroid-connector.mjs   # the same as its line in SHA256SUMS

Для сообщения о уязвимости используйте политику безопасности репозитория (GitHub's private vulnerability reporting).