Fail2Ban-Report/README.md

Fail2Ban-Report

Beta 3.1 | Version 0.3.1

A simple and clean web-based dashboard to turn your daily Fail2Ban logs into searchable and filterable JSON reports — with optional IP blocklist management for UFW.

🛡️ Note: This tool is a visualization and management layer — it does not replace proper intrusion detection or access control. Deploy it behind IP restrictions or HTTP authentication.

🔐 Security Notice

Current Status:
Fail2Ban-Report currently manages bans and unbans via UFW as a safe intermediate solution.
It does not yet directly modify Fail2Ban jails or existing fail2ban configurations.

Future Direction:
The goal is to support direct management of Fail2Ban jails in upcoming versions — including user-controlled bans and unbans per jail.
To ensure full control and auditability, all manual ban actions are already tracked in a structured blocklist.json, which will later serve as the trusted source for persistent and reviewable ban state.

Please read the Installation Instructions carefully and secure your deployment with the provided .htaccess.

still a little experimental feature : Use the Installer It would be great if you tell me if the installer worked for your needs.

---

📚 What It Does

Fail2Ban-Report parses your fail2ban.log and generates JSON-based reports viewable via a web dashboard. It adds optional tools to:

• Visualize ban/unban events
• Interact with IPs (e.g. manually block/unblock)
• Maintain a persistent blocklist.json
• Sync that list with your system firewall (via ufw (other Firewalls than UFW or direct communication with fail2ban jails not yet supported))

🧱 The architecture:

• Backend Shell Scripts: Parse logs, write JSON, and update UFW accordingly to blocklist.json
• Frontend Web Interface: Visualizes data and offers action buttons
• JSON Blocklist: Stores manually blocked IPs (active=true)

---

📦 Features

• 🔍 Searchable + filterable log reports (date, jail, IP)
• 🔧 Integrated JSON blocklist with action buttons
• 🧱 Firewall sync using UFW (planned: nftables, firewalld)
• ⚡ Lightweight setup — no DB, no frameworks
• 🔐 Compatible with hardened environments (no external assets, strict headers)
• 🛠️ Installer script to automate setup and permissions
• 🧩 Modular design for easy extension
• 🪵 Optional logging of block/unblock actions (set true/false and logpath in firewall-update.sh)
• 🕵️ Optional Feature : IP reputation check via AbuseIPDB (manual lookup from web interface)

🧰 Works even on small setups (Raspberry Pi, etc.)

---

👥 Discussions

If you want to join the conversation or have questions or ideas, visit the 💬 Discussions page.

---

🆕 What's New in V 0.3.1

• Protected access to JSON files
  • Direct access to /archive/*.json is now blocked via .htaccess
  • Frontend scripts no longer request raw .json files directly
• New secure PHP endpoints
  • includes/get-json.php and includes/get-blocklist.php act as controlled proxies to serve JSON data
  • Only PHP scripts with proper logic now expose required JSON content
• Hardened frontend behavior
  • JavaScript files (jsonreader.js, blocklist-overlay.js) fetch data only via the new PHP proxies
• New Ministats in Header
  • Shows today's ban/unban statistics in the page header:
  • 🚫 Bans
  • 🟢 Unbans
  • 📊 Total events
  • Adds quick insight into current Fail2Ban activity
• Mobile-Friendly
  • Site is now more mobile friendly
  • added favicon (🕵️) to make browsers happy

🧪 as promised there is an highly experimental feature for using fail2ban instead of UFW. (⚠️ not recommended)

---

📄 Changelog

Details about all new features, improvements, and changed files can be found in the Changelog.

This is especially useful if you want to manually patch or update individual files.

---

🪳 Bugfixes

• Found a bug? → Open an issue

• ✅ Date filter now correctly limits displayed events
• ✅ Jail filter now correctly shows only the jails present in the displayed event list.
• ✅ File date filtering fix to include today's JSON logs and ensure latest files are listed correctly.

---

🛣️ Roadmap

🔧 Setup & Automation

• ✅ Automated installer script
• ✅ Optional cron setup for log parsing and firewall sync
• 🧩 More robust installer
• ⏳ Secure-by-default deployments

🔐 Security

• ✅ Hardened .htaccess with best practices
• ✅ add security layer between json and js
• 🧩 moove archive/ out of webdirectory
• ⏳ Further improvements (ongoing goal)

🔥 Active Defense

• ✅ Manual IP blocking via UI in UFW
• ✅ IP reputation lookup via AbuseIPDB
• 🧩 Support for nftables, firewalld
• 🧩 full integration with fail2ban jails for block/unblock actions
• ⏳ Bulk blocking of multiple IPs
• ⏳ Optional automatic blocking based on patterns or thresholds
• ⏳ Integration with external services (e.g. AbuseIPDB reporting)

🌿 User Interface

• ⏳ Improve CSS and styling

👀 Outlook

• 🔭 next major version will focus on security by mooving archive/ out of webdirectory.

---

🖼️ Screenshots

---

🤝 Contributing

Pull requests, feature ideas and bug reports are very welcome!

• Found a bug? → Open an issue
• Want to contribute? → Fork and submit a pull request
• Have an idea? → Start a discussion or reach out directly : visit the 💬 Discussions page

💡 “Wouldn’t it be cool if it could also do XYZ?”
Absolutely — I’m happy to hear your ideas.

---

📄 License

This project is licensed under the GPLv3.
Feel free to use, modify and share — but please respect the license terms.