This guide explains how to secure your CGC installation, especially when exposing it to the internet.

• Security Overview
• Quick Start: Secure Setup
• API Key Management
• Rate Limiting
• Data Protection
• Network Security
• Best Practices
• Security Configuration

CGC includes multiple layers of security:

The secure server has all protections enabled by default:

cgc serve --secure

You'll see:

Starting secure CGC API server on 127.0.0.1:8420
Authentication: REQUIRED
Rate limiting: ENABLED

Since authentication is required, you need to create a key first. Temporarily disable auth:

Windows (Command Prompt):

set CGC_REQUIRE_AUTH=false
cgc serve --secure

Windows (PowerShell):

$env:CGC_REQUIRE_AUTH = "false"
cgc serve --secure

Mac/Linux:

CGC_REQUIRE_AUTH=false cgc serve --secure

With the server running, open your browser to:

http://localhost:8420/docs

Find the POST /admin/api-keys endpoint and click "Try it out".

Fill in:

• name: admin (or your preferred name)
• permissions: *,admin (full access including admin)
• expires_days: 365 (or leave blank for no expiration)

Click "Execute".

Important: Copy the API key from the response! It looks like:

cgc_lGlmobBzC2ReZZZq...

This key is only shown once. Save it somewhere safe!

Stop the server (Ctrl+C) and restart normally:

cgc serve --secure

Try accessing the API with your key:

curl -H "X-API-Key: cgc_your_key_here" http://localhost:8420/sources

You should see a list of sources (empty if none connected yet).

Without the key:

curl http://localhost:8420/sources

You'll get an authentication error.

Keys can have different permission levels:

Full Access (Admin):

permissions: *,admin

Read Only:

permissions: read

SQL Only (no file access):

permissions: sql:read

Specific Sources:

allowed_sources: mydb,documents

If a key is compromised:

1. Go to http://localhost:8420/docs
2. Use the admin endpoints to list and revoke keys
3. Create new keys for affected users

• Never share keys in code repositories or public places
• Use environment variables instead of hardcoding keys
• Create separate keys for each user or application
• Set expiration dates for temporary access
• Regularly rotate keys for sensitive applications

Rate limiting prevents abuse by limiting how many requests can be made.

This means: 100 requests per minute per IP address.

Every response includes these headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

• Limit: Maximum requests in the window
• Remaining: Requests left in current window
• Reset: Unix timestamp when the window resets

If you exceed the limit, you'll receive:

HTTP 429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Limit: 100 per 60s"
}

The response includes a Retry-After header telling you when to try again.

Set via environment variables:

CGC_RATE_LIMIT_REQUESTS=200
CGC_RATE_LIMIT_WINDOW=60

Or in the config file (~/.cgc/security.json):

{
  "rate_limit_enabled": true,
  "rate_limit_requests": 200,
  "rate_limit_window_seconds": 60
}

Different API keys can have different limits:

{
  "name": "high-volume-client",
  "rate_limit": 1000
}

CGC blocks dangerous SQL keywords by default:

Blocked:

• DROP, DELETE, TRUNCATE
• ALTER, CREATE
• INSERT, UPDATE
• GRANT, REVOKE
• EXEC, EXECUTE
• Comments (--, /*, */)

Allowed:

• SELECT queries only

If you need write access, grant sql:write permission to specific keys.

CGC blocks access to sensitive paths:

Always Blocked:

• System directories (/etc, /var, C:\Windows)
• Home directories (/home, C:\Users)
• Hidden files (.env, .git, .ssh)
• Credential files (id_rsa, credentials, secrets)

Allowed Paths:

By default, any path not on the blocked list is allowed. For stricter control, set allowed paths:

{
  "allowed_paths": [
    "C:\\Data\\Reports",
    "C:\\Data\\Documents"
  ]
}

Sensitive information is automatically masked in logs and error messages:

Before: Connection failed: postgresql://admin:secret123@localhost/db
After:  Connection failed: postgresql://admin:****@localhost/db

By default, CGC only accepts connections from your local machine:

bind_host: 127.0.0.1

This means other computers on your network can't access it.

To allow access from other machines:

Local Network:

CGC_BIND_HOST=0.0.0.0 cgc serve --secure

Caution: This exposes CGC to your entire network.

For internet access, use ngrok:

1. Install ngrok from https://ngrok.com

2. Start CGC with security enabled:

   cgc serve --secure
   

3. Start ngrok:

   ngrok http 8420
   

4. Use the ngrok URL (like https://abc123.ngrok.io)

Important: Always use the secure server when exposing to the internet!

By default, only localhost origins are allowed:

{
  "allowed_origins": ["http://localhost:*"]
}

To allow specific domains:

{
  "allowed_origins": [
    "https://your-app.com",
    "https://n8n.your-company.com"
  ]
}

Never use * in production! This allows any website to access your API.

1. Use cgc serve (without security) for quick testing
2. Use cgc serve --secure when testing security features
3. Create a dedicated development API key

1. Always use cgc serve --secure
2. Create separate keys for each team member
3. Use permission restrictions based on role
4. Set key expiration (e.g., 30-90 days)

1. Always use cgc serve --secure
2. Use strong, unique API keys
3. Set up ngrok with authentication if possible
4. Monitor access logs regularly
5. Set aggressive rate limits
6. Restrict allowed paths strictly
7. Consider a VPN instead of public exposure

1. Run behind a reverse proxy (nginx, traefik)
2. Use HTTPS (the proxy handles SSL)
3. Implement IP whitelisting if possible
4. Set up log aggregation and alerting
5. Regular security audits
6. Keep CGC updated

Create ~/.cgc/security.json:

{
  "require_auth": true,
  "api_keys_file": "~/.cgc/api_keys.json",

  "rate_limit_enabled": true,
  "rate_limit_requests": 100,
  "rate_limit_window_seconds": 60,

  "allow_raw_sql": false,
  "sql_max_rows": 10000,
  "sql_timeout_seconds": 30,
  "blocked_sql_keywords": [
    "DROP", "DELETE", "TRUNCATE", "ALTER", "CREATE",
    "INSERT", "UPDATE", "GRANT", "REVOKE", "EXEC"
  ],

  "allowed_paths": [],
  "blocked_paths": [
    "/etc", "/var", "/root", "/home",
    "C:\\Windows", "C:\\Program Files",
    ".env", ".git", ".ssh", "credentials", "secrets"
  ],
  "max_file_size_mb": 100,

  "allowed_origins": ["http://localhost:*"],
  "bind_host": "127.0.0.1",
  "bind_port": 8420,

  "max_request_size_mb": 10,
  "request_timeout_seconds": 60,

  "log_requests": true,
  "log_queries": true,
  "mask_credentials": true
}

All settings can be overridden with environment variables:

1. Immediately revoke the compromised key
2. Create a new key for the affected user
3. Review access logs for suspicious activity
4. Change any credentials the key had access to

1. Check rate limit logs for unusual patterns
2. Review blocked requests (SQL injection attempts, etc.)
3. Temporarily increase rate limiting if under attack
4. Consider IP blocking at the network level

• Watch for CGC updates that address security issues
• Apply security patches promptly
• Review the changelog for security-related changes

• API Reference - Detailed endpoint documentation
• CLI Reference - Command-line usage
• Technical Overview - How CGC works