CorpusIQ

CorpusIQ Apps SDK - Security Guide

CorpusIQ Apps SDK - Security Guide

Overview

This document outlines the security features and best practices implemented in the CorpusIQ Apps SDK.

Security Features

1. CORS Protection

  • Default: CORS is disabled (empty origin list) requiring explicit configuration
  • Configuration: Set CORPUSIQ_CORS_ALLOW_ORIGINS_CSV with specific comma-separated origins
  • Warning: Wildcard (*) origins trigger a security warning and should not be used in production

2. Rate Limiting

  • Default: 60 requests per minute per IP address
  • Configuration: Adjust via CORPUSIQ_RATE_LIMIT_REQUESTS_PER_MINUTE
  • Implementation: In-memory tracking with automatic cleanup
  • Note: For multi-instance deployments, consider Redis-based rate limiting

3. Security Headers

All responses include the following security headers:

  • X-Content-Type-Options: nosniff - Prevents MIME type sniffing
  • X-Frame-Options: DENY - Prevents clickjacking attacks
  • X-XSS-Protection: 1; mode=block - Enables browser XSS protection
  • Referrer-Policy: strict-origin-when-cross-origin - Controls referrer information
  • Server header removal - Reduces information disclosure

4. Input Validation

  • Query Length: Maximum 1000 characters
  • Result Limits: Maximum 20 results per query
  • Validation: Pydantic models with custom validators
  • Sanitization: Empty/whitespace-only queries are rejected

5. Error Handling

  • Generic Errors: Internal errors return generic messages to prevent information disclosure
  • Logging: Detailed errors are logged server-side for debugging
  • Request Tracking: Each request gets a unique ID for tracing

6. Debug Endpoints

  • Default: Debug endpoints are disabled in production
  • Configuration: Enable via CORPUSIQ_DEBUG_MODE=true (development only)
  • Endpoints: /debug/tools, /debug/ping
  • Warning: These endpoints do not require authentication

7. Request Logging

  • Request ID: Each request is assigned a unique UUID
  • Timing: Request duration is logged
  • Headers: Request ID is returned in X-Request-ID header

8. Frontend Security (HTML Widget)

  • XSS Prevention: Uses textContent instead of innerHTML for user content
  • Error Handling: Generic error messages shown to users
  • Input Validation: Client-side validation before API calls

Production Deployment Checklist

  • [ ] Set CORPUSIQ_DEBUG_MODE=false
  • [ ] Configure specific CORS origins (not *)
  • [ ] Set appropriate CORPUSIQ_LOG_LEVEL (INFO or WARNING)
  • [ ] Configure rate limiting based on expected traffic
  • [ ] Review and adjust CORPUSIQ_MAX_REQUEST_SIZE
  • [ ] Set up centralized logging for production monitoring
  • [ ] Use HTTPS/TLS for all connections
  • [ ] Run behind a reverse proxy (nginx, cloudflared) with additional security
  • [ ] Implement monitoring and alerting for rate limit violations
  • [ ] Regular security audits and updates

Environment Variables

See .env.example for all available configuration options with security recommendations.

Monitoring

The application logs:

  • All incoming requests with method, path, and duration
  • Rate limit violations
  • Security warnings (CORS misconfiguration, debug mode enabled)
  • Error details (server-side only, not exposed to clients)

Known Limitations

  1. Rate Limiting: Current implementation uses in-memory storage. For distributed deployments, implement Redis-based rate limiting.
  2. Debug Mode: Debug endpoints have no authentication. Only enable in secure development environments.
  3. Host Header: Host header validation is disabled to support tunnel proxies (cloudflared, ngrok).

Reporting Security Issues

If you discover a security vulnerability, please report it to the maintainers privately rather than through public channels.