This document outlines essential security practices for deploying and operating VC Stack in production environments.

Version 1.0.1+ includes the following security enhancements:

• Removed hardcoded passwords: Default passwords are now sourced from environment variables
• Increased bcrypt cost: Password hashing now uses cost factor 12 (up from 10) for better security
• Input validation: Added comprehensive validation for network names, IPs, CIDRs to prevent command injection
• Security headers: Added security headers middleware (CSP, X-Frame-Options, HSTS, etc.)
• Password strength requirements: Enforced minimum password complexity requirements
• Environment-based configuration: Sensitive values must be set via environment variables
• Improved CORS handling: More secure CORS configuration with origin validation

• Authentication & Authorization
• Secrets Management
• Database Security
• Network Security
• Configuration Security
• Monitoring & Auditing
• Security Checklist

CRITICAL: Default credentials have been removed from the codebase!

As of version 1.0.1, VC Stack no longer contains hardcoded default passwords. You must set the following environment variables:

# Required: Set admin default password
export ADMIN_DEFAULT_PASSWORD="YourSecurePassword123!"

# Required: Generate and set JWT secret
export IDENTITY_JWT_SECRET=$(openssl rand -base64 64)

If ADMIN_DEFAULT_PASSWORD is not set:

• A secure random password will be automatically generated on first start
• The password will be displayed in the logs (WARNING message)
• You MUST change this password immediately after first login

Password Requirements:

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one digit
• At least one special character (!@#$%^&*()_+-=[]{}...)

Generate a strong JWT secret using:

# Generate a 64-byte random secret
openssl rand -base64 64

# Or use /dev/urandom
head -c 64 /dev/urandom | base64

Configuration:

identity:
  jwt:
    secret: <YOUR_GENERATED_SECRET_HERE>
    access_token_expires_in: 24h
    refresh_token_expires_in: 168h

Best Practices:

• Use unique secrets for each environment (dev, staging, production)
• Rotate JWT secrets periodically (recommended: every 90 days)
• Never commit secrets to version control
• Use environment variables or secret management tools

Enforce strong password policies:

• Minimum length: 12 characters
• Require: uppercase, lowercase, numbers, and special characters
• Enable password expiration (e.g., 90 days)
• Prevent password reuse (last 5 passwords)
• Implement account lockout after failed attempts

Never store secrets in:

• Configuration files committed to Git
• Docker Compose files in repositories
• Environment variables in CI/CD logs
• Plain text files on servers

Recommended Solutions:

1. HashiCorp Vault - Enterprise-grade secrets management
2. AWS Secrets Manager - For AWS deployments
3. Azure Key Vault - For Azure deployments
4. Kubernetes Secrets - For K8s deployments
5. Docker Secrets - For Docker Swarm

Use .env files for local development only:

# .env (add to .gitignore)
DATABASE_PASSWORD=your_secure_password
IDENTITY_JWT_SECRET=your_jwt_secret

Load in Docker Compose:

services:
  vc-controller:
    env_file:
      - .env

Production Configuration:

database:
  host: db.example.com
  port: 5432
  name: vcstack
  username: vcstack_app
  password: ${DATABASE_PASSWORD}  # From environment or secrets manager
  sslmode: verify-full  # ⚠️ REQUIRED for production
  # SSL certificate configuration
  sslrootcert: /path/to/ca.crt
  sslcert: /path/to/client.crt
  sslkey: /path/to/client.key

SSL/TLS Requirements:

1. Use sslmode: require at minimum
2. Prefer verify-full for certificate validation
3. Use separate database credentials for each service
4. Implement least-privilege access control

• Disable remote root login
• Use strong, unique passwords for all database users
• Implement IP whitelisting for database access
• Enable audit logging
• Regular security updates and patching
• Encrypt data at rest
• Regular backups with encryption

Always use HTTPS in production:

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

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    # Modern SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
}

Restrict network access:

# Allow only necessary ports
# Controller API
ufw allow 8080/tcp

# PostgreSQL (internal only)
ufw allow from 10.0.0.0/8 to any port 5432

# Deny all other traffic
ufw default deny incoming
ufw default allow outgoing

• Use private networks for inter-service communication
• Implement network segmentation
• Use VPCs or VLANs to isolate environments
• Deploy Web Application Firewall (WAF)

Set restrictive permissions on configuration files:

# Configuration files
chmod 600 /etc/vc-stack/vc-controller.yaml
chown vcstack:vcstack /etc/vc-stack/vc-controller.yaml

# SSL certificates
chmod 600 /etc/ssl/private/vcstack.key
chown root:ssl-cert /etc/ssl/private/vcstack.key

1. Use configuration templates with environment-specific values
2. Separate secrets from configuration
3. Validate configuration before deployment
4. Version control configuration templates (without secrets)
5. Audit configuration changes

# vc-controller.yaml
database:
  host: ${DB_HOST}
  port: ${DB_PORT}
  name: ${DB_NAME}
  username: ${DB_USER}
  password: ${DB_PASSWORD}  # From secret manager
  sslmode: verify-full

# Load from environment or secret manager
export DB_HOST="db.example.com"
export DB_PASSWORD=$(vault kv get -field=password secret/vcstack/db)

Implement comprehensive logging and monitoring:

1. Authentication Events

   • Failed login attempts
   • Password changes
   • Token generation and validation

2. Authorization Events

   • Access denials
   • Permission changes
   • Privilege escalations

3. System Events

   • Configuration changes
   • Service restarts
   • Error conditions

• Centralize logs using ELK Stack, Splunk, or similar
• Enable audit logging for database operations
• Set up alerts for suspicious activities
• Retain logs according to compliance requirements
• Encrypt logs in transit and at rest

Regular security assessments:

# Dependency scanning
go list -json -m all | docker run --rm -i sonatypeiq/nancy:latest sleuth

# Container scanning
trivy image vcstack/controller:latest

# Code scanning
gosec ./...

• Changed all default passwords and credentials
• Generated strong, unique JWT secret
• Enabled SSL/TLS for all network communications
• Configured SSL mode for database connections
• Implemented secrets management solution
• Set restrictive file permissions on configuration files
• Configured firewall rules
• Enabled audit logging
• Set up security monitoring and alerts
• Performed security scanning (dependencies, containers, code)
• Implemented backup and disaster recovery procedures
• Documented security procedures and incident response plan

• Rotate credentials and secrets (every 90 days)
• Apply security updates and patches
• Review access logs for anomalies
• Update SSL/TLS certificates before expiration
• Conduct security audits and penetration testing
• Review and update firewall rules
• Test backup and recovery procedures
• Update documentation

1. Identify and contain the incident
2. Assess the impact and scope
3. Preserve evidence for investigation
4. Eradicate the threat
5. Recover services
6. Document lessons learned
7. Update security measures

Maintain a list of emergency contacts:

• Security team
• System administrators
• Database administrators
• Network operations
• Management

• OWASP Security Guidelines
• CIS Benchmarks
• NIST Cybersecurity Framework
• Go Security Best Practices

If you discover a security vulnerability in VC Stack, please report it to:

Email: security@vcstack.com (if available)

Please do not:

• Disclose the vulnerability publicly
• Test the vulnerability on production systems
• Access or modify other users' data

We appreciate responsible disclosure and will acknowledge your report within 48 hours.

Last Updated: January 2026

Version: 1.0

Review Schedule: Quarterly