Skip to content

Workspace Operator 2.2.4 - security hardening and internal refactor

Choose a tag to compare

@Artoxem Artoxem released this 18 Nov 12:12
· 8 commits to master since this release

Workspace Operator 2.2.4

First PyPI/GHCR release since 2.1.2. Versions 2.2.0 to 2.2.3 were internal steps and were not published, so these notes cover everything since 2.1.2.

The MCP surface is unchanged: the tools, their order and JSON schemas, annotations, prompts, resources and server instructions are identical to 2.1.2 in all four profiles (compared programmatically). What changes is security behaviour, listed first because some of it needs action.

⚠️ Read before upgrading

  • Docker: the image now binds 127.0.0.1 by default. A plain docker run -p 8765:8765 IMAGE no longer answers. Add --http --host 0.0.0.0 --allow-network --insecure and keep the -p 127.0.0.1:8765:8765 mapping (docker-compose does this already).
  • HTTP token: the server refuses to start over HTTP with a placeholder (change_me, …) or a token shorter than 24 characters. Generate one: python -c "import secrets; print(secrets.token_urlsafe(32))" and prefer the MCP_AUTH_TOKEN environment variable over config.yaml.
  • Approval links: the agent no longer receives a browser link. Run workspace-operator approvals link <id> to get it (it carries a per-approval secret). Old links without ?k= return 404.
  • drive_write(action="upload") refuses OAuth secrets, .env*, keys and ~/.google, ~/.ssh, ~/.aws, and files outside upload_roots when you set it (MCP_UPLOAD_ROOTS).

Security fixes

  • Path traversal: a mail attachment named ..\..\x could be written outside the target folder. Names from remote data are now reduced to a plain file name.
  • An agent that knew an approval id and the server URL could approve its own request over HTTP. Approvals now need a secret the agent never sees, an Origin/Host check and strict headers.
  • token.json is refreshed under a file lock, written atomically and readable by the owner only. workspace-operator doctor now flags a token stored in config.yaml, stray credentials (token.json.bak-*, service-account.json) and files readable by other users.

Fixes

  • Bulk jobs lost results on cancel: items already running when a job was cancelled changed Google data but were not recorded, so bulk_undo skipped them and resume repeated them. They are recorded now.
  • handlers.__all__ listed a name that does not exist; the server.json package version lagged one release.

Under the hood

  • server.py went from 3,740 to 325 lines: tool definitions are JSON data (workspace_operator/definitions/), the handler table is dispatch.py, the call path is ToolRouter, prompts and resources have their own modules. Each step was pinned by characterisation tests taken from the old code.
  • CI (Linux and Windows, Python 3.10/3.12/3.13, ruff, mypy, bandit, pip-audit) now gates both publish workflows. mypy: 152 errors to 0. 421 tests (one skipped on Linux/macOS by design), coverage 56%.
  • New contributor guide ("Adding a tool or action") in both READMEs.

Full list: docs/VERSIONS.md.


Workspace Operator 2.2.4 (русский)

Первый релиз в PyPI/GHCR после 2.1.2. Версии 2.2.0–2.2.3 были внутренними этапами и не публиковались, поэтому заметки охватывают всё с 2.1.2.

MCP-поверхность не изменилась: инструменты, их порядок и JSON-схемы, аннотации, промпты, ресурсы и инструкции сервера идентичны 2.1.2 во всех четырёх профилях (сравнивалось программно). Меняется поведение безопасности; оно вынесено вперёд, потому что часть изменений требует действий.

⚠️ Прочитайте перед обновлением

  • Docker: образ по умолчанию слушает 127.0.0.1. Обычный docker run -p 8765:8765 IMAGE больше не отвечает. Добавьте --http --host 0.0.0.0 --allow-network --insecure и оставьте проброс -p 127.0.0.1:8765:8765 (docker-compose это уже делает).
  • Токен HTTP: сервер не запустится по HTTP с заглушкой (change_me, …) или токеном короче 24 символов. Сгенерируйте: python -c "import secrets; print(secrets.token_urlsafe(32))", лучше в переменной MCP_AUTH_TOKEN, а не в config.yaml.
  • Ссылки одобрений: агент больше не получает ссылку для браузера. Получите её командой workspace-operator approvals link <id> (в ней секрет конкретного одобрения). Старые ссылки без ?k= дают 404.
  • drive_write(action="upload") отклоняет секреты OAuth, .env*, ключи и ~/.google, ~/.ssh, ~/.aws, а также файлы вне upload_roots, если он задан (MCP_UPLOAD_ROOTS).

Исправления безопасности

  • Path traversal: вложение письма с именем ..\..\x могло записаться за пределы целевой папки. Имена из удалённых данных теперь сводятся к простому имени файла.
  • Агент, знающий id одобрения и адрес сервера, мог одобрить свой запрос по HTTP. Теперь нужны секрет, которого агент не видит, проверка Origin/Host и строгие заголовки.
  • token.json обновляется под файловой блокировкой, пишется атомарно и доступен только владельцу. workspace-operator doctor теперь находит токен в config.yaml, лишние учётные данные (token.json.bak-*, service-account.json) и файлы, доступные другим пользователям.

Исправления

  • Bulk-задачи теряли результаты при отмене: элементы, уже запущенные к моменту отмены, меняли данные в Google, но не записывались, поэтому bulk_undo их пропускал, а возобновление повторяло. Теперь они записываются.
  • В handlers.__all__ было несуществующее имя; версия пакета в server.json отставала на один релиз.

Внутри

  • server.py: 3740 → 325 строк. Определения инструментов теперь JSON-данные (workspace_operator/definitions/), таблица handler'ов в dispatch.py, путь вызова в ToolRouter, у промптов и ресурсов свои модули. Каждый шаг закреплён тестами, снятыми со старого кода.
  • CI (Linux и Windows, Python 3.10/3.12/3.13, ruff, mypy, bandit, pip-audit) теперь блокирует оба workflow публикации. mypy: 152 ошибки → 0. 421 тест (один пропускается на Linux/macOS намеренно), покрытие 56%.
  • Руководство для контрибьюторов («Как добавить инструмент или действие») в обоих README.

Полный список: docs/VERSIONS.md.