Vericto Proxy mode (local, PostgreSQL)

Vericto Proxy

无需修改代码，即可拦截破坏性 SQL，防止其到达数据库，无论 SQL 来自 AI Agent、脚本还是人员。

AI Agent、脚本和人员都会使用真实凭据对生产环境运行 SQL。 没有人会在每条语句运行前逐一审查，而数据库角色决定的是用户 可以访问哪些内容，而不是这条特定语句是否应该运行。一个没有 WHERE 的 DELETE 就能清空整张表。对错误列执行 SELECT，就可能将电子邮件或卡号 复制到结果流向的任何地方。

vericto-proxy 位于客户端与数据库之间，使用数据库自身的 线协议。它会使用 vericto-engine AST 解析器解析每条查询， 根据规则进行检查，然后将查询转发到真实数据库，或通过普通 SQL 错误将其拦截。应用程序只需更改连接 字符串中的主机和端口。

许可证。 源码可用，采用 FSL-1.1-ALv2 许可证。你可以自行托管并免费使用，包括 在营利性公司的生产环境中使用。许可证不允许的情形是竞争性使用： 在商业产品或服务中向他人提供本软件，且该产品或服务替代本软件 或提供实质上类似的功能，例如基于本软件构建的 SQL 防火墙 服务。每个版本也会在 Vericto 将其发布两年后转为 Apache-2.0 许可证。 LICENSING.md 解答了常见问题。

一个代理实例连接一个数据库，并且只使用一种线协议；部署时通过 VERICTO_WIRE_PROTOCOL 选择：

VERICTO_WIRE_PROTOCOL	数据库	拦截响应
postgres (default)	PostgreSQL	原生 ErrorResponse SQLSTATE 42501
mysql	MySQL	原生 ERR_Packet ERROR 1142

其他所有内容——配置、评估、遥测——在各引擎之间完全相同。只有上述值和（可选的）默认端口会改变。

不使用 AI，也没有随机启发式方法——相同输入始终产生相同结果。

其他方言（Oracle、SQL Server、Snowflake、SQLite）：可通过 HTTP API、CLI 或 MCP 进行评估； 它们没有线代理。Snowflake 完全没有 TCP 线协议，因此 VERICTO_WIRE_PROTOCOL=snowflake 会在代理启动时因错误而终止。 SQLite 是链接到应用程序中的库，也没有线协议： 它的 SQL 会在运行前于应用程序中进行检查。

---

使用 Docker 试用

只需要 Docker：无需账户、API 密钥或构建。此操作会启动一个临时 Postgres，在它前面部署带有内置规则集的代理，并使用 Postgres 镜像自带的 psql 发送几条查询。密码 demo 仅用于这个一次性数据库。

docker network create vericto-demo
docker run -d --name vericto-demo-db --network vericto-demo \
  -e POSTGRES_PASSWORD=demo postgres:17
docker run -d --name vericto-demo-proxy --network vericto-demo \
  -e UPSTREAM_HOST=vericto-demo-db vericto/vericto-proxy:4.23.0
until docker exec vericto-demo-db pg_isready -q -h localhost -U postgres; do sleep 1; done

docker run --rm --network vericto-demo postgres:17 \
  psql postgresql://postgres:demo@vericto-demo-proxy:5433/postgres \
  -c "CREATE TABLE users (id int PRIMARY KEY, email text)" \
  -c "INSERT INTO users VALUES (1, '[email protected]'), (42, '[email protected]')" \
  -c "DELETE FROM users" \
  -c "DELETE FROM users WHERE id = 42" \
  -c "SELECT id, email FROM users"

镜像来自 Docker Hub；ghcr.io/vericto/vericto-proxy:4.23.0 提供相同的 摘要（见 Docker）。

不带 WHERE 的 DELETE 不会到达数据库；带 WHERE 的则会：

CREATE TABLE
INSERT 0 2
ERROR:  Vericto blocked this query [VERICTO-001] — AST node: DeleteStmt > WhereClause = NULL. Suggestion: DELETE FROM users WHERE id = $1
DELETE 1
 id |      email
