spec: usk/3.0

id: mgc_database_security

version: 1.1.0

name: 数据库凭证安全（零暴露版）

description: 使用 MGC Blackbox 实现数据库凭证的安全管理。支持 MySQL、PostgreSQL、SQLite、MariaDB 等数据库。将凭证本地加密存储，运行时动态获取，确保 AI 模型无法直接访问明文凭证。

author: MirginCipher 团队

license: MIT

tags: database, mysql, postgresql, sqlite, mariadb, security, credential-management, zero-exposure, mgc

platform_compatibility: windows, macos, linux

changelog:

- version: 1.1.0

changes:

- 添加完整示例章节与工作流模板

- 添加全面的故障排查章节

- 添加常见问题解答（FAQ）章节

- 添加反模式章节，包含正确实践

- 添加“何时使用 / 何时不使用”说明

- 添加能力边界解释

- 添加高级场景章节

- 添加 SKILL.md 和本地脚本模板

- version: 1.0.1

changes:

- 更新内容以强调 MCP 工具优于 CLI

- version: 1.0.0

changes:

- 初始发布，包含数据库零暴露模式

概述

数据库凭证安全是一项文档类技能，指导如何使用 MGC Blackbox 安全地管理数据库凭证。支持 MySQL、PostgreSQL、SQLite、MariaDB 等多种数据库。该方案使 AI 代理能够在执行数据库操作时，始终不暴露数据库密码或连接字符串给 AI 模型。

本技能不含可执行代码，适合自动审批。

本技能能实现的功能

阅读本文档后，AI 代理将掌握以下能力：

• 将数据库凭证（如 MySQL、PostgreSQL、SQLite、MariaDB 等）安全地存储在 MGC Blackbox 中
• 在运行时通过 MCP 工具检索凭证，避免 AI 接触明文信息
• 通过本地脚本执行数据库查询操作
• 安全管理多个数据库连接
• 在不修改代码的前提下轮换凭证
• 对数据库脚本进行封存，实现跨节点安全执行

适用场景

必须使用的情况

1. 生产环境

- 所有生产环境中的数据库访问都需采用安全凭证管理

- 防止凭证泄露至日志、提示词或 AI 上下文中

1. 自动化任务

- 需要访问数据库的定时脚本

- 连接数据库的 CI/CD 流水线

1. 多节点协作

- 节点 A 创建数据库脚本，节点 B 执行

- 使用 mgc_seal 命令，用目标节点公钥加密脚本

1. AI 需要访问数据库但不能看到密码

- AI 仅提供 SQL 语句

- 本地脚本负责凭证获取与执行

典型触发场景

• “安全地连接到 MySQL 数据库”
• “在不暴露密码的情况下执行 SQL 查询”
• “为 PostgreSQL 创建定时备份脚本”
• “安全地运行数据库迁移”
• “与其他节点安全共享数据库脚本”

不适用场景

本技能不适用于以下情况：

1. 公开数据库

- 无需认证即可访问的数据库

- 只读公共数据源

1. 本地开发且无敏感数据

- 临时测试数据库

- 使用模拟数据的演示环境

1. 交互式手动访问

- 用户每次手动输入凭证

- 直接使用数据库工具（如 DBeaver、MySQL Workbench 等）

能力边界

本技能具有明确的使用边界，用户需清楚理解：

本技能实现的功能

• 凭证存储：将数据库凭证安全地保存在 MGC Blackbox 中
• 凭证获取：通过 MCP 工具在运行时检索凭证
• 模式指导：提供数据库凭证管理的安全实践指南
• 多节点封存：对数据库脚本进行加密，仅限可信节点解密执行

本技能不实现的功能

• 非数据库客户端：不能直接连接数据库
• 非 SQL 执行器：不会运行 SQL 查询
• 非迁移工具：不处理数据库结构变更
• 非备份工具：不执行数据库备份操作

本技能仅提供凭证管理功能。所有敏感数据库操作（连接、查询、迁移、备份等）必须由本地脚本完成。

前置条件

