odysseus/specs/discovery/safety-boundaries.md

Safety boundaries

This document prioritizes review of broad authority. It records code-grounded safeguards and questions; it does not declare a vulnerability merely because a feature is powerful. No destructive test, external connection, or real credential was used for this map.

Shell and subprocess execution

Boundary. Shell routes, agent bash and python tools, local model serving, and detached background jobs.

Available authority. Commands run as the application process user and can create child processes.

User-controlled inputs. Direct shell requests, model-produced tool arguments, scheduled-task prompts, and model-serving configuration.

Current safeguards. Agent dispatch applies owner/admin checks and tool policy; process helpers use timeouts or bounded background-job lifecycle where implemented.

Confirmed risks or gaps. Intentional authority with a confirmed gap: the agent shell starts in its workspace but is not sandboxed to it, and has no egress sandbox. This is documented in source and the threat model; it is not a newly demonstrated bypass.

Required verification. Role-gate and disabled-tool outcomes, direct shell-route behaviour, and timeout, cancellation, and output handling for foreground and detached processes remain unverified.

Filesystem access and workspace confinement

Boundary. Agent read, write, patch, listing, glob, and grep tools.

Available authority. Read and modify files within active workspace confinement or fallback allowlisted roots.

User-controlled inputs. Tool paths, patches, file contents, search patterns, and workspace selection passed into the tool dispatcher.

Current safeguards. src/tool_execution.py resolves paths, blocks sensitive subpaths, applies allowlist containment, and tightens paths to the active workspace when one is bound. File tools use those resolvers.

Confirmed risks or gaps. Intentional authority with safeguards. The file-tool policy does not sandbox the shell; treating a workspace as a whole-process containment boundary would be incorrect.

Required verification. Traversal, symlink, sensitive-name, absolute-path, and workspace-switch behaviour remains unverified.

Agent-controlled tool dispatch

Boundary. Model output becomes native or parsed tool calls and is dispatched by the agent loop.

Available authority. The authority of every enabled tool, including privileged built-ins and external tools.

User-controlled inputs. Chat content, attached/retrieved content that may influence the model, tool arguments, per-request tool selection, and policy toggles.

Current safeguards. src/tool_security.py blocks protected tools for non-admin users and fails closed for malformed tool names; src/tool_policy.py supports disabled and guide-only policy; prompt-security helpers label untrusted context.

Confirmed risks or gaps. Credible risk requiring verification: aliases, legacy text tools, native function calls, and MCP-qualified names must all reach the same policy outcome. The code has specific alias handling for email/MCP names, which makes this a sensitive compatibility seam.

Required verification. The current policy outcomes for owner role, request mode, disabled state, native versus parsed invocation, qualified aliases, and external-content entry points remain unverified.

MCP and external tool servers

Boundary. Configured MCP servers and their tools are exposed to the agent through the MCP manager and routes.

Available authority. Depends on the server: external network access, local process access, messaging, or data mutation may be delegated outside the application.

User-controlled inputs. Server configuration, remote OAuth completion, tool arguments, and model-selected MCP calls.

Current safeguards. MCP routes are registered through routes/mcp_routes.py; MCP-qualified tools are denied to non-admin users by src/tool_security.py. OAuth state and token persistence are handled in src/mcp_oauth.py.

Confirmed risks or gaps. Credible risk requiring verification: an MCP server authority is broader than the application can infer from its tool name. This map does not establish a trust or approval model for server installation and individual tool invocation.

Required verification. Server onboarding, credential storage, server-origin trust, OAuth callback deployment, tool disablement, and invocation audit behaviour remain unverified.

Outbound network requests and URL validation

Boundary. Search/content fetch, research, webhooks, skill import, provider endpoints, and other HTTP clients.

Available authority. The application can make outbound requests from its network position.

User-controlled inputs. Search/fetch URLs, imported skill URLs, webhook configuration, and some endpoint settings.