----+-----------------
  1 | [email protected]
(1 row)

docker logs vericto-demo-proxy 会显示判定结果。要在自己的数据库前部署代理，请参阅 Docker 和 连接字符串。使用以下命令清理：

docker rm -f vericto-demo-db vericto-demo-proxy && docker network rm vericto-demo

如需通过断言测试文章中扩展协议、管道、预备策略刷新、TLS/SCRAM、取消、COPY 和 PostgreSQL 18 场景， 请运行 examples/postgres-wire-article/run.sh。

---

架构定位

Your app / ORM
     │
     │  SQL wire protocol (proxy listen port, default 5433)
     ▼
 vericto-proxy   ──── vericto-engine (lib) ────►  ALLOWED / BLOCKED
     │
     │  (if ALLOWED) forwards query
     ▼
 Real database upstream

将 DATABASE_URL 的主机指向 vericto-proxy，而不是实际数据库。 无需更改代码——你的 ORM/驱动程序不会感知代理的存在。

---

拦截内容

使用内置规则集时，以下操作不会到达数据库：

• 不带 WHERE 的 DELETE / UPDATE
• DROP TABLE、DROP SCHEMA、TRUNCATE
• OR 恒真 SQL 注入（WHERE id = $1 OR 1=1）
• ALTER TABLE DROP COLUMN / RENAME
• … 完整规则列表 →

严重性较低的问题——不带 WHERE 的 SELECT *、不带 LIMIT 的 SELECT、 未显式列出列名的 INSERT——会被转发并记录，而非拦截。启用控制平面连接后， 工作区策略会根据每项问题的严重性决定采取何种操作。

限制读取范围（4.17.0）。 要限制 Agent 的读取范围，而不只是标记问题，可使用带有 action: { rewrite_limit: n } 的业务策略（改写模式中的 LIMIT 上限模板），让代理在 Postgres 和 MySQL 中为简单语句和预备语句添加 LIMIT n，或将更大的 LIMIT 调低。此功能需要设置 VERICTO_POLICY_RULES=enforce；请参阅 docs/CONFIGURATION.md。

被拦截的查询会作为当前协议的原生错误返回（见上表），因此应用程序无需进行特殊处理。

PostgreSQL 管道和预备语句（4.17.3）。 本地拦截和会话上下文回复会在其上游响应周期的准确位置按序返回，且排在所有更早的管道结果之后。后端消息会按帧处理，因此即使是较大的行或 COPY 消息，也不会被合成回复拆分。命名和未命名的预备 SQL 会在规则、策略、主体或会话上下文刷新后，于 Bind 和 Execute 阶段重新检查；可能读取时间的业务策略（time.*）会在每次 Execute 时检查，其他策略则保留在相同规则、策略、规则包和会话上下文下得出的判定（见 docs/CONFIGURATION.md）。如果掩码或 rewrite_limit 现在需要不同的 SQL，代理会返回 VERICTO-PREPARED-STALE，客户端必须关闭并重新预备该语句。即使源语句已关闭或被替换，Portal 仍会保留其绑定时使用的计划。PostgreSQL COPY BOTH/复制操作会通过关闭会话来拒绝，以避免响应顺序错乱。Agent 访问策略拒绝的 FunctionCall 也会导致会话关闭，因为基于 Query 的顺序标记会改变未命名语句的状态。本次补丁不会改变 MySQL 行为：MySQL 预备语句仍只在预备时检查，不会在之后执行时重新检查。

---

敏感列

可在 Vericto 控制面板中按数据库标记敏感列（Team 和 Enterprise 方案）。这些标记会随规则集传递到代理（/sync/rules，因此需要控制平面连接和 VERICTO_DATABASE_ID），并在查询发送过程中、数据库看到查询之前强制执行。查询读取多个已标记列时，最严格的策略优先（block > mask > flag）。**代理会强制执行策略：**不同于只提供建议的 Validation API 或 CLI，代理的决定就是数据库收到的内容。

