Security Policy

Version: 1.3.0
Last Updated: November 16, 2025

Reporting Security Vulnerabilities

If you discover a security vulnerability, please report it privately:

Email: security@hivellm.dev
Expected Response Time: 48 hours
Public Disclosure: After fix is released

Please do NOT:

Open public GitHub issues for security vulnerabilities
Disclose vulnerabilities before a fix is available
Exploit vulnerabilities in production systems

Security Features

1. Authentication

JWT Tokens

Algorithm: RS256 (RSA with SHA-256)
Expiration: Configurable (default: 24 hours)
Refresh: Supported via token refresh endpoint

API Keys

Format: UUID v4 (128-bit random)
Storage: Hashed with bcrypt
Rotation: Supported via API
Expiration: Optional, configurable per key

2. Rate Limiting

Prevents API abuse and DoS attacks.

Configuration (config.yml):

security:
  rate_limiting:
    enabled: true
    requests_per_second: 100
    burst_size: 200

Limits:

Per API Key: 100 req/s (configurable)
Burst Capacity: 200 requests (configurable)
Response: HTTP 429 (Too Many Requests)

Headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1698332400

3. TLS/mTLS

Encrypted communication for production deployments.

TLS Configuration

security:
  tls:
    enabled: true
    cert_path: "/path/to/server.crt"
    key_path: "/path/to/server.key"

Requirements:

TLS 1.3 minimum
Strong cipher suites only
Valid certificate from trusted CA

mTLS (Mutual TLS)

Client certificate authentication for high-security environments.

security:
  tls:
    enabled: true
    mtls_enabled: true
    cert_path: "/path/to/server.crt"
    key_path: "/path/to/server.key"
    client_ca_path: "/path/to/client-ca.crt"

4. Audit Logging

Tracks all API calls for compliance and forensics.

security:
  audit:
    enabled: true
    max_entries: 10000
    log_auth_attempts: true
    log_failed_requests: true
    log_admin_actions: true

Logged Events:

All API requests (method, endpoint, status, duration)
Authentication attempts (success and failures)
Administrative actions (config changes, server restart)
Permission checks (RBAC decisions)

Audit Log Entry:

{
  "timestamp": "2025-10-25T10:30:45Z",
  "principal": "api-key-abc123",
  "method": "POST",
  "endpoint": "/collections",
  "status_code": 200,
  "duration_ms": 15,
  "client_ip": "192.168.1.100",
  "correlation_id": "550e8400-e29b-41d4-a716-446655440000"
}

5. Role-Based Access Control (RBAC)

Fine-grained permissions for different user types.

security:
  rbac:
    enabled: true
    default_role: "Viewer"

Predefined Roles

Viewer (Read-Only):

✅ List collections
✅ Read collection details
✅ Search vectors
✅ Get vector by ID
✅ View system stats
❌ Create/update/delete anything

Editor (Read/Write):

✅ All Viewer permissions
✅ Create collections
✅ Update collections
✅ Insert vectors
✅ Update vectors
✅ Delete vectors
✅ Batch operations
❌ Delete collections
❌ Admin actions

Admin (Full Access):

✅ All Editor permissions
✅ Delete collections
✅ Manage API keys
✅ View audit logs
✅ Configure server
✅ Manage replication
✅ View metrics
✅ Restart server
✅ Backup/restore data

6. Enhanced Security Features

Advanced security capabilities for high-security environments.

Multi-Factor Authentication (MFA)

Optional MFA support for additional authentication layers:

security:
  enhanced:
    authentication:
      enable_mfa: true
      mfa_methods: ["totp", "sms", "email"]
      account_lockout:
        enabled: true
        max_attempts: 5
        lockout_duration_seconds: 900

Supported MFA Methods:

TOTP (Time-based One-Time Password)
SMS verification
Email verification
Biometric authentication (platform-dependent)

Threat Detection

Automated threat detection and response:

security:
  enhanced:
    threat_detection:
      enabled: true
      alert_thresholds:
        failed_login_attempts: 5
        suspicious_activity_score: 80
      response_actions:
        - "block_ip"
        - "require_mfa"
        - "notify_admin"

Detected Threats:

