Fail2Ban-Report/Docs/Setup-Instructions.md

🔧 Fail2Ban-Report Beta 2 – Manual Setup Instructions

These instructions explain how to manually install and configure Fail2Ban-Report v2 on a Linux system.

---

✅ Requirements

• A Linux system (tested with debian only) with the following installed:
  • fail2ban
  • jq
  • awk (gawk)
  • curl
  • ufw (only UFW is supported at this time)
• A PHP-enabled web server (e.g. Apache with PHP 7.4+)
• The web server user (e.g. www-data) must have write access to the /archive/ directory

---

📁 Project Structure

Place the project in your desired web directory, for example:

/var/www/html/Fail2Ban-Report/

The structure should look like this:

Fail2Ban-Report/
├── assets/
│   ├── css/style.css
│   ├── images/*.png
│   └── js/*.js
├── includes/
│   ├── actions/*.php
│   ├── block-ip.php
│   ├── unblock-ip.php
│   ├── list-files.php
│   └── footer.php
├── archive/               ← must be writable by web server
├── index.php
├── .htaccess
├── README.md
├── Setup-Instructions.md
└── (Shell scripts stored outside the web root)

---

🔐 Permissions

Make the /archive/ directory writable for the web server:

chown -R www-data:www-data /var/www/html/Fail2Ban-Report/
find /var/www/html/Fail2Ban-Report/ -type d -exec chmod 755 {} \;
find /var/www/html/Fail2Ban-Report/ -type f -exec chmod 644 {} \;

---

⚙️ Shell Scripts

The following two shell scripts must not be placed inside the web root. Recommended path: /opt/Fail2Ban-Report/

• fail2ban_log2json.sh
• firewall-update.sh

Adjust paths in these scripts if necessary:

• fail2ban_log2json.sh reads the Fail2Ban log and writes JSON files to /archive/ (archive/ is a folder placed in the Webspace of /Fail2Ban-Report/
• firewall-update.sh reads blocklist.json and syncs it with UFW (blocks/unblocks) so it also needs the path to /archive/

Make sure both scripts are executable (chmod +x)

---

🕒 Cronjob Configuration

Set up two cronjobs:

1. Convert logs to JSON every 5–15 minutes:

   */5 * * * * root /opt/Fail2Ban-Report/fail2ban_log2json.sh

2. Sync firewall blocklist with UFW every 5–15 minutes:

   */5 * * * * root /opt/Fail2Ban-Report/firewall-update.sh

Make sure both scripts are executable (chmod +x)

---

🌐 Web Interface Configuration

• No PHP configuration is required.
• All scripts in includes/ and includes/actions/ work without manual changes.
• The web interface displays log information and lets you:
  • View ban history
  • Block/unblock IPs manually
  • Manage the blocklist.json interactively

---

🔒 Security Notes

The .htaccess file includes:

• Protection against direct access to:
  • .json, .sh, .ini, .log, .bak, .OLD
• Rewrite rules for archive/*.json and includes/*.php
• Strong HTTPS headers
• (Optional) examples for basic authentication and IP restrictions (commented)

Make sure your Apache server honors .htaccess, and you enable mod_rewrite.

---

✅ Setup Complete

You can now access the tool at:

http(s)://yourdomain.tld/Fail2Ban-Report/

Monitor your logs, manage bans, and secure your system visually and efficiently.

---

🌐 Optional: AbuseIPDB Integration

Fail2Ban-Report supports an optional IP reputation check and reporting via AbuseIPDB, a public threat intelligence platform.

🔎 What It Does

• Displays how often an IP has been reported on AbuseIPDB
• Allows you to manually report abusive IPs directly from the interface
• Helps assess the trustworthiness of IP addresses before unblocking them

🧰 Requirements

• A free account at AbuseIPDB.com
• A personal API key (available in your AbuseIPDB dashboard)

🛠 Configuration

1. Create a config file outside the web root, e.g. at:

   /opt/Fail2Ban-Report/fail2ban-report.config
   

2. Add the following content (replace the API key placeholder):

   [reports]
   report=true
   report_types=abuseipdb
   
   [AbuseIPDB API Key]
   abuseipdb_key=YOUR_API_KEY_HERE
   

3. Ensure the config file is readable by the web server (e.g. www-data):

   chown www-data:www-data /opt/Fail2Ban-Report/fail2ban-report.config
   chmod 640 /opt/Fail2Ban-Report/fail2ban-report.config
   

4. Done — if the file exists and is valid, the web interface will show AbuseIPDB info and allow reporting.

⚠️ Custom Path or Filename

If you choose a different location or name for the config file:

• Open this file:

  includes/actions/reports/abuseipdb.php
  

• Look for the line that defines the path:

  $configPath = '/opt/Fail2Ban-Report/fail2ban-report.config';
  

• Adjust it to match your actual file path.

⚠️ The config file must be placed outside the web root for security reasons.

💡 Notes

• The feature is fully optional — Fail2Ban-Report works fine without it.
• AbuseIPDB requests are made server-side, your API key is not exposed in the browser.
• Their free tier currently allows 1,000 requests per day