# Secure Command Execution (Modular Security Architecture) The J4F Assistant implements a comprehensive, modular security architecture for command execution, providing multiple layers of protection through specialized security modules working in concert. --- ## Modular Security Architecture ### Security Module Overview The security system is built with specialized modules in `src/core/secure/`: - **CommandExecutor.js**: Secure command execution with isolation - **CommandRiskAnalyzer.js**: Advanced risk assessment and classification - **AuditLogger.js**: Comprehensive security event logging - **ConfirmationManager.js**: User confirmation workflow management - **WorkspaceManager.js**: Workspace isolation and access control ### Security Orchestrator - **secure-executor.js**: Main security orchestrator that coordinates all security modules - **Centralized Security**: Single entry point for all security-related operations - **Policy Enforcement**: Consistent security policy application across all tools ## Advanced Command Risk Analysis ### Multi-Level Risk Classification Commands are analyzed through multiple security dimensions: 1. **Command Pattern Analysis**: Pattern matching against known dangerous commands 2. **Argument Risk Assessment**: Analysis of command arguments and flags 3. **Context Awareness**: Risk evaluation based on current workspace and environment 4. **Historical Analysis**: Learning from previous command execution patterns ### Risk Categories & Examples - **SAFE (Green)**: Read-only operations with minimal impact - `ls`, `pwd`, `git status`, `cat file.txt`, `echo`, `date` - **LOW (Blue)**: Minor modifications with limited scope - `mkdir`, `touch`, `git add`, `npm list`, `find` - **MODERATE (Yellow)**: Significant operations requiring awareness - `git commit`, `npm install`, `cp`, `mv`, `chmod` - **HIGH (Orange)**: Potentially dangerous operations requiring confirmation - `rm -rf`, `git reset --hard`, `npm uninstall`, `kill` - **CRITICAL (Red)**: System-threatening operations requiring explicit approval - `rm -rf /`, `format`, `dd`, `sudo rm`, `reboot` ### Dynamic Risk Assessment ``` Command Input → Context Analysis → Pattern Matching → Argument Analysis → Historical Lookup → Risk Score → Classification ``` --- ## Comprehensive Audit Logging ### Enhanced Audit System The `AuditLogger` module provides enterprise-grade logging: - **Structured Logging**: JSON-formatted logs with consistent schema - **Multiple Log Levels**: DEBUG, INFO, WARN, ERROR, CRITICAL - **Event Correlation**: Commands linked to conversation and session context - **Performance Metrics**: Execution time, resource usage tracking - **Security Events**: Failed attempts, privilege escalations, anomalies ### Audit Entry Schema ```json { "id": "cmd_1729342342342", "timestamp": "2025-06-19T10:30:00.123Z", "eventType": "command_execution", "command": { "raw": "git reset --hard HEAD~1", "parsed": ["git", "reset", "--hard", "HEAD~1"], "tool": "SystemTools" }, "context": { "conversationId": "conv_abc123", "sessionId": "sess_xyz789", "workspace": "/home/user/project", "user": "admin", "interface": "web" }, "security": { "riskLevel": "HIGH", "riskScore": 8.5, "riskFactors": ["destructive_operation", "git_history_modification"], "confirmationRequired": true, "confirmationProvided": true }, "execution": { "status": "completed", "result": "success", "executionTime": 1250, "exitCode": 0, "outputSize": 156 }, "metadata": { "clientIP": "192.168.1.100", "userAgent": "Mozilla/5.0...", "apiVersion": "v1" } } ``` ### Audit Log Management - **Rotation**: Automatic log rotation based on size and age - **Compression**: Historical logs compressed for storage efficiency - **Retention Policies**: Configurable retention periods for compliance - **Export Capabilities**: JSON, CSV export for external analysis - **Query Interface**: Advanced filtering and search capabilities --- ## Sophisticated Confirmation Management ### Confirmation Workflow Engine The `ConfirmationManager` handles complex approval workflows: 1. **Risk-Based Triggering**: Automatic confirmation requirements based on risk level 2. **Context-Aware Prompts**: Detailed explanations of command impact 3. **Timeout Handling**: Automatic rejection of stale confirmation requests 4. **Batch Operations**: Confirmation of multiple related commands 5. **Override Mechanisms**: Admin overrides for trusted operations ### Confirmation Flow Architecture ``` Command → Risk Analysis → ├─ SAFE/LOW → Execute Immediately ├─ MODERATE → Brief Confirmation → Execute ├─ HIGH → Detailed Confirmation → Execute └─ CRITICAL → Multi-Step Confirmation → Execute ``` ### Enhanced Confirmation Interface - **Risk Visualization**: Color-coded risk indicators and impact descriptions - **Command Preview**: Show exactly what will be executed - **Impact Analysis**: Explain potential consequences and affected files - **Alternative Suggestions**: Suggest safer alternatives when available - **Confirmation Persistence**: Remember trusted commands for user convenience ### Confirmation Request Schema ```json { "confirmationId": "conf_xyz123", "command": "rm -rf temp/", "riskLevel": "HIGH", "riskFactors": ["recursive_deletion", "directory_operation"], "impactAnalysis": { "affectedFiles": ["temp/file1.txt", "temp/subdir/"], "estimatedCount": 42, "irreversible": true }, "alternatives": [ "mv temp/ temp_backup/", "rm -i temp/*" ], "timeout": 300, "requiresExplicitApproval": true } ``` --- ## Advanced Workspace Security ### Workspace Isolation The `WorkspaceManager` provides comprehensive workspace security: - **Path Validation**: Strict validation of all file system operations - **Sandbox Enforcement**: Commands restricted to configured workspace boundaries - **Access Control**: Fine-grained permissions for different workspace areas - **Git Integration**: Branch-aware security policies - **Resource Limits**: CPU, memory, and disk usage controls ### Workspace Security Policies ```json { "workspaceId": "proj_abc123", "securityPolicy": { "allowedCommands": ["git", "npm", "node", "python"], "blockedCommands": ["rm", "dd", "format"], "pathRestrictions": { "readOnly": [".git/", "node_modules/"], "noAccess": ["/etc/", "/usr/", "/sys/"] }, "resourceLimits": { "maxExecutionTime": 300, "maxMemoryMB": 512, "maxFileSize": "100MB" } } } ``` --- ## Configuration & Security Hardening ### Environment Configuration Comprehensive security configuration via environment variables: ```bash # Command Execution Security ENABLE_SYSTEM_COMMANDS=false COMMAND_CONFIRMATION_REQUIRED=true COMMAND_TIMEOUT_SECONDS=300 MAX_CONCURRENT_COMMANDS=3 # Risk Analysis Configuration DEFAULT_RISK_THRESHOLD=5.0 RISK_ANALYZER_STRICT_MODE=true CUSTOM_RISK_PATTERNS_FILE=/path/to/patterns.json # Audit Configuration AUDIT_LOG_LEVEL=INFO AUDIT_LOG_RETENTION_DAYS=90 AUDIT_LOG_MAX_SIZE=100MB AUDIT_LOG_COMPRESSION=true # Workspace Security WORKSPACE_ISOLATION_ENABLED=true WORKSPACE_PATH_VALIDATION=strict WORKSPACE_RESOURCE_LIMITS=true # API Security API_RATE_LIMIT=100 ALLOWED_ORIGINS=http://localhost:3000 CSRF_PROTECTION=true ``` ### Production Security Hardening 1. **Container Isolation** - Docker containerization with restricted capabilities - Non-root user execution - Read-only file system where possible - Network isolation and restricted outbound access 2. **Access Control** - Role-based permissions for different user types - API key authentication for programmatic access - Session management with secure tokens - CSRF protection for web interfaces 3. **Monitoring & Alerting** - Real-time security event monitoring - Anomaly detection for unusual command patterns - Automated alerting for critical security events - Integration with SIEM systems 4. **Compliance & Governance** - Audit trail preservation for compliance requirements - Data retention policies aligned with regulations - Regular security assessments and penetration testing - Documentation of security procedures and policies --- ## Security Event Examples ### Safe Operation Example ``` User: "List files in current directory" Command: ls -la Risk Level: SAFE Action: Execute immediately Audit: Logged as routine file listing operation ``` ### Moderate Risk Example ``` User: "Install npm package" Command: npm install lodash Risk Level: MODERATE Action: Brief confirmation required Confirmation: "Install npm package 'lodash'? This will modify package.json and node_modules." Audit: Logged with package installation details ``` ### High Risk Example ``` User: "Remove temporary files" Command: rm -rf temp/ Risk Level: HIGH Action: Detailed confirmation required Analysis: "This will permanently delete 42 files in temp/ directory. Operation is irreversible." Alternatives: "Consider 'mv temp/ temp_backup/' or 'rm -i temp/*'" Audit: Comprehensive logging with risk factors and user decision ``` ### Critical Risk Example ``` User: "Reset Git repository" Command: git reset --hard HEAD~10 Risk Level: CRITICAL Action: Multi-step confirmation required Impact Analysis: "This will permanently lose 10 commits (affecting 23 files). Local changes will be discarded." Required Confirmation: User must type "CONFIRM RESET" to proceed Audit: Detailed logging with commit hashes and affected files ``` --- ## Security Monitoring & Analytics ### Real-time Monitoring - **Command Execution Metrics**: Success rates, execution times, error patterns - **Risk Assessment Trends**: Risk level distributions, confirmation rates - **User Behavior Analysis**: Command patterns, workspace usage, security events - **System Health Monitoring**: Resource usage, performance metrics, error rates ### Security Dashboards - **Executive Summary**: High-level security posture and trends - **Operational View**: Real-time command execution and security events - **Audit Review**: Historical analysis and compliance reporting - **Risk Analysis**: Risk assessment accuracy and pattern analysis ### Automated Response - **Threat Detection**: Automatic detection of suspicious command patterns - **Rate Limiting**: Dynamic rate limiting based on risk assessment - **Emergency Response**: Automatic lockdown for critical security events - **Incident Management**: Automated incident creation and escalation ## Integration with LangChain Streaming ### Streaming Security Security integration with LangChain streaming ensures: - **Real-time Risk Assessment**: Commands analyzed as they're generated - **Interactive Confirmation**: User confirmation seamlessly integrated into streaming flow - **Audit Continuity**: Complete audit trail maintained across streaming sessions - **Context Preservation**: Security context maintained throughout conversation For detailed implementation information, see [Backend Overview](../backend/Overview.md) and [LangChain Streaming](../backend/LangChain-Streaming.md). For API security endpoints, see [API Reference](../api/Reference.md). --- # Security & Command Execution ## Security & Audit Layer (2025) The Security & Audit Layer provides centralized security documentation and guidelines for the J4F Assistant, ensuring a consistent and robust approach to security and audit across all components. ### Security Principles - **Least Privilege**: Ensure minimal permissions necessary for each component and user. - **Defense in Depth**: Multiple layers of security controls to protect resources. - **Fail Securely**: In case of a failure, the system should default to a secure state. - **Auditability**: All actions should be traceable and logged for review. ### Security Controls - **Authentication**: Verify the identity of users and systems. - **Authorization**: Grant access based on verified identity and defined policies. - **Encryption**: Protect data at rest and in transit using strong encryption standards. - **Integrity**: Ensure data is not tampered with through checksums and hashes. - **Non-repudiation**: Guarantee that a sender cannot deny sending a message that was received. ### Compliance Adhere to relevant legal, regulatory, and contractual obligations, including but not limited to: - **GDPR**: General Data Protection Regulation - **HIPAA**: Health Insurance Portability and Accountability Act - **PCI-DSS**: Payment Card Industry Data Security Standard - **SOX**: Sarbanes-Oxley Act ### Security Assessment & Testing Regularly test and assess the security of the system through: - **Vulnerability Scanning**: Automated scanning for known vulnerabilities. - **Penetration Testing**: Simulated attacks to identify and exploit vulnerabilities. - **Security Audits**: Comprehensive reviews of security policies, controls, and procedures. ### Incident Response Establish and maintain an incident response plan to: - **Prepare**: Equip the team with the necessary tools and knowledge. - **Detect**: Identify potential security incidents quickly. - **Respond**: Contain and mitigate the impact of security incidents. - **Recover**: Restore systems and processes to normal operation. - **Review**: Analyze the incident to prevent future occurrences. ### Security Training & Awareness Provide regular security training and awareness programs for all users to: - Recognize security threats and vulnerabilities. - Understand security policies and procedures. - Respond appropriately to security incidents. ### Documentation Maintain comprehensive documentation for all security policies, procedures, and controls, ensuring: - Accessibility to authorized personnel. - Regular updates to reflect changes in the environment or regulations. - Retention of historical documentation for reference and compliance. ### Roles & Responsibilities Define and assign security roles and responsibilities to ensure accountability and effective implementation of security controls, including: - **Security Officer**: Overall responsible for security policy and implementation. - **System Administrator**: Manages and maintains security controls on systems. - **User**: Follows security policies and reports potential security incidents. ### Review & Revision Regularly review and revise security policies, procedures, and controls to ensure their effectiveness and relevance, considering: - Changes in the threat landscape. - Changes in business operations or technology. - Results of security assessments and audits. For detailed information on specific security policies and procedures, refer to the respective documentation sections.