Security considerations

Understand how SQL Flow protects connections, credentials and data at rest, and what each component is allowed to do.

This page describes the security model of SQL Flow: which component talks to which, how each connection is protected, where secrets live, and how access is approved and audited. It applies to both deployment models.

Network exposure

• Agents and log brokers dial out. They reach the control plane over outbound HTTPS. The control plane never connects to them, and never connects to a source or target database. Connection tests in the UI run on an agent.
• Two listeners accept inbound connections, both inside your network. A log broker listens for agents on its data port (7003 by default). An apply agent in a relay pipeline listens for its capture agent (7420 by default). Nothing else on an agent or broker host listens.
• Row data never reaches the control plane. It flows from source to agent to target, or from capture agent to apply agent over a relay. Even a raw log export for support stays on the agent's disk. See Diagnostics for support.

See Network and ports for every connection.

The log broker

Capture modes that read log files never give the agent access to the database host. A log broker does that instead, and it's built to be verified:

• It's a small, single-purpose executable that serves file bytes and nothing else. Spectral Core provides its complete source code for your security audit on request.
• It serves only files inside the folders you allow with --allow-paths, and only to the agent addresses you allow with --allow-ips.
• It opens files with read-only operating-system handles, never writes to them, never connects to a database and holds no database credential.
• It records every refused connection, and every file it opens or refuses to open, in its audit log.

Most modes need only the log files in --allow-paths. Sybase ASE Reconstruction also reads data and LOB pages, so its broker serves the database's data and LOB device files, which hold table data. See Architecture: Log brokers.

Encryption in transit

Agents and brokers learn which certificate authority to trust from the join code: it carries the authority's SHA-256 fingerprint, and install keeps the authority only if it matches. You never handle the certificate yourself. A proxy that decrypts HTTPS breaks this check; see Proxies and TLS inspection.

Enrollment and approval

• Join codes. Add agent and Add broker mint a join code that is valid for 15 minutes and, by default, for one registration. See Install many agents for multi-use codes. A code can only create a pending registration in the account that minted it.
• Approval. A new agent or broker is Pending until a user approves it on the Agents page. A pending agent runs nothing, and a pending broker serves nothing. Check the host name and, for a broker, the Certificate SHA-256 under Details before you approve.
• Revocation. Revoke rejects an agent's credential at once. A revoked broker stops serving at once, and its identity is refused until you cancel the revocation.

See Agents and Log brokers.

Credentials and secrets

See Database credentials and secret references.

Data at rest

• Change spool. Every agent spool is encrypted with AES-256-GCM, with its own key. There is no setting that turns this off.
• Agent keys. The agent keeps its keys in its data directory. On Windows they are protected with DPAPI for the account the agent runs as. On Linux they are files readable only by the agent's user, in a directory only it can open. Keys are never written to logs.
• Control plane. It stores no row data. Its PostgreSQL database holds definitions, metadata, redacted diagnostics bundles and the encrypted secrets above. Protect it with PostgreSQL's own encryption and backups when you run it yourself.

Least privilege

• Agents run as a dedicated service account: NT SERVICE\SqlFlow.Agent on Windows, or the sqlflow-agent system user on Linux.
• Log brokers serve only the folders given in --allow-paths, read-only, and only the files a pipeline's key is scoped to. On Linux they run as the sqlflow-logbroker system user with read access granted on those folders. On Windows the service account depends on what it must read; see Log brokers.
• --allow-ips limits which addresses may connect to a broker's data port. The check runs before any TLS byte is exchanged. Set it on every broker.
• Database logins need only the privileges each capture mode checks for. See the source pages.
• Users have per-account roles. A Viewer can't change anything. See Accounts and team.

Sign-in protection

• Passwords need at least 12 characters, with an uppercase letter, a lowercase letter and a digit.
• A user created by an administrator must choose a new password at first sign-in. Until then every request except the password change is refused.
• Sessions last 8 hours and extend while in use. A deleted or demoted user loses access on the next request.
• Password-reset links expire after 1 hour and stop working once the password changes.
• By default, sign-in is limited to 10 attempts per minute per client address, and agent and broker registration to 5 per minute.

Diagnostics for support

When a pipeline stops on something SQL Flow support must look at, you can collect one of two files from the pipeline's Actions menu:

• Download diagnostics holds logs, commands and a redacted record of the stop, with no row data, passwords or keys. User and Account admin can request it. It goes through the control plane, which keeps it for 14 days.
• Save raw log bytes on agent (contains row data)… saves the raw SQL Server log blocks the pipeline stopped at, including the values they carry. Only an Account admin can request it, after confirming. Each agent saves its part in support-exports in its own data directory, readable only by the agent's service account, for up to 24 hours. Nothing is uploaded. Contact Spectral Core support for instructions to transfer the file securely.

Every diagnostics request, and every download of a diagnostics bundle, is recorded in the audit log. See Diagnostics for support for the steps.

Audit

• Control plane. Every change made through the UI or the CLI is recorded with the user, the request and the outcome, including refused attempts, and so is every download of a diagnostics bundle. See Audit log.
• Agent and broker hosts. Every install and uninstall action, and every refusal, is one line in agent.log or logbroker.log in the data directory. On Windows the same lines go to the Application event log under the sources SqlFlow.Agent and SqlFlow.LogBroker.
• Broker data port. Every connection decision (address refused, TLS failure, authorization, file open, read and close) is one JSON line in audit.jsonl in the broker's data directory. The file rolls at 256 MB and keeps 8 rolled files.

See also

• Deployment models
• Network and ports
• Database credentials and secret references
• Encrypted data support