Brute force attacks
Suspicious access patterns
Unusual API usage
Resource exhaustion attempts
Anomalous behavior patterns

Security Policy Engine

Configurable security policies for compliance:

security:
  enhanced:
    security_policy:
      enabled: true
      rules:
        - name: "password_policy"
          type: "password_complexity"
          min_length: 12
          require_uppercase: true
          require_lowercase: true
          require_numbers: true
          require_special: true

7. System Guardrails

Runtime protection against system crashes and resource exhaustion.

Guardrails Configuration

security:
  guardrails:
    enabled: true
    max_memory_percent: 75.0
    max_cpu_percent: 90.0
    min_free_memory_mb: 512
    max_concurrent_ops: 4
    auto_throttle: true
    windows_protection: true

Protection Features:

Memory usage monitoring (prevents OOM crashes)
CPU usage throttling (prevents system overload)
Concurrent operation limits (prevents resource exhaustion)
Automatic throttling under load
Windows-specific protections (prevents BSOD)

Violation Handling:

Automatic resource throttling
Operation queuing when limits exceeded
Violation logging and alerting
Graceful degradation

Security Best Practices

Production Deployment

✅ Required

✅ Recommended

⚠️ Avoid

❌ Exposing server directly to internet without TLS
❌ Using default API keys in production
❌ Using default Docker credentials (admin/admin) in production
❌ Committing .env files or credentials to version control
❌ Disabling authentication
❌ Running as root user
❌ Storing credentials in code or config files
❌ Using weak passwords or JWT secrets
❌ Disabling audit logging

Network Security

Firewall Rules

# Allow only necessary ports
ufw allow 15002/tcp  # Vectorizer API
ufw allow 7001/tcp   # Replication (if master)
ufw deny 4317/tcp    # Block OTLP (internal only)
ufw enable

Reverse Proxy

Use nginx/Apache as reverse proxy:

server {
    listen 443 ssl http2;
    server_name vectorizer.example.com;

    ssl_certificate /etc/ssl/certs/vectorizer.crt;
    ssl_certificate_key /etc/ssl/private/vectorizer.key;
    ssl_protocols TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://127.0.0.1:15002;
        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;

        # Rate limiting at proxy level
        limit_req zone=vectorizer burst=20 nodelay;
    }
}

API Key Management

Generate Secure API Keys

# Use vectorizer CLI
vectorizer-cli api-key create --name "production-app" --role Editor

# Or generate manually
openssl rand -hex 32

Rotate API Keys

# 1. Create new key
vectorizer-cli api-key create --name "production-app-new"

# 2. Update client applications

# 3. Revoke old key
vectorizer-cli api-key revoke "old-key-id"

Secrets Management

Environment Variables

# Never commit .env files
export VECTORIZER_JWT_SECRET="your-secret-here"
export VECTORIZER_API_KEY="your-api-key-here"

# Start server
./vectorizer

Docker Authentication

⚠️ CRITICAL: Docker images include default credentials that MUST be changed in production!

Default Credentials:

Username: admin
Password: admin
JWT Secret: change-this-secret-in-production

Production Deployment:

# Generate strong credentials
ADMIN_PASSWORD=$(openssl rand -base64 32)
JWT_SECRET=$(openssl rand -base64 48)

# Run with secure credentials
docker run -d \
  --name vectorizer \
  -p 15002:15002 \
  -v $(pwd)/vectorizer-data:/vectorizer/data \
  -e VECTORIZER_AUTH_ENABLED=true \
  -e VECTORIZER_ADMIN_USERNAME=admin \
  -e VECTORIZER_ADMIN_PASSWORD="${ADMIN_PASSWORD}" \
  -e VECTORIZER_JWT_SECRET="${JWT_SECRET}" \
  --restart unless-stopped \
  hivehub/vectorizer:latest

Docker Compose with .env:

# Copy and customize .env file
cp .env.example .env

# Edit .env with your credentials
# NEVER commit .env to version control!

# Start with docker-compose
docker-compose up -d

Security Checklist for Docker:

Change default admin password
Generate strong JWT secret (minimum 48 characters)
Use environment variables or Docker secrets
Never commit credentials to version control
Enable TLS with reverse proxy (nginx/Traefik)
Use Docker secrets for production
Regularly rotate credentials
Monitor authentication logs

