Выполнение shell

Инструмент shell -- один из трёх основных инструментов PRX, доступный как в реестрах default_tools(), так и all_tools(). Он обеспечивает выполнение команд на уровне ОС внутри настраиваемой песочницы, гарантируя, что инициированные агентом команды выполняются в условиях строгой изоляции, ограничений по времени и размеру вывода.

Когда LLM определяет, что нужно выполнить shell-команду -- установить пакет, скомпилировать код, запросить состояние системы или выполнить скрипт -- он вызывает инструмент shell со строкой команды. PRX оборачивает выполнение в настроенный бэкенд песочницы, применяет 60-секундный таймаут по умолчанию, ограничивает вывод 1 МБ и удаляет конфиденциальные переменные окружения перед порождением дочернего процесса.

Инструмент shell, как правило, самый мощный и самый ограниченный инструмент в арсенале PRX. Он является основной целью движка политик безопасности, и большинство развёртываний помечают его как supervised для требования одобрения человеком перед выполнением.

Конфигурация

Сам инструмент shell не имеет отдельного раздела конфигурации. Его поведение контролируется через песочницу безопасности и лимиты ресурсов:

[security.sandbox]
enabled = true
backend = "auto"         # "auto" | "landlock" | "firejail" | "bubblewrap" | "docker" | "none"

# Пользовательские аргументы Firejail (при backend = "firejail")
firejail_args = ["--net=none", "--noroot"]

[security.sandbox.docker]
image = "prx-sandbox:latest"
network = "none"
memory_limit = "256m"
cpu_limit = "1.0"

[security.sandbox.bubblewrap]
allow_network = false
writable_paths = ["/tmp"]
readonly_paths = ["/usr", "/lib"]

[security.resources]
max_memory_mb = 512
max_cpu_time_seconds = 60
max_subprocesses = 10
memory_monitoring = true

Для пометки shell как supervised (требование одобрения для каждого вызова):

[security.tool_policy.tools]
shell = "supervised"

Бэкенды песочницы

PRX поддерживает пять бэкендов песочницы. При backend = "auto" PRX проверяет доступные бэкенды в следующем порядке приоритета и выбирает первый найденный:

Бэкенд	Платформа	Уровень изоляции	Накладные расходы	Примечания
Landlock	Linux (5.13+)	LSM файловой системы	Минимальные	Встроен в ядро, без дополнительных зависимостей. Ограничивает пути файловой системы на уровне ядра.
Firejail	Linux	Полный (сеть, ФС, PID)	Низкие	Песочница пользовательского пространства. Поддерживает --net=none для сетевой изоляции, PID namespace, seccomp-фильтрацию.
Bubblewrap	Linux, macOS	На основе пространств имён	Низкие	Использует пользовательские пространства имён. Настраиваемые списки путей для записи/только чтения.
Docker	Любая	Полная контейнеризация	Высокие	Выполняет команды внутри одноразового контейнера. Максимальная изоляция, но наибольшая задержка.
None	Любая	Только на уровне приложения	Отсутствуют	Без изоляции на уровне ОС. PRX по-прежнему применяет таймаут и ограничение вывода, но процесс имеет полный доступ к ОС.

Landlock

Landlock -- это Linux Security Module, доступный в ядре 5.13+. Он ограничивает доступ к файловой системе на уровне ядра без требования привилегий root. PRX использует Landlock для ограничения путей, которые shell-команда может читать и в которые может записывать.

Firejail

Firejail обеспечивает комплексную песочницу через пространства имён Linux и seccomp. Пользовательские аргументы могут передаваться через firejail_args:

[security.sandbox]
backend = "firejail"
firejail_args = ["--net=none", "--noroot", "--nosound", "--no3d"]

Bubblewrap

Bubblewrap (bwrap) использует пользовательские пространства имён для создания минимальных изолированных сред. Он легче Firejail и работает на некоторых конфигурациях macOS:

[security.sandbox.bubblewrap]
allow_network = false
writable_paths = ["/tmp", "/home/user/workspace"]
readonly_paths = ["/usr", "/lib", "/bin"]

Docker

Docker обеспечивает полную контейнерную изоляцию. Каждая команда выполняется в новом контейнере на основе настроенного образа:

[security.sandbox.docker]
image = "prx-sandbox:latest"
network = "none"
memory_limit = "256m"
cpu_limit = "1.0"

Использование

Инструмент shell вызывается LLM во время агентных циклов. В разговорах агента LLM генерирует вызов инструмента:

{
  "name": "shell",
  "arguments": {
    "command": "ls -la /home/user/project"
  }
}

