Skip to content

v4.8.0: Security hardening release

Latest

Choose a tag to compare

@praisonai-triage-agent praisonai-triage-agent released this 19 Nov 16:53
· 6 commits to main since this release

Security hardening release

This release makes PraisonAI safer by default. Servers stay on your own machine unless you give them a token. Tools that read files, fetch URLs or run code now stay inside clear limits. A project you clone can no longer change your trust settings.

Most users need to do nothing. If a change stops something you rely on, the Migration table names the setting that brings the old behaviour back.

Packages in this release

Package Version
praisonaiagents (PyPI) 1.8.0
praisonai (PyPI) 4.8.0
praisonai-code (PyPI) 0.2.0
praisonai-bot (PyPI) 0.2.0
praisonai-mcp (PyPI) 0.2.0
praisonai-sandbox (PyPI) 0.2.0
praisonai-browser (PyPI) 0.2.0
praisonai-deploy (PyPI) 0.2.0
praisonai-train (PyPI) 0.2.0
praisonai (npm) 1.8.0, follows shortly
PraisonAI Desktop 4.8.0

Upgrade with:

pip install -U praisonai          # installs every Python package above
npm install praisonai@latest      # TypeScript SDK (1.8.0, follows shortly)

Servers and binds

One rule now applies to every built-in server: it listens on 127.0.0.1 by default. A server that you open to the network needs a token.

  • Every network server binds 127.0.0.1 by default.
  • A non-loopback bind without a token refuses to start, with a message that names the setting to use. This covers AgentServer, the Jobs API, praisonai serve agents/a2a/unified/openai, rag serve, registry serve, recipe serve, AgentOS (Python and TypeScript, including serve({ host })), the call server, praisonai-browser remote mode, the TypeScript MCP server and the N8N listener.
  • praisonai call --public needs CALL_SERVER_TOKEN.
  • Webhook receivers without a signing secret stay on loopback. HTTPApproval on a public host needs allowed_approvers.
  • A2A.serve(), MCP over SSE and launch() still start on a public host, but print a generated token that every request must send.
  • A2A on loopback checks PRAISONAI_LAUNCH_AUTH_TOKEN when it is set. /info needs the token when one is set.
  • The dashboard and the replay viewer follow the same bind rule.
  • A Jobs API started with uvicorn ...:create_app --factory and no key answers only /health, unless PRAISONAI_JOBS_BIND_HOST=127.0.0.1 says it is local.
  • Keyless local servers refuse requests from other websites (a foreign or null Origin) and requests with a non-local Host. If you use a reverse proxy, keep Host: localhost or set a key.
  • Request bodies are capped: 10 MB on the MCP HTTP-stream server and 25 MB on the gateway. Larger bodies get 413.
  • Token checks use constant-time comparison.
  • The recipe server keeps bounded per-client rate-limit and metrics state.
  • On the MCP server, tools/search needs tools:read, and a method with no scope mapping needs admin.
  • The desktop engine answers only requests addressed to a local host name.

