# Calejo Control Adapter - Security & Compliance Framework

## Overview

The Calejo Control Adapter implements a comprehensive security framework designed for critical infrastructure protection. The system is built with security-by-design principles and complies with major industrial and information security standards.

**Security Philosophy**: "Defense in Depth" - Multiple layers of security controls protecting critical control systems.

## Regulatory Compliance Framework

### Supported Standards & Regulations

#### 1. IEC 62443 - Industrial Automation and Control Systems Security
- **IEC 62443-3-3**: System security requirements and security levels
- **IEC 62443-4-1**: Secure product development lifecycle requirements
- **IEC 62443-4-2**: Technical security requirements for IACS components

#### 2. ISO 27001 - Information Security Management
- **Annex A Controls**: Comprehensive security control implementation
- **Risk Management**: Systematic risk assessment and treatment
- **Continuous Improvement**: Ongoing security management

#### 3. NIS2 Directive - Network and Information Systems Security
- **Essential Entities**: Classification as essential entity
- **Security Measures**: Required security and reporting measures
- **Incident Reporting**: Mandatory incident reporting requirements

#### 4. Additional Standards
- **NIST Cybersecurity Framework**: Risk management framework
- **CIS Controls**: Critical security controls
- **Water Sector Security**: Industry-specific security requirements

## Security Architecture

### Defense in Depth Strategy

```
┌─────────────────────────────────────────────────────────┐
│  Layer 7: Physical Security                             │
│  - Access control to facilities                         │
│  - Environmental controls                               │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 6: Network Security                              │
│  - Firewalls & segmentation                             │
│  - Network monitoring                                   │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 5: System Security                               │
│  - OS hardening                                         │
│  - Patch management                                     │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 4: Application Security                          │
│  - Authentication & authorization                       │
│  - Input validation                                     │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 3: Data Security                                 │
│  - Encryption at rest & in transit                      │
│  - Data integrity protection                            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 2: Audit & Monitoring                            │
│  - Comprehensive logging                                │
│  - Security monitoring                                  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  Layer 1: Incident Response                             │
│  - Response procedures                                  │
│  - Recovery capabilities                                │
└─────────────────────────────────────────────────────────┘
```

## Security Components

### 1. Authentication System (`src/core/security.py`)

#### JWT-Based Authentication

```python
class AuthenticationManager:
    """Manages user authentication with JWT tokens and password hashing."""
    
    def authenticate_user(self, username: str, password: str) -> Optional[User]:
        """Authenticate user and return user object if successful."""
        
    def create_access_token(self, user: User) -> str:
        """Create a JWT access token for the user."""
        
    def verify_token(self, token: str) -> Optional[TokenData]:
        """Verify and decode a JWT token."""
```

#### Password Security

- **bcrypt Hashing**: Industry-standard password hashing
- **Salt Generation**: Unique salt per password
- **Work Factor**: Configurable computational cost
- **Timing Attack Protection**: Constant-time verification

#### Token Management

- **JWT Tokens**: Stateless authentication tokens
- **Configurable Expiry**: Token expiration management
- **Revocation Support**: Token invalidation capability
- **Secure Storage**: Protected token storage

### 2. Authorization System

#### Role-Based Access Control (RBAC)

```python
class UserRole(str, Enum):
    """User roles for role-based access control."""
    OPERATOR = "operator"
    ENGINEER = "engineer"
    ADMINISTRATOR = "administrator"
    READ_ONLY = "read_only"

class AuthorizationManager:
    """Manages role-based access control (RBAC) for authorization."""
    
    def has_permission(self, role: UserRole, permission: str) -> bool:
        """Check if a role has the specified permission."""
```

#### Permission Matrix

