Процесс одобрения

Когда политика безопасности инструмента установлена в "supervised", PRX приостанавливает выполнение и ожидает одобрения человеком перед запуском вызова инструмента. Это обеспечивает критический уровень безопасности для высокорисковых операций -- команд оболочки, записи файлов, сетевых запросов или любых действий с необратимыми последствиями.

Обзор

Процесс одобрения располагается между циклом агента и выполнением инструмента:

Цикл агента
    │
    ├── LLM генерирует вызов инструмента: shell("rm -rf /tmp/data")
    │
    ▼
┌───────────────────────────────────┐
│        Движок политик             │
│                                   │
│  Инструмент: "shell"             │
│  Политика: "supervised"          │
│  Действие: ТРЕБУЕТСЯ ОДОБРЕНИЕ   │
└───────────────┬───────────────────┘
                │
                ▼
┌───────────────────────────────────┐
│      Запрос одобрения             │
│                                   │
│  Ожидание...                     │
│  ├── Уведомить супервизора       │
│  ├── Ожидать ответа              │
│  └── Таймаут через N секунд      │
└───────────────┬───────────────────┘
                │
         ┌──────┴──────┐
         │             │
    ┌────▼────┐   ┌────▼────┐
    │ Одобрено│   │Отклонено│
    │         │   │         │
    │Выполнить│   │Вернуть  │
    │инструмен│   │ ошибку  │
    └─────────┘   └─────────┘

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

Настройка политик инструментов

Настройте, какие инструменты требуют одобрения, в config.toml:

[security.tool_policy]
# Политика по умолчанию для всех инструментов.
# "allow" -- выполнять немедленно
# "deny" -- полностью блокировать выполнение
# "supervised" -- требовать одобрения перед выполнением
default = "allow"

# Переопределения политик для отдельных инструментов.
[security.tool_policy.tools]
shell = "supervised"
file_write = "supervised"
http_request = "supervised"
git_operations = "allow"
memory_store = "allow"
browser = "deny"

# Политики на уровне групп.
[security.tool_policy.groups]
sessions = "allow"
automation = "supervised"

Настройки одобрения

[security.approval]
# Время ожидания ответа перед таймаутом (секунды).
timeout_secs = 300

# Действие при таймауте одобрения: "deny" или "allow".
# "deny" -- безопасное значение по умолчанию -- неотвеченные запросы отклоняются.
on_timeout = "deny"

# Канал уведомления для запросов одобрения.
# Супервизор уведомляется через этот канал.
notify_channel = "telegram"

# ID пользователя-супервизора или идентификатор.
# Только этот пользователь может одобрять или отклонять запросы.
supervisor_id = "admin"

# Паттерны автоодобрения: вызовы инструментов, совпадающие с этими паттернами,
# одобряются автоматически без вмешательства человека.
# Используйте с осторожностью.
[[security.approval.auto_approve]]
tool = "shell"
command_pattern = "^(ls|cat|head|tail|wc|grep|find|echo) "

[[security.approval.auto_approve]]
tool = "file_write"
path_pattern = "^/tmp/"

Поток одобрения

Шаг 1: Проверка политики

Когда агент генерирует вызов инструмента, движок политик оценивает его:

1. Проверка политики конкретного инструмента (security.tool_policy.tools.<name>)
2. При отсутствии политики инструмента -- проверка политики группы (security.tool_policy.groups.<group>)
3. При отсутствии политики группы -- использование политики по умолчанию (security.tool_policy.default)

Если разрешённая политика -- "supervised", запускается поток одобрения.

Шаг 2: Проверка автоодобрения

Перед уведомлением супервизора PRX проверяет, совпадает ли запрос с каким-либо паттерном auto_approve. Правила автоодобрения используют регулярные выражения для сопоставления с аргументами инструмента:

Поле	Описание
tool	Имя инструмента, к которому применяется правило
command_pattern	Регулярное выражение для команды оболочки (для инструмента shell)
path_pattern	Регулярное выражение для путей файлов (для file_write, file_read)
url_pattern	Регулярное выражение для URL (для http_request)
args_pattern	Регулярное выражение для полных JSON-аргументов

