CalejoControl/SECURITY.md

# Calejo Control Adapter - Security Hardening Guide

## Overview

This document provides security hardening guidelines for the Calejo Control Adapter in production environments.

## Network Security

### Firewall Configuration

```bash
# Allow only necessary ports
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp    # SSH
ufw allow 5432/tcp  # PostgreSQL (restrict to internal network)
ufw allow 8080/tcp  # REST API (consider restricting)
ufw allow 9090/tcp  # Prometheus metrics (internal only)
ufw enable
```

### Network Segmentation

- Place database on internal network
- Use VPN for remote access
- Implement network ACLs
- Consider using a reverse proxy (nginx/traefik)

## Application Security

### Environment Variables

Never commit sensitive data to version control:

```bash
# .env file (add to .gitignore)
JWT_SECRET_KEY=your-very-long-random-secret-key-minimum-32-chars
API_KEY=your-secure-api-key
DATABASE_URL=postgresql://calejo:secure-password@localhost:5432/calejo
```

### Authentication & Authorization

1. **JWT Configuration**
   - Use strong secret keys (min 32 characters)
   - Set appropriate token expiration
   - Implement token refresh mechanism

2. **API Key Security**
   - Rotate API keys regularly
   - Use different keys for different environments
   - Implement rate limiting

### Input Validation

- Validate all API inputs
- Sanitize database queries
- Use parameterized queries
- Implement request size limits

## Database Security

### PostgreSQL Hardening

```sql
-- Change default port
ALTER SYSTEM SET port = 5433;

-- Enable SSL
ALTER SYSTEM SET ssl = on;

-- Restrict connections
ALTER SYSTEM SET listen_addresses = 'localhost';

-- Apply changes
SELECT pg_reload_conf();
```

### Database User Permissions

```sql
-- Create application user with minimal permissions
CREATE USER calejo_app WITH PASSWORD 'secure-password';
GRANT CONNECT ON DATABASE calejo TO calejo_app;
GRANT USAGE ON SCHEMA public TO calejo_app;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO calejo_app;
```

## Container Security

### Docker Security Best Practices

```dockerfile
# Use non-root user
USER calejo

# Read-only filesystem where possible
VOLUME ["/tmp", "/logs"]

# Health checks
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1
```

### Docker Compose Security

```yaml
services:
  calejo-control-adapter:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
```

## Monitoring & Auditing

### Security Logging

- Log all authentication attempts
- Monitor for failed login attempts
- Track API usage patterns
- Audit database access

### Security Monitoring

```yaml
# Prometheus alert rules for security
- alert: FailedLoginAttempts
  expr: rate(calejo_auth_failures_total[5m]) > 5
  for: 2m
  labels:
    severity: warning
  annotations:
    summary: "High rate of failed login attempts"
```

## SSL/TLS Configuration

### Generate Certificates

```bash
# Self-signed certificate for development
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Production: Use Let's Encrypt or commercial CA
```

### Application Configuration

```python
# Enable TLS in settings
TLS_ENABLED = True
TLS_CERT_PATH = "/path/to/cert.pem"
TLS_KEY_PATH = "/path/to/key.pem"
```

## Backup Security

### Secure Backup Storage

- Encrypt backup files
- Store backups in secure location
- Implement access controls
- Regular backup testing

### Backup Encryption

```bash
# Encrypt backups with GPG
gpg --symmetric --cipher-algo AES256 backup_file.sql.gz

# Decrypt for restore
gpg --decrypt backup_file.sql.gz.gpg > backup_file.sql.gz
```

## Incident Response

### Security Incident Checklist

1. **Detection**
   - Monitor security alerts
   - Review access logs
   - Check for unusual patterns

2. **Containment**
   - Isolate affected systems
   - Change credentials
   - Block suspicious IPs

3. **Investigation**
   - Preserve logs and evidence
   - Identify root cause
   - Assess impact

4. **Recovery**
   - Restore from clean backup
   - Apply security patches
   - Update security controls

5. **Post-Incident**
   - Document lessons learned
   - Update security policies
   - Conduct security review

## Regular Security Tasks

### Monthly Security Tasks

- [ ] Review and rotate credentials
- [ ] Update dependencies
- [ ] Review access logs
- [ ] Test backup restoration
- [ ] Security patch application

### Quarterly Security Tasks

- [ ] Security audit
- [ ] Penetration testing
- [ ] Access control review
- [ ] Security policy review

## Compliance & Standards

### Relevant Standards

- **NIST Cybersecurity Framework**
- **IEC 62443** (Industrial control systems)
- **ISO 27001** (Information security)
- **GDPR** (Data protection)

### Security Controls

- Access control policies
- Data encryption at rest and in transit
- Regular security assessments
- Incident response procedures
- Security awareness training

## Contact Information

For security vulnerabilities or incidents:

- **Security Team**: security@calejo-control.com
- **PGP Key**: [Link to public key]
- **Responsible Disclosure**: Please report vulnerabilities privately

---

**Note**: This document should be reviewed and updated regularly to address new security threats and best practices.