<p align="center">
    <img src="../resources/provisioning_logo.svg" alt="Provisioning Logo" width="300"/>
</p>

<p align="center">
    <img src="../resources/logo-text.svg" alt="Provisioning" width="500"/>
</p>

# Security System

Enterprise-grade security infrastructure with 12 integrated components providing
authentication, authorization, encryption, and compliance.

## Overview

The Provisioning platform security system delivers comprehensive protection across all layers of
the infrastructure automation platform. Built for enterprise deployments, it provides defense-in-depth
through multiple security controls working together.

## Security Architecture

The security system is organized into 12 core components:

| Component | Purpose | Key Features |
| --------- | ------- | ------------ |
| **Authentication** | User identity verification | JWT tokens, session management, multi-provider auth |
| **Authorization** | Access control enforcement | Cedar policy engine, RBAC, fine-grained permissions |
| **MFA** | Multi-factor authentication | TOTP, WebAuthn/FIDO2, backup codes |
| **Audit Logging** | Comprehensive audit trails | 7-year retention, 5 export formats, compliance reporting |
| **KMS** | Key management | 5 KMS backends, envelope encryption, key rotation |
| **Secrets Management** | Secure secret storage | SecretumVault integration, SOPS/Age, dynamic secrets |
| **Encryption** | Data protection | At-rest and in-transit encryption, AES-256-GCM |
| **Secure Communication** | Network security | TLS/mTLS, certificate management, secure channels |
| **Certificate Management** | PKI operations | CA management, certificate issuance, rotation |
| **Compliance** | Regulatory adherence | SOC2, GDPR, HIPAA, policy enforcement |
| **Security Testing** | Validation framework | 350+ tests, vulnerability scanning, penetration testing |
| **Break-Glass** | Emergency access | Multi-party approval, audit trails, time-limited access |

## Security Layers

### Layer 1: Identity and Access

<p align="center">
    <img src="../resources/diagrams/security/authentication-flow.svg"
         alt="Authentication Flow JWT OAuth MFA Token Refresh Session" width="750"/>
</p>

- **Authentication**: Verify user identity with JWT tokens and Argon2id password hashing

<p align="center">
    <img src="../resources/diagrams/security/authorization-cedar.svg"
         alt="Authorization Cedar Policy Engine RBAC Permit Deny Evaluation" width="700"/>
</p>

- **Authorization**: Enforce access control with Cedar policies and RBAC
- **MFA**: Add second factor with TOTP or FIDO2 hardware keys

### Layer 2: Data Protection

<p align="center">
    <img src="../resources/diagrams/security/encryption-layers.svg"
         alt="Encryption Layers At-Rest In-Transit Post-Quantum Secrets Management" width="650"/>
</p>

- **Encryption**: Protect data at rest with AES-256-GCM and in transit with TLS 1.3
- **Secrets Management**: Store secrets securely in SecretumVault with automatic rotation
- **KMS**: Manage encryption keys with envelope encryption across 5 backend options

### Layer 3: Network Security

- **Secure Communication**: Enforce TLS/mTLS for all service-to-service communication
- **Certificate Management**: Automate certificate lifecycle with cert-manager integration
- **Network Policies**: Control traffic flow with Kubernetes NetworkPolicies

### Layer 4: Compliance and Monitoring

- **Audit Logging**: Record all security events with 7-year retention
- **Compliance**: Validate against SOC2, GDPR, and HIPAA frameworks
- **Security Testing**: Continuous validation with automated security test suite

## Performance Characteristics

- **Authentication Overhead**: Less than 20ms per request with JWT verification
- **Authorization Decision**: Less than 10ms with Cedar policy evaluation
- **Encryption Operations**: Less than 5ms with KMS-backed envelope encryption
- **Audit Logging**: Asynchronous with zero blocking on critical path
- **MFA Verification**: Less than 100ms for TOTP, less than 500ms for WebAuthn

## Security Standards

The security system adheres to industry standards and best practices:

- **OWASP Top 10**: Protection against common web vulnerabilities
- **NIST Cybersecurity Framework**: Aligned with identify, protect, detect, respond, recover
- **Zero Trust Architecture**: Never trust, always verify principle
- **Defense in Depth**: Multiple layers of security controls
- **Least Privilege**: Minimal access rights for users and services
- **Secure by Default**: Security controls enabled out of the box

## Component Integration

All security components work together as a cohesive system:

```text
┌─────────────────────────────────────────────────────────────┐
│                    User Request                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Authentication (JWT + Session)                             │
│  ↓                                                           │
│  Authorization (Cedar Policies)                             │
│  ↓                                                           │
│  MFA Verification (if required)                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Audit Logging (Record all actions)                         │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Secure Communication (TLS/mTLS)                            │
│  ↓                                                           │
│  Data Access (Encrypted with KMS)                           │
│  ↓                                                           │
│  Secrets Retrieved (SecretumVault)                          │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Compliance Validation (SOC2/GDPR checks)                   │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                    Response                                 │
└─────────────────────────────────────────────────────────────┘
```

