Skip to content

Security: formio/uag

Security

SECURITY.md

Security Policy

Reporting a vulnerability

Please do not open a public GitHub issue for security vulnerabilities.

Report vulnerabilities privately via one of:

Include a description of the issue, steps to reproduce, and the affected package or image and its version. We will acknowledge receipt within 5 business days.

Supported versions

Package or image From this repository Supported
@formio/uag, image formio/uag Yes The latest published version
@formio/uag-sdk, @formio/uag-jev, @formio/uag-claude 2.x, @formio/uag-openai, @formio/uag-grok, @formio/uag-gemini, @formio/uag-js Yes, released with the UAG at its version The latest published version
@formio/uag-engines, image formio/uag-engines Yes, released with the UAG at its version The latest published version
@formio/uag-extras, image formio/uag-documents No: released from a separate repository, at a 2.x version of their own whose major is the UAG's The latest published version. Report vulnerabilities in them the same way.
The retired Claude integration, @formio/uag-claude 1.x and image formio/uag-claude Yes, from the 1.x branch Security fixes on its 1.3.x line

Scope notes

  • The UAG is a server you deploy. It holds credentials for the Form.io deployment it is bound to — PROJECT_KEY or ADMIN_KEY, which it uses to read the project, install a module's template, forward the requests of portal team members once Form.io's team rules allow them, and serve callers that authenticate with that key, but never to run a task or save its results for anyone else (a task started by a caller who presented the key, with no agent role, runs as administrator) — and signs its own JWTs, including the scoped tokens it sends an engine server for research, with JWT_SECRET. A scoped token carries the caller's own token sealed, so the engine server cannot read it, and is honored only by the project it was issued for. Enabled engines add model API keys: TYPESAFE_API_KEY (jev), CLAUDE_API_KEY or ANTHROPIC_API_KEY (claude), OPENAI_API_KEY (openai), XAI_API_KEY (grok), and GEMINI_API_KEY or GOOGLE_API_KEY (gemini). A remote engine adds the engine server key (UAG_ENGINE_<NAME>_KEY, the engine server's UAG_ENGINE_SERVER_KEY); with remote engines, the model keys live only on the engine server, which holds no Form.io credential. Treat all of these as secrets and supply them through your platform's secret store rather than a committed file.
  • Enabling an engine sends submission data to its provider's API (TypeSafe for jev, Anthropic for claude, OpenAI or the server it is pointed at for openai, xAI for grok, Google for gemini): a task's criteria, its input (or, without an input, the whole submission except the fields being answered), its uagContext values and today's date, plus, when a task lists research tools in uagTools, whatever those tools return. A file in a task's input or uagContext is sent as its text, and a module that calls an engine, such as AI Document, sends the documents it processes. A form's chat sends its agent engine: the UAG's chat instructions, the form's title, description and uagChatInstructions; the conversation (the newest messages within agentApi.chat.maxTranscriptChars); for each field the chat may collect, its path, label, type, description, placeholder, value rule, format and static options, and its current value (each value cut to 500 characters, all of them within maxTranscriptChars); the labels of the fields still needed, the optional ones and those to finish in the form; and today's date. Nothing else from the request's data is sent: not task fields, hidden fields or fields the chat cannot collect. Do not enable an engine for data that must not leave your deployment.
  • No model is ever given a tool that may write: the UAG validates every value and makes every write itself. Research tools (uagTools) are read-only, off by default, and run with the caller's identity — for an "Agent: Run task" action, the user who submitted, never the action's agent role; administrator access for servers calling the Agent API with the project or admin key — so list only the tools a task needs, and only on forms whose submissions you trust: text in a submission can steer what a model looks up.
  • Keep an engine server on a private network that only the UAG reaches, and do not publish its port: every request needs its key, but it is the gateway to your model keys. Outside its image it listens on 127.0.0.1 unless HOST says otherwise. Engine packages are code the UAG runs: UAG_ENGINES and UAG_ENGINE_PATH choose which, so treat them like any other deployment setting.
  • Modules and plugins run in the UAG process, with everything it can reach; the module API is not a sandbox. Use only those you trust, and treat what loads them (UAG_MODULE or /app/module, the plugins files UAG_PLUGINS or the add-ons and folders under /app/plugins) as deployment settings. Each add-on image, such as formio/uag-documents, is code that runs in the UAG process. Module routes (routes.form) get the agent operations' credential checks, body limit and rate limits, and on a form with uagAnonymous: "true" are open to anonymous visitors as those operations are; routes a module adds with the lower-level formRoutes get none of these. Module components are served publicly under /uag-js/, so they must hold no secrets.
  • Project and admin keys (x-token, x-admin-key) act as administrator, and the UAG refuses them (401) on any request with an Origin or Sec-Fetch-Site header, so they cannot be used from a browser. Never ship one to a browser: anything acting for a person should present that person's own Form.io or UAG token.
  • A visitor with no credential reaches a form's agent operations only when the form sets uagAnonymous: "true" and lets the Anonymous role create submissions, within per-address and total rate limits (AGENT_ANONYMOUS_RATE_LIMIT, AGENT_ANONYMOUS_TOTAL_RATE_LIMIT) kept by each UAG process. Each such request may call a model at your expense. Values the operations return are suggestions in the visitor's browser: re-decide anything that routes or approves on the server with Run task and uagAuthoritative.
  • OAuth sign-in for remote MCP clients is off unless MCP_OAUTH=true (with the UAG's database). Turn it on only when remote agents genuinely need to connect in. Its discovery documents publish the URL derived from each request (the forwarded headers when TRUST_PROXY is set) or BASE_URL; set TRUST_PROXY only for a proxy you control.
  • With JWT_SECRET the same as the Form.io Enterprise server's, the UAG can sign tokens Form.io accepts. It signs only short-lived (5-minute) tokens for the user a Run task action acts for: with the action's agent role, or, for research and chained actions with no agent role, with the user's own roles, admin roles left out. They never carry an administrator's access or an admin role, are never logged or stored, and reach an engine server only sealed inside a scoped token. Guard JWT_SECRET as you guard the Form.io server's.
  • Form.io user tokens (x-jwt-token) sent to the UAG are verified with Form.io and forwarded unchanged, never re-signed. A token tied to a Form.io session (one with a jti claim) is always checked with Form.io, even with a shared JWT_SECRET: sent as x-jwt-token, carried in a scoped token, or wrapped in a remote MCP client's UAG access token. A logout takes effect at the UAG within a minute, or two for an access token, whose check is cached too. A token that names no session is honored until it expires (JWT_EXPIRE_TIME).
  • Tasks run only for submissions sent to the UAG. Fields a task owns and marks uagAuthoritative are removed from what a client sends to the UAG, but Form.io itself has no per-field rule: to keep users from writing those fields by posting straight to Form.io, give the agent a role of its own and deny users write access on the form (see Project setup for agents).
  • The UAG's own database (MONGO) holds only its uag-* collections: authorization codes, stored by their SHA-256 hash with the token they exchange for sealed, and task-run records, which name the user a run acts for and never hold a token. It never holds submissions. Restrict the MONGO user to the UAG_DATABASE database.
  • NODE_TLS_REJECT_UNAUTHORIZED=0 disables TLS certificate verification for all outbound requests. It exists for local and internal deployments using self-signed certificates — never set it on a deployment reachable from outside your network.
  • CORS defaults to true, which allows every origin, for ease of local development. Set it to the origins that call the UAG from browsers (several separated by commas) before exposing it beyond a trusted network. /uag-js/*, the browser scripts and styles, is public to every origin whatever CORS says.
  • Local MCP clients, such as your own application or an engine server researching with the UAG's tools, connect outward to the UAG, so the UAG does not need to be publicly reachable for them to work. Prefer a private network over a public endpoint where possible.

There aren't any published security advisories