策略	Postgres	MySQL
block	查询不会到达数据库：ErrorResponse，SQLSTATE 42501	不会到达数据库：ERR_Packet，ERROR 1142
flag	按原样转发，记录为 FLAGGED	相同
mask	代理会转发改写后的查询，将列替换为遮罩值（full、last4、email 或 hash），并使用该列的原名称，绝不转发原始查询。客户端会收到遮罩后的值。	相同：代理会在同一条 COM_QUERY 或 COM_STMT_PREPARE 中转发改写后的查询，绝不转发原始查询。

如果改写无法可靠完成，代理会以 VERICTO-085 阻止查询，而不是转发原始查询。对含有被遮罩或被阻止列的表执行 SELECT * 会被阻止；请列出具体列。完整行为（两种协议、预处理语句、故障安全情况、解析错误、遥测、已知限制）见 docs/SENSITIVE_COLUMNS.md。

---

Agent 访问权限

可在 Vericto 控制面板中按数据库用户设置允许列表（Team 和 Enterprise 方案）：该用户可以读取哪些表和列，以及可以写入哪些表和列。其他操作都会被拒绝（VERICTO-087）。这些策略会随规则集传递到代理（/sync/rules，因此需要控制平面连接和 VERICTO_DATABASE_ID），以数据库用户为键；还可选用 "*" 为所有未列出的用户设置默认策略。

会话身份由通过身份验证的数据库用户确定，因此请为每个 Agent 创建单独的数据库用户，并为该用户设置策略。在策略约束下，每处引用都会被计入（WHERE、JOIN、子查询、RETURNING，不仅仅是查询返回的内容）；DDL 始终会被拒绝，且无法在会话内部更改身份（SET ROLE、USE、COM_CHANGE_USER 等操作都会被拒绝）。在 observe 模式下，策略会记录本应拒绝的操作，并转发查询。

完整行为（名称解析、写入和锁、打开的会话中的策略变更、遥测、已知限制）见 docs/AGENT_ACCESS.md。

**紧急停止开关（4.18.0）。**所有者或管理员在控制面板的 Incident response 面板中阻止某个 Agent（或工作区中的所有 Agent）后，从下一次规则同步开始，代理会以 VERICTO-105 和 Runtime API 返回的紧急停止开关消息，拒绝该数据库用户的所有语句；此操作在任何评估之前、所有模式下生效，包括 SELECT 1、SET 和 BEGIN，以及阻止前已准备的语句。解除阻止后，会话将在下一次同步时恢复。参见 docs/AGENT_ACCESS.md。

---

MCP：Agent 通过 Vericto 执行 SQL（代理模式）

vericto-proxy mcp（4.21.0）是面向 AI Agent 的 MCP 服务：Claude Code、Cursor、 Codex 或任何 MCP 客户端都会获得一个 execute_sql 工具，且没有数据库凭据。 每条语句都会先经过评估，服务随后在 PostgreSQL 上只读执行评估结果（或策略对其进行的改写）， 并在始终回滚的事务中运行，同时限制行数、数据大小和执行时间。它还提供 describe_schema、本地 check_sql 和 whoami。开发者的机器可通过 stdio 使用，团队可通过 Streamable HTTP 使用。

无需账户即可试用。 未配置控制平面时，它会基于内置规则集在本地运行（即 TCP 代理独立运行时使用的规则），且不会报告任何内容：

claude mcp add vericto-db -- \
  docker run -i --rm --user "$(id -u):$(id -g)" \
    -v ~/.config/vericto/shop.url:/run/secrets/db.url:ro \
    vericto/vericto-proxy:4.23.0 /usr/local/bin/vericto-proxy mcp --database-url-file /run/secrets/db.url

连接到 Vericto，以使用自定义规则、业务策略、敏感列屏蔽、审计和仪表板：添加 -e VERICTO_API_KEY=vtro_... -e VERICTO_DATABASE_ID=<id> （并将两者传入容器）。已配置的控制平面绝不会被内置规则替代：在首个签名规则包生效之前，服务会返回 NOT_READY。