Gateway and bots

  • The local gateway refuses browser pages from other sites (HTTP and WebSocket) unless the origin is listed in GATEWAY_ALLOWED_ORIGINS.
  • With a scope policy, /v1/* and /mcp need the write scope, and /api/pairing/pending needs pairing.
  • With a scope policy, a session resumes only for the token that created it.
  • At most 1000 HTTP API sessions stay live. The oldest idle one is closed and can be resumed from the store.
  • On a gateway with a token, unauthenticated /health shows only the status.
  • People who cannot message a bot cannot press its buttons or run its slash commands.
  • With admin_users set, /undo, /blueprint and /automations are admin-only.
  • An email or AgentMail bot with no allowed_users and the default unknown_user_policy (deny) no longer answers unknown senders.
  • In a shared Slack channel, an unthreaded "yes" no longer counts as an approval when the bot cannot read thread replies. The request times out and is denied.
  • Bot daemon install refuses a config path that contains ", % or a control character.
  • session_search returns only sessions of the current user, then of the current agent.

Outbound fetching

Tools that fetch a URL now use one shared check. It refuses private, loopback and cloud-metadata addresses, and pins the address it checked.

  • URL readers, fetch tools, document loaders, image .save(), the praisonai-code image command, MCP OAuth and OIDC metadata, remote instruction sources and bot inbound media refuse private and loopback addresses. Set ALLOW_LOCAL_CRAWL=true to fetch local services in development.
  • Webhooks to 100.64.0.0/10 are refused.
  • Bot media URLs written in IPv4-in-IPv6 form are refused.
  • MCP OAuth follows a metadata redirect through a plain-HTTP hop when the final document is HTTPS. (It used to refuse.)
  • crawl4ai crawls (optional [crawl] extra) stop browser requests to blocked addresses, and return an error instead of content when the final URL is blocked. Known limit: a browser redirect can still send one request to a blocked address before it is stopped; no response content is returned. If this matters, add network-level egress rules.
  • JIRA tools that use JIRA_API_TOKEN from the environment need JIRA_URL, and send the token only to that origin.
  • OpenAPIToolset(spec_url=..., auth=...) raises when the fetched spec names a server on another origin. Pass base_url= to choose the server.
  • Jobs webhooks open one connection per notification.

File paths

File tools now stay inside the folder you work in, unless you give them another root.

  • FastContext search tools, MCP file tools, the wrapper list_files, and the screenshot, crawl and dataset helpers stay inside the current directory unless given a root.
  • The grep_search, glob_files and glob_directories tools default to the current directory. PRAISONAI_WORKSPACE sets another root.
  • multiedit(workspace_root=...) may only narrow the current directory, not widen it.
  • Recipe registry names and versions, and action-orchestrator file steps, resolve only inside their own folder.
  • FileTools.list_files skips matches reached through a symlink that leaves the folder.
  • A project rule file's @~/ import reads only Markdown files in your home folder. User-level rule files are unchanged.
  • Memory checkpoints skip, and restores refuse, paths outside the current directory.
  • Recipe trace_name values with /, \ or .. are refused. The run still completes, without history.
  • Recipe bundles that contain links fail to install on a Python without the tarfile data filter.
  • Bot send_message attachments must be inside the agent workspace, the current directory or allow_roots.
  • Bot custom commands read @file only under the bot's current directory.
  • The CLI SandboxExecutor (BASIC and STRICT) refuses ../, ~ and quoted paths into blocked folders, and paths outside allowed_paths. Absolute paths inside its run directory are allowed.

Project-file trust

A project file is a file in the folder you run in, such as .praisonai/config.yaml, praisonai.yaml, or command and agent front matter. It may tune behaviour. It can no longer grant a capability. Those settings now count only from your user config (~/.praisonai), the environment or code.

  • MCP servers named in a project file start only if their command line is listed under mcp.trusted_servers in ~/.praisonai/config.yaml.
  • An MCP url that is not a URL never starts a process.
  • A project file can no longer set the model endpoint or API key, open the project-plugin gate, turn on !cmd`` shell expansion, add allow permission rules, or send `${VAR}` values to an untrusted remote MCP server. Each ignored key logs a warning that names the user setting to use instead.
  • PRAISONAI_ALLOW_LOCAL_TOOLS alone no longer loads an included recipe's tools.py from outside the current directory. That needs PRAISONAI_ALLOW_TEMPLATE_TOOLS=true.
  • create_tool_registry_with_overrides(tools_sources=...) needs PRAISONAI_ALLOW_TEMPLATE_TOOLS=true.
  • CLI "always allow" and "always deny" choices now live in $PRAISONAI_HOME/permissions/projects/<id>. Old copies inside a project are ignored with a warning.

Approvals

  • Tools that send or act for you need approval by default: send_email and the other mail-sending tools, send_message, ask_conversation, mail drafts, archive and create_inbox, schedule_* changes, and execute_code_with_tools. In a terminal you are asked. With no way to ask, the call is denied. Bots with auto_approve_tools are unchanged.
  • A tool with the same name as one of these is gated the same way.
  • "This session" and "always" grants for tools other than shell and file tools cover the same arguments only.
  • A skill's allowed-tools pre-approves only low-risk tools.
  • PolicyEngine(default_action="deny") denies resources that no rule matches. YAML match: rules match only their own resource.
  • MCP allowed_tools and disabled_tools also block at call time, not only in the tool list.
  • MCP tool output is marked as external content for the model.
  • Recipes whose list-form or roles: agents use a tool that is denied by default need it in tools.allow.
  • A deep-copied Agent asks for its own session approval.
  • execute_code always runs in the sandbox. The model no longer sees a sandbox_mode option.

Sandboxes and child environment

  • SubprocessSandbox raises UnenforceablePolicyError when asked for allow_network=False or allow_file_write=False (including SecurityPolicy.strict()), because it cannot enforce them. SandboxConfig.subprocess() now defaults to allow_network=True. Use the Docker or Sandlock backend to block network or writes.
  • With allow_subprocess=False (the default): execute(language="bash") is refused; Python that imports multiprocessing or calls os.fork, os.exec* or os.spawn* is refused; a computed importlib.import_module(name) is refused when imports are restricted.
  • Sandbox commands that name a folder holding a blocked path (for example ls ~ or cd /etc) are refused.
  • Sandbox write_file and read_file refuse .. and any symlink.
  • SandlockSandbox stays offline unless allow_network=True. A working_dir outside the sandbox is refused. SandboxConfig.native() run from a home folder raises.
  • The CLI SandboxExecutor network_isolated mode refuses network tools. A non-empty allowed_hosts raises, because it cannot be enforced. CPU, file-size and memory limits now apply.
  • Shell commands and code run by the model (ShellTools, the CLI shell, the code tool run_python, and the TypeScript sandbox, CodeAgent and shell tool) get only a short list of environment variables, such as PATH, HOME, LANG and TMPDIR. Name others in PRAISONAI_SHELL_ENV_ALLOWLIST, or pass them with env=.

Input validation

  • TypeScript NLPostgresClient.executeSQL runs exactly one statement. With readOnly, it runs inside a read-only transaction. Tables outside the configured list are refused.
  • IMAP search terms that contain " or \ are searched literally.
  • get_plugin_template() refuses multi-line values.
  • Invalid Couchbase names, identifiers that end in a newline, invalid SingleStore dimensions, a non-integer limit and non-numeric embeddings in several vector stores raise ValueError.
  • Deploy image references, file names, environment variable names and cloud CLI values are validated. GCP environment values that contain , are passed in gcloud's ^DELIM^ form.
  • Browser (CDP) selectors are passed as JSON string literals. Normal selectors work as before.
  • A tool name from the model resolves only to declared or registered tools.

Migration

Every new refusal or default, and the setting that adjusts it. "Checked" means the name was found in the release source.

You notice What to do Checked
A server refuses to start on 0.0.0.0 Set its token: ServerConfig(auth_token=...) for AgentServer; PRAISONAI_JOBS_API_KEY for the Jobs API; --api-key or PRAISONAI_SERVE_API_KEY for praisonai serve agents; --api-key for serve openai and rag serve; --token (or --read-only) for registry serve; auth: api-key or jwt with a key for recipe serve; AgentOSConfig(api_key=...) or PRAISONAI_AGENTOS_API_KEY for AgentOS; PRAISONAI_BROWSER_TOKEN for praisonai-browser; A2U_AUTH_TOKEN for serve a2u yes
praisonai call --public refuses Set CALL_SERVER_TOKEN yes
TypeScript MCP server or AgentOS refuses a public host Set authToken or PRAISONAI_MCP_AUTH_TOKEN (MCP server); apiKey or PRAISONAI_AGENTOS_API_KEY (AgentOS); { token } (N8N listener) yes
A2A.serve(), MCP SSE or launch() prints a token Set your own: A2A(auth_token=...) or PRAISONAI_LAUNCH_AUTH_TOKEN; MCP_SSE_AUTH_TOKEN for MCP SSE yes
A2A on loopback asks for a token Unset PRAISONAI_LAUNCH_AUTH_TOKEN, or send it yes
Webhook receiver stays on loopback Set its signing secret: TELEGRAM_WEBHOOK_SECRET, WHATSAPP_APP_SECRET, LINEAR_WEBHOOK_SECRET, AGENTMAIL_WEBHOOK_SECRET, or verify: {hmac: {secret: ...}} for the webhook channel. PRAISONAI_WEBHOOK_HOST=127.0.0.1 keeps a keyless dev setup local yes
HTTPApproval(host="0.0.0.0") refuses Pass allowed_approvers=[...] or set HTTP_APPROVERS yes
Jobs API (--factory) answers only /health Set PRAISONAI_JOBS_API_KEY, or PRAISONAI_JOBS_BIND_HOST=127.0.0.1 when it is local yes
Dashboard or replay viewer refuses a public host Set its token (name to be confirmed in the final build) no (change in progress)
A local server returns 403 behind a reverse proxy or to a browser page Keep Host: localhost in the proxy, or set the server's key n/a
Gateway refuses a browser page from another origin Add the origin to GATEWAY_ALLOWED_ORIGINS yes
413 for a large request Raise PRAISONAI_MAX_BODY_BYTES (MCP HTTP stream; the gateway uses the larger of this and 25 MB) yes
Gateway session not found after 1000 live sessions It was closed while idle; resume it from the store. No setting n/a
Gateway 403 on /v1/*, /mcp or pairing Give the token the write or pairing scope n/a
Email or AgentMail bot ignores unknown senders Set allowed_users, or unknown_user_policy: allow for an open inbox yes
A bot command is admin-only Add the user to admin_users yes
Bot attachment refused Move the file into the workspace, or add its folder to allow_roots yes
A fetch of a private or local address is refused Set ALLOW_LOCAL_CRAWL=true (development only) yes
JIRA tool refuses a URL Set JIRA_URL to your JIRA site yes
OpenAPIToolset raises about another origin Pass base_url= yes
A file tool refuses a path outside the current directory Pass a root: workspace_root= (FastContext, multiedit), or start in the right folder yes
grep_search or glob_files refuses a path Set PRAISONAI_WORKSPACE to the root you want searched name yes; new default in progress
SandboxExecutor refuses a path Add the folder to allowed_paths yes
Recipe bundle with links fails to install Use a Python with the tarfile data filter (3.10.12+, 3.11.4+, 3.12+) n/a
A project's MCP server does not start List its exact command line under mcp.trusted_servers in ~/.praisonai/config.yaml (PRAISONAI_MCP_TRUST still works) yes
A project file's endpoint, key, plugin or shell setting is ignored Set it in ~/.praisonai/config.yaml or the environment: OPENAI_BASE_URL and your provider key; PRAISONAI_ALLOW_PROJECT_PLUGINS=true; PRAISONAI_ALLOW_SHELL=true yes
An included recipe's tools.py does not load Set PRAISONAI_ALLOW_TEMPLATE_TOOLS=true yes
Old project "always allow" rules are ignored Approve again once; the choice is saved under $PRAISONAI_HOME yes
send_email, send_message or schedule_* asks for approval Approve when asked; for unattended agents pass approval=True (or a preset such as approval="full"); for bots use auto_approve_tools yes
Unmatched resource denied by PolicyEngine Add an allow rule, or use default_action="allow" yes
A recipe tool is denied Add it to tools.allow in the recipe yes
UnenforceablePolicyError from SubprocessSandbox Use the Docker or Sandlock backend, or set allow_network=True / allow_file_write=True yes
execute(language="bash") or a subprocess call is refused in the sandbox Set allow_subprocess=True in the sandbox policy yes
Sandlock has no network Set allow_network=True yes
SandboxExecutor raises on allowed_hosts Remove allowed_hosts; use network_isolated or no isolation yes
A shell command or code run is missing an environment variable Add its name to PRAISONAI_SHELL_ENV_ALLOWLIST (comma-separated), or pass env= yes
executeSQL refuses a statement Send one statement per call; add the table to the configured table list yes
ValueError from a store, deploy value or plugin template Fix the name, number or value that the message names n/a

Thanks

Thank you to everyone who reported issues privately. The people who reported the changes in this release are credited in the security advisory. We also thank these people, whose reports were confirmed and had already been fixed in earlier changes:

@0xRomSec, @1491342590, @1diot9, @a25370, @Akokonunes, @aurlep, @baeseungwon1010, @Carbene, @chakrapani150, @dajiaohuang, @EddieMurphy89, @gn00295120, @highlightime, @manus-pi, @manus-use, @mohammedix88, @rajivraj, @rexpository, @superbot-helper, @Vancir