Secrets and Security

Secrets and security keep sensitive values and external access under explicit control. SOIT stores secret references and resolves them through governed ports instead of passing plaintext secrets through business logic.

The secret reference model

A SOIT secret is a pointer, not a value: a tenant-scoped record with a name, a provider (vault | kms | local), and a reference path. The plaintext value lives in Vault (or a compatible KMS) and is resolved only at the adapter boundary, at call time:

• Agents, workflows, plugins, and tools refer to secrets as secret:name references in their specs.
• The secrets port resolves the reference when a governed adapter actually needs the value.
• Business rows, spec JSON, logs, traces, and API responses never contain plaintext secret values.

This means rotating a credential is a Vault operation — no agent or workflow definitions change.

Egress policy

External calls are deny-by-default. Before a tool call or HTTP request leaves the platform, the egress policy check runs at the port. Policy status is recorded with the call's audit evidence, so "which external destinations did this agent touch, and was each allowed" is a queryable question.

Private networks

New in v1.4.0. A model server, tool, or MCP server on a private or loopback address — a local Ollama, an on-premises vLLM — can be reached once its network is listed in EGRESS_PRIVATE_NETWORKS and the target is on the workspace or tenant egress allowlist:

# CIDR ranges governed calls may reach, here an Ollama on the same host
EGRESS_PRIVATE_NETWORKS=["127.0.0.1/32"]

• The list is empty by default, which keeps refusing every non-public address.
• Listing a network does not allow a target by itself: each target still needs an allowlist entry, set per scope with /api/v1/security/egress/workspace or /api/v1/security/egress/tenant.
• Entries are CIDR ranges, validated when the settings load; 0.0.0.0/0 is refused at startup.

Before v1.4.0 every non-public address was refused whatever the configuration, even with the egress policy off, so a local Ollama or an on-premises model server could not be used although an allowlist entry was documented as enough.

What the gateway enforces

Every external boundary crossing — model call, tool call, vector query, storage access, secret resolution — passes through a policy-aware port that consistently applies:

• Timeouts and retry policy (idempotent operations only).
• Rate limits per tenant and workspace.
• Audit logging tied to request_id, run_id, and step_id.
• Secret resolution by reference.
• Egress policy checks.

Because modules cannot call provider SDKs directly (the import rules forbid it), there is no code path that skips these controls.

Run content and personal data

Two workspace settings under Settings › Security decide what the runtime keeps and passes on:

• Content capture. Setting the workspace's content_capture to metadata_only stores run and step summaries, output previews, and error text as a length and a SHA-256 prefix, while statuses, tokens, costs, and timings are still recorded. A workspace admin may switch it on; only a tenant admin may switch it back. See Content-free runs.
• Personal data handling (since v1.3.0). The built-in content safety rules redact credentials by default and record personal data rather than rewrite it. A workspace can choose observe, redact, or block for personal data entering the runtime (prompts, retrieved text) and leaving it (model answers, tool arguments), as pii_action_inbound and pii_action_outbound on PATCH /api/v1/workspaces/{workspace_id}. Null follows the deployment's CONTENT_SAFETY_PII_ACTION, reported as pii_action_default. Workspace owners and admins may handle personal data more strictly than the deployment; handling it more loosely takes a tenant admin. Credentials keep the deployment's action, and the override applies to the built-in provider, not to an external classifier.

How it connects

• Models provider credentials are stored as secret references from day one.
• Plugins and MCP tools receive secrets through the same reference resolution.
• Audit evidence lands in Observe — the Audit Explorer (/observe/audits?gateway_type=tool) shows policy-gateway request and response evidence.
• Identity and Access controls who may manage the secret inventory.

API and UI surfaces

• API prefixes: /api/v1/secrets, /api/v1/security
• Related prefixes: /api/v1/plugins, /api/v1/runs
• Web routes: /settings/secrets (secret inventory), /system, /observe (audit evidence)