При обнаружении совпадения запрос автоодобряется и выполнение продолжается немедленно. Это полезно для безопасных, только-для-чтения команд, которые вызвали бы чрезмерную усталость от одобрений.

Шаг 3: Уведомление

Если ни одно правило автоодобрения не совпало, PRX создаёт запрос одобрения и уведомляет супервизора:

[APPROVAL REQUIRED]

Tool: shell
Arguments: {"command": "rm -rf /tmp/data"}
Session: abc-123
Agent: default
Time: 2026-03-21 14:30:22 UTC

Reply with:
  /approve -- execute the tool call
  /deny -- reject the tool call
  /deny reason: <explanation> -- reject with reason

Уведомление отправляется через настроенный notify_channel. Поддерживаемые каналы:

Канал	Метод уведомления
Telegram	Сообщение в чат супервизора
Discord	ЛС супервизору
Slack	ЛС супервизору
CLI	Запрос в терминале (stdin)
Email	Письмо на настроенный адрес
Webhook	HTTP POST на настроенный URL

Шаг 4: Ожидание

Цикл агента приостанавливается на время ожидания ответа супервизора. В это время:

• Агент не может выполнять инструменты (текущий вызов инструмента блокирует)
• Другие сессии продолжают работать независимо
• Запрос одобрения имеет уникальный ID для отслеживания

Шаг 5: Разрешение

Супервизор отвечает одним из вариантов:

Ответ	Эффект
Одобрить	Вызов инструмента выполняется штатно и результат возвращается агенту
Отклонить	Вызов инструмента отклоняется и агенту возвращается сообщение об ошибке
Отклонить с причиной	То же, что отклонение, но причина включается в сообщение об ошибке, чтобы агент мог адаптироваться
Таймаут	Применяется действие on_timeout (по умолчанию: отклонение)

Жизненный цикл запроса

Каждый запрос одобрения проходит через следующие состояния:

PENDING -> APPROVED -> EXECUTED
       -> DENIED
       -> TIMED_OUT
       -> CANCELLED (если сессия завершена до разрешения)

Состояние	Описание
PENDING	Ожидание ответа супервизора
APPROVED	Супервизор одобрил, инструмент выполняется
EXECUTED	Выполнение инструмента завершено после одобрения
DENIED	Супервизор явно отклонил запрос
TIMED_OUT	Нет ответа в течение timeout_secs
CANCELLED	Сессия завершена до разрешения

Интерфейсы одобрения

В режиме CLI запросы одобрения отображаются как интерактивные запросы в терминале с именем инструмента, аргументами и уровнем риска. Для программного доступа PRX предоставляет REST API:

# Список ожидающих запросов / одобрить / отклонить
curl http://localhost:8080/api/approvals?status=pending
curl -X POST http://localhost:8080/api/approvals/{id}/approve
curl -X POST http://localhost:8080/api/approvals/{id}/deny \
  -d '{"reason": "Not permitted"}'

Аудиторский след

Все решения об одобрении фиксируются в журнале активности с полями: request_id, tool, arguments, session_id, decision, decided_by, decided_at, reason и execution_result. Доступ через prx audit approvals --last 50 или экспорт с --format json.

Замечания по безопасности

• Отклонение по умолчанию при таймауте -- всегда устанавливайте on_timeout = "deny" в продакшене. Разрешение неотвеченных запросов на продолжение обесценивает весь смысл контроля.
• Автоодобрение с осторожностью -- слишком широкие паттерны автоодобрения могут обходить процесс одобрения. Используйте конкретные регулярные выражения и регулярно проверяйте их.
• Аутентификация супервизора -- убедитесь, что notify_channel аутентифицирует супервизора. Скомпрометированный канал уведомлений может позволить несанкционированные одобрения.
• Ограничение частоты -- если агент повторно запускает запросы одобрения для одной операции, рассмотрите обновление политики на "deny" для этого инструмента или добавление более конкретного правила автоодобрения.
• Несколько супервизоров -- в командных развёртываниях рассмотрите настройку нескольких супервизоров. Любой из них может одобрить или отклонить.

Связанные страницы

• Обзор безопасности
• Движок политик
• Песочница
• Аудиторское журналирование
• Обзор инструментов