provisioning/docs/src/security/security-system.md

# Complete Security System (v4.0.0)

## 🔐 Enterprise-Grade Security Implementation

A comprehensive security system with 39,699 lines across 12 components providing enterprise-grade protection for infrastructure automation.

## Core Security Components

### 1. **Authentication** (JWT)

- **Type**: RS256 token-based authentication
- **Features**: Argon2id hashing, token rotation, session management
- **Roles**: 5 distinct role levels with inheritance
- **Commands**:

  ```bash
  provisioning login
  provisioning mfa totp verify
  ```

### 2. **Authorization** (Cedar)

- **Type**: Policy-as-code using Cedar authorization engine
- **Features**: Context-aware policies, hot reload, fine-grained control
- **Updates**: Dynamic policy reloading without service restart

### 3. **Multi-Factor Authentication** (MFA)

- **Methods**: TOTP (Time-based OTP) + WebAuthn/FIDO2
- **Features**: Backup codes, rate limiting, device binding
- **Commands**:

  ```bash
  provisioning mfa totp enroll
  provisioning mfa webauthn enroll
  ```

### 4. **Secrets Management**

- **Dynamic Secrets**: AWS STS, SSH keys, UpCloud credentials
- **KMS Integration**: Vault + AWS KMS + Age + Cosmian
- **Features**: Auto-cleanup, TTL management, rotation policies
- **Commands**:

  ```bash
  provisioning secrets generate aws --ttl 1hr
  provisioning ssh connect server01
  ```

### 5. **Key Management System** (KMS)

- **Backends**: RustyVault, Age, AWS KMS, HashiCorp Vault, Cosmian
- **Features**: Envelope encryption, key rotation, secure storage
- **Commands**:

  ```bash
  provisioning kms encrypt
  provisioning config encrypt secure.yaml
  ```

### 6. **Audit Logging**

- **Format**: Structured JSON logs with full context
- **Compliance**: GDPR-compliant with PII filtering
- **Retention**: 7-year data retention policy
- **Exports**: 5 export formats (JSON, CSV, SYSLOG, Splunk, CloudWatch)

### 7. **Break-Glass Emergency Access**

- **Approval**: Multi-party approval workflow
- **Features**: Temporary elevated privileges, auto-revocation, audit trail
- **Commands**:

  ```bash
  provisioning break-glass request "reason"
  provisioning break-glass approve <id>
  ```

### 8. **Compliance Management**

- **Standards**: GDPR, SOC2, ISO 27001, incident response procedures
- **Features**: Compliance reporting, audit trails, policy enforcement
- **Commands**:

  ```bash
  provisioning compliance report
  provisioning compliance gdpr export <user>
  ```

### 9. **Audit Query System**

- **Filtering**: By user, action, time range, resource
- **Features**: Structured query language, real-time search
- **Commands**:

  ```bash
  provisioning audit query --user alice --action deploy --from 24h
  ```

### 10. **Token Management**

- **Features**: Rotation policies, expiration tracking, revocation
- **Integration**: Seamless with auth system

### 11. **Access Control**

- **Model**: Role-based access control (RBAC)
- **Features**: Resource-level permissions, delegation, audit

### 12. **Encryption**

- **Standards**: AES-256, TLS 1.3, envelope encryption
- **Coverage**: At-rest and in-transit encryption

## Performance Characteristics

- **Overhead**: <20 ms per secure operation
- **Tests**: 350+ comprehensive test cases
- **Endpoints**: 83+ REST API endpoints
- **CLI Commands**: 111+ security-related commands

## Quick Reference

| Component | Command | Purpose |
| ----------- | --------- | --------- |
| Login | `provisioning login` | User authentication |
| MFA TOTP | `provisioning mfa totp enroll` | Setup time-based MFA |
| MFA WebAuthn | `provisioning mfa webauthn enroll` | Setup hardware security key |
| Secrets | `provisioning secrets generate aws --ttl 1hr` | Generate temporary credentials |
| SSH | `provisioning ssh connect server01` | Secure SSH session |
| KMS Encrypt | `provisioning kms encrypt <file>` | Encrypt configuration |
| Break-Glass | `provisioning break-glass request "reason"` | Request emergency access |
| Compliance | `provisioning compliance report` | Generate compliance report |
| GDPR Export | `provisioning compliance gdpr export <user>` | Export user data |
| Audit | `provisioning audit query --user alice --action deploy --from 24h` | Search audit logs |

## Architecture

Security system is integrated throughout provisioning platform:

- **Embedded**: All authentication/authorization checks
- **Non-blocking**: <20 ms overhead on operations
- **Graceful degradation**: Fallback mechanisms for partial failures
- **Hot reload**: Policies update without service restart

## Configuration

Security policies and settings are defined in:

- `provisioning/kcl/security.k` - KCL security schema definitions
- `provisioning/config/security/*.toml` - Security policy configurations
- Environment-specific overrides in `workspace/config/`

## Documentation

- Full implementation: [ADR-009: Security System Complete](../architecture/adr/adr-009-security-system-complete.md)
- User guides: [Authentication Layer Guide](authentication-layer-guide.md)
- Admin guides: [MFA Admin Setup Guide](../operations/mfa-admin-setup-guide.md)
- Implementation details: Supplementary documentation in subdirectories

## Help Commands

```bash
# Show security help
provisioning help security

# Show specific security command help
provisioning login --help
provisioning mfa --help
provisioning secrets --help
```