LogCarverGuard

LogCarverGuard

English | 繁體中文

一个 MCP 代理，让 AI 编码 Agent（Claude Code、Cursor，……）能够读取和写入 生产环境 SQL Server，而无需向其提供真实凭据或不受限制的权限。每条语句都以调用者自己的 SQL 登录名和权限运行；危险语句会在到达数据库前被拦截，所有内容都会写入审计日志。

状态： 早期阶段（v0.1）。

功能

AI agent --(MCP, API key)--> LogCarverGuard proxy --(EXECUTE AS the caller's own login)--> SQL Server

• 一个工具：execute_sql。 读取和写入都通过它执行。SELECT 会返回相应行（显示前 100 行，并注明其余行数）。写入操作会执行并记录在审计日志中。
• 由真正的 T-SQL 解析器决定允许执行的内容，而非通过匹配关键字判断，因此注释或字符串中的伪关键字不会产生影响。
• AI 永远看不到数据库密码。 代理持有一个服务登录名。每个人都会获得一个映射到其本人 SQL 登录名的 API 密钥；代理会模拟该登录名，因此其现有的 GRANT/DENY 仍决定其可以执行哪些操作。
• 服务登录名不需要 sysadmin 权限。 它需要对每个用户的登录名具有 IMPERSONATE 权限，并且在目标数据库中拥有一个数据库用户，以便连接。主机测试会通过一个非 sysadmin 的服务账号执行 SELECT、UPDATE，以及因权限被拒绝的 DELETE。
• 数据更改会在代理控制的事务中运行。 如果批处理中任何语句失败，包含 INSERT / UPDATE / DELETE 的整个批次都会回滚。DDL（ALTER TABLE……）、TRUNCATE 和 EXEC 会直接执行，不会作为批次的一部分回滚。调用者发起的 BEGIN TRAN / COMMIT / ROLLBACK 会被拦截。
• 审计日志存储在本地 SQLite 文件中：记录操作者、时间、SQL 语句，以及该语句是被拦截还是已执行。已执行的语句会在提交后记录。SQL Server 拒绝的语句（例如权限不足）或使用了无效密钥的请求不会被记录。

始终拦截

DROP TABLE、DROP DATABASE、RESTORE DATABASE / RESTORE LOG、ALTER DATABASE … SET、sp_executesql、xp_cmdshell、对变量或字符串执行动态 EXEC、身份切换（REVERT、EXECUTE AS、SETUSER）、权限更改（GRANT、DENY、REVOKE），以及调用者管理的事务（BEGIN TRAN、COMMIT、ROLLBACK、SAVE TRANSACTION）。

除非管理员将其加入允许列表，否则会被拦截

TRUNCATE TABLE、ALTER TABLE … DROP COLUMN，以及对具名存储过程执行的 EXEC（包括 INSERT … EXEC）。允许列表条目以 schema.name 的形式书写；语句中指定数据库或服务器（OtherDb.dbo.T、[srv].db.dbo.P）时，永远不会与允许列表中的条目匹配。

此列表有意保持精简。它并非“AI 可能造成的所有破坏”：DROP INDEX、sp_rename、BACKUP DATABASE 或链接服务器的 OPENQUERY 都不会经过特殊处理；如果真实登录名有权执行，它们就会运行。真正的安全边界是 SQL 登录名自身的权限，因此，每个 API 密钥都应对应一个权限尽可能低、但仍符合需求的账号，绝不能使用 sysadmin 或 db_owner。

本地模式

在自己的机器上运行，由 AI 工具通过 stdio 启动。无需服务、Docker 或 API 密钥。设置仅来自环境变量（不读取 appsettings.json 或命令行）。已在启用集成身份验证的 Windows 上测试。

dotnet tool install -g LogCarverGuard.Local
claude mcp add logcarverguard --env LOGCARVERGUARD_CONNECTION_STRING="Server=localhost;Database=MyDb;Integrated Security=true;TrustServerCertificate=true" -- logcarverguard

也可以通过 dnx 运行，无需安装（命令末尾加上 -- dotnet dnx LogCarverGuard.Local --yes）。

变量	用途	默认值
LOGCARVERGUARD_CONNECTION_STRING（或 _FILE）	运行语句时使用的登录名	必填
LOGCARVERGUARD_READ_ONLY	true 表示仅允许查询	false
LOGCARVERGUARD_AUDIT_DB_PATH	审计日志 SQLite 文件	本地应用程序数据文件夹下的 LogCarverGuard/audit.db
LOGCARVERGUARD_TRUNCATE_ALLOWLIST、LOGCARVERGUARD_EXEC_WHITELIST、LOGCARVERGUARD_ALTER_DROP_COLUMN_ALLOWLIST	与中央服务相同的允许列表	空（全部禁止）

只读模式允许执行 SELECT（不含 INTO），以及 SET、DECLARE 和 PRINT。其他所有内容都会被拦截并说明原因，包括即使在允许列表中的 EXEC、NEXT VALUE FOR，以及远程或文件数据源 OPENQUERY、OPENROWSET 和 OPENDATASOURCE（它们可能会在其他服务器上执行写入操作）。只读模式无法防范以下情况：调用带有副作用的 CLR 或扩展存储过程函数的 SELECT、运行时间过长或开销过大的查询，以及锁。还应只向登录名授予所需权限；防护机制是第二道防线，而不是第一道。

本地模式是什么，不是什么。 它是一种防护措施，用于防止 Agent 意外执行破坏性操作，但不是安全边界：

• 连接字符串及其中的凭据保存在你的机器和 AI 工具配置中。能够运行 shell 命令或读取该配置的 Agent，可以直接连接 SQL Server 并绕过此代理。
• 每条语句都使用连接字符串中的同一个登录名执行。系统不会区分个人身份；审计日志记录的是操作系统用户名，并且保存在本地文件中。
• 如需真正的安全边界，请使用下方的中央服务：SQL Server 只接受来自代理的连接，并且每个人都有自己的登录名。

安装中央服务

需要一台装有 Docker 的 Linux 主机，以及一台已启用 TCP/IP 和混合模式身份验证的 SQL Server。

1. 创建服务登录名，并允许其模拟每位用户自己的登录名：

   CREATE LOGIN logcarverguard_svc WITH PASSWORD = '…';
   GRANT IMPERSONATE ON LOGIN::[alice_sql_login] TO logcarverguard_svc;
   

   在目标数据库中，为服务登录名和每位用户的登录名都创建数据库用户，然后授予每位用户通常拥有的权限；代理不会扩大这些权限：

   CREATE USER logcarverguard_svc FOR LOGIN logcarverguard_svc;
   CREATE USER alice_sql_login FOR LOGIN alice_sql_login;
   GRANT SELECT, UPDATE ON dbo.Orders TO alice_sql_login;
   

2. 克隆并配置

   git clone https://github.com/caiderek/LogCarverGuard
   cd LogCarverGuard
   

   编辑 docker-compose.yml 并设置 LOGCARVERGUARD_SQLSERVER_CONNECTION_STRING。生产环境中建议使用挂载的机密文件，并设置 LOGCARVERGUARD_SQLSERVER_CONNECTION_STRING_FILE。

3. 启动

   docker compose up -d --build
   docker compose logs -f
   

4. 签发 API 密钥（--login 指用户自己的 SQL 登录名，而不是服务登录名）。密钥只会显示一次：

   docker compose exec logcarverguard dotnet cli/LogCarverGuard.Cli.dll \
     issue-key --owner alice --login alice_sql_login
   

5. 将 MCP 客户端指向 http://<host>:8080/，并在请求头 X-LogCarverGuard-Key 中发送密钥。

其他密钥相关命令：list-keys（不会显示密钥本身）和 revoke-key --id <n>。

配置

所有设置均为环境变量；其优先级高于 appsettings.json。

变量	用途	默认值
LOGCARVERGUARD_SQLSERVER_CONNECTION_STRING（或 _FILE）	代理的服务登录凭据	必填
LOGCARVERGUARD_AUDIT_DB_PATH	审计日志 SQLite 文件	logcarverguard-audit.db
LOGCARVERGUARD_APIKEYS_DB_PATH	API 密钥 SQLite 文件	logcarverguard-apikeys.db
LOGCARVERGUARD_TRUNCATE_ALLOWLIST	允许执行 TRUNCATE 的表	空（全部禁止）
LOGCARVERGUARD_EXEC_WHITELIST	允许通过 EXEC 执行的存储过程	空（全部禁止）
LOGCARVERGUARD_ALTER_DROP_COLUMN_ALLOWLIST	允许执行 DROP COLUMN 的表	空（全部禁止）
LOGCARVERGUARD_ALLOWED_CLIENT_IPS	允许连接的 IP / CIDR 范围，在密钥验证前检查	空（不限制）
LOGCARVERGUARD_TRUSTED_PROXIES	可信任其设置 X-Forwarded-For 的对端（仅在反向代理后使用）	空（不读取该标头）
ASPNETCORE_URLS	监听地址	取决于部署环境

在连接字符串中设置 Initial Catalog，指定 Agent 应操作的数据库。

生产环境加固

• 生产环境中不要保留 TrustServerCertificate=true。 示例连接字符串为了方便而使用此设置；它会关闭对 SQL Server 证书的验证，因此请安装可信证书并移除此设置。
• 使用 TLS。 密钥通过 HTTP 标头传输；如果使用纯 HTTP，密钥可能被窃取，持有密钥的人就能获得该用户的全部 SQL 访问权限。请在前端部署一个终止 TLS 的反向代理。出于这个原因，compose 文件默认绑定到 127.0.0.1。
• 除了配置主机防火墙外，还应通过 LOGCARVERGUARD_ALLOWED_CLIENT_IPS 限制可连接的客户端。使用反向代理时，还应设置 LOGCARVERGUARD_TRUSTED_PROXIES，否则每个请求看起来都像是来自代理。
• 备份 /data 卷。 其中存放审计日志和密钥哈希。
• 保持 .NET 运行时和 MCP SDK 为最新版本。

已知限制

• 仅支持 SQL Server。核心服务在 Linux（Docker）上运行；本地模式已在 Windows 上使用集成身份验证进行测试。
• 它只管控通过此 MCP 连接发送的 SQL。如果 Agent 还有其他工具（文件、API、云控制台），此代理无法看到或阻止这些操作。
• API 密钥是单个静态密钥：不支持 mTLS、设备绑定或短期令牌。
• 读取时不做数据屏蔽：如果某个账户可以通过 SELECT 查询敏感数据，Agent 就可以读取这些数据。
• SQL Server 自身的错误文本会原样返回给调用方。错误文本可能包含数据库、对象和登录名；此外，OPENROWSET / OPENQUERY 等功能不会被阻止，因此持有权限足够的密钥的 Agent 可以利用这些功能探测 SQL Server 能访问的内容。
• SELECT 在内存中最多保留 1000 行（显示前 100 行，并报告实际行数）。
• 审计日志是可直接读取的 SQLite 文件；没有用于浏览该日志的 MCP 工具。

构建和测试

dotnet build
dotnet test

集成测试需要本地 SQL Server 和具有 sysadmin 权限的 Windows 登录；测试会自行创建和删除 LogCarverGuard_* 数据库和登录名。

相关项目

LogCarver（免费，MIT）可从 SQL Server 事务日志中读取已删除的行。LogCarver.Mcp 可通过 MCP 将其提供给 AI 助手。

许可证

MIT，详见 LICENSE。