database-credential-security-zero-exposure-edition

原始内容

---

spec: usk/3.0
id: mgc_database_security
version: 1.2.0
name: Database Credential Security (Zero‑Exposure Edition)
description: Secure database credential management using MGC Blackbox. Supports MySQL, PostgreSQL, SQLite, MariaDB and other databases. Store credentials locally in encrypted form, retrieve at runtime without exposing to AI models. Requires MGC 1.4.7+.
author: MirginCipher Team
license: MIT
tags: database, mysql, postgresql, sqlite, mariadb, security, credential-management, zero-exposure, mgc
platform_compatibility: windows, macos, linux
changelog:
  - version: 1.2.0
    changes:
      - Requires MGC 1.4.7+ for mgc_run support
      - Use mgc_run instead of mgc_get action="run"
  - version: 1.1.0
    changes:
      - Added complete example section with workflow templates
      - Added comprehensive troubleshooting section
      - Added FAQ section
      - Added anti‑patterns section with correct practices
      - Added when to use / when not to use sections
      - Added capability boundary explanation
      - Added advanced scenarios section
      - Added templates for SKILL.md and local scripts
  - version: 1.0.1
    changes:
      - Updated to emphasize MCP tools over CLI
  - version: 1.0.0
    changes:
      - Initial release with database zero-exposure pattern

---

# Overview

Database Credential Security is a documentation skill that teaches how to manage database credentials securely using MGC Blackbox. Supports MySQL, PostgreSQL, SQLite, MariaDB and other databases. It enables AI agents to execute database operations without ever exposing database passwords or connection strings to the AI model.

This skill contains **no executable code** and is safe for automatic approval.

---

# What This Skill Enables

After reading this documentation, an AI agent will understand how to:

- Store database credentials (MySQL, PostgreSQL, SQLite, MariaDB, etc.) securely in MGC Blackbox
- Retrieve credentials at runtime without AI seeing plaintext
- Execute database queries through local scripts
- Manage multiple database connections safely
- Rotate credentials without code changes
- Seal database scripts for multi‑node execution

---

# When to Use This Skill

## Must Use Cases

1. **Production environments**
   - Any database access in production requires secure credential management
   - Prevents credential leakage in logs, prompts, and AI context

2. **Automation tasks**
   - Scheduled scripts that need database access
   - CI/CD pipelines that connect to databases

3. **Multi‑node collaboration**
   - Node A creates a database script, Node B executes it
   - Use `mgc_seal` to encrypt the script with target node's public key

4. **AI needs database access but must not see passwords**
   - AI provides SQL statements only
   - Local scripts handle credential retrieval and execution

## Example Triggers

- "Connect to MySQL database securely"
- "Execute a SQL query without exposing the password"
- "Create a scheduled backup script for PostgreSQL"
- "Run database migrations safely"
- "Share a database script with another node securely"

---

# When NOT to Use This Skill

This skill is NOT needed in these scenarios:

1. **Public databases**
   - Databases that require no authentication
   - Read‑only public data sources

2. **Local development with no sensitive data**
   - Disposable test databases
   - Demo environments with mock data

3. **Interactive manual access**
   - When user provides credentials manually each time
   - Direct database tool usage (DBeaver, MySQL Workbench, etc.)

---

# Capability Boundary

This skill has specific boundaries that users must understand:

## What This Skill Does

- **Credential storage**: Securely store database credentials in MGC Blackbox
- **Credential retrieval**: Retrieve credentials at runtime via MCP tools
- **Pattern guidance**: Provide secure patterns for database credential management
- **Multi‑node sealing**: Encrypt database scripts for trusted nodes

## What This Skill Does NOT Do

- **NOT a database client**: Cannot connect to databases directly
- **NOT a SQL executor**: Does not run SQL queries
- **NOT a migration tool**: Does not handle schema changes
- **NOT a backup tool**: Does not perform database backups

The skill provides **credential management only**. All sensitive database operations (connect, query, migrate, backup) must be performed by local scripts.

---

# Prerequisites

