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.1by 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, includingserve({ host })), the call server, praisonai-browser remote mode, the TypeScript MCP server and the N8N listener. praisonai call --publicneedsCALL_SERVER_TOKEN.- Webhook receivers without a signing secret stay on loopback.
HTTPApprovalon a public host needsallowed_approvers. A2A.serve(), MCP over SSE andlaunch()still start on a public host, but print a generated token that every request must send.- A2A on loopback checks
PRAISONAI_LAUNCH_AUTH_TOKENwhen it is set./infoneeds 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 --factoryand no key answers only/health, unlessPRAISONAI_JOBS_BIND_HOST=127.0.0.1says it is local. - Keyless local servers refuse requests from other websites (a foreign or
nullOrigin) and requests with a non-localHost. If you use a reverse proxy, keepHost: localhostor 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/searchneedstools:read, and a method with no scope mapping needsadmin. - 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/mcpneed thewritescope, and/api/pairing/pendingneedspairing. - 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
/healthshows only the status. - People who cannot message a bot cannot press its buttons or run its slash commands.
- With
admin_usersset,/undo,/blueprintand/automationsare admin-only. - An email or AgentMail bot with no
allowed_usersand the defaultunknown_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_searchreturns 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-codeimagecommand, MCP OAuth and OIDC metadata, remote instruction sources and bot inbound media refuse private and loopback addresses. SetALLOW_LOCAL_CRAWL=trueto fetch local services in development. - Webhooks to
100.64.0.0/10are 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_TOKENfrom the environment needJIRA_URL, and send the token only to that origin. OpenAPIToolset(spec_url=..., auth=...)raises when the fetched spec names a server on another origin. Passbase_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_filesandglob_directoriestools default to the current directory.PRAISONAI_WORKSPACEsets 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_filesskips 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_namevalues with/,\or..are refused. The run still completes, without history. - Recipe bundles that contain links fail to install on a Python without the
tarfiledata filter. - Bot
send_messageattachments must be inside the agent workspace, the current directory orallow_roots. - Bot custom commands read
@fileonly under the bot's current directory. - The CLI
SandboxExecutor(BASIC and STRICT) refuses../,~and quoted paths into blocked folders, and paths outsideallowed_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_serversin~/.praisonai/config.yaml. - An MCP
urlthat 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, addallowpermission 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_TOOLSalone no longer loads an included recipe'stools.pyfrom outside the current directory. That needsPRAISONAI_ALLOW_TEMPLATE_TOOLS=true.create_tool_registry_with_overrides(tools_sources=...)needsPRAISONAI_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_emailand the other mail-sending tools,send_message,ask_conversation, mail drafts, archive andcreate_inbox,schedule_*changes, andexecute_code_with_tools. In a terminal you are asked. With no way to ask, the call is denied. Bots withauto_approve_toolsare 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-toolspre-approves only low-risk tools. PolicyEngine(default_action="deny")denies resources that no rule matches. YAMLmatch:rules match only their own resource.- MCP
allowed_toolsanddisabled_toolsalso 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 intools.allow. - A deep-copied Agent asks for its own session approval.
execute_codealways runs in the sandbox. The model no longer sees asandbox_modeoption.
Sandboxes and child environment
SubprocessSandboxraisesUnenforceablePolicyErrorwhen asked forallow_network=Falseorallow_file_write=False(includingSecurityPolicy.strict()), because it cannot enforce them.SandboxConfig.subprocess()now defaults toallow_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 importsmultiprocessingor callsos.fork,os.exec*oros.spawn*is refused; a computedimportlib.import_module(name)is refused when imports are restricted. - Sandbox commands that name a folder holding a blocked path (for example
ls ~orcd /etc) are refused. - Sandbox
write_fileandread_filerefuse..and any symlink. SandlockSandboxstays offline unlessallow_network=True. Aworking_diroutside the sandbox is refused.SandboxConfig.native()run from a home folder raises.- The CLI
SandboxExecutornetwork_isolatedmode refuses network tools. A non-emptyallowed_hostsraises, 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 andshelltool) get only a short list of environment variables, such asPATH,HOME,LANGandTMPDIR. Name others inPRAISONAI_SHELL_ENV_ALLOWLIST, or pass them withenv=.
Input validation
- TypeScript
NLPostgresClient.executeSQLruns exactly one statement. WithreadOnly, 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
limitand non-numeric embeddings in several vector stores raiseValueError. - 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