前提是 Agent 没有其他数据库凭据，经过检查的内容就是实际执行的内容：如果服务在其环境中发现数据库凭据，会发出警告。每种客户端的设置方法（无论是否有账户）、HTTP 模式、限制和安全说明，请参阅 docs/MCP.md。

---

配置

所有变量都与数据库方言无关——相同的名称适用于每种数据库引擎。

必需项

变量	说明
UPSTREAM_HOST	要代理连接的真实数据库的主机名

端口

变量	默认值	说明
UPSTREAM_PORT	协议默认值¹	上游数据库的端口
PROXY_LISTEN_PORT	协议默认值¹	代理监听的端口

¹ 默认值取决于 VERICTO_WIRE_PROTOCOL：Postgres 的上游端口为 5432 / 监听端口为 5433；MySQL 的上游端口为 3306 / 监听端口为 3307。

其他配置

其余配置均为可选，详见 docs/CONFIGURATION.md：

• 控制平面连接 （VERICTO_API_URL、VERICTO_API_KEY、VERICTO_DATABASE_ID，三项需同时配置）：将决策上报至 Vericto API，并同步工作区的规则和策略。未配置时，代理仍会使用内置规则集进行防护，但不会上报任何信息。还介绍了遥测缓冲区、 超过每月配额时的处理方式、 磁盘暂存区大小以及 在同一卷上运行多个代理。
• 每个链路上的 TLS：客户端→代理，以及代理→数据库。对于 MySQL，两个链路必须同时启用 TLS，或都不启用。
• 查询准入限制： VERICTO_MAX_QUERY_BYTES（TCP 默认值为 1 MiB；MCP 仍为 64 KiB），以及针对二元运算符超过 10,000 个的表达式的线性预解析保护 （VERICTO_MAX_BINARY_OPERATORS）。
• 业务策略规则 （VERICTO_POLICY_RULES，默认值为 off）：此功能为预览版，除非手动启用，否则处于关闭状态；关闭时，代理会跳过基于主体的策略评估。PostgreSQL 响应排序和预处理语句跟踪仍会启用。启用后，代理只会应用 Ed25519 签名验证通过的同步包 （对于 Vericto 以外的控制平面，请参阅 VERICTO_BUNDLE_SIGNING_KEYS）。
• 面向负载均衡器的 健康检查（VERICTO_HEALTHZ_PORT）。
• 可观测性：日志，以及以 Prometheus 或 CloudWatch EMF 格式提供的指标。
• CPU 配置：每个 vCPU 的容量、扩容时机（任务 CPU 使用率达到预留量的 50–60% 时），以及 VERICTO_WORKER_THREADS（默认根据容器的 CPU 限制配置；0.5 vCPU 的任务使用 1 个工作线程）。
• 引擎专属说明，包括 MySQL 详情（TLS、协议压缩）。

如需从源代码运行并运行测试，请参阅 CONTRIBUTING.md。

---

Docker

发布镜像托管在 Docker Hub 上，名称为 vericto/vericto-proxy（从 4.14.1 起），也托管在 ghcr.io/vericto/vericto-proxy，支持 linux/amd64 和 linux/arm64，拉取时无需凭据。发布工作流会将其推送到 GHCR 的多架构索引复制过去，因此两个注册表在相同标签（<version>、<major>.<minor>、<major> 和 latest）下提供相同的摘要：从你的环境允许访问的注册表拉取即可。

# Postgres. On Linux, add --add-host=host.docker.internal:host-gateway
docker run --rm -e UPSTREAM_HOST=host.docker.internal -p 5433:5433 \
  vericto/vericto-proxy:4.23.0

# MySQL
docker run --rm \
  -e VERICTO_WIRE_PROTOCOL=mysql \
  -e UPSTREAM_HOST=host.docker.internal \
  -p 3307:3307 \
  vericto/vericto-proxy:4.23.0

# The same image from GHCR
docker pull ghcr.io/vericto/vericto-proxy:4.23.0

从现在起发布的镜像都附带构建来源证明（Sigstore、GitHub Actions），将其摘要关联到此仓库、发布工作流和提交。在部署前验证来源证明，并按摘要部署：