Из CLI можно наблюдать вызовы инструмента shell в выводе агента. Вызов инструмента показывает выполняемую команду и используемый бэкенд песочницы.

Поток выполнения

1. LLM генерирует вызов инструмента shell с аргументом command
2. Движок политик безопасности проверяет, разрешён ли вызов, запрещён или требует наблюдения
3. Если supervised, PRX запрашивает у пользователя одобрение перед продолжением
4. Бэкенд песочницы оборачивает команду в соответствующий слой изоляции
5. Переменные окружения очищаются (см. ниже)
6. Команда выполняется с 60-секундным таймаутом
7. stdout и stderr захватываются, обрезаются до 1 МБ при необходимости
8. Результат возвращается LLM как ToolResult со статусом успеха/неудачи

Параметры

Параметр	Тип	Обязательный	По умолчанию	Описание
command	string	Да	--	Shell-команда для выполнения. Передаётся в /bin/sh -c (или эквивалент).

Инструмент возвращает ToolResult, содержащий:

Поле	Тип	Описание
success	bool	true если команда завершилась с кодом 0
output	string	Объединённые stdout и stderr, обрезанные до 1 МБ
error	string?	Сообщение об ошибке при неудаче или таймауте команды

Очистка переменных окружения

Инструмент shell передаёт дочерним процессам только строгий белый список переменных окружения. Это предотвращает случайную утечку API-ключей, токенов и секретов, которые могут присутствовать в окружении демона.

Разрешённые переменные окружения:

Переменная	Назначение
PATH	Путь поиска исполняемых файлов
HOME	Домашний каталог пользователя
TERM	Тип терминала
LANG	Язык локали
LC_ALL	Переопределение локали
LC_CTYPE	Тип символов локали
USER	Текущее имя пользователя
SHELL	Путь к shell по умолчанию
TMPDIR	Каталог для временных файлов

Все остальные переменные -- включая API_KEY, AWS_SECRET_ACCESS_KEY, GITHUB_TOKEN, OPENAI_API_KEY и любые пользовательские переменные -- удаляются из окружения дочернего процесса. Это жёстко заданная граница безопасности, которую нельзя переопределить через конфигурацию.

Ограничения ресурсов

Ограничение	По умолчанию	Настраиваемо	Описание
Таймаут	60 секунд	security.resources.max_cpu_time_seconds	Максимальное реальное время на команду
Размер вывода	1 МБ	--	Максимальный объединённый stdout + stderr
Память	512 МБ	security.resources.max_memory_mb	Максимальное потребление памяти на команду
Подпроцессы	10	security.resources.max_subprocesses	Максимум порождённых дочерних процессов

При превышении таймаута PRX отправляет SIGTERM, за которым следует SIGKILL после льготного периода. Результат инструмента сообщает о таймауте как об ошибке.

При превышении вывода 1 МБ он обрезается с добавлением примечания об обрезке.

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

• Изоляция песочницей: Команды выполняются внутри настроенного бэкенда песочницы, ограничивающего доступ к файловой системе, сети и процессам
• Очистка окружения: Дочерним процессам передаются только 9 разрешённых переменных окружения
• Движок политик: Каждый вызов shell проходит через движок политик безопасности перед выполнением
• Журнал аудита: Все shell-команды и их результаты логируются в журнал аудита при security.audit.enabled = true
• Режим наблюдения: Инструмент shell может быть помечен как supervised в политике инструментов, требуя явного одобрения пользователя перед каждым выполнением
• Лимиты ресурсов: Жёсткие ограничения на таймаут, память, размер вывода и количество подпроцессов предотвращают исчерпание ресурсов

Митигация угроз

Инструмент shell -- основной вектор для атак внедрения промптов. Если злоумышленник может повлиять на рассуждения LLM (например, через содержимое вредоносного документа), инструмент shell -- то, что он использовал бы для выполнения команд. PRX снижает этот риск через:

1. Ограничение песочницей -- даже при выполнении вредоносной команды она работает с ограниченным доступом к файловой системе и сети
2. Удаление переменных окружения -- API-ключи и секреты недоступны дочернему процессу
3. Режим наблюдения -- человек в цепочке может просмотреть каждую команду перед выполнением
4. Журнал аудита -- все команды логируются для последующего анализа

Связанные разделы

• Песочница безопасности -- подробная документация по бэкендам песочницы
• Движок политик -- правила контроля доступа к инструментам
• Справочник конфигурации -- поля security.sandbox и security.resources
• Обзор инструментов -- все 46+ инструментов и система реестра