1. Install MGC Blackbox: `pip install mgc-blackbox`
2. Start MGC service: `mgc` (runs at http://127.0.0.1:57219)
3. Token file: `~/.mgc/database/mgc_black_box/.mgc_token`
4. Database driver installed (mysql‑connector‑python, psycopg2, etc.)

---

# Complete Example: Full Database Credential Workflow

This section demonstrates a complete flow from credential storage to secure database operation.

## Step 1: Store Database Credentials

### MySQL Credential Storage

```
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 Credential Storage

```
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 Credential Storage

```
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\"
  }"
```

> **Note:** Replace placeholder values with actual database credentials. The `info_owner` value is your reference identifier—you'll use this same value when retrieving credentials.

## Step 2: Reference Credentials in Your Skill

```
# In your SKILL.md:

database_reference:
  info_type:  "config"
  info_owner: "my_mysql_prod"
  # The AI never sees actual credentials, only the reference
```

## Step 3: Retrieve Credentials

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

The MCP tool returns the stored JSON content. The AI receives:
- Host and port (non‑sensitive)
- Database name (non‑sensitive)
- Username (may be non‑sensitive)
- But **never** the password

## Step 4: Execute Database Operation (Conceptual)

A local script performs the actual database operation:

```
# Conceptual script flow (NOT executable):

1. Call mgc_get with info_owner="my_mysql_prod"
2. Parse returned JSON for connection parameters
3. Use database driver to connect
4. Execute SQL query
5. Return only query results (no credentials)
6. NEVER log or expose the password
```

## Multi‑Node Example: Sealing Database Scripts

When Node A needs Node B to execute a database script:

### Node A: Seal the database script

```
Tool: mgc_seal
Parameters:
  info_type:   "script"
  info_owner:  "mysql_backup_script"
  ext01:       "python"
  ext04:       "-----BEGIN PUBLIC KEY-----\n...Node B's public key...\n-----END PUBLIC KEY-----"
```

Returns: Encrypted capsule containing the database script

### Node B: Execute the sealed script

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

Node B uses its private key to decrypt and execute. Node A's database script is never exposed to Node B.

---

# FAQ

## MGC Related

### Q: What if MGC is not installed?
**A:** Install MGC Blackbox: `pip install mgc-blackbox`

### Q: What if MGC is not running?
**A:** Start MGC: `mgc` in a terminal. Service runs at http://127.0.0.1:57219

### Q: How do I check if MGC is running?
**A:** Open http://127.0.0.1:57219 in a browser. If you see a response, MGC is running.

### Q: Port 57219 is already in use
**A:** Stop other applications using that port, or configure MGC to use a different port.

## Credential Management

### Q: How do I update database credentials?
**A:** Call `mgc_save` again with the same `info_type` and `info_owner`. The old credentials will be replaced.

### Q: How do I manage multiple databases?
**A:** Use different `info_owner` values for each database:
- "my_mysql_prod"
- "my_postgres_dev"
- "my_mysql_reporting"

### Q: How do I rotate database credentials?
**A:**
1. Update credentials in the database
2. Call `mgc_save` with new credentials (same `info_owner`)
3. Local scripts automatically retrieve new credentials on next run

### Q: What if credentials are not found?
**A:**
1. Verify `info_owner` matches exactly (case‑sensitive)
2. Verify `info_type` matches
3. List all stored credentials: `mgc_list`

## Security

### Q: How do I ensure AI never sees database passwords?
**A:**
1. Never include credentials in SKILL.md prompts
2. Never pass credentials as parameters to AI
3. Always use MGC to store credentials
4. Local scripts retrieve credentials directly from MGC
5. AI only receives non‑sensitive query results

### Q: Can AI read credentials from MGC?
**A:** Yes, if AI calls `mgc_get`. **Never call mgc_get unless you want AI to process the result.** For zero‑exposure, use local scripts that call MGC, not AI directly.

### Q: What if AI accidentally logs credentials?
**A:** Ensure your local script:
- Never prints or logs credential values
- Only logs non‑sensitive information (query, row count, etc.)
- Uses secure logging practices

## Multi‑Node Scenarios

### Q: How do I share a database script securely?
**A:**
1. Node A creates the database script
2. Use `mgc_seal` with Node B's public key
3. Node B decrypts and executes using `mgc_run`

### Q: Can I seal a script for multiple nodes?
**A:** Currently, `mgc_seal` targets one node at a time. For multiple nodes, seal separately with each node's public key.

---

# Anti‑Patterns

## Common Mistakes and Correct Practices

### ❌ Anti‑Pattern 1: Hardcoding Database Password in Scripts

```python
# WRONG - Never do this
def connect_to_db():
    connection = pymysql.connect(
        host="db.example.com",
        password="secret_password"  # Exposed!
    )
```

**Correct Practice:**
```python
# RIGHT - Retrieve from MGC
def connect_to_db():
    credentials = get_credentials_from_mgc("my_mysql_prod")
    connection = pymysql.connect(
        host=credentials["host"],
        password=credentials["password"]
    )
```

---

### ❌ Anti‑Pattern 2: Exposing Connection String in SKILL.md

```markdown
# WRONG - In SKILL.md
Use the following database credentials:
- Host: db.example.com
- Password: my_secret_password
```

**Correct Practice:**
```markdown
# RIGHT - In SKILL.md
Database credentials are stored securely in MGC.
Reference: info_owner="my_mysql_prod"
AI should NOT handle credentials directly.
```

---

### ❌ Anti‑Pattern 3: Putting Password in ext04

```json
// WRONG
{
  "info_owner": "my_database",
  "ext04": "password=secret123"  // This is NOT for passwords!
}
```

**Correct Practice:**
```json
// RIGHT
{
  "info_owner": "my_database",
  "info_type": "config",
  "ext04": "-----BEGIN PUBLIC KEY-----\nNodeB_Public_Key...\n-----END PUBLIC KEY-----"
}
// ext04 is ONLY for public keys when sealing
```

---

### ❌ Anti‑Pattern 4: Writing Credentials to Local Files

```bash
# WRONG
echo "password=secret" > db_credentials.txt
```

**Correct Practice:**
```bash
# RIGHT
# Store in MGC using mgc_save
# Never write credentials to disk files
```

---

### ❌ Anti‑Pattern 5: Passing Credentials as Prompt Parameters

```markdown
# WRONG
Execute SQL: SELECT * FROM users WHERE password='{user_password}'
```

**Correct Practice:**
```markdown
# RIGHT
Execute SQL using credentials stored in MGC.
Reference: info_owner="my_mysql_prod"
The local script handles credential retrieval.
```

---

### ❌ Anti‑Pattern 6: Logging Credentials in Database Scripts

```python
# WRONG
def execute_query(sql):
    creds = get_credentials_from_mgc("my_database")
    print(f"Connecting with password: {creds['password']}")  # Exposed!
    # ... execute query
```

**Correct Practice:**
```python
# RIGHT
def execute_query(sql):
    creds = get_credentials_from_mgc("my_database")
    logger.info(f"Connecting to {creds['host']}")  # No password logged
    # ... execute query
```

---

# Troubleshooting

## Common Errors and Solutions

### Error: "Credential not found"

**Symptoms:** `mgc_get` returns empty or error

**Solutions:**
1. Verify `info_owner` matches exactly (case‑sensitive)
2. Verify `info_type` matches
3. List all credentials: `mgc_list`
4. Re‑store credentials if needed

---

### Error: "info_type mismatch"

**Symptoms:** API returns wrong data or error

**Solutions:**
1. Check the `info_type` used when saving
2. Use the same `info_type` when retrieving
3. Common types: "config", "credential", "script"

---

### Error: "Database connection failed"

**Symptoms:** Cannot connect to database

**Solutions:**
1. Verify credentials are correct in MGC
2. Check database server is running
3. Verify network connectivity to database host
4. Check port is correct (MySQL: 3306, PostgreSQL: 5432, SQL Server: 1433)
5. Verify firewall allows connection

---

### Error: "Invalid credentials"

**Symptoms:** Authentication fails when connecting

**Solutions:**
1. Verify username and password in MGC storage
2. Check if password was recently changed
3. Update credentials in MGC using `mgc_save`
4. Verify user has permission to access the database

---

### Error: "MGC not running"

**Symptoms:** Cannot connect to MGC service

**Solutions:**
1. Start MGC: `mgc` in terminal
2. Check service URL: http://127.0.0.1:57219
3. Verify token file exists: `~/.mgc/database/mgc_black_box/.mgc_token`
4. Restart MGC if needed

---

### Error: "MCP tool call failed"

**Symptoms:** Tool execution error

**Solutions:**
1. Verify MGC is running
2. Check service URL
3. Verify token file is readable
4. Check MCP tool parameters are correct

---

### Error: "Permission denied"

**Symptoms:** Cannot access MGC storage

**Solutions:**
1. Check file permissions on `~/.mgc/`
2. Verify token file is readable
3. Run MGC with appropriate permissions

---

# MGC Blackbox API Reference

## Service Endpoint

- Base URL: http://127.0.0.1:57219
- Token File: ~/.mgc/database/mgc_black_box/.mgc_token
- Token: String token read from token file, required for all API calls

## Get Credentials API

**Endpoint:** /api/mgc/sensitive/get
**Method:** POST
**Headers:**
- X-MGC-Token: (string token read from token file)
- Content-Type: application/json

**Body fields:**
- info_type: "config"
- info_owner: your chosen identifier

**Response fields:**
- code: status code
- data.content: JSON string containing stored credentials

## Save Credentials API

**Endpoint:** /api/mgc/sensitive/save
**Method:** POST
**Headers:** same as above

**Body fields:**
- info_type: "config"
- info_owner: your identifier
- content: JSON string of credentials

---

# Advanced Scenarios

## Multi‑Database Credential Management

Manage credentials for multiple databases:

```
# Storage identifiers:
info_owner: "my_mysql_prod"      # MySQL production
info_owner: "my_postgres_prod"   # PostgreSQL production
info_owner: "my_mysql_dev"       # MySQL development
info_owner: "my_mysql_test"      # MySQL testing
```

## Multi‑Node Database Task Distribution

### Node A: Prepares database operation script

```
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-----"
```

### Node B: Executes the sealed script

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

## Credential Rotation

Regularly rotate database credentials:

1. **Generate new credentials** in database
2. **Update MGC storage**:
   ```
   Tool: mgc_save
   Parameters:
     info_type:   "config"
     info_owner:  "my_mysql_prod"
     content:     "{new_credentials}"
   ```
3. **No code changes needed** - local scripts automatically use new credentials

## Credential Version Management

Track credential versions using info_owner suffixes:

```
info_owner: "my_mysql_prod_v1"   # Version 1
info_owner: "my_mysql_prod_v2"   # Version 2 (after rotation)
```

---

# Example Directory Structure

When creating a database skill:

```
database_skill/
  SKILL.md           # Skill definition
  README.md          # User documentation
  scripts/           # Local scripts (conceptual)
    execute_query.py
    backup.py
    migrate.py
```

---

# Security Best Practices

1. **Never embed credentials in code**
2. **Use MGC for credential storage**
3. **Retrieve credentials at runtime only**
4. **Never log or print credentials**
5. **Rotate credentials regularly**
6. **Use separate credentials per database**
7. **Use separate credentials per environment** (dev/staging/prod)
8. **Enable SSL/TLS for database connections**
9. **Limit database user permissions** to minimum required

---

# Common Patterns

## Python Database Connection (Conceptual)

```
import mysql.connector

def get_connection(credentials):
    return mysql.connector.connect(
        host=credentials["host"],
        port=credentials["port"],
        database=credentials["database"],
        user=credentials["user"],
        password=credentials["password"]
    )

def execute_query(sql):
    creds = retrieve_from_mgc("my_mysql_prod")
    conn = get_connection(creds)
    cursor = conn.cursor()
    cursor.execute(sql)
    result = cursor.fetchall()
    cursor.close()
    conn.close()
    return result
```

---

# Use Cases

- Database administration scripts
- Automated backup operations
- Data migration tools
- Application database access
- Multiple environment management (dev/staging/prod)
- Scheduled database operations
- Multi‑node database task execution

---

# Template: Zero‑Exposure Database SKILL.md

When creating a new database skill:

```markdown
---

spec: usk/3.0
id: your_skill_id
version: 1.0.0
name: Your Database Skill
description: Brief description
author: Your Name
license: MIT
tags: database, mgc, zero-exposure
platform_compatibility: windows, macos, linux

---

# Overview

What this skill does.

# Prerequisites

- Install MGC Blackbox
- Store database credentials in MGC (info_owner: "your_reference")
- Install required database driver

# Usage

How to use this skill.

# Database Credentials

- info_type: "config"
- info_owner: "your_reference"
- Required fields: host, port, database, user, password

# Security

This skill uses Zero‑Exposure design.
Credentials are stored in MGC, never exposed to AI.

---

# Entrypoint

Describe how to use this skill.
```

---

# Template: Database Local Script Structure

```python
# Template structure (documentation only)

import json
import pymysql  # or psycopg2, pymssql, etc.

# MGC Configuration
MGC_BASE_URL = "http://127.0.0.1:57219"
TOKEN_FILE = "~/.mgc/database/mgc_black_box/.mgc_token"

def get_mgc_token():
    # Read token from file
    pass

def get_credentials(info_owner, info_type="config"):
    # Call MGC API to retrieve credentials
    # Return: dict of credential data
    pass

def execute_query(credentials, sql):
    # Use credentials to connect and execute
    # NEVER log credential values
    # Return: query results only
    pass

def main():
    # 1. Get credentials from MGC
    creds = get_credentials(info_owner="your_database_reference")

    # 2. Execute query
    result = execute_query(creds, "SELECT * FROM users")

    # 3. Return result (not credentials!)
    print(result)

if __name__ == "__main__":
    main()
```

---

# License

MIT

spec: usk/3.0 id: mgc_database_security version: 1.2.0 name: Database Credential Security (Zero‑Exposure Edition) description: Secure database credential management using MGC Blackbox. Supports MySQL, PostgreSQL, SQLite, MariaDB and other databases. Store credentials locally in encrypted form, retrieve at runtime without exposing to AI models. Requires MGC 1.4.7+. author: MirginCipher Team license: MIT tags: database, mysql, postgresql, sqlite, mariadb, security, credential-management, zero-exposure, mgc platform_compatibility: windows, macos, linux changelog:

version: 1.2.0 changes:
- Requires MGC 1.4.7+ for mgc_run support
- Use mgc_run instead of mgc_get action="run"
version: 1.1.0 changes:
- Added complete example section with workflow templates
- Added comprehensive troubleshooting section
- Added FAQ section
- Added anti‑patterns section with correct practices
- Added when to use / when not to use sections
- Added capability boundary explanation
- Added advanced scenarios section
- Added templates for SKILL.md and local scripts
version: 1.0.1 changes:
- Updated to emphasize MCP tools over CLI
version: 1.0.0 changes:
- Initial release with database zero-exposure pattern

Overview

Database Credential Security is a documentation skill that teaches how to manage database credentials securely using MGC Blackbox. Supports MySQL, PostgreSQL, SQLite, MariaDB and other databases. It enables AI agents to execute database operations without ever exposing database passwords or connection strings to the AI model.

This skill contains no executable code and is safe for automatic approval.

What This Skill Enables

After reading this documentation, an AI agent will understand how to:

Store database credentials (MySQL, PostgreSQL, SQLite, MariaDB, etc.) securely in MGC Blackbox
Retrieve credentials at runtime without AI seeing plaintext
Execute database queries through local scripts
Manage multiple database connections safely
Rotate credentials without code changes
Seal database scripts for multi‑node execution

When to Use This Skill

Must Use Cases

Production environments
- Any database access in production requires secure credential management
- Prevents credential leakage in logs, prompts, and AI context
Automation tasks
- Scheduled scripts that need database access
- CI/CD pipelines that connect to databases
Multi‑node collaboration
- Node A creates a database script, Node B executes it
- Use mgc_seal to encrypt the script with target node's public key
AI needs database access but must not see passwords
- AI provides SQL statements only
- Local scripts handle credential retrieval and execution

Example Triggers

"Connect to MySQL database securely"
"Execute a SQL query without exposing the password"
"Create a scheduled backup script for PostgreSQL"
"Run database migrations safely"
"Share a database script with another node securely"

When NOT to Use This Skill

This skill is NOT needed in these scenarios:

Public databases
- Databases that require no authentication
- Read‑only public data sources
Local development with no sensitive data
- Disposable test databases
- Demo environments with mock data
Interactive manual access
- When user provides credentials manually each time
- Direct database tool usage (DBeaver, MySQL Workbench, etc.)

Capability Boundary

This skill has specific boundaries that users must understand:

What This Skill Does

Credential storage: Securely store database credentials in MGC Blackbox
Credential retrieval: Retrieve credentials at runtime via MCP tools
Pattern guidance: Provide secure patterns for database credential management
Multi‑node sealing: Encrypt database scripts for trusted nodes

What This Skill Does NOT Do

NOT a database client: Cannot connect to databases directly
NOT a SQL executor: Does not run SQL queries
NOT a migration tool: Does not handle schema changes
NOT a backup tool: Does not perform database backups

The skill provides credential management only. All sensitive database operations (connect, query, migrate, backup) must be performed by local scripts.

Prerequisites

Install MGC Blackbox: pip install mgc-blackbox
Start MGC service: mgc (runs at http://127.0.0.1:57219)
Token file: ~/.mgc/database/mgc_black_box/.mgc_token
Database driver installed (mysql‑connector‑python, psycopg2, etc.)

Complete Example: Full Database Credential Workflow

This section demonstrates a complete flow from credential storage to secure database operation.

Step 1: Store Database Credentials

MySQL Credential Storage

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 Credential Storage

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 Credential Storage

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\"
  }"

Note: Replace placeholder values with actual database credentials. The info_owner value is your reference identifier—you'll use this same value when retrieving credentials.

Step 2: Reference Credentials in Your Skill

# In your SKILL.md:

database_reference:
  info_type:  "config"
  info_owner: "my_mysql_prod"
  # The AI never sees actual credentials, only the reference

Step 3: Retrieve Credentials

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

The MCP tool returns the stored JSON content. The AI receives:

Host and port (non‑sensitive)
Database name (non‑sensitive)
Username (may be non‑sensitive)
But never the password

Step 4: Execute Database Operation (Conceptual)

A local script performs the actual database operation:

# Conceptual script flow (NOT executable):

1. Call mgc_get with info_owner="my_mysql_prod"
2. Parse returned JSON for connection parameters
3. Use database driver to connect
4. Execute SQL query
5. Return only query results (no credentials)
6. NEVER log or expose the password

Multi‑Node Example: Sealing Database Scripts

When Node A needs Node B to execute a database script:

Node A: Seal the database script

Tool: mgc_seal
Parameters:
  info_type:   "script"
  info_owner:  "mysql_backup_script"
  ext01:       "python"
  ext04:       "-----BEGIN PUBLIC KEY-----\n...Node B's public key...\n-----END PUBLIC KEY-----"

Returns: Encrypted capsule containing the database script

Node B: Execute the sealed script

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

Node B uses its private key to decrypt and execute. Node A's database script is never exposed to Node B.

FAQ

MGC Related

Q: What if MGC is not installed?

A: Install MGC Blackbox: pip install mgc-blackbox

Q: What if MGC is not running?

A: Start MGC: mgc in a terminal. Service runs at http://127.0.0.1:57219

Q: How do I check if MGC is running?

A: Open http://127.0.0.1:57219 in a browser. If you see a response, MGC is running.

Q: Port 57219 is already in use

A: Stop other applications using that port, or configure MGC to use a different port.

Credential Management

Q: How do I update database credentials?

A: Call mgc_save again with the same info_type and info_owner. The old credentials will be replaced.

Q: How do I manage multiple databases?

A: Use different info_owner values for each database:

"my_mysql_prod"
"my_postgres_dev"
"my_mysql_reporting"

Q: How do I rotate database credentials?

Update credentials in the database
Call mgc_save with new credentials (same info_owner)
Local scripts automatically retrieve new credentials on next run

Q: What if credentials are not found?

Verify info_owner matches exactly (case‑sensitive)
Verify info_type matches
List all stored credentials: mgc_list

Security

Q: How do I ensure AI never sees database passwords?

Never include credentials in SKILL.md prompts
Never pass credentials as parameters to AI
Always use MGC to store credentials
Local scripts retrieve credentials directly from MGC
AI only receives non‑sensitive query results

Q: Can AI read credentials from MGC?

A: Yes, if AI calls mgc_get. Never call mgc_get unless you want AI to process the result. For zero‑exposure, use local scripts that call MGC, not AI directly.

Q: What if AI accidentally logs credentials?

A: Ensure your local script:

Never prints or logs credential values
Only logs non‑sensitive information (query, row count, etc.)
Uses secure logging practices

Multi‑Node Scenarios

Q: How do I share a database script securely?

Node A creates the database script
Use mgc_seal with Node B's public key
Node B decrypts and executes using mgc_run

Q: Can I seal a script for multiple nodes?

A: Currently, mgc_seal targets one node at a time. For multiple nodes, seal separately with each node's public key.

Anti‑Patterns

Common Mistakes and Correct Practices

❌ Anti‑Pattern 1: Hardcoding Database Password in Scripts

# WRONG - Never do this
def connect_to_db():
    connection = pymysql.connect(
        host="db.example.com",
        password="secret_password"  # Exposed!
    )

Correct Practice:

# RIGHT - Retrieve from MGC
def connect_to_db():
    credentials = get_credentials_from_mgc("my_mysql_prod")
    connection = pymysql.connect(
        host=credentials["host"],
        password=credentials["password"]
    )

❌ Anti‑Pattern 2: Exposing Connection String in SKILL.md

# WRONG - In SKILL.md
Use the following database credentials:
- Host: db.example.com
- Password: my_secret_password

Correct Practice:

# RIGHT - In SKILL.md
Database credentials are stored securely in MGC.
Reference: info_owner="my_mysql_prod"
AI should NOT handle credentials directly.

❌ Anti‑Pattern 3: Putting Password in ext04

// WRONG
{
  "info_owner": "my_database",
  "ext04": "password=secret123"  // This is NOT for passwords!
}

Correct Practice:

// RIGHT
{
  "info_owner": "my_database",
  "info_type": "config",
  "ext04": "-----BEGIN PUBLIC KEY-----\nNodeB_Public_Key...\n-----END PUBLIC KEY-----"
}
// ext04 is ONLY for public keys when sealing

❌ Anti‑Pattern 4: Writing Credentials to Local Files

# WRONG
echo "password=secret" > db_credentials.txt

Correct Practice:

# RIGHT
# Store in MGC using mgc_save
# Never write credentials to disk files

❌ Anti‑Pattern 5: Passing Credentials as Prompt Parameters

# WRONG
Execute SQL: SELECT * FROM users WHERE password='{user_password}'

Correct Practice:

# RIGHT
Execute SQL using credentials stored in MGC.
Reference: info_owner="my_mysql_prod"
The local script handles credential retrieval.

❌ Anti‑Pattern 6: Logging Credentials in Database Scripts

# WRONG
def execute_query(sql):
    creds = get_credentials_from_mgc("my_database")
    print(f"Connecting with password: {creds['password']}")  # Exposed!
    # ... execute query

Correct Practice:

# RIGHT
def execute_query(sql):
    creds = get_credentials_from_mgc("my_database")
    logger.info(f"Connecting to {creds['host']}")  # No password logged
    # ... execute query

Troubleshooting

Common Errors and Solutions

Error: "Credential not found"

Symptoms: mgc_get returns empty or error

Solutions:

Verify info_owner matches exactly (case‑sensitive)
Verify info_type matches
List all credentials: mgc_list
Re‑store credentials if needed

Error: "info_type mismatch"

Symptoms: API returns wrong data or error

Solutions:

Check the info_type used when saving
Use the same info_type when retrieving
Common types: "config", "credential", "script"

Error: "Database connection failed"

Symptoms: Cannot connect to database

Solutions:

Verify credentials are correct in MGC
Check database server is running
Verify network connectivity to database host
Check port is correct (MySQL: 3306, PostgreSQL: 5432, SQL Server: 1433)
Verify firewall allows connection

Error: "Invalid credentials"

Symptoms: Authentication fails when connecting

Solutions:

Verify username and password in MGC storage
Check if password was recently changed
Update credentials in MGC using mgc_save
Verify user has permission to access the database

Error: "MGC not running"

Symptoms: Cannot connect to MGC service

Solutions:

Start MGC: mgc in terminal
Check service URL: http://127.0.0.1:57219
Verify token file exists: ~/.mgc/database/mgc_black_box/.mgc_token
Restart MGC if needed

Error: "MCP tool call failed"

Symptoms: Tool execution error

Solutions:

Verify MGC is running
Check service URL
Verify token file is readable
Check MCP tool parameters are correct

Error: "Permission denied"

Symptoms: Cannot access MGC storage

Solutions:

Check file permissions on ~/.mgc/
Verify token file is readable
Run MGC with appropriate permissions

MGC Blackbox API Reference

Service Endpoint

Base URL: http://127.0.0.1:57219
Token File: ~/.mgc/database/mgc_black_box/.mgc_token
Token: String token read from token file, required for all API calls

Get Credentials API

Endpoint: /api/mgc/sensitive/get Method: POST Headers:

X-MGC-Token: (string token read from token file)
Content-Type: application/json

Body fields:

info_type: "config"
info_owner: your chosen identifier

Response fields:

code: status code
data.content: JSON string containing stored credentials

Save Credentials API

Endpoint: /api/mgc/sensitive/save Method: POST Headers: same as above

Body fields:

info_type: "config"
info_owner: your identifier
content: JSON string of credentials

Advanced Scenarios

Multi‑Database Credential Management

Manage credentials for multiple databases:

# Storage identifiers:
info_owner: "my_mysql_prod"      # MySQL production
info_owner: "my_postgres_prod"   # PostgreSQL production
info_owner: "my_mysql_dev"       # MySQL development
info_owner: "my_mysql_test"      # MySQL testing

Multi‑Node Database Task Distribution

Node A: Prepares database operation script

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-----"

Node B: Executes the sealed script

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

Credential Rotation

Regularly rotate database credentials:

Generate new credentials in database

Update MGC storage:

Tool: mgc_save
Parameters:
  info_type:   "config"
  info_owner:  "my_mysql_prod"
  content:     "{new_credentials}"

No code changes needed - local scripts automatically use new credentials

Credential Version Management

Track credential versions using info_owner suffixes:

info_owner: "my_mysql_prod_v1"   # Version 1
info_owner: "my_mysql_prod_v2"   # Version 2 (after rotation)

Example Directory Structure

When creating a database skill:

database_skill/
  SKILL.md           # Skill definition
  README.md          # User documentation
  scripts/           # Local scripts (conceptual)
    execute_query.py
    backup.py
    migrate.py

Security Best Practices

Never embed credentials in code
Use MGC for credential storage
Retrieve credentials at runtime only
Never log or print credentials
Rotate credentials regularly
Use separate credentials per database
Use separate credentials per environment (dev/staging/prod)
Enable SSL/TLS for database connections
Limit database user permissions to minimum required

Common Patterns

Python Database Connection (Conceptual)

import mysql.connector

def get_connection(credentials):
    return mysql.connector.connect(
        host=credentials["host"],
        port=credentials["port"],
        database=credentials["database"],
        user=credentials["user"],
        password=credentials["password"]
    )

def execute_query(sql):
    creds = retrieve_from_mgc("my_mysql_prod")
    conn = get_connection(creds)
    cursor = conn.cursor()
    cursor.execute(sql)
    result = cursor.fetchall()
    cursor.close()
    conn.close()
    return result

Use Cases

Database administration scripts
Automated backup operations
Data migration tools
Application database access
Multiple environment management (dev/staging/prod)
Scheduled database operations
Multi‑node database task execution

Template: Zero‑Exposure Database SKILL.md

When creating a new database skill:

---

spec: usk/3.0
id: your_skill_id
version: 1.0.0
name: Your Database Skill
description: Brief description
author: Your Name
license: MIT
tags: database, mgc, zero-exposure
platform_compatibility: windows, macos, linux

---

# Overview

What this skill does.

# Prerequisites

- Install MGC Blackbox
- Store database credentials in MGC (info_owner: "your_reference")
- Install required database driver

# Usage

How to use this skill.

# Database Credentials

- info_type: "config"
- info_owner: "your_reference"
- Required fields: host, port, database, user, password

# Security

This skill uses Zero‑Exposure design.
Credentials are stored in MGC, never exposed to AI.

---

# Entrypoint

Describe how to use this skill.

Template: Database Local Script Structure

# Template structure (documentation only)

import json
import pymysql  # or psycopg2, pymssql, etc.

# MGC Configuration
MGC_BASE_URL = "http://127.0.0.1:57219"
TOKEN_FILE = "~/.mgc/database/mgc_black_box/.mgc_token"

def get_mgc_token():
    # Read token from file
    pass

def get_credentials(info_owner, info_type="config"):
    # Call MGC API to retrieve credentials
    # Return: dict of credential data
    pass

def execute_query(credentials, sql):
    # Use credentials to connect and execute
    # NEVER log credential values
    # Return: query results only
    pass

def main():
    # 1. Get credentials from MGC
    creds = get_credentials(info_owner="your_database_reference")

    # 2. Execute query
    result = execute_query(creds, "SELECT * FROM users")

    # 3. Return result (not credentials!)
    print(result)

if __name__ == "__main__":
    main()

License

MIT