ngxnode

# NGXNode - Real-time Nginx Log Monitor 🚀 **NGXNode** is a powerful Node.js-based real-time nginx log monitoring tool with enhanced error analysis and an interactive CLI dashboard. It's a modern alternative to the original Python ngxtop with additional features for security threat detection and detailed error categorization. ## ✨ Features - 🔍 **Real-time log monitoring** - Watch nginx access logs as they update - 📊 **Interactive CLI dashboard** - Beautiful terminal-based interface with live updates - 🛡️ **Enhanced security analysis** - Detect SQL injection, XSS, path traversal, and other attacks - 📈 **Detailed error analysis** - Comprehensive error categorization and counting - 🌍 **GeoIP integration** - Show geographic location of error-generating IPs - 🤖 **Bot detection** - Identify and categorize bot traffic - 📱 **User agent analysis** - Parse and categorize browsers, OS, and devices - 🔄 **Auto log detection** - Automatically find nginx log files on your system - 📋 **Multiple output formats** - Dashboard, JSON, or simple text output - ⚡ **High performance** - Efficient log parsing and real-time updates ## 🚀 Quick Start ### Global Installation from NPM ```bash # Install globally from npm npm install -g ngxnode # Start monitoring (auto-detects log files) ngxnode # Monitor specific log file ngxnode -l /var/log/nginx/access.log # Use different log format ngxnode -f common ``` ### Installation from Source ```bash # Clone the repository git clone https://github.com/boparaiamrit/ngxnode.git cd ngxnode # Install dependencies npm install # Create global link npm link # Verify installation ngxnode --version ``` ### Local Development ```bash # Clone and install dependencies git clone https://github.com/boparaiamrit/ngxnode.git cd ngxnode npm install # Run locally npm start # Or run directly node src/index.js ``` ## 📖 Usage ### Basic Commands ```bash # Start real-time monitoring (default command) ngxnode # Show system information and detected log files ngxnode info # Validate a log file ngxnode validate /path/to/access.log # Test log parser ngxnode test -f combined ``` ### Command Options ```bash ngxnode [command] [options] Commands: monitor (default) Monitor nginx access logs in real-time info Show information about nginx configuration validate <file> Validate and analyze a log file test Test the log parser with sample data Options: -l, --log <file> Access log file to parse -f, --format <format> Log format: combined, common, custom (default: combined) -i, --interval <seconds> Refresh interval in seconds (default: 2) --no-follow Process existing log content instead of following -v, --verbose Verbose output --detect Auto-detect nginx log files -h, --help Display help for command -V, --version Display version number ``` ### Dashboard Controls When the dashboard is running: - **q, Esc, Ctrl+C** - Quit application - **r** - Reset all statistics - **p** - Pause/Resume updates - **h** - Show help - **F5** - Force refresh ## 📊 Dashboard Sections ### 1. Statistics Panel - Uptime and total requests - Requests per second - Overall error rate - Status code breakdown (2xx, 3xx, 4xx, 5xx) ### 2. Top Errors Panel - Most frequent error codes - Error percentages - Error descriptions ### 3. Error Paths Panel - Paths generating the most errors - Status codes for each path - Error counts and percentages ### 4. Top Error IPs Panel - IP addresses generating most errors - Geographic location (country, city) - Error type breakdown per IP ### 5. Security Threats Panel - Detected attack patterns - Threat severity levels - Attack type categorization ## 🔍 Supported Log Formats ### Combined (Default) ``` $remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" ``` ### Common ``` $remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent ``` ### Custom ``` $remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$http_x_forwarded_for" ``` ### Proxy/CDN Formats NGXNode automatically handles logs with multiple IP addresses (e.g., from Cloudflare, load balancers): ``` "40.126.12.108,172.69.165.11" - - [12/Sep/2025:15:16:23 +0000] "POST /api/subscription/listen HTTP/1.1" 202 18 "-" "-" "-" cf="40.126.12.108" ``` The parser will extract: - **Client IP**: `40.126.12.108` (original client) - **Proxy IPs**: `172.69.165.11` (CDN/proxy servers) - **All IPs**: Complete list for analysis ## 🛡️ Security Features NGX automatically detects various security threats: ### Attack Pattern Detection - **SQL Injection** - Detects common SQL injection patterns - **XSS (Cross-Site Scripting)** - Identifies XSS attempt patterns - **Path Traversal** - Catches directory traversal attempts - **Command Injection** - Detects command injection patterns ### Behavioral Analysis - **Scanning Activity** - Identifies automated scanning tools - **Brute Force Detection** - Detects repeated authentication failures - **DDoS Pattern Recognition** - Identifies potential DDoS attacks - **Bot Classification** - Categorizes legitimate vs malicious bots ## 🌍 GeoIP Integration The tool includes GeoIP functionality to show the geographic origin of requests: - Country and city identification - ISP and organization details - Timezone information - Threat correlation by geography ## 📁 Auto-Detection NGX automatically searches for nginx log files in common locations: - `/var/log/nginx/access.log` - `/var/log/nginx/error.log` - `/usr/local/var/log/nginx/access.log` - `/opt/nginx/logs/access.log` - Docker container paths - macOS Homebrew paths - Windows paths ## 🔧 Configuration ### Environment Variables ```bash # Set default log file export NGX_LOG_FILE="/path/to/access.log" # Set default format export NGX_LOG_FORMAT="combined" # Set refresh interval export NGX_REFRESH_INTERVAL=2 ``` ### Custom Log Formats You can extend the parser to support custom nginx log formats by modifying the `LogParser` class in `src/parsers/logParser.js`. ## 🚀 Performance NGX is optimized for high-performance log processing: - **Efficient parsing** - Regex-based parsing with minimal overhead - **Memory management** - Automatic cleanup of old statistics - **Non-blocking I/O** - Asynchronous file operations - **Real-time updates** - Minimal latency between log entries and display ## 🐛 Troubleshooting ### Common Issues 1. **Permission denied** ```bash sudo chown $USER:$USER /var/log/nginx/access.log # or run with sudo sudo ngx -l /var/log/nginx/access.log ``` 2. **Log file not found** ```bash # Use info command to detect available logs ngx info # Or specify the correct path ngx -l /path/to/your/access.log ``` 3. **Parsing errors** ```bash # Validate your log file format ngx validate /path/to/access.log -f your-format # Test the parser ngx test -f your-format ``` ### Debug Mode Enable verbose logging: ```bash ngx -v -l /var/log/nginx/access.log ``` ## 🤝 Contributing Contributions are welcome! Please feel free to submit a Pull Request. ### Development Setup ```bash git clone https://github.com/boparaiamrit/ngxnode.git cd ngxnode npm install npm run dev # Start with nodemon for development ``` ### Running Tests ```bash npm test ``` ### Linting ```bash npm run lint ``` ## 📝 License This project is licensed under the MIT License - see the LICENSE file for details. ## 🙏 Acknowledgments - Inspired by the original [ngxtop](https://github.com/lebinh/ngxtop) Python tool - Built with [blessed](https://github.com/chjj/blessed) for the terminal interface - Uses [geoip-lite](https://github.com/bluesmoon/node-geoip) for geographic data ## 📊 Comparison with Original ngxtop | Feature | Original ngxtop | NGX (Node.js) | |---------|----------------|---------------| | Language | Python | Node.js | | Real-time Dashboard | ✓ | ✓ Enhanced | | Security Analysis | ✗ | ✓ | | GeoIP Integration | ✗ | ✓ | | Bot Detection | ✗ | ✓ | | Interactive Controls | Basic | Advanced | | Auto Log Detection | ✗ | ✓ | | Multiple Output Formats | ✗ | ✓ | | Performance | Good | Excellent | --- **NGXNode** - Making nginx log monitoring powerful, beautiful, and secure! 🚀