# Samba API Architecture Analysis ## Overview The Samba API serves as an interface between web applications and samba-tool functionalities for Active Directory management. This document analyzes different architectural approaches to handle the security and communication challenges between the API layer and the privileged Samba operations. ## Problem Statement Samba operations require elevated privileges to manage Active Directory objects (users, groups, computers, OUs). The challenge is to provide a secure, scalable, and maintainable interface while minimizing security risks and maintaining proper separation of concerns. ## Architectural Solutions ### 1. Pass-Through System (Direct Execution) #### Description The Samba API container runs with elevated privileges and directly executes samba-tool commands and LDAP operations. #### Implementation ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Web App │◄──►│ Samba API │◄──►│ Samba DC │ │ │ │ (Privileged) │ │ (LDAP/Kerberos)│ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ ▼ ┌──────────────────┐ │ samba-tool │ │ execution │ └──────────────────┘ ``` #### Advantages - **Simplicity**: Direct implementation with minimal complexity - **Performance**: No additional communication overhead - **Real-time Operations**: Immediate execution and response - **Complete Feature Set**: Access to all samba-tool capabilities - **Atomic Operations**: Operations complete in single request cycle #### Drawbacks - **Security Risk**: API container requires root/domain admin privileges - **Attack Surface**: Web-facing service with elevated privileges - **Blast Radius**: Compromise of API means full domain compromise - **Audit Complexity**: Difficult to track individual operations - **Resource Intensive**: Each API instance needs full Samba stack - **Scaling Issues**: Privileged containers are harder to scale securely #### Security Considerations - Container must run with `privileged: true` or specific capabilities - Network access to domain controller required - Domain admin credentials stored in container - No privilege separation between web interface and domain operations --- ### 2. File-Based Communication with inotify #### Description Separation of concerns using file system communication. The API writes operation requests to files, and a privileged worker container monitors file changes using inotify to execute operations. #### Implementation ``` ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ Web App │◄──►│ Samba API │ │ Samba Worker │ │ │ │ (Unprivileged) │ │ (Privileged) │ └─────────────────┘ └──────────────────┘ └──────────────────┘ │ │ ▼ ▼ ┌─────────────────────────────────────┐ │ Shared Volume │ │ /requests/ │ /responses/ │ │ *.json │ *.json │ └─────────────────────────────────────┘ ▲ │ ┌─────────────┐ │ inotify │ │ watcher │ └─────────────┘ ``` #### Advantages - **Security Isolation**: API container runs unprivileged - **Clear Separation**: Web interface isolated from domain operations - **Audit Trail**: All operations logged as files - **Scalability**: Multiple API instances can share worker - **Resilience**: Operations survive container restarts - **Debugging**: Easy to inspect pending/completed operations #### Drawbacks - **Complexity**: Additional components and file management - **Latency**: File I/O overhead and polling delays - **Race Conditions**: File locking and concurrent access issues - **Storage Requirements**: Persistent storage for operation queues - **Error Handling**: Complex error propagation through files - **Limited Real-time**: Delays in operation execution - **File System Dependencies**: Shared volume requirements #### Implementation Details ```python # API writes request request = { "id": "uuid-123", "operation": "user_create", "params": {"username": "john", "password": "***"}, "timestamp": "2025-10-22T10:30:00Z" } # Write to /requests/uuid-123.json # Worker processes with inotify import inotify.adapters i = inotify.adapters.Inotify() i.add_watch('/requests') for event in i.event_gen(): if event and 'IN_CLOSE_WRITE' in event[1]: process_request(event[3]) # filename ``` --- ### 3. MQTT-Based Communication #### Description Message queue architecture using MQTT broker for communication between API and privileged worker containers. #### Implementation ``` ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ Web App │◄──►│ Samba API │ │ Samba Worker │ │ │ │ (Unprivileged) │ │ (Privileged) │ └─────────────────┘ └──────────┬───────┘ └─────────┬────────┘ │ │ ▼ ▼ ┌─────────────────────────────────────┐ │ MQTT Broker │ │ │ │ Topics: │ │ • samba/requests │ │ • samba/responses │ │ • samba/status │ └─────────────────────────────────────┘ ``` #### Advantages - **Security Isolation**: API container completely unprivileged - **Scalability**: Multiple workers, load balancing - **Reliability**: Message persistence and delivery guarantees - **Real-time**: Near real-time operation execution - **Monitoring**: Built-in message tracking and metrics - **Flexibility**: Easy to add new operation types - **Resilience**: Message queuing survives container failures - **Load Distribution**: Work distributed across multiple workers #### Drawbacks - **Infrastructure Complexity**: Additional MQTT broker service - **Network Dependencies**: Broker availability critical - **Message Overhead**: JSON serialization/deserialization - **Debugging Complexity**: Distributed system debugging - **Additional Security**: MQTT broker security configuration - **Resource Usage**: Additional memory and CPU for broker - **Message Size Limits**: Large payloads may need special handling #### Implementation Details ```python # API publishes request import paho.mqtt.client as mqtt request = { "id": "uuid-123", "operation": "user_create", "params": {"username": "john", "password": "***"}, "reply_to": "samba/responses/uuid-123" } client.publish("samba/requests", json.dumps(request)) # Worker subscribes and processes def on_message(client, userdata, message): request = json.loads(message.payload) result = execute_samba_operation(request) client.publish(request["reply_to"], json.dumps(result)) ``` --- ### 4. gRPC-Based Microservice (Alternative Solution) #### Description Dedicated privileged microservice exposing gRPC interface for Samba operations. #### Implementation ``` ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ Web App │◄──►│ Samba API │◄──►│ Samba Service │ │ │ │ (Unprivileged) │ │ (Privileged) │ └─────────────────┘ └──────────────────┘ └──────────────────┘ │ │ │ gRPC/HTTP │ └────────────────────────┘ ``` #### Advantages - **Type Safety**: Strongly typed interfaces with Protocol Buffers - **Performance**: Binary protocol, efficient serialization - **Security**: mTLS authentication and encryption - **Standardized**: Well-established patterns and tooling - **Streaming**: Support for real-time operation streams - **Multi-language**: Easy client generation for different languages - **Service Discovery**: Built-in load balancing and discovery #### Drawbacks - **Complexity**: gRPC setup and maintenance - **Debugging**: Binary protocol harder to debug - **Firewall Issues**: HTTP/2 may have network restrictions - **Learning Curve**: Team familiarity with gRPC required --- ### 5. Unix Domain Sockets (Alternative Solution) #### Description Communication through Unix domain sockets with a privileged daemon. #### Advantages - **Performance**: Fastest IPC mechanism - **Security**: File system permissions control access - **Simplicity**: No network configuration required #### Drawbacks - **Single Host**: Cannot scale across multiple machines - **Socket Management**: File cleanup and permissions complexity - **Container Limitations**: Requires shared volume mounts --- ## Recommendation Matrix | Criteria | Pass-Through | File-based | MQTT | gRPC | Unix Sockets | |----------|--------------|------------|------|------|--------------| | Security | ❌ Poor | ✅ Good | ✅ Good | ✅ Good | ⚠️ Medium | | Performance | ✅ Excellent | ⚠️ Medium | ✅ Good | ✅ Excellent | ✅ Excellent | | Scalability | ❌ Poor | ⚠️ Medium | ✅ Excellent | ✅ Good | ❌ Poor | | Complexity | ✅ Simple | ⚠️ Medium | ❌ Complex | ❌ Complex | ✅ Simple | | Reliability | ⚠️ Medium | ✅ Good | ✅ Excellent | ✅ Good | ⚠️ Medium | | Audit Trail | ❌ Poor | ✅ Excellent | ✅ Good | ⚠️ Medium | ❌ Poor | | Real-time | ✅ Excellent | ❌ Poor | ✅ Good | ✅ Excellent | ✅ Excellent | | Maintenance | ✅ Simple | ⚠️ Medium | ❌ Complex | ❌ Complex | ✅ Simple | ## Final Recommendation ### **Recommended Solution: MQTT-Based Architecture** For production environments, the **MQTT-based approach** is recommended because: 1. **Security First**: Complete isolation of privileged operations 2. **Enterprise Scale**: Supports multiple workers and high availability 3. **Operational Excellence**: Built-in monitoring, logging, and error handling 4. **Future-Proof**: Easy to extend with new features and integrations ### **Development/Testing Alternative: File-Based** For development or smaller deployments, the **file-based approach** offers: - Good security with simpler implementation - Excellent debugging capabilities - Lower resource requirements - Easier troubleshooting ### **Implementation Phases** 1. **Phase 1**: Start with file-based for MVP and testing 2. **Phase 2**: Migrate to MQTT for production deployment 3. **Phase 3**: Add advanced features like operation batching and workflow management ## Security Best Practices Regardless of chosen architecture: 1. **Principle of Least Privilege**: Minimize permissions at every level 2. **Input Validation**: Sanitize all inputs before processing 3. **Audit Logging**: Log all operations with user attribution 4. **Encryption**: Encrypt communication channels and stored credentials 5. **Network Segmentation**: Isolate Samba operations network 6. **Regular Updates**: Keep all components updated with security patches 7. **Monitoring**: Implement comprehensive monitoring and alerting ## Conclusion The choice of architecture depends on specific requirements: - **Security-critical environments**: MQTT or gRPC - **Simple deployments**: File-based or Unix sockets - **Performance-critical**: Pass-through (with additional security measures) The recommended MQTT approach provides the best balance of security, scalability, and maintainability for enterprise deployments.