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" в коде.
Пример
// Демонстрация потребителя в песочнице: сначала разобрать политику, затем позволить 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-write | workspace-write | ask | Рабочее пространство с возможностью записи, запрашивать у пользователя подтверждение для чувствительных операций |
danger-full-access | danger-full-access | never | Обход песочницы, без запросов; можно запускать только в одноразовой среде |
Таблица пресетов управляется конфигурацией; таблица по умолчанию поставляется с двумя вышеуказанными; имя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 |