initial commit

README.md

@@ -0,0 +1,99 @@
+> **AI-Generated Content Warning:** This project was developed with the assistance of generative AI (Claude by Anthropic). Code, documentation, and design decisions may reflect AI-generated output and should be reviewed accordingly before use in production environments.
+
+---
+
+# // NXSTATS //
+
+A fast nginx log parser that generates cyberpunk-themed HTML reports with charts, searchable tables, and optional GeoIP2 hit maps.
+
+![Dashboard overview](screenshot1.png)
+
+![Access log table](screenshot2.png)
+
+## Features
+
+- Parses nginx **access** and **error** logs, including gzip-compressed rotated logs
+- Generates a self-contained **single-file HTML report** — no server required
+- **Status code distribution** bar chart
+- **Top paths** and **requests-per-hour** charts (Chart.js)
+- Searchable, filterable **access log table** with status badges
+- Optional **GeoIP2 world map** (Leaflet.js) when a MaxMind `.mmdb` is supplied
+- **Split-by-day** mode writes one report per calendar day plus a summary index page
+- Zero runtime dependencies — the binary is statically compiled Go
+
+## Installation
+
+### Build from source
+
+Requires Go 1.21+.
+
+```bash
+git clone https://github.com/mr0xb/nxstats.git
+cd nxstats
+go build -o nxstats .
+```
+
+### Pre-built binary
+
+Download the latest release binary from the [releases page](../../releases) and place it somewhere on your `$PATH`.
+
+## Usage
+
+```
+nxstats [flags]
+```
+
+| Flag | Short | Default | Description |
+|---|---|---|---|
+| `--dir` | `-d` | `/var/log/nginx` | Directory to scan for nginx logs |
+| `--output` | `-o` | `report.html` | Output HTML file path |
+| `--access-log` | `-a` | | Specific access log file (skips dir scan) |
+| `--error-log` | `-e` | | Specific error log file (skips dir scan) |
+| `--geoip` | | | Path to MaxMind `GeoLite2-City.mmdb` (enables map) |
+| `--no-gzip` | | `false` | Skip `.gz` compressed rotated logs |
+| `--split-by-day` | | `false` | Write one HTML report per calendar day plus index |
+
+### Examples
+
+**Quick report from the default nginx log directory:**
+```bash
+nxstats -o report.html
+```
+
+**Specific log files:**
+```bash
+nxstats -a /var/log/nginx/access.log -e /var/log/nginx/error.log -o report.html
+```
+
+**With GeoIP2 map enabled:**
+```bash
+nxstats --dir /var/log/nginx --geoip ./GeoLite2-City.mmdb -o report.html
+```
+
+**Split into per-day reports:**
+```bash
+nxstats --dir /var/log/nginx --split-by-day -o index.html
+# Writes index.html + 2024-01-15.html, 2024-01-16.html, etc.
+```
+
+## GeoIP2 Setup
+
+The geographic distribution map requires a free MaxMind GeoLite2-City database.
+
+1. Sign up at [maxmind.com](https://www.maxmind.com/en/geolite2/signup)
+2. Download `GeoLite2-City.mmdb`
+3. Pass the path via `--geoip ./GeoLite2-City.mmdb`
+
+## Log Format
+
+nxstats expects the standard nginx combined log format for access logs:
+
+```
+$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"
+```
+
+Error logs use the standard nginx error log format.
+
+## License
+
+MIT