1. 安装 MGC Blackbox：pip install mgc-blackbox
2. 启动 MGC 服务：mgc（默认运行于 http://127.0.0.1:57219）
3. Token 文件路径：~/.mgc/database/mgc_black_box/.mgc_token
4. 安装对应数据库驱动（如 mysql-connector-python、psycopg2 等）

完整示例：完整的数据库凭证工作流

本节演示从凭证存储到安全数据库操作的完整流程。

步骤 1：存储数据库凭证

MySQL 凭证存储

Tool: mgc_save
Parameters:
  info_type:   "config"
  info_owner:  "my_mysql_prod"
  content:     "{
    \"host\": \"db.example.com\",
    \"port\": 3306,
    \"database\": \"production_db\",
    \"user\": \"app_user\",
    \"password\": \"your_secure_password\"
  }"

PostgreSQL 凭证存储

Tool: mgc_save
Parameters:
  info_type:   "config"
  info_owner:  "my_postgres_prod"
  content:     "{
    \"host\": \"db.example.com\",
    \"port\": 5432,
    \"database\": \"production_db\",
    \"user\": \"app_user\",
    \"password\": \"your_secure_password\",
    \"sslmode\": \"require\"
  }"

SQL Server 凭证存储

Tool: mgc_save
Parameters:
  info_type:   "config"
  info_owner:  "my_sqlserver_prod"
  content:     "{
    \"host\": \"db.example.com\",
    \"port\": 1433,
    \"database\": \"production_db\",
    \"user\": \"app_user\",
    \"password\": \"your_secure_password\"
  }"

注意：请将占位符替换为实际数据库凭证。info_owner 是您的引用标识符——后续检索时需使用相同值。

步骤 2：在技能中引用凭证

# 在 SKILL.md 中定义：

database_reference:
  info_type:  "config"
  info_owner: "my_mysql_prod"
  # AI 仅接收引用，不会看到实际凭证

步骤 3：获取凭证

Tool: mgc_get
Parameters:
  info_type:  "config"
  info_owner: "my_mysql_prod"

MCP 工具返回存储的 JSON 内容。AI 接收到的信息包括：

• 主机和端口（非敏感）
• 数据库名称（非敏感）
• 用户名（可能非敏感）
• 但永远不会包含密码

步骤 4：执行数据库操作（概念性流程）

本地脚本负责实际数据库操作：

# 概念性脚本流程（不可直接执行）：

1. 调用 mgc_get，参数为 info_owner="my_mysql_prod"
2. 解析返回的 JSON 以获取连接参数
3. 使用数据库驱动建立连接
4. 执行 SQL 查询
5. 仅返回查询结果（不包含凭证）
6. 绝不记录或暴露密码

多节点示例：封存数据库脚本

当节点 A 需要节点 B 执行数据库脚本时：

节点 A：封存数据库脚本

Tool: mgc_seal
Parameters:
  info_type:   "script"
  info_owner:  "mysql_backup_script"
  ext01:       "python"
  ext04:       "-----BEGIN PUBLIC KEY-----\n...节点 B 的公钥...\n-----END PUBLIC KEY-----"

返回结果：使用节点 B 公钥加密的脚本胶囊

节点 B：执行封存脚本

Tool: mgc_get
Parameters:
  info_type:  "script"
  info_owner: "mysql_backup_script"
  action:     "run"

节点 B 使用私钥解密并执行脚本。节点 A 的数据库脚本对节点 B 完全不可见。

常见问题解答（FAQ）

MGC 相关

问：如果未安装 MGC 怎么办？

答：安装 MGC Blackbox：pip install mgc-blackbox

问：如果 MGC 未运行怎么办？

答：在终端运行 mgc 启动服务。服务默认运行于 http://127.0.0.1:57219

问：如何检查 MGC 是否正在运行？

答：打开浏览器访问 http://127.0.0.1:57219，若返回响应则表示服务正常运行。

问：端口 57219 已被占用怎么办？

答：停止占用该端口的其他程序，或配置 MGC 使用其他端口。

凭证管理

问：如何更新数据库凭证？