## Security Configuration

Security settings are managed through hierarchical configuration:

```toml
# Security defaults in config/security.toml
[security]
auth_enabled = true
mfa_required = true
audit_enabled = true
encryption_at_rest = true
tls_min_version = "1.3"

[security.jwt]
algorithm = "RS256"
access_token_ttl = 900        # 15 minutes
refresh_token_ttl = 604800    # 7 days

[security.mfa]
totp_enabled = true
webauthn_enabled = true
backup_codes_count = 10

[security.kms]
backend = "secretumvault"
envelope_encryption = true
key_rotation_days = 90

[security.audit]
retention_days = 2555         # 7 years
export_formats = ["json", "csv", "parquet", "sqlite", "syslog"]

[security.compliance]
frameworks = ["soc2", "gdpr", "hipaa"]
policy_enforcement = "strict"
```

## Quick Start

Enable security system for your deployment:

```bash
# Enable all security features
provisioning config set security.enabled true

# Configure authentication
provisioning config set security.auth.jwt_algorithm RS256
provisioning config set security.auth.mfa_required true

# Set up SecretumVault integration
provisioning config set security.secrets.backend secretumvault
provisioning config set security.secrets.url  [http://localhost:8200](http://localhost:8200)

# Enable audit logging
provisioning config set security.audit.enabled true
provisioning config set security.audit.retention_days 2555

# Configure compliance framework
provisioning config set security.compliance.frameworks soc2,gdpr

# Verify security configuration
provisioning security validate
```

## Documentation Structure

This security documentation is organized into 12 detailed guides:

1. **[Authentication](authentication.md)** - JWT token-based authentication and session management
2. **[Authorization](authorization.md)** - Cedar policy engine and RBAC access control
3. **[Multi-Factor Authentication](mfa.md)** - TOTP and WebAuthn/FIDO2 implementation
4. **[Audit Logging](audit-logging.md)** - Comprehensive audit trails and compliance reporting
5. **[Key Management Service](kms-guide.md)** - Encryption key management and rotation
6. **[Secrets Management](secrets-management.md)** - SecretumVault and SOPS/Age integration
7. **[Encryption](encryption.md)** - At-rest and in-transit data protection
8. **[Secure Communication](secure-communication.md)** - TLS/mTLS and network security
9. **[Certificate Management](certificate-management.md)** - PKI and certificate lifecycle
10. **[Compliance](compliance.md)** - SOC2, GDPR, HIPAA frameworks
11. **[Security Testing](security-testing.md)** - Test suite and vulnerability scanning
12. **Break-Glass Procedures** - Emergency access and recovery

## Security Metrics

The security system tracks key metrics for monitoring and reporting:

- **Authentication Success Rate**: Percentage of successful login attempts
- **MFA Adoption Rate**: Percentage of users with MFA enabled
- **Policy Violations**: Count of authorization denials
- **Audit Event Rate**: Events logged per second
- **Secret Rotation Compliance**: Percentage of secrets rotated within policy
- **Certificate Expiration**: Days until certificate expiration
- **Compliance Score**: Overall compliance posture percentage
- **Security Test Pass Rate**: Percentage of security tests passing

## Best Practices

Follow these security best practices:

1. **Enable MFA for all users**: Require second factor for all accounts
2. **Rotate secrets regularly**: Automate secret rotation every 90 days
3. **Monitor audit logs**: Review security events daily
4. **Test security controls**: Run security test suite before deployments
5. **Keep certificates current**: Automate certificate renewal 30 days before expiration
6. **Review policies regularly**: Audit Cedar policies quarterly
7. **Limit break-glass access**: Require multi-party approval for emergency access
8. **Encrypt all data**: Enable encryption at rest and in transit
9. **Follow least privilege**: Grant minimal required permissions
10. **Validate compliance**: Run compliance checks before production deployments

## Getting Help

For security issues and questions:

- **Security Documentation**: Complete guides in this security section
- **CLI Help**: `provisioning security help`
- **Security Validation**: `provisioning security validate`
- **Audit Query**: `provisioning security audit query`
- **Compliance Check**: `provisioning security compliance check`

## Security Updates

The security system is continuously updated to address emerging threats and vulnerabilities. Subscribe to security advisories and apply updates promptly.

---

**Next Steps**:

- Read [Authentication Guide](authentication.md) to set up user authentication
- Configure [Authorization](authorization.md) with Cedar policies
- Enable [MFA](mfa.md) for all user accounts
- Set up [Audit Logging](audit-logging.md) for compliance