| Permission | Read Only | Operator | Engineer | Administrator |
|------------|-----------|----------|----------|---------------|
| read_pump_status | ✅ | ✅ | ✅ | ✅ |
| read_safety_status | ✅ | ✅ | ✅ | ✅ |
| read_audit_logs | ✅ | ✅ | ✅ | ✅ |
| emergency_stop | ❌ | ✅ | ✅ | ✅ |
| clear_emergency_stop | ❌ | ✅ | ✅ | ✅ |
| view_alerts | ❌ | ✅ | ✅ | ✅ |
| configure_safety_limits | ❌ | ❌ | ✅ | ✅ |
| manage_pump_configuration | ❌ | ❌ | ✅ | ✅ |
| view_system_metrics | ❌ | ❌ | ✅ | ✅ |
| manage_users | ❌ | ❌ | ❌ | ✅ |
| configure_system | ❌ | ❌ | ❌ | ✅ |
| access_all_stations | ❌ | ❌ | ❌ | ✅ |

### 3. Compliance Audit Logger (`src/core/compliance_audit.py`)

#### Audit Event Types

```python
class AuditEventType(Enum):
    """Audit event types for compliance requirements."""
    
    # Authentication and Authorization
    USER_LOGIN = "user_login"
    USER_LOGOUT = "user_logout"
    USER_CREATED = "user_created"
    USER_MODIFIED = "user_modified"
    USER_DELETED = "user_deleted"
    PASSWORD_CHANGED = "password_changed"
    ROLE_CHANGED = "role_changed"
    
    # System Access
    SYSTEM_START = "system_start"
    SYSTEM_STOP = "system_stop"
    SYSTEM_CONFIG_CHANGED = "system_config_changed"
    
    # Control Operations
    SETPOINT_CHANGED = "setpoint_changed"
    EMERGENCY_STOP_ACTIVATED = "emergency_stop_activated"
    EMERGENCY_STOP_RESET = "emergency_stop_reset"
    PUMP_CONTROL = "pump_control"
    VALVE_CONTROL = "valve_control"
    
    # Security Events
    ACCESS_DENIED = "access_denied"
    INVALID_AUTHENTICATION = "invalid_authentication"
    SESSION_TIMEOUT = "session_timeout"
    CERTIFICATE_EXPIRED = "certificate_expired"
    CERTIFICATE_ROTATED = "certificate_rotated"
    
    # Data Operations
    DATA_READ = "data_read"
    DATA_WRITE = "data_write"
    DATA_EXPORT = "data_export"
    DATA_DELETED = "data_deleted"
    
    # Network Operations
    CONNECTION_ESTABLISHED = "connection_established"
    CONNECTION_CLOSED = "connection_closed"
    CONNECTION_REJECTED = "connection_rejected"
    
    # Compliance Events
    AUDIT_LOG_ACCESSED = "audit_log_accessed"
    COMPLIANCE_CHECK = "compliance_check"
    SECURITY_SCAN = "security_scan"
```

#### Audit Severity Levels

```python
class AuditSeverity(Enum):
    """Audit event severity levels."""
    LOW = "low"       # Informational events
    MEDIUM = "medium" # Warning events
    HIGH = "high"     # Security events
    CRITICAL = "critical" # Critical security events
```

### 4. TLS/SSL Encryption (`src/core/tls_manager.py`)

#### Certificate Management

- **Certificate Generation**: Automated certificate creation
- **Certificate Rotation**: Scheduled certificate updates
- **Certificate Validation**: Strict certificate verification
- **Key Management**: Secure key storage and handling

#### Encryption Standards

- **TLS 1.2/1.3**: Modern encryption protocols
- **Strong Ciphers**: Industry-approved cipher suites
- **Perfect Forward Secrecy**: Ephemeral key exchange
- **Certificate Pinning**: Enhanced certificate validation

## Protocol Security

### OPC UA Security

#### Security Policies
- **Basic256Sha256**: Standard security policy
- **Aes256Sha256RsaPss**: Enhanced security policy
- **Certificate Authentication**: X.509 certificate support
- **User Token Authentication**: Username/password authentication

#### Security Features
- **Message Signing**: Digital signature verification
- **Message Encryption**: End-to-end encryption
- **Session Security**: Secure session management
- **Access Control**: Node-level access restrictions

### Modbus TCP Security