答：使用相同的 info_type 和 info_owner 再次调用 mgc_save，旧凭证将被覆盖。

问：如何管理多个数据库？

答：为每个数据库使用不同的 info_owner 值：

• "my_mysql_prod"
• "my_postgres_dev"
• "my_mysql_reporting"

问：如何轮换数据库凭证？

答：

1. 在数据库中更新凭证
2. 使用 mgc_save 以新凭证覆盖原存储（保持 info_owner 不变）
3. 本地脚本将在下次运行时自动获取新凭证

问：如果凭证找不到怎么办？

答：

1. 确认 info_owner 完全匹配（区分大小写）
2. 确认 info_type 正确
3. 列出所有已存储凭证：mgc_list

安全性

问：如何确保 AI 永远看不到数据库密码？

答：

1. 不在 SKILL.md 提示中包含凭证
2. 不将凭证作为参数传递给 AI
3. 始终使用 MGC 存储凭证
4. 本地脚本直接从 MGC 获取凭证
5. AI 仅接收非敏感的查询结果

问：AI 能否读取 MGC 中的凭证？

答：可以，如果 AI 调用了 mgc_get。除非你希望 AI 处理结果，否则不要调用 mgc_get。实现零暴露时，应由本地脚本调用 MGC，而非 AI 直接调用。

问：如果 AI 误将凭证记录到日志怎么办？

答：确保本地脚本：

• 不打印或记录凭证值
• 仅记录非敏感信息（如查询语句、行数等）
• 采用安全的日志策略

多节点场景

问：如何安全共享数据库脚本？

答：

1. 节点 A 创建数据库脚本
2. 使用 mgc_seal 并指定节点 B 的公钥
3. 节点 B 使用 mgc_get 且 action="run" 解密并执行

问：能否对多个节点封存同一脚本？

答：目前 mgc_seal 一次只能针对一个节点。若需分发给多个节点，需分别使用各节点的公钥进行封存。

反模式（Anti-Patterns）

常见错误与正确做法

❌ 反模式 1：在脚本中硬编码数据库密码

# 错误 —— 永远不要这样做
def connect_to_db():
    connection = pymysql.connect(
        host="db.example.com",
        password="secret_password"  # 明文暴露！
    )

正确做法：

# 正确 —— 从 MGC 获取
def connect_to_db():
    credentials = get_credentials_from_mgc("my_mysql_prod")
    connection = pymysql.connect(
        host=credentials["host"],
        password=credentials["password"]
    )

❌ 反模式 2：在 SKILL.md 中暴露连接字符串

# 错误 —— 在 SKILL.md 中
使用以下数据库凭证：
- 主机：db.example.com
- 密码：my_secret_password

正确做法：

# 正确 —— 在 SKILL.md 中
数据库凭证已安全存储于 MGC。
引用：info_owner="my_mysql_prod"
AI 不应直接处理凭证。

❌ 反模式 3：将密码放入 ext04 字段

// 错误
{
  "info_owner": "my_database",
  "ext04": "password=secret123"  // 此字段绝不能用于密码！
}

正确做法：

// 正确
{
  "info_owner": "my_database",
  "info_type": "config",
  "ext04": "-----BEGIN PUBLIC KEY-----\nNodeB_Public_Key...\n-----END PUBLIC KEY-----"
}
// ext04 仅用于封存时的公钥

❌ 反模式 4：将凭证写入本地文件

# 错误
echo "password=secret" > db_credentials.txt

正确做法：

# 正确
# 使用 mgc_save 存储到 MGC
# 永远不要将凭证写入磁盘文件

❌ 反模式 5：将凭证作为提示参数传递

# 错误
执行 SQL：SELECT * FROM users WHERE password='{user_password}'

正确做法：

# 正确
使用存储在 MGC 中的凭证执行 SQL。
引用：info_owner="my_mysql_prod"
本地脚本负责凭证获取。

❌ 反模式 6：在数据库脚本中记录凭证

# 错误
def execute_query(sql):
    creds = get_credentials_from_mgc("my_database")
    print(f"连接使用密码：{creds['password']}")  # 明文暴露！
    # ... 执行查询

