WHOOSH/SECURITY.md

Security Policy

Overview

WHOOSH implements enterprise-grade security controls to protect against common web application vulnerabilities and ensure safe operation in production environments. This document outlines our security implementation, best practices, and procedures.

🔐 Security Implementation

Authentication & Authorization

JWT Authentication

• Role-based access control (admin/user roles)
• Configurable token expiration (default: 24 hours)
• Support for file-based and environment-based secrets
• Secure token validation with comprehensive error handling

Service Token Authentication

• Internal service-to-service authentication
• Scoped permissions for automated systems
• Support for multiple service tokens
• Configurable token management

Protected Endpoints All administrative endpoints require proper authentication:

• Council management (/api/v1/councils/*/artifacts)
• Repository operations (/api/v1/repositories/*)
• Team management (/api/v1/teams/*)
• Task ingestion (/api/v1/tasks/ingest)
• Project operations (/api/v1/projects/*)

Input Validation & Sanitization

Comprehensive Input Validation

• Regex-based validation for all input types
• Request body size limits (1MB default, 10MB for webhooks)
• UUID validation for all identifiers
• Safe character restrictions for names and titles

Validation Rules

Project Names:    ^[a-zA-Z0-9\s\-_]+$           (max 100 chars)
Git URLs:         Proper URL format validation
Task Titles:      Safe characters only           (max 200 chars)
Agent IDs:        ^[a-zA-Z0-9\-]+$             (max 50 chars)
UUIDs:           RFC 4122 compliant format

Injection Prevention

• SQL injection prevention through parameterized queries
• XSS prevention through input sanitization
• Command injection prevention through input validation
• Path traversal prevention through path sanitization

CORS Configuration

Production-Safe CORS

• No wildcard origins in production
• Configurable allowed origins via environment variables
• Support for file-based origin configuration
• Restricted allowed headers and methods

Configuration Example

# Production CORS configuration
WHOOSH_CORS_ALLOWED_ORIGINS=https://app.company.com,https://admin.company.com
WHOOSH_CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
WHOOSH_CORS_ALLOWED_HEADERS=Authorization,Content-Type,X-Requested-With
WHOOSH_CORS_ALLOW_CREDENTIALS=true

Rate Limiting

Per-IP Rate Limiting

• Default: 100 requests per minute per IP address
• Configurable limits and time windows
• Automatic cleanup to prevent memory leaks
• Support for proxy headers (X-Forwarded-For, X-Real-IP)

Configuration

WHOOSH_RATE_LIMIT_ENABLED=true
WHOOSH_RATE_LIMIT_REQUESTS=100        # Requests per window
WHOOSH_RATE_LIMIT_WINDOW=60s          # Rate limiting window
WHOOSH_RATE_LIMIT_CLEANUP_INTERVAL=300s  # Cleanup frequency

Security Headers

HTTP Security Headers

Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin

Webhook Security

Gitea Webhook Protection

• HMAC SHA-256 signature validation
• Timing-safe signature comparison using hmac.Equal
• Request body size limits (10MB maximum)
• Content-Type header validation
• Comprehensive attack attempt logging

Configuration

WHOOSH_WEBHOOK_SECRET_FILE=/run/secrets/webhook_secret
WHOOSH_MAX_WEBHOOK_SIZE=10485760  # 10MB

🛡️ Security Best Practices

Production Deployment

Secret Management

# Use file-based secrets in production
WHOOSH_JWT_SECRET_FILE=/run/secrets/jwt_secret
WHOOSH_GITEA_TOKEN_FILE=/run/secrets/gitea_token
WHOOSH_WEBHOOK_SECRET_FILE=/run/secrets/webhook_secret

# Docker Swarm secrets example
echo "strong-jwt-secret-32-chars-min" | docker secret create whoosh_jwt_secret -

Database Security

# Use SSL/TLS for database connections
WHOOSH_DATABASE_URL=postgres://user:pass@host/db?sslmode=require

# Connection pool limits
WHOOSH_DB_MAX_OPEN_CONNS=25
WHOOSH_DB_MAX_IDLE_CONNS=10
WHOOSH_DB_CONN_MAX_LIFETIME=300s

TLS Configuration

# Enable TLS in production
WHOOSH_TLS_ENABLED=true
WHOOSH_TLS_CERT_FILE=/path/to/cert.pem
WHOOSH_TLS_KEY_FILE=/path/to/key.pem
WHOOSH_TLS_MIN_VERSION=1.2

Security Monitoring

Logging & Monitoring

• Structured logging with security event correlation
• Failed authentication attempt monitoring
• Rate limit violation alerting
• Administrative action audit logging

Health & Security Endpoints

• /health - Basic health check (unauthenticated)
• /admin/health/details - Detailed system status (authenticated)
• /metrics - Prometheus metrics (unauthenticated)

Access Control

Role-Based Permissions

• Admin Role: Full system access, administrative operations
• User Role: Read-only access to public endpoints
• Service Tokens: Scoped access for internal services

Endpoint Protection Matrix

Endpoint Category	Authentication	Authorization
Public Health	None	None
Public APIs	JWT	User/Admin
Admin Operations	JWT	Admin Only
Internal Services	Service Token	Scoped Access
Webhooks	HMAC	Signature

🔍 Security Testing

Vulnerability Assessment

Regular Security Audits

• OWASP Top 10 compliance verification
• Dependency vulnerability scanning
• Static code analysis with security focus
• Penetration testing of critical endpoints

Automated Security Testing

# Static security analysis
go run honnef.co/go/tools/cmd/staticcheck ./...

# Dependency vulnerability scanning
go mod tidy && go list -json -deps | audit

# Security linting
golangci-lint run --enable gosec

Security Validation

Authentication Testing

• Token validation bypass attempts
• Role escalation prevention verification
• Session management security testing
• Service token scope validation

Input Validation Testing

• SQL injection attempt testing
• XSS payload validation testing
• Command injection prevention testing
• File upload security testing (if applicable)

📊 Compliance & Standards

Industry Standards Compliance

OWASP Top 10 2021 Protection

• ✅ A01: Broken Access Control - Comprehensive authentication/authorization
• ✅ A02: Cryptographic Failures - Strong JWT signing, HTTPS enforcement
• ✅ A03: Injection - Parameterized queries, input validation
• ✅ A04: Insecure Design - Security-by-design architecture
• ✅ A05: Security Misconfiguration - Secure defaults, configuration validation
• ✅ A06: Vulnerable Components - Regular dependency updates
• ✅ A07: Identity & Authentication - Robust authentication framework
• ✅ A08: Software & Data Integrity - Webhook signature validation
• ✅ A09: Logging & Monitoring - Comprehensive security logging
• ✅ A10: Server-Side Request Forgery - Input validation prevents SSRF

Enterprise Compliance

• SOC 2 Type II: Access controls, monitoring, data protection
• ISO 27001: Information security management system
• NIST Cybersecurity Framework: Identify, Protect, Detect functions

🚨 Incident Response

Security Incident Handling

Immediate Response

1. Detection: Monitor logs for security events
2. Assessment: Evaluate impact and scope
3. Containment: Implement immediate protective measures
4. Investigation: Analyze attack vectors and impact
5. Recovery: Restore secure operations
6. Learning: Update security measures based on findings

Contact Information For security issues, please follow our responsible disclosure policy:

1. Do not disclose security issues publicly
2. Contact the development team privately
3. Provide detailed reproduction steps
4. Allow reasonable time for fix development

🔧 Configuration Reference

Security Environment Variables

# Authentication
WHOOSH_JWT_SECRET=your-strong-secret-here
WHOOSH_JWT_SECRET_FILE=/run/secrets/jwt_secret
WHOOSH_JWT_EXPIRATION=24h
WHOOSH_JWT_ISSUER=whoosh
WHOOSH_JWT_ALGORITHM=HS256

# Service Tokens
WHOOSH_SERVICE_TOKEN=your-service-token
WHOOSH_SERVICE_TOKEN_FILE=/run/secrets/service_token
WHOOSH_SERVICE_TOKEN_HEADER=X-Service-Token

# CORS Security
WHOOSH_CORS_ALLOWED_ORIGINS=https://app.company.com
WHOOSH_CORS_ALLOWED_ORIGINS_FILE=/run/secrets/allowed_origins
WHOOSH_CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
WHOOSH_CORS_ALLOWED_HEADERS=Authorization,Content-Type
WHOOSH_CORS_ALLOW_CREDENTIALS=true

# Rate Limiting
WHOOSH_RATE_LIMIT_ENABLED=true
WHOOSH_RATE_LIMIT_REQUESTS=100
WHOOSH_RATE_LIMIT_WINDOW=60s
WHOOSH_RATE_LIMIT_CLEANUP_INTERVAL=300s

# Input Validation
WHOOSH_MAX_REQUEST_SIZE=1048576    # 1MB
WHOOSH_MAX_WEBHOOK_SIZE=10485760   # 10MB
WHOOSH_VALIDATION_STRICT=true

# TLS Configuration
WHOOSH_TLS_ENABLED=false           # Set to true in production
WHOOSH_TLS_CERT_FILE=/path/to/cert.pem
WHOOSH_TLS_KEY_FILE=/path/to/key.pem
WHOOSH_TLS_MIN_VERSION=1.2

Production Security Checklist

Deployment Security

• All secrets configured via files or secure environment variables
• CORS origins restricted to specific domains (no wildcards)
• TLS enabled with valid certificates
• Rate limiting configured and enabled
• Input validation strict mode enabled
• Security headers properly configured
• Database connections using SSL/TLS
• Webhook secrets properly configured
• Monitoring and alerting configured
• Security audit logging enabled

Operational Security

• Regular security updates applied
• Access logs monitored
• Failed authentication attempts tracked
• Rate limit violations monitored
• Administrative actions audited
• Backup security validated
• Incident response procedures documented
• Security training completed for operators

📚 Related Documentation

• Security Audit Report - Detailed security audit findings and remediation
• Configuration Guide - Complete configuration documentation
• API Specification - API security details and authentication
• Deployment Guide - Secure production deployment procedures

---

Security Status: Production Ready ✅
Last Security Audit: 2025-09-12
Compliance Level: Enterprise-Grade

For security questions or to report security vulnerabilities, please refer to our incident response procedures above.