Current safeguards. src/url_security.py validates untrusted public HTTP URLs and fails closed on unsuitable schemes or private addresses. services/search/content.py resolves and rejects non-public hosts, pins resolved addresses for fetches, caps bodies, and limits redirects.

Confirmed risks or gaps. Intentional split: administrator-created model endpoints may target private providers, while untrusted URLs use public-address checks. That distinction is required for self-hosted deployments but needs explicit call-site review.

Required verification. The URL-source classification for outbound clients and the current handling of redirects and DNS changes remain unverified.

Secrets, credentials, and vault sessions

Boundary. Application-managed encrypted secrets, API keys, provider credentials, and Bitwarden/Vaultwarden CLI sessions.

Available authority. Credentials unlock remote providers and connected personal services.

User-controlled inputs. Administrative configuration, login/unlock requests, imported settings, and agent vault tool arguments.

Current safeguards. src/secret_storage.py uses a locally stored Fernet key with restrictive permissions for supported database secrets. Vault routes require an administrator, avoid passing master passwords in command arguments, and set restrictive permissions on the vault-session file.

Confirmed risks or gaps. Confirmed current boundary: vault session data is persisted through the vault path, not through src/secret_storage.py. This is an unresolved question about current security semantics, not a confirmed exposure.

Required verification. Current encryption-at-rest, owner scope, rotation, lock/logout, backup/restore, and log/tool-result exposure behaviour remains unverified.

Authentication and privileged administration

Boundary. Session authentication, API tokens, privileged routes, and internal tool loopback.

Available authority. Administrative identity can access execution, settings, integrations, data deletion, and secrets.

User-controlled inputs. Login/signup data, session cookies, API tokens, authentication configuration, and requests to privileged routes.

Current safeguards. core/auth.py, core/middleware.py, and route-level checks establish identity and administrator gates. app.py warns when localhost bypass is configured; SECURITY.md documents deployment requirements.

Confirmed risks or gaps. Intentional authority with safeguards. Security depends on deployments keeping authentication enabled and internal services private; this map does not audit reverse-proxy or environment configuration.

Required verification. Setup, anonymous, non-admin, admin, token, and internal-loopback behaviour, including privileged-route gate consistency, remains unverified.

Deletion, wipe, backup, and restore

Boundary. Administrative wipe, cleanup, backup import/export, and the backup restore command.

Available authority. Delete or replace user data and credentials.

User-controlled inputs. Administrative HTTP requests, cleanup choices, backup payloads, archive paths, and restore command options.

Current safeguards. Administrative wipe routes use the administrative boundary. Cleanup exposes a preview route before mutation. The documented backup tool requires explicit restore confirmation, stages the old data directory, and validates archive members before extraction.

Confirmed risks or gaps. Intentional destructive authority. Backup archives contain secrets by design, as documented in docs/backup-restore.md; this is an operator confidentiality responsibility, not a code defect established here.

Required verification. Role-gate, confirmation, archive-rejection, staged-recovery, and owner-isolation behaviour remains unverified. No destructive runtime test was performed.

Background jobs and unattended task execution

Boundary. Scheduled tasks, background-job monitor, startup tasks, and notification/delivery work that continue without an active browser request.

Available authority. Scheduled agent work can obtain model access and, for eligible owners, shell and file tools; task output can interact with connected services.

User-controlled inputs. Stored task prompt, schedule, model/crew selection, enabled-tool configuration, output target, and prior persisted state.

Current safeguards. src/task_scheduler.py serializes execution, records task runs, associates work with an owner, and applies the agent owner-based tool gate. src/bg_jobs.py keeps bounded state and can terminate overlong subprocess jobs.

Confirmed risks or gaps. Credible risk requiring verification: authority is inherited and exercised later, so changes to roles, task configuration, and disabled tools must be checked at execution time rather than assumed from task creation.

Required verification. Creation, editing, role-change, scheduling, cancellation, restart-recovery, and execution behaviour remains unverified, including whether current policy is re-evaluated before privileged action.