For detailed Docker authentication guide, see: docs/users/getting-started/DOCKER_AUTHENTICATION.md

Docker Secrets

version: "3.8"
services:
  vectorizer:
    image: vectorizer:latest
    secrets:
      - admin_password
      - jwt_secret
      - api_key
    environment:
      - VECTORIZER_AUTH_ENABLED=true
      - VECTORIZER_ADMIN_USERNAME=admin
      - VECTORIZER_ADMIN_PASSWORD_FILE=/run/secrets/admin_password
      - VECTORIZER_JWT_SECRET_FILE=/run/secrets/jwt_secret

secrets:
  admin_password:
    external: true
  jwt_secret:
    external: true
  api_key:
    external: true

Create Docker secrets:

echo "your-secure-password" | docker secret create admin_password -
echo "your-jwt-secret-key-minimum-48-chars" | docker secret create jwt_secret -

Client SDK Security

All Vectorizer client SDKs implement security best practices:

SDK Security Features

TypeScript/JavaScript SDKs:

✅ Secure credential storage (never in code)
✅ TLS/HTTPS enforcement
✅ Request signing support
✅ Automatic retry with exponential backoff
✅ Input validation and sanitization

Python SDK:

✅ Environment variable support for credentials
✅ Secure credential management
✅ TLS certificate validation
✅ Request timeout protection
✅ Input sanitization

Rust SDK:

✅ Type-safe credential handling
✅ Zero-copy where possible
✅ Memory-safe operations
✅ TLS certificate pinning support
✅ Secure defaults

Go SDK:

✅ Secure credential storage
✅ TLS configuration support
✅ Context-based cancellation
✅ Input validation
✅ Error handling without information leakage

C# SDK:

✅ Secure credential management
✅ Async/await for non-blocking operations
✅ TLS certificate validation
✅ Disposable pattern for resource cleanup
✅ Strong typing for security

SDK Security Best Practices

// ✅ GOOD: Use environment variables
const client = new VectorizerClient({
  baseURL: process.env.VECTORIZER_URL,
  apiKey: process.env.VECTORIZER_API_KEY,
});

// ❌ BAD: Hardcoded credentials
const client = new VectorizerClient({
  baseURL: "https://api.example.com",
  apiKey: "hardcoded-key-12345", // NEVER DO THIS
});

Recommendations:

Store API keys in secure vaults (AWS Secrets Manager, HashiCorp Vault)
Use separate API keys per environment (dev/staging/prod)
Rotate API keys regularly
Never commit credentials to version control
Use least-privilege principle for API key permissions

Compliance

GDPR

✅ Audit logs track data access
✅ Data deletion support (delete collections/vectors)
✅ Data portability (export via API)
⚠️ User consent management (application responsibility)

SOC 2

✅ Access control (RBAC)
✅ Audit logging
✅ Encryption in transit (TLS)
✅ Encryption at rest (Zstd compression)
⚠️ Incident response plan (documentation required)

HIPAA

✅ Access control (RBAC)
✅ Audit logging
✅ Encryption in transit (TLS)
⚠️ Business Associate Agreement required
⚠️ Additional controls may be needed

Security Checklist

Development

Review code for security issues
Run cargo audit for dependency vulnerabilities
Run cargo clippy with security lints
Write security tests
Document security decisions

Staging

Production

Vulnerability Disclosure

Supported Versions

Version	Supported
1.3.x	✅ Yes
1.2.x	✅ Yes
1.1.x	✅ Yes
1.0.x	⚠️ Limited
< 1.0	❌ No

Security Updates

Critical: Released within 24 hours
High: Released within 7 days
Medium: Released within 30 days
Low: Released in next regular release

Contact

Security Team: security@hivellm.dev
General Support: support@hivellm.dev
GitHub: https://github.com/hivellm/vectorizer/security

Acknowledgments

We thank security researchers who responsibly disclose vulnerabilities. Hall of Fame for contributors will be maintained in SECURITY_HALL_OF_FAME.md.

For monitoring and observability, see: docs/MONITORING.md

Security: hivellm/vectorizer

Security

SECURITY.md