#### Security Enhancements
- **Connection Authentication**: Source IP validation
- **Command Validation**: Input sanitization
- **Rate Limiting**: Request throttling
- **Session Management**: Connection state tracking

#### Industrial Security
- **Read-Only Access**: Limited write capabilities
- **Command Validation**: Safe command execution
- **Error Handling**: Graceful error responses
- **Logging**: Comprehensive operation logging

### REST API Security

#### API Security Features
- **HTTPS Enforcement**: TLS/SSL encryption
- **API Key Authentication**: Secure API key management
- **Rate Limiting**: Request rate control
- **Input Validation**: Comprehensive input sanitization
- **CORS Configuration**: Cross-origin resource sharing

#### OpenAPI Security
- **Security Schemes**: Defined security mechanisms
- **Authentication**: JWT token authentication
- **Authorization**: Role-based access control
- **Documentation**: Comprehensive security documentation

## Compliance Implementation

### IEC 62443 Compliance

#### Security Level 2 (SL-2) Requirements

| Requirement | Implementation | Status |
|-------------|----------------|---------|
| **FR 1** - Identification and authentication control | JWT authentication, RBAC | ✅ |
| **FR 2** - Use control | Permission-based access control | ✅ |
| **FR 3** - System integrity | Safety framework, watchdog | ✅ |
| **FR 4** - Data confidentiality | TLS encryption, data protection | ✅ |
| **FR 5** - Restricted data flow | Network segmentation, firewalls | ✅ |
| **FR 6** - Timely response to events | Real-time monitoring, alerts | ✅ |
| **FR 7** - Resource availability | High availability design | ✅ |

#### Technical Security Requirements

- **SR 1.1**: Human user identification and authentication
- **SR 1.2**: Software process and device identification and authentication
- **SR 2.1**: Authorization enforcement
- **SR 2.2**: Wireless use control
- **SR 3.1**: Communication integrity
- **SR 3.2**: Malicious code protection
- **SR 4.1**: Information confidentiality
- **SR 5.1**: Network segmentation
- **SR 6.1**: Audit log availability
- **SR 7.1**: Denial of service protection

### ISO 27001 Compliance

#### Annex A Controls Implementation

| Control Domain | Key Controls | Implementation |
|----------------|--------------|----------------|
| **A.5** Information security policies | Policy framework | Security policy documentation |
| **A.6** Organization of information security | Roles and responsibilities | RBAC, user management |
| **A.7** Human resource security | Background checks, training | User onboarding procedures |
| **A.8** Asset management | Asset inventory, classification | System component tracking |
| **A.9** Access control | Authentication, authorization | JWT, RBAC implementation |
| **A.10** Cryptography | Encryption, key management | TLS, certificate management |
| **A.12** Operations security | Logging, monitoring | Audit logging, health monitoring |
| **A.13** Communications security | Network security | Protocol security, segmentation |
| **A.14** System acquisition, development and maintenance | Secure development | Security-by-design, testing |
| **A.16** Information security incident management | Incident response | Alert system, response procedures |
| **A.17** Information security aspects of business continuity management | Business continuity | High availability, backup |
| **A.18** Compliance | Legal and regulatory compliance | Compliance framework, reporting |

### NIS2 Directive Compliance

#### Essential Entity Requirements

| Requirement | Implementation | Evidence |
|-------------|----------------|----------|
| **Risk Management** | Systematic risk assessment | Risk assessment documentation |
| **Security Policies** | Comprehensive security policies | Policy documentation |
| **Incident Handling** | Incident response procedures | Incident response plan |
| **Business Continuity** | High availability design | Business continuity plan |
| **Supply Chain Security** | Secure development practices | Supplier security requirements |
| **Security Training** | Security awareness training | Training documentation |
| **Encryption** | End-to-end encryption | Encryption implementation |
| **Vulnerability Management** | Vulnerability assessment | Security testing results |

## Security Configuration

### Security Settings

