DeepSeek Harness: песочница и одобрение — как сделать опасные действия агента контролируемыми

В предыдущей главе рассматривался конвейер выполнения инструментов; два этапа вызывают наибольшее беспокойство: как песочница ограничивает команды и как одобрение решает «можно ли это выполнить».

В этом разделе мы подробно разберёмctx.sandboxиctx.approval—эти два сервиса, проясним их соответствующие обязанности и принципы fail-closed.

Одним предложением: песочница управляет тем, «в каких границах выполняется команда», а одобрение управляет тем, «разрешена ли эта конкретная операция»; оба по умолчанию работают по принципу fail-closed.


Сначала общая картина: решение песочницы + поток одобрения

На диаграмме ниже оба сервиса показаны рядом: слева показано, как песочница оборачивает argv, а справа — как одобрение принимает одноразовое решение.

沙箱决策与审批流程图

Вместе они отвечают на один и тот же вопрос: когда Агент хочет совершить что-то рискованное, как его ограничивают?

Песочница ограничивает, «какие файлы процесс может трогать», а одобрение передаёт решение «разрешать ли эту операцию» на усмотрение отвечающего.


ctx.sandbox: оборачивать argv в соответствии с политикой

Модель песочницы процесса такова: потребитель передаётточный argv, а бэкенд оборачивает его в соответствии с политикой файловых эффектов.

Ключевой момент — именно «точный argv», а не shell-строка; потребитель в виде shell должен передать['bash', '-c', command]。

ctx.sandbox.confine(argv, policy)возвращаетConfinedArgv, т. е. «подставленный argv плюс факты применения ограничений бэкенда».

SandboxMode(режим песочницы) управляет только эффектами файловой системы; он не распространяется на сеть или видимость процессов.

read-only: разрешает только необходимые получатели данных (например,/dev/null), запрещает запись.

workspace-write: также разрешает запись в корневом каталоге рабочей области и во временной области, обещанной бэкендом.

danger-full-access: обходит изоляцию, при этом потребитель напрямую запускает необработанный argv, не вызывая ctx.sandbox.

Провайдеру отправляются только первые два режима,danger-full-accessОн вообще не входит в песочницу.

Это гарантирует свойство безопасности: ограниченное выполнение обязательно достигаетctx.sandbox, а незаметный неизолированный сквозной проход никогда не является допустимым.


Уровень применения ограничений и правила отката

Бэкенд сообщает фактическую полноту применения ограничений, которой он достиг:enforcement: 'full' | 'partial'。

fullозначает, что бэкенд управлял всеми файловыми эффектами, обещанными этим режимом;partialуказывая, что контролируется только подмножество.

Текущие случаи частичного применения включают старые ABI Landlock, а также границы Everyone и жёстких ссылок в Windows ACL runner.

Потребители, требующие абсолютных границ, должны поместитьpartialСчитайте это "недостаточным" — отклоните это или передайте это различие наверх.

Разрешение политик имеет чётко определённый порядок отката; официальная документация представляет его в виде трёх уровней:

ПриоритетSourceОписание
НаивысшаяУтверждённый явный режимТот, который был передан при однократной повторной попытке повышения привилегийmode, перевешивая политики сеанса
Во-вторыхПоследний сеансsandbox/modeEventsСохраняется вместе с журналами сеанса и может быть воспроизведён для реконструкции
Резервный вариантРежим развертывания по умолчаниюВызовы без агента и сессии без cwd используют настроенный корневой каталог

Обычные вызовы инструментов происходят из неизменяемого cwd вызывающей сессииworkspaceRoot。

root сначала нормализуется по семантике файловой системы, затем по лексическим правилам, поэтому включаетsymlink/..cwd указывает каталог, в котором фактически выполняется процесс.

Безопасный отказ: когда нет доступного бэкенда,ctx.sandbox.confineвыброситSandboxUnavailableError, код ошибкиSANDBOX_UNAVAILABLE。

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


Практический пример: запуск bash в ограниченном режиме

Давайте настроим путь вызова для "изолированного bash" в коде.

Пример

// Путь к файлу: my-plugins/sandbox-demo/src/index.ts
// Демонстрация потребителя в песочнице: сначала разобрать политику, затем позволить ctx.sandbox обернуть argv.
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'sandbox-demo'
export const inject = ['tools', 'sandbox', 'sandboxPolicy']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'sandboxed_echo',
    description: 'Запустить echo внутри песочницы. Пример демонстрационной команды.',
    parameters: {
      text: { type: 'string', required: true, description: 'Текст для вывода с помощью echo' },
    },
    output: { schema: { type: 'string' } },
    async execute(args, exec) {
      // 1. Разобрать полную политику для этого вызова: cwd сессии — граница рабочего пространства.
      const policy = ctx.sandboxPolicy.resolve({ session: exec.agent?.session })

      // 2. Потребитель передаёт точный argv (программу плюс аргументы), а не строку оболочки.
      const argv = ['bash', '-c', `echo ${JSON.stringify(args.text)}`]

      // 3. danger-full-access запускается напрямую; остальные оборачиваются песочницей.
      if (policy.mode === 'danger-full-access') {
        const { spawn } = await import('node:child_process')
        // ... spawn(argv) и собрать вывод
        return `echo ${args.text}` // Демо: обычный возврат
      }

      // 4. Ограниченный режим: confine возвращает заменённый argv и выбрасывает SANDBOX_UNAVAILABLE, если нет бэкенда.
      const confined = ctx.sandbox.confine(argv, { mode: policy.mode, workspaceRoot: policy.workspaceRoot })

      // 5. устранить费方再 spawn confined.argv, и нажмите confined.enforcement определить, выполнено ли требование полностью。
      if (confined.enforcement === 'partial' && policy.mode !== 'read-only') {
        return { isError: true, error: { message: 'частичное принуждение недопустимо для демонстрационного примера' } }
      }
      return `confined echo ${args.text} (enforcement: ${confined.enforcement})`
    },
  }))
}

