Security

Brokle is designed with security as a core principle. This guide covers security best practices, data handling, and compliance considerations.

Security Overview

Brokle protects your data through:

• Encryption at rest and in transit
• Role-based access control (RBAC)
• API key management with rotation
• Audit logging
• Data isolation between organizations

Data Security

Encryption

Data Isolation

• Multi-tenant architecture: Each organization's data is logically isolated
• Project-level scoping: Traces, prompts, and evaluations are project-scoped
• API key scoping: Keys are bound to specific projects

Data Retention

Configure retention policies per project:

# SDK-level configuration
brokle = Brokle(
    project_id="proj_123",
    # Traces older than 30 days are automatically deleted
)

Dashboard configuration:

• Navigate to Settings → Data Retention
• Set retention period (7, 30, 90 days, or custom)
• Configure archival vs deletion

Authentication

API Keys

API keys follow the format bk_{40_random_chars}:

bk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Best practices:

• Rotate keys every 90 days
• Use separate keys for development and production
• Never commit keys to version control
• Store keys in secrets managers

JWT Authentication

Dashboard authentication uses JWT tokens:

• Access tokens expire in 24 hours
• Refresh tokens expire in 7 days
• Tokens are bound to user sessions

SSO (Enterprise)

Enterprise customers can configure:

• SAML 2.0: Okta, Azure AD, OneLogin
• OIDC/OAuth2: Google, GitHub, custom providers

Authorization

Role-Based Access Control

Scopes (Enterprise)

Fine-grained permissions with scopes:

• traces:read, traces:write
• prompts:read, prompts:write, prompts:publish
• projects:manage
• members:manage

Network Security

Recommended Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Secure Deployment                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│    Internet                                                      │
│        │                                                         │
│        ▼                                                         │
│    ┌──────────────┐                                              │
│    │   WAF/CDN    │  Rate limiting, DDoS protection              │
│    └──────────────┘                                              │
│        │                                                         │
│        ▼                                                         │
│    ┌──────────────┐                                              │
│    │ Load Balancer│  TLS termination                             │
│    └──────────────┘                                              │
│        │                                                         │
│        ▼                                                         │
│    ┌──────────────┐     ┌──────────────┐                        │
│    │  Brokle API  │────▶│  Databases   │  Private subnet        │
│    └──────────────┘     └──────────────┘                        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Firewall Rules

Rate Limiting

Default rate limits (configurable):

• SDK ingestion: 1000 requests/minute per API key
• Dashboard API: 100 requests/minute per user
• Authentication: 10 attempts/minute per IP

Secrets Management

Environment Variables

Never hardcode secrets. Use environment variables:

# Required secrets
JWT_SECRET=<min-32-chars>
AI_KEY_ENCRYPTION_KEY=<base64-encoded-32-bytes>

# Database credentials
DATABASE_URL=postgresql://user:pass@host/db

Secrets Managers

Integrate with your secrets manager:

# AWS Secrets Manager
JWT_SECRET=$(aws secretsmanager get-secret-value --secret-id brokle/jwt)

# HashiCorp Vault
JWT_SECRET=$(vault kv get -field=jwt-secret secret/brokle)

# Kubernetes Secrets
kubectl create secret generic brokle-secrets \
  --from-literal=jwt-secret="$JWT_SECRET"

Audit Logging

Brokle logs all security-relevant events:

Access audit logs:

• Dashboard: Settings → Audit Log
• API: GET /api/v1/audit-logs

Compliance

Self-Hosted Compliance

For organizations with compliance requirements, self-hosting gives you full control:

• Deploy within your own compliant infrastructure
• Manage data residency requirements
• Apply your organization's security policies

HIPAA (Enterprise)

For healthcare customers:

• BAA available
• PHI handling procedures
• Enhanced encryption
• Audit trail requirements

Vulnerability Reporting

Report security vulnerabilities:

• Email: security@brokle.dev
• HackerOne: hackerone.com/brokle

We follow responsible disclosure and aim to respond within 24 hours.

Security Checklist

Self-Hosted Deployments

• Use TLS for all connections
• Configure strong JWT secrets (32+ chars)
• Enable rate limiting
• Restrict database access to internal networks
• Set up regular backups
• Configure log retention
• Enable audit logging
• Review access permissions regularly
• Keep Brokle updated

SDK Integration

• Store API keys in environment variables
• Use separate keys for dev/prod
• Implement key rotation
• Filter sensitive data from traces
• Set appropriate retention policies

Related