```yaml
security:
  # Authentication settings
  authentication:
    jwt_secret_key: "your-secret-key-here"
    jwt_token_expire_minutes: 60
    bcrypt_rounds: 12
    
  # Authorization settings
  authorization:
    default_role: "read_only"
    session_timeout_minutes: 30
    
  # Audit logging
  audit:
    enabled: true
    retention_days: 365
    database_logging: true
    
  # TLS/SSL settings
  tls:
    enabled: true
    certificate_path: "/path/to/certificate.pem"
    private_key_path: "/path/to/private_key.pem"
    ca_certificate_path: "/path/to/ca_certificate.pem"
    
  # Protocol security
  protocols:
    opcua:
      security_policy: "Basic256Sha256"
      user_token_policy: "Username"
    modbus:
      connection_timeout_seconds: 30
      max_connections: 100
    rest_api:
      rate_limit_requests_per_minute: 100
      cors_origins: ["https://example.com"]
```

### User Management

#### Default User Accounts

```python
default_users = [
    {
        "user_id": "admin_001",
        "username": "admin",
        "email": "admin@calejo.com",
        "role": UserRole.ADMINISTRATOR,
        "password": "admin123"  # Change in production
    },
    {
        "user_id": "operator_001",
        "username": "operator",
        "email": "operator@calejo.com",
        "role": UserRole.OPERATOR,
        "password": "operator123"  # Change in production
    },
    # ... additional users
]
```

#### User Provisioning

- **Initial Setup**: Default user creation
- **User Management**: Administrative user management
- **Role Assignment**: Granular role assignment
- **Password Policies**: Configurable password requirements

## Security Monitoring & Incident Response

### Security Monitoring

#### Real-Time Monitoring
- **Authentication Events**: Login attempts, failures
- **Authorization Events**: Access control decisions
- **Security Events**: Security policy violations
- **System Events**: System configuration changes

#### Security Metrics
- **Authentication Rate**: Successful/failed login attempts
- **Access Violations**: Authorization failures
- **Security Incidents**: Security policy violations
- **System Health**: Security component status

### Incident Response

#### Incident Classification

| Severity | Description | Response Time |
|----------|-------------|---------------|
| **Critical** | System compromise, data breach | Immediate (< 1 hour) |
| **High** | Security policy violation, unauthorized access | Urgent (< 4 hours) |
| **Medium** | Suspicious activity, policy warnings | Standard (< 24 hours) |
| **Low** | Informational events, minor issues | Routine (< 7 days) |

#### Response Procedures

1. **Detection**: Security event detection
2. **Analysis**: Incident investigation
3. **Containment**: Impact limitation
4. **Eradication**: Root cause removal
5. **Recovery**: System restoration
6. **Lessons Learned**: Process improvement

## Security Testing & Validation

### Security Testing Framework

#### Authentication Testing
- **Password Strength**: Password policy enforcement
- **Token Validation**: JWT token security
- **Session Management**: Session timeout and security
- **Multi-factor Authentication**: Additional authentication layers

#### Authorization Testing
- **Role-Based Access**: Permission enforcement
- **Privilege Escalation**: Prevention mechanisms
- **Access Control**: Resource protection
- **Session Security**: Secure session handling

#### Protocol Security Testing
- **OPC UA Security**: Protocol-level security
- **Modbus Security**: Industrial protocol protection
- **REST API Security**: Web service security
- **Encryption Testing**: Cryptographic implementation

### Compliance Validation

#### Regular Audits
- **Security Controls**: Periodic security control validation
- **Compliance Checks**: Regulatory compliance verification
- **Vulnerability Assessment**: Security vulnerability scanning
- **Penetration Testing**: Security penetration testing

#### Documentation Requirements
- **Security Policies**: Comprehensive security policy documentation
- **Compliance Evidence**: Regulatory compliance evidence
- **Audit Reports**: Security audit reports
- **Incident Reports**: Security incident documentation

---

*This security and compliance framework provides comprehensive protection for the Calejo Control Adapter system. All security controls are designed to meet industrial and information security standards for critical infrastructure protection.*