Файловые операции

PRX предоставляет два основных инструмента файловых операций -- file_read и file_write -- которые входят в минимальный набор default_tools(). Эти инструменты всегда доступны, не требуют дополнительной настройки и составляют основу способности агента взаимодействовать с локальной файловой системой.

Оба инструмента подчиняются движку политик безопасности. Валидация путей гарантирует, что агент может обращаться только к файлам в разрешённых каталогах. При включённом ACL памяти file_read дополнительно блокирует доступ к markdown-файлам памяти, предотвращая обход контроля доступа через прямое чтение хранилища памяти.

В отличие от инструмента shell, файловые операции не порождают внешних процессов. Они реализованы как прямые Rust I/O операции внутри процесса PRX, что делает их быстрее и проще для аудита по сравнению с эквивалентными shell-командами типа cat или echo >.

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

Файловые операции не имеют отдельного раздела конфигурации. Их поведение контролируется через движок политик безопасности и настройки ACL памяти:

# ACL памяти влияет на поведение file_read
[memory]
acl_enabled = false    # При true file_read блокирует доступ к файлам памяти

# Политика безопасности может ограничивать пути доступа к файлам
[security.tool_policy.tools]
file_read = "allow"    # "allow" | "deny" | "supervised"
file_write = "allow"

# Правила политики на основе путей
[[security.policy.rules]]
name = "allow-workspace-read"
action = "allow"
tools = ["file_read"]
paths = ["/home/user/workspace/**"]

[[security.policy.rules]]
name = "allow-workspace-write"
action = "allow"
tools = ["file_write"]
paths = ["/home/user/workspace/**"]

[[security.policy.rules]]
name = "block-sensitive-paths"
action = "deny"
tools = ["file_read", "file_write"]
paths = ["/etc/shadow", "/root/**", "**/.ssh/**", "**/.env"]

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

file_read

Инструмент file_read читает содержимое файла и возвращает его как строку. Это основной способ, которым агент просматривает файлы во время своего цикла рассуждений.

{
  "name": "file_read",
  "arguments": {
    "path": "/home/user/project/src/main.rs"
  }
}

Агент обычно использует file_read для:

• Проверки исходного кода перед внесением изменений
• Чтения конфигурационных файлов для понимания состояния системы
• Просмотра файлов журналов для поиска сообщений об ошибках
• Обзора документации или README-файлов

file_write

Инструмент file_write записывает содержимое в файл, создавая его при отсутствии или перезаписывая содержимое при наличии.

{
  "name": "file_write",
  "arguments": {
    "path": "/home/user/project/src/config.toml",
    "content": "[server]\nport = 8080\nhost = \"0.0.0.0\"\n"
  }
}

Агент обычно использует file_write для:

• Создания новых исходных или конфигурационных файлов
• Изменения существующих файлов (после чтения через file_read)
• Записи генерируемых отчётов или сводок
• Сохранения обработанных данных на диск

Параметры

Параметры file_read

Параметр	Тип	Обязательный	По умолчанию	Описание
path	string	Да	--	Абсолютный или относительный путь к файлу для чтения

Возвращает:

Поле	Тип	Описание
success	bool	true если файл был успешно прочитан
output	string	Содержимое файла как строка UTF-8
error	string?	Сообщение об ошибке при неудачном чтении (файл не найден, доступ запрещён, ACL заблокировал и т.д.)

Параметры file_write

Параметр	Тип	Обязательный	По умолчанию	Описание
path	string	Да	--	Абсолютный или относительный путь к файлу для записи
content	string	Да	--	Содержимое для записи в файл

Возвращает:

Поле	Тип	Описание
success	bool	true если файл был успешно записан
output	string	Подтверждающее сообщение (напр., "File written: /path/to/file")
error	string?	Сообщение об ошибке при неудачной записи (доступ запрещён, путь заблокирован и т.д.)

Валидация путей

Оба инструмента выполняют валидацию путей перед выполнением I/O операции:

1. Нормализация пути -- относительные пути разрешаются относительно текущего рабочего каталога. Символические ссылки разрешаются для обнаружения обхода путей.
2. Проверка политики -- разрешённый путь проверяется по правилам политики безопасности. Если ни одно правило явно не разрешает путь и действие по умолчанию -- deny, операция блокируется.
3. Блокировка специальных путей -- определённые пути всегда блокируются независимо от политики:
   • /proc/, /sys/ (интерфейсы ядра Linux)
   • Файлы устройств в /dev/ (за исключением /dev/null, /dev/urandom)
   • Файлы хранилища памяти при memory.acl_enabled = true

Предотвращение обхода путей

Инструменты разрешают символические ссылки и нормализуют компоненты .. перед проверкой политик. Это предотвращает использование символических ссылок или трюков с относительными путями для выхода за пределы разрешённых каталогов:

# Все эти пути разрешаются и проверяются:
/home/user/workspace/../../../etc/passwd  →  /etc/passwd  →  ЗАПРЕЩЕНО
/home/user/workspace/link-to-etc          →  /etc/        →  ЗАПРЕЩЕНО (если символическая ссылка)

Применение ACL памяти

При memory.acl_enabled = true в конфигурации инструмент file_read применяет дополнительные ограничения:

• Файлы памяти заблокированы: file_read отказывается читать markdown-файлы, хранящиеся в каталоге памяти (обычно ~/.local/share/openprx/memory/). Это предотвращает обход контроля доступа к памяти через чтение необработанных файлов хранилища.
• Memory recall отключён: Инструмент memory_recall полностью удаляется из реестра инструментов при включённом ACL.
• Только целевой доступ: Агент должен использовать memory_get или memory_search с надлежащими проверками ACL для доступа к содержимому памяти.

[memory]
acl_enabled = true    # Активирует ограничения file_read на пути памяти

Это разделение гарантирует, что даже если агент знает физическое расположение файлов памяти, он не сможет прочитать их за пределами контролируемого API памяти.

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

Интеграция с движком политик

Каждый вызов file_read и file_write проходит через движок политик безопасности перед выполнением. Движок политик оценивает правила в порядке:

1. Политика для инструмента (security.tool_policy.tools.file_read)
2. Правила на основе путей (security.policy.rules с совпадающими паттернами paths)
3. Действие по умолчанию (security.policy.default_action)

Журнал аудита

При включённом журналировании аудита каждая файловая операция записывается с:

• Меткой времени
• Именем инструмента (file_read или file_write)
• Разрешённым путём файла
• Статусом успешности/неудачи
• Причиной ошибки (при отказе или сбое)

[security.audit]
enabled = true
log_path = "audit.log"

Защита конфиденциальных файлов

Политика безопасности по умолчанию блокирует доступ к распространённым конфиденциальным путям:

• SSH-ключи (~/.ssh/)
• Файлы окружения (.env, .env.local)
• Учётные данные Git (.git-credentials)
• История shell (.bash_history, .zsh_history)
• Системные файлы паролей (/etc/shadow)

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

Обработка бинарных файлов

Инструмент file_read читает файлы как строки UTF-8. Бинарные файлы приведут к искажённому выводу или ошибкам кодировки. Для проверки бинарных файлов агенту следует использовать инструмент shell с соответствующими командами (напр., xxd, file, hexdump).

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

• Выполнение shell -- инструмент выполнения команд (альтернатива для бинарных файлов)
• Инструменты памяти -- контролируемый доступ к памяти с ACL
• Движок политик -- правила контроля доступа на основе путей
• Справочник конфигурации -- настройки памяти и безопасности
• Обзор инструментов -- все инструменты и система реестра