Architecture Overview
Architecture Overview
Section titled “Architecture Overview”Understand how SSH-KLM components work together to provide comprehensive SSH key lifecycle management.
System Architecture
Section titled “System Architecture”SSH-KLM uses a three-tier architecture designed for scalability, reliability, and security.
┌─────────────────────────────────────────────────────────────────────────┐│ CLIENTS ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ Web │ │ CLI │ │ SDK │ │ API │ ││ │ UI │ │ Client │ │ Client │ │ Direct │ ││ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │└───────┼─────────────┼─────────────┼─────────────┼───────────────────────┘ │ │ │ │ └─────────────┴──────┬──────┴─────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────────────┐│ API GATEWAY ││ ┌─────────────────────────────────────────────────────────────────┐ ││ │ Authentication │ Rate Limiting │ Request Routing │ TLS Term │ ││ └─────────────────────────────────────────────────────────────────┘ │└─────────────────────────────────────────────────────────────────────────┘ │ ┌────────────────────┼────────────────────┐ │ │ │ ▼ ▼ ▼┌───────────────┐ ┌───────────────┐ ┌───────────────┐│ API Server │ │ API Server │ │ API Server ││ (Replica) │ │ (Replica) │ │ (Replica) │└───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │ │ └───────────────────┼───────────────────┘ │ ┌─────────────┼─────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │PostgreSQL│ │ Redis │ │ Queue │ │(Primary) │ │ (Cache) │ │ (Jobs) │ └──────────┘ └──────────┘ └──────────┘ │ ┌─────────────┼─────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Worker │ │ Worker │ │ Worker │ │(Discovery│ │(Rotation)│ │(Rotation)│ └──────────┘ └──────────┘ └──────────┘ │┌─────────────────────────────────────────────────────────────────────────┐│ TARGET INFRASTRUCTURE ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ Agent │ │ Agent │ │ Agent │ │ Agentless│ ││ │ Server 1 │ │ Server 2 │ │ Server N │ │ (SSH) │ ││ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │└─────────────────────────────────────────────────────────────────────────┘Core Components
Section titled “Core Components”API Server
Section titled “API Server”The API Server handles all client requests and business logic.
| Responsibility | Description |
|---|---|
| Authentication | JWT-based auth with RBAC |
| REST API | RESTful endpoints for all operations |
| WebSocket | Real-time updates for UI |
| Validation | Request validation and sanitization |
Worker Nodes
Section titled “Worker Nodes”Background workers process async tasks.
| Worker Type | Purpose |
|---|---|
| Discovery Worker | Scans hosts for SSH keys |
| Rotation Worker | Executes key rotation jobs |
| Notification Worker | Sends alerts and notifications |
| Cleanup Worker | Archives old keys, purges logs |
Database (PostgreSQL)
Section titled “Database (PostgreSQL)”Primary data store for all persistent data:
- Host inventory
- SSH key metadata
- Rotation policies
- Audit logs
- User accounts
Cache (Redis)
Section titled “Cache (Redis)”High-performance caching and job queue:
- Session management
- API response caching
- Job queue (discovery, rotation tasks)
- Rate limiting counters
- Real-time metrics
SSH-KLM Agent
Section titled “SSH-KLM Agent”Lightweight agent installed on target hosts:
┌─────────────────────────────────────┐│ SSH-KLM Agent │├─────────────────────────────────────┤│ ┌─────────────┐ ┌───────────────┐ ││ │ Discovery │ │ Rotation │ ││ │ Module │ │ Module │ ││ └─────────────┘ └───────────────┘ ││ ┌─────────────┐ ┌───────────────┐ ││ │ Heartbeat │ │ Secure │ ││ │ Service │ │ Comms │ ││ └─────────────┘ └───────────────┘ │└─────────────────────────────────────┘Data Flow
Section titled “Data Flow”Discovery Flow
Section titled “Discovery Flow”sequenceDiagram participant UI as Dashboard participant API as API Server participant Queue as Job Queue participant Worker as Discovery Worker participant Agent as SSH Agent participant DB as Database
UI->>API: Start Discovery Scan API->>Queue: Enqueue Discovery Job API-->>UI: Job ID Queue->>Worker: Dequeue Job Worker->>Agent: Request Key Inventory Agent->>Agent: Scan ~/.ssh, /etc/ssh Agent-->>Worker: Key List + Metadata Worker->>DB: Store Discovered Keys Worker->>Queue: Job Complete UI->>API: Poll Status API->>DB: Get Results API-->>UI: Discovery ResultsRotation Flow
Section titled “Rotation Flow”sequenceDiagram participant API as API Server participant Queue as Job Queue participant Worker as Rotation Worker participant Agent as SSH Agent participant Target as Target Host
API->>Queue: Enqueue Rotation Job Queue->>Worker: Dequeue Job Worker->>Worker: Generate New Key Pair Worker->>Agent: Deploy Public Key Agent->>Target: Update authorized_keys Agent-->>Worker: Deployment Confirmed Worker->>Worker: Verify New Key Access Worker->>Agent: Remove Old Key Agent->>Target: Update authorized_keys Worker->>API: Rotation CompleteSecurity Architecture
Section titled “Security Architecture”Network Security
Section titled “Network Security”- All API traffic over TLS 1.3
- Agent communication over mTLS
- Database connections encrypted
- Network segmentation recommended
Authentication & Authorization
Section titled “Authentication & Authorization”| Layer | Mechanism |
|---|---|
| API | JWT tokens with short expiry |
| Agent | mTLS certificates |
| Database | Credential rotation |
| Secrets | HashiCorp Vault integration |
Data Protection
Section titled “Data Protection”- SSH private keys encrypted at rest (AES-256)
- Audit logs immutable and signed
- PII data encrypted
- Key material never leaves secure boundary
Scalability
Section titled “Scalability”Horizontal Scaling
Section titled “Horizontal Scaling”| Component | Scaling Method |
|---|---|
| API Server | Add replicas behind load balancer |
| Workers | Add worker pods/instances |
| Database | Read replicas, connection pooling |
| Cache | Redis Cluster |
Performance Characteristics
Section titled “Performance Characteristics”| Metric | Capacity |
|---|---|
| Hosts | 10,000+ per cluster |
| Keys | 1M+ managed keys |
| Discovery | 1,000 hosts/minute |
| Rotations | 500 keys/minute |