[FEATURE][SECURITY]: Security Configuration Validation and Startup Checks

Goal

Implement comprehensive security configuration validation that warns about insecure settings at application startup without breaking the application. This provides visibility into security issues while allowing the application to run, making it easier to gradually improve security posture.

Why Now?

1. Security Misconfigurations: Leading cause of breaches
2. Default Credentials: Many deployments run with default secrets
3. Compliance: Security audits require documented security posture
4. Developer Experience: Clear warnings help developers fix issues
5. Gradual Hardening: Allows incremental security improvements

📖 User Stories

Scenario: Default secret warning
  Given JWT_SECRET_KEY="my-test-key" (default)
  When the application starts
  Then a warning should be logged about default JWT secret
  And the warning should suggest generating a strong secret

Scenario: Default password warning
  Given BASIC_AUTH_PASSWORD="changeme"
  When the application starts
  Then a warning should be logged about default admin password
  And the application should still start (not fail)

Scenario: SSL verification disabled warning
  Given SKIP_SSL_VERIFY=true
  And DEV_MODE=false
  When the application starts
  Then a warning should be logged about disabled SSL verification

Scenario: Strict mode enabled
  Given REQUIRE_STRONG_SECRETS=true
  And JWT_SECRET_KEY="my-test-key"
  When the application starts
  Then startup should be aborted
  And an error should indicate the security issue

Scenario: Strict mode disabled (default)
  Given REQUIRE_STRONG_SECRETS=false (default)
  And JWT_SECRET_KEY="my-test-key"
  When the application starts
  Then startup should succeed with warnings

Scenario: All secrets strong
  Given REQUIRE_STRONG_SECRETS=true
  And JWT_SECRET_KEY is 32+ random characters
  And BASIC_AUTH_PASSWORD is strong
  When the application starts
  Then startup should succeed without warnings

Scenario: Security health endpoint
  Given I am authenticated
  When I call GET /health/security
  Then I should see a security score (0-100)
  And I should see which checks passed/failed
  And I should see warning count

Scenario: CLI security check
  Given the security check script exists
  When I run python scripts/check_security.py
  Then I should see the security score
  And exit code should reflect security status

Scenario: UI without auth warning
  Given MCPGATEWAY_UI_ENABLED=true
  And AUTH_REQUIRED=false
  When the application starts
  Then a warning should be logged about unprotected Admin UI

Scenario: Wildcard CORS warning
  Given CORS_ENABLED=true
  And ALLOWED_ORIGINS contains "*"
  When the application starts
  Then a warning should be logged about permissive CORS

Scenario: Federation without auth warning
  Given FEDERATION_ENABLED=true
  And AUTH_REQUIRED=false
  When the application starts
  Then a critical warning should be logged

🏗 Architecture

Validation Flow

flowchart TD
    A[Application Startup] --> B[Load Settings]
    B --> C[Run Validators]
    C --> D{Collect Warnings}
    D --> E{Critical Issues?}
    E -->|Yes| F{REQUIRE_STRONG_SECRETS?}
    F -->|true| G[Abort Startup]
    F -->|false| H[Log Warnings]
    E -->|No| H
    H --> I[Calculate Security Score]
    I --> J[Continue Startup]

Security Checks

classDiagram
    class SecurityValidator {
        +validate_secrets()
        +validate_passwords()
        +validate_cors_origins()
        +validate_database_url()
        +validate_combinations()
        +get_security_warnings(): List
        +get_security_status(): Dict
        +get_security_score(): int
    }

📋 Implementation Tasks

Phase 1: Secret Validators

• Add JWT secret validation
• Add encryption secret validation
• Check for default/weak secrets
• Check secret length
• Check secret entropy

Phase 2: Password Validators

• Add admin password validation
• Check for default password
• Check password length
• Check password complexity

Phase 3: Configuration Validators

• Validate CORS origins
• Validate database URL
• Validate SSL settings
• Validate dangerous combinations

Phase 4: Startup Integration

• Run validators on startup
• Log warnings with severity
• Implement REQUIRE_STRONG_SECRETS gate
• Print security recommendations

Phase 5: Health Endpoint

• Add /health/security endpoint
• Calculate security score
• Return structured status
• Require authentication for details

Phase 6: CLI Tool

• Create scripts/check_security.py
• Exit codes for CI/CD integration
• Machine-readable output option

Phase 7: Documentation

• Document all validators
• Document security recommendations
• Add to deployment guide

⚙️ Configuration Example

# Security Validation Settings
MIN_SECRET_LENGTH=32
MIN_PASSWORD_LENGTH=12

# Strict mode - fail startup on critical issues
REQUIRE_STRONG_SECRETS=false

# Example strong configuration
JWT_SECRET_KEY=<generated-32-char-random-string>
AUTH_ENCRYPTION_SECRET=<generated-32-char-random-string>
BASIC_AUTH_PASSWORD=<strong-complex-password>
AUTH_REQUIRED=true
SKIP_SSL_VERIFY=false
DEBUG=false
DEV_MODE=false

✅ Success Criteria

• Secret validation working
• Password validation working
• CORS validation working
• Combination validation working
• Warnings logged at startup
• REQUIRE_STRONG_SECRETS gates startup
• Security score calculated
• Health endpoint implemented
• CLI tool working

🏁 Definition of Done

• All validators implemented
• Startup validation integrated
• REQUIRE_STRONG_SECRETS implemented
• /health/security endpoint working
• CLI tool created
• Unit tests pass
• Integration tests pass
• Code passes make verify
• Documentation complete

🔗 Related Issues

• Related: [FEATURE][CONFIG]: Simple endpoint feature flags #537 (Feature flags - warns about enabled features)
• Related: [FEATURE][SECURITY]: Configurable password and secret policy engine #426 (Configurable Password Policy)
• Security best practices documentation