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

# 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

# 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

# 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

# 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

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

# 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

   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

   # Use info command to detect available logs
   ngx info
      
   # Or specify the correct path
   ngx -l /path/to/your/access.log

3. Parsing errors

   # 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:

ngx -v -l /var/log/nginx/access.log

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

git clone https://github.com/boparaiamrit/ngxnode.git
cd ngxnode
npm install
npm run dev  # Start with nodemon for development

Running Tests

npm test

Linting

npm run lint

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the original ngxtop Python tool
• Built with blessed for the terminal interface
• Uses geoip-lite 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! 🚀