Database Proxy - agentsh

agentsh provides database-aware enforcement for Postgres-family traffic. Declare protected upstreams with db_services, route governed processes through the per-session proxy, and apply connection and statement policy before SQL reaches the database.
The shipped database runtime is Postgres-family only. PostgreSQL and Aurora Postgres use the primary supported path; Redshift and CockroachDB use the same protocol and classifier path with beta coverage. MySQL, MongoDB, Snowflake, BigQuery, Databricks, ClickHouse, MSSQL, Cassandra, Redis, and Oracle remain roadmap items.
The DB proxy is unavoidable for processes inside the agentsh-governed process tree, for declared db_services, assuming the agentsh supervisor and proxy are not compromised. Processes outside the session, undeclared databases, and compromised supervisor/proxy paths are out of model.
For each protected database service, agentsh starts a per-session Unix-socket listener and generates policy that redirects the agent's TCP connect to that listener. The proxy authenticates the connecting process with Linux peer credentials, evaluates startup and statement policy, forwards approved traffic upstream, and emits database audit events.
The proxy owns PostgreSQL BackendKeyData remapping for cancellation. Clients receive synthetic cancel keys; CancelRequest side-channel connections are correlated back through the proxy and evaluated with match_kind: cancel rules.
Do not give the agent a proxy socket path or a separate proxy host. Keep the agent's normal database configuration pointed at the declared upstream host:port, then run the agent inside an agentsh-governed session. When policies.db.unavoidability is observe or enforce, agentsh starts the per-session DB proxy and rewrites matching outbound connects to that proxy before traffic reaches the database.
The agent or application can keep using a normal Postgres connection string or libpq environment variables:
The upstream address in DATABASE_URL, PGHOST, or the application's DB config must match the declared db_services.*.upstream. Processes outside the agentsh session are not redirected, and traffic to undeclared database destinations is governed only by the rest of your network policy.
agentsh does not expose a standalone TCP listener for agents to connect to. The agent-facing address remains the original Postgres TCP host and port; agentsh uses connect_redirect to move that connection onto a per-session Unix socket internally. The socket path is generated per session and authenticated with Linux peer credentials, so operators should not bake it into application configuration.
Database policy lives in the normal policy YAML. A complete Postgres read-only policy with safe user-table redirection looks like this:
database_connection_rules evaluate before any SQL statement is classified. They control normal connection startup, cancellation, and replication-mode startup.
Replication startup and GSS encryption are default-deny. If explicitly allowed, the proxy switches to passthrough and emits a degraded_visibility_warning because statement-level inspection is no longer available.
database_rules run after the Postgres classifier converts a statement into one or more effects. Effects include an operation group, optional subtype, object set, and object-resolution confidence. Evaluation is order-independent: every object slot in every effect must be covered by a non-deny rule, and any matching deny wins.
audit is allow-with-observation. It forwards the statement and records decision.verb: "audit". For dangerous operations, agentsh warns at policy load unless the rule sets acknowledge_audit_on_dangerous: true.
Use require_where: true for narrow mutation rules where accidental full-table updates or deletes are the main risk:
This covers statements such as UPDATE public.users SET disabled = true WHERE id = 123, but it does not cover UPDATE public.users SET disabled = true. The guard is syntactic: a top-level WHERE must exist, but agentsh does not prove that the predicate is selective or tenant-safe.
require_where only changes whether that specific rule matches. If another unguarded allow, audit, or approve rule covers the same modify or delete effect, a no-WHERE mutation can still be permitted. Policy validation rejects require_where on rules whose operations expand beyond modify and delete.
Statement-level decision: redirect performs safe read-only Postgres relation replacement. It is intentionally narrow:
The runtime path is implemented for Simple Query and Extended Query Parse. Unsupported redirect shapes fail closed; the proxy does not forward the original SQL after a redirect decision that cannot be planned safely.
policies.db.unavoidability controls whether agentsh starts the proxy and installs generated routing and bypass-prevention rules for declared services.
When enabled, agentsh synthesizes policy before the session starts:
The destination egress deny is the security boundary. The command rules are useful diagnostics, but custom tunnel binaries are still caught when they try to reach the declared upstream destination.
Database proxying emits normal agentsh events, so session reports, event streams, and OCSF export can include database activity.
Statement text redaction is controlled by policies.db.log_statements. The default is parameters_redacted; set full only where storing raw SQL and parameter values is acceptable.
Use the database explain command to inspect classifier effects, object resolution, per-object coverage, warnings, and the final decision offline:
Catalog fixtures can be supplied for local debugging of relations and functions selectors. Fixtures are snapshots, not live DB connections; the runtime proxy resolves catalog metadata through the protected database service.