This document outlines security features, best practices, and configuration for BackBone-AI.

• Authentication
• Rate Limiting
• Input Validation
• Security Configuration
• Security Best Practices
• Vulnerability Reporting

BackBone-AI supports two authentication methods:

Simple and straightforward for service-to-service communication.

Setup:

# .env
ENABLE_AUTH=true
API_KEY=your-secure-api-key-here  # Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"

Usage:

curl -H "X-API-Key: your-api-key" http://localhost:8000/api/v1/generate

Generating a secure API key:

import secrets
api_key = secrets.token_urlsafe(32)
print(api_key)  # Use this in .env

More secure for user-based applications with expiration and scopes.

Creating a token:

from app.core.security import create_access_token
from datetime import timedelta

token = create_access_token(
    data={"sub": "user@example.com", "scopes": ["generate", "validate"]},
    expires_delta=timedelta(hours=24)
)

Usage:

curl -H "Authorization: Bearer <token>" http://localhost:8000/api/v1/generate

# .env
ENABLE_AUTH=false

⚠️ WARNING: Never disable authentication in production!

Protects against abuse and controls costs.

Responses include rate limit information:

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

When exceeded (429 Too Many Requests):

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit. Please try again later.",
  "retry_after": 30
}

Configure in .env:

# Not yet implemented - coming soon
RATE_LIMIT_PUBLIC=20/minute
RATE_LIMIT_AUTHENTICATED=100/minute

Comprehensive validation prevents security issues and resource abuse.

1. JSON Structure: Valid JSON syntax
2. Size Validation: Within limits
3. Required Fields: project_name, schema
4. Type Validation: Correct data types
5. Suspicious Patterns: SQL injection, XSS, code injection
6. Sanitization: Null bytes removed, strings truncated

The following patterns are blocked in schema input:

• drop table
• delete from
• <script>
• javascript:
• eval(
• exec(

Error Response (400 Bad Request):

{
  "detail": "Suspicious pattern detected in schema: drop table"
}

# =====================================================
# SECURITY CONFIGURATION
# =====================================================

# Authentication
ENABLE_AUTH=true  # Enable/disable authentication
API_KEY=your-secure-api-key-32-chars-min

# JWT Settings (if using JWT)
JWT_SECRET_KEY=your-jwt-secret-key
JWT_ALGORITHM=HS256
JWT_EXPIRATION_HOURS=24

# Rate Limiting
ENABLE_RATE_LIMITING=true  # Always enabled in production

# Input Validation
MAX_JSON_SIZE=10485760  # 10 MB in bytes
MAX_TABLES=50
MAX_COLUMNS_PER_TABLE=100
MAX_RELATIONSHIPS_PER_TABLE=50

# CORS (Cross-Origin Resource Sharing)
CORS_ORIGINS=["https://yourdomain.com"]
CORS_ALLOW_CREDENTIALS=true

# Security Headers
ENABLE_SECURITY_HEADERS=true

• Enable authentication (ENABLE_AUTH=true)
• Use strong API keys (32+ characters, cryptographically random)
• Rotate API keys regularly (every 90 days)
• Enable HTTPS (use reverse proxy like nginx)
• Configure CORS properly (don't use *)
• Monitor rate limits and adjust as needed
• Enable security headers (CSP, HSTS, etc.)
• Keep dependencies updated (check weekly)
• Enable logging for security events
• Set up alerts for suspicious activity
• Regular security audits (quarterly)
• Backup API keys securely (use secrets manager)

DO: ✅ Generate keys with secrets.token_urlsafe(32) ✅ Store in environment variables or secrets manager ✅ Use different keys for dev/staging/production ✅ Rotate keys regularly ✅ Log key usage and failures

DON'T: ❌ Hardcode keys in code ❌ Commit keys to git ❌ Share keys via email/chat ❌ Use same key across environments ❌ Use predictable keys

Multiple layers of security:

1. Network Level: Firewall, VPN, IP whitelist
2. Application Level: Authentication, rate limiting
3. Input Level: Validation, sanitization
4. Output Level: Encoding, escaping
5. Monitoring Level: Logging, alerting, auditing

If you suspect a security breach:

1. Immediately rotate all API keys
2. Review logs for suspicious activity
3. Check metrics for anomalies
4. Block suspicious IPs if identified
5. Notify team and stakeholders
6. Document incident for post-mortem
7. Update security measures based on learnings

Dependencies are updated to latest secure versions:

langchain==0.3.27  # Updated from 0.3.0
fastapi==0.115.6   # Updated from 0.115.0
pydantic==2.10.5   # Updated from 2.8.0
jinja2==3.1.5      # Updated from 3.1.4

# Install safety
pip install safety

# Check dependencies
safety check --json

# Or use pip-audit
pip install pip-audit
pip-audit

• Critical vulnerabilities: Immediate
• High severity: Within 7 days
• Medium severity: Within 30 days
• Low severity: Next release cycle

Always use HTTPS in production. Configure with nginx:

server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Add security headers via nginx or middleware:

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header Content-Security-Policy "default-src 'self'" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

• Failed authentication attempts
• Rate limit violations
• Suspicious input patterns
• Unusual API usage patterns
• Large requests
• Error rate spikes

# Failed auth attempts (Prometheus)
rate(backbone_http_requests_total{status="401"}[5m]) > 5

# Rate limit violations
rate(backbone_http_requests_total{status="429"}[5m]) > 10

# Error rate spike
rate(backbone_http_requests_total{status=~"5.."}[5m]) > 0.1

BackBone-AI follows security best practices:

• ✅ OWASP Top 10 protection
• ✅ Input validation and sanitization
• ✅ Authentication and authorization
• ✅ Rate limiting and DoS protection
• ✅ Secure defaults (auth required)
• ✅ Security logging and monitoring
• ✅ Dependency scanning and updates

Found a security issue? Please report responsibly.

Do NOT:

• Open public GitHub issues
• Share details publicly

Instead:

1. Email: security@yourdomain.com (set this up!)
2. Include:
   • Description of vulnerability
   • Steps to reproduce
   • Impact assessment
   • Suggested fix (if known)

Response Timeline:

• Acknowledgment: 24 hours
• Initial assessment: 72 hours
• Fix timeline: Based on severity

• OWASP API Security Top 10
• FastAPI Security
• JWT Best Practices
• Rate Limiting Patterns

For security questions or concerns:

• GitHub Issues: https://github.com/vidinsight-miniflow/BackBone-AI/issues
• Documentation: https://github.com/vidinsight-miniflow/BackBone-AI/docs
• Security Email: (set up dedicated email)