gh attestation verify oci://ghcr.io/vericto/vericto-proxy:<version> --repo vericto/vericto-proxy

# Docker Hub (4.14.1 and later): the same digest, attested under its Docker Hub name
gh attestation verify oci://docker.io/vericto/vericto-proxy:<version> --repo vericto/vericto-proxy

每个平台的镜像（4.15.2 及更高版本）还附带签名的 SPDX SBOM 证明，该证明针对平台清单的摘要生成（docker buildx imagetools inspect 会列出两者）：

gh attestation verify oci://ghcr.io/vericto/vericto-proxy@<platform digest> \
  --repo vericto/vericto-proxy --predicate-type https://spdx.dev/Document/v2.3

运行时基础镜像为 Chainguard glibc-dynamic （4.15.2 及更高版本；此前使用 debian:bookworm-slim）：包含 glibc、libgcc 和 CA 证书包，不含 shell 和包管理器。代理以 65532:65532（nonroot）身份运行（截至 4.15.1 为 1001:1001，因此请对旧镜像写入的卷运行 chown，或传入 --user 1001:1001）。健康检查以 exec 形式调用二进制文件，而非 shell： ["CMD", "/usr/local/bin/vericto-proxy", "healthcheck"]（Docker Compose 的 healthcheck.test、ECS 的 healthCheck.command）。它会连接健康检查监听器 （VERICTO_HEALTHZ_PORT），连接成功或未设置端口时退出码为 0，否则为 1。在此镜像中，CMD-SHELL 检查、bash -c、curl 或 wget 都会失败。

要从此检出版本构建镜像：

docker build -t vericto/proxy:local .

使用 Docker Compose：

proxy:
  image: ${VERICTO_PROXY_IMAGE:-vericto/vericto-proxy:4.23.0}
  ports:
    - "5433:5433"
  environment:
    UPSTREAM_HOST: postgres
    UPSTREAM_PORT: "5432"
    PROXY_LISTEN_PORT: "5433"
    # For MySQL: VERICTO_WIRE_PROTOCOL: "mysql" + the matching ports.
    # Optional — uncomment for telemetry + rule sync (all three together):
    # VERICTO_API_URL: "https://api.vericto.com"
    # VERICTO_API_KEY: "${VERICTO_API_KEY}"
    # VERICTO_DATABASE_ID: "${VERICTO_DATABASE_ID}"

---

连接字符串

	连接字符串
通过代理连接 Postgres	postgres://user:pass@localhost:5433/mydb
通过代理连接 MySQL	mysql://user:pass@localhost:3307/mydb

凭据与直接连接时相同，只有主机和端口会变化。

---

贡献

线协议、TLS、遥测和部署相关修复应提交到此处；规则和解析器变更应提交到 vericto-engine。 请参阅 CONTRIBUTING.md 和 SECURITY.md。

许可证

版权所有 2026 Vericto S.A.S. 自 4.14.0 起，源代码依据 Functional Source License, Version 1.1, ALv2 Future License （SPDX FSL-1.1-ALv2）提供：可出于除竞争用途以外的任何目的使用、修改和再分发；每个版本在发布两年后转为 Apache-2.0。4.13.0 及更早版本仍依据 Elastic License 2.0 提供。LICENSING.md 解答常见问题，包括嵌入式 vericto-engine 的许可方式；另请参阅 NOTICE 和 TRADEMARKS.md。 如需商业许可证，请联系 [email protected]。

Docker 镜像在 /usr/share/doc/vericto-proxy/ 中附带 LICENSE、NOTICE 和 THIRD_PARTY_LICENSES（二进制文件中编译的所有依赖项的许可证），并包含标签 org.opencontainers.image.licenses=FSL-1.1-ALv2：

# The image has no shell or `cat` (4.15.2 and later), so copy the file out:
id=$(docker create ghcr.io/vericto/vericto-proxy:latest)
docker cp "$id":/usr/share/doc/vericto-proxy/THIRD_PARTY_LICENSES - | tar -xO
docker rm "$id" >/dev/null