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:

  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:

  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:

  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:

  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:

  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:

  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:

  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
• User guides: Authentication Layer Guide
• Admin guides: MFA Admin Setup Guide
• Implementation details: Supplementary documentation in subdirectories

Help Commands

# Show security help
provisioning help security

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