Примечание: приведённый выше код — демонстрационная эталонная реализация; в ней опущены детали spawn и сбора вывода.

Потребители промышленного уровняdsh-bash-sandbox, которые также отвечают за spawn и атрибуцию результатов.

Настоящая сложность заключается в классификации результатов: различение "отказа исполнителя песочницы" и "нормальной работы песочницы, но с отклонением".

Песочница также возвращает два ортогональных классификатора stderr:

denialSignatures: определять случаи, когда песочница работает нормально, а ограниченные команды блокируются (текст EROFS от bwrap, EACCES от Landlock, EPERM от Seatbelt).

runnerFailureRules: определяет случаи, когда runner отклоняет или завершается с ошибкой до выполнения команды (сбой Landlock требует код выхода 125 плюс фатальную диагностическую строку).

Потребители должны сначала сообщать о сбоях runner как о сбоях инфраструктуры песочницы, а не как об обычных сбоях задачи.


ctx.approval: одноразовое решение о разрешении

Служба одобрения отвечает на очень узкий вопрос:Может ли эта конкретная операция продолжиться?

Он пропускаетсяapproval/requestwaterfall распределяет вопросы респонденту.

Респондент возвращает результат при обработке запроса, иначе вызываетnext()Делегирование; первый респондент занимает единственный слот для принятия решения.

Тип результатаApprovalOutcomeзакрыт:

РезультатЗначениеПоведение вызывающего
allowed-onceОдноразовый пропускЕдинственный результат разрешения, авторизующий только одну запрошенную операцию
rejectedЯвно отклонитьОтклонить
cancelledЗапрос отозван (например, сигнал прерывания)Отклонить
unavailableНет ответчика, ответчик выбрасывает исключение, или возвращаемое значение не соответствует требованиямБезопасный отказ, отклонять всё

Ключевое свойство безопасности: отсутствующий ответчик, тот, который не обрабатывает запрос, выбрасывает исключение или не соответствует требованиям, — все они порождаютunavailable, а не разрешают это.

Для вызывающегоrejected、cancelledиunavailableВсегда применять отказ.


Политики одобрения для сеанса: ask и never

ApprovalPolicyОпределяет, что происходит перед запуском интерактивного ответчика.

ПолитикаПоведениеТипичные сценарии
ask(По умолчанию)Делегировать составной цепочке респондеров; если респондер отсутствует, откатиться кunavailableИнтерактивный UI, требующий принятия решений человеком
neverДетерминированный возвратrejected, не диспетчеризует никакие респондерыCI, строгий headless-режим для запусков без участия человека

Действующее значение — последняя запись в журнале сессииapproval/policyсобытие, с откатом к конфигурации сервиса.

setApprovalPolicy(session, policy)является единственным путём записи, поэтому повторное воспроизведение может восстановить значения переопределений.

neverпринудительно применяется внутри сервиса, до waterfall-диспетчеризации, так что даже если позже использоватьprependЗарегистрированные респондеры тоже не могут его обойти.

Разница между видимостью аудита и видимостью модели: пара событий аудита одобрения (approval/askedиapproval/decided) только записывают логи; они не попадают в транскрипт модели.

Видимое модели поведение — это результаты инструментов, полученные вызывающей стороной, и снимок текущего контекста выполнения.


Пресеты разрешений: два параметра, объединённые в именованные пресеты

Режим песочницы (sandbox/mode) и политики одобрения (approval/policy) — это два взаимно независимых параметра.

Слой пресетов разрешенийctx.permissionPresetsОбъедините их в именованные пресеты, чтобы клиенты могли представить их как единый селектор "permission".

ПресетРежим песочницыПолитики подтвержденияЗначение
workspace-writeworkspace-writeaskРабочее пространство с возможностью записи, запрашивать у пользователя подтверждение для чувствительных операций
danger-full-accessdanger-full-accessneverОбход песочницы, без запросов; можно запускать только в одноразовой среде

Таблица пресетов управляется конфигурацией; таблица по умолчанию поставляется с двумя вышеуказанными; имяcustomзарезервировано для "производного состояния, не являющегося пресетом".

current(events)Собрать фактически действующий пресет из двух ручек, а не только смотреть на собственные события пресета.

Когда два пресета используют одну и ту же комбинацию ручек,permission/presetСобытия позволяютcurrent()всё ещё сохранить, какой именно из них выбрал пользователь.

Важно: пресет разрешений описывает только те возможности, которыми он фактически управляет.

Официальный разбор инцидента 0002 предупредил: доступ к файловой системе в момент композиции не может безопасно следовать пресету runtime bash-only.

В примере продуктивной среды,danger-full-accessследует настраивать только для одноразовых, выбрасываемых сред sandbox.


Итоговая самопроверка

Песочница и утверждение разделяют «границы возможностей» и «авторизацию решений»: песочница оборачивает argv политикой файловых эффектов, а утверждение использует водопад респондеров, чтобы выдать одноразовый допуск.

Вопросы для самопроверки:

ПроблемаСсылка
Потребитель хочет запуститьdanger-full-accessрежим, вызовет ли он ctx.sandbox?Нет — он напрямую запускает необработанный argv, не входя в песочницу
В цепочке одобрения нет отвечающих — каков результат?unavailable, отказ в закрытом состоянии, вызывающий отклоняет.
В CI, если вы хотите "никогда не запрашивать подтверждение и детерминированно отклонять все одобрения", какую политику следует использовать?approval/policy: never
Другие расширения