正确做法：

# 正确
def execute_query(sql):
    creds = get_credentials_from_mgc("my_database")
    logger.info(f"连接至 {creds['host']}")  # 不记录密码
    # ... 执行查询

故障排查

常见错误与解决方案

错误：凭证未找到

症状：mgc_get 返回空或报错

解决方案：

1. 确认 info_owner 完全匹配（区分大小写）
2. 确认 info_type 正确
3. 列出所有已存储凭证：mgc_list
4. 必要时重新存储凭证

错误：info_type 不匹配

症状：API 返回错误数据或报错

解决方案：

1. 检查保存时使用的 info_type
2. 检查检索时是否使用了相同的 info_type
3. 常见类型："config"、"credential"、"script"

错误：数据库连接失败

症状：无法连接数据库

解决方案：

1. 确认 MGC 中的凭证正确
2. 检查数据库服务器是否运行
3. 检查网络连通性
4. 确认端口正确（MySQL: 3306，PostgreSQL: 5432，SQL Server: 1433）
5. 检查防火墙是否允许连接

错误：凭证无效

症状：连接时认证失败

解决方案：

1. 检查 MGC 中用户名和密码是否正确
2. 确认密码是否最近更改过
3. 使用 mgc_save 更新 MGC 中的凭证
4. 确认用户拥有数据库访问权限

错误：MGC 未运行

症状：无法连接 MGC 服务

解决方案：

1. 在终端运行 mgc 启动服务
2. 检查服务地址：http://127.0.0.1:57219
3. 确认 token 文件存在：~/.mgc/database/mgc_black_box/.mgc_token
4. 必要时重启 MGC

错误：MCP 工具调用失败

症状：工具执行出错

解决方案：

1. 确认 MGC 正在运行
2. 检查服务地址
3. 确认 token 文件可读
4. 检查 MCP 工具参数是否正确

错误：权限不足

症状：无法访问 MGC 存储

解决方案：

1. 检查 ~/.mgc/ 目录的文件权限
2. 确认 token 文件可读
3. 使用适当权限运行 MGC

MGC Blackbox API 参考

服务端点

• 基础地址：http://127.0.0.1:57219
• Token 文件：~/.mgc/database/mgc_black_box/.mgc_token
• Token：从 token 文件读取的字符串，所有 API 调用必需

获取凭证 API

端点：/api/mgc/sensitive/get

方法：POST

请求头：

• X-MGC-Token: (从 token 文件读取的字符串)
• Content-Type: application/json

请求体字段：

• info_type: "config"
• info_owner: 自定义标识符

响应字段：

• code: 状态码
• data.content: 包含凭证的 JSON 字符串

保存凭证 API

端点：/api/mgc/sensitive/save

方法：POST

请求头：同上

请求体字段：

• info_type: "config"
• info_owner: 标识符
• content: 凭证的 JSON 字符串

高级场景

多数据库凭证管理

管理多个数据库的凭证：

# 存储标识符：
info_owner: "my_mysql_prod"      # MySQL 生产环境
info_owner: "my_postgres_prod"   # PostgreSQL 生产环境
info_owner: "my_mysql_dev"       # MySQL 开发环境
info_owner: "my_mysql_test"      # MySQL 测试环境

多节点数据库任务分发

节点 A：准备数据库操作脚本

Tool: mgc_seal
Parameters:
  info_type:   "script"
  info_owner:  "mysql_migration_script"
  ext01:       "python"
  ext04:       "-----BEGIN PUBLIC KEY-----\nNodeB_Public_Key...\n-----END PUBLIC KEY-----"

节点 B：执行封存脚本

Tool: mgc_get
Parameters:
  info_type:  "script"
  info_owner: "mysql_migration_script"
  action:     "run"

凭证轮换

定期轮换数据库凭证：

1. 在数据库中生成新凭证
2. 更新 MGC 存储：

   Tool: mgc_save
   Parameters:
     info_type:   "config"
     info_owner:  "